Horace README =============== Horace is an event generator for Drell-Yan processes at hadron colliders including the ElectroWeak radiative corrections. The generator is developed by C.M. Carloni Calame [1], G. Montagna [2,3], O. Nicrosini [3,2] and A. Vicini [4]. [1] CERN, supported by a "Angelo Della Riccia" fellowship [2] Dipartimento di Fisica Nucleare e Teorica, Universita' di Pavia (Italy) [3] INFN, Sezione di Pavia [4] Dipartimento di Fisica, Universita' di Milano, and INFN, Sezione di Milano (Italy) For information, updates and citing the code, please refer to the web page http://www.pv.infn.it/hepcomplex/horace.html Compiling the code ------------------------------ Horace is written in the standard FORTRAN 77 language, with a small C function (trapfpe.c) to trap floating point exceptions. A Makefile is provided in order to build the executable file 'horace'. By default, the g77 GNU Fortran compiler is used. Please, set in the Makefile file the relevant path variables and set correctly the FFLAGS variable: by default it is strongly tuned for a Pentium4 processor. The Horace package includes a copy of the libraries LoopTools2 (http://www.feynarts.de/looptools/, patched to cover the complex W and Z mass in vertex and box functions) and Cuba-1.2 (http://www.feynarts.de/cuba/, for the calculation of the subtraction terms) and includes the file hadr5n.f by F. Jegerlehner (http://www-com.physik.hu-berlin.de/~fjeger/) for the calculation of the hadronic contribution to the vacuum polarization. Running Horace -------------- The value of the input parameters which have to be provided to the program can be conveniently specified in the file input-test. Input parameters (see below for a more detailed description) ------------------------------------------------------------ new ! HORACE mode: old = only final state QED in Parton Shower approximation, new = exact O(alpha) EW corrections matched with higher orders QED alpha ! order of radiative corrections alpha = up to first order corrections exp = alpha + higher-order QED (best) born = Born cross-section 2212 ! initial state hadrons: 2212 protons, -2212 antiprotons 2212 1 ! PDF set in HORACE 1 = MRST2004QED 2 = CTEQ6L 3 = LHAPDF (to be activated by the user in the file PDF.f) 14000. ! CoM energy (GeV) W+andW- ! boson Drell-Yan production possible choices: W+, W-, W+andW-, Z 1 ! EW input scheme: 0 = pure alpha, M_W, M_Z input scheme 1 = G_\mu scheme for W production, IBA for Z production muon ! final state lepton(s) possible choices: muon, electron test_run/ ! name of the directory where all the data of the ! run will be saved 10000 ! number of events unweighted ! unweightening: possible choices are: weighted, unweighted 15. ! rescaling factor to adjust the efficiency of the unweightening procedure yes ! if events have to be stored (yes/no) read ! mode to include the subtraction terms possible choices are: read, calculate subtractionfile.dat ! file of subtraction terms no ! if photon-induced processes have to be included (yes/no) 1234234 ! seed for r.n.g. 2.5 ! maximum lepton rapidity 25. ! minumum lepton pt (GeV) 25. ! minumum missing pt (GeV) If the option unweighted is chosen, the program will generate the requested number of unweighted events (given the unweightening efficiency, a larger number of points will be thrown in the phase-space). If the option weighted is chosen, the program will generate the specified number of points and compute the cross-section and the distributions. The rescaling factor to adjust the efficiency of the unweightening procedure changes the maximum value in the "hit or miss" procedure: if too large the efficiency decreases, if too small a certain number of points could exceed the maximum value and can not be correctly unweighted, introducing a bias in the estimate of the hit or miss cross section. In the output file 'statistics.txt' a recommended value for this parameter is suggested 'a posteriori' and the bias induced by the points which exceed the maximum is evaluated. The rescaling factor must be chosen large enough to make the bias vanish. Nevertheless, a smaller value can increase the efficiency while keeping the bias at a tolerable level. For a given hadronic center-of-mass energy, for a given choice of the PDF and the PDF factorization scale, the program allows to compute only once the subtraction terms which remove the initial state collinear singularities. When the variable which specifies the subtraction mode is set to 'calculate' the subtraction terms are computed and saved in the file 'subtractionfile.dat' (which can be set in input). The next time, the program can be run with the subtraction mode 'read', and the grid which interpolates the subtraction terms is read from the file 'subtractionfile.dat'. We provide also a routine to apply selection cuts to the event sample. By default, we impose cuts on the lepton and neutrino (or leptons) pt and lepton(s) pseudorapidity, the values of which can be set in the input file. The user can implement his/her own cuts by modifying the file cuts.f. The events produced by HORACE can be dumped to an external file (test_run/*.evts) and can be given as input to standard showering Monte Carlo generators using the Les Houches Interface Accord. User modifiable routines ------------------------ The subroutines the user may need to modify are: -> 'userinterface' (in the file init.f) where the masses and widths of the elementary particles, the values of the coupling constants and of the CKM matrix are defined -> 'initPDFhorace' (in the file PDF.f) where it is possible to choose, beside the two basic pdf sets (MRST2004QED and CTEQ6L), to use the LHAPDF interface; in this latter case the user needs to 1) uncomment the calls to the routines initPDFsetByName and InitPDF 2) uncomment the calls to the routine evolvePDF(x,s,f) and following lines in the routine pdf_wrapper (in the file PDF.f) 3) define in the Makefile the variable PDFLIB -> 'cuts' (in the file cuts.f) where the experimental cuts are implememted Output files ------------ The output files are saved in the 'test_run/' directory (which can be set by the user). The files are -> statistics.txt: it is the file where cross sections, statistics information, input parameters, etc. are printed. After the input parameters entered by the user, the weighted integrated cross section is printed. It is subdivided by photon multiplicity: each cross section depends on the 'eps' parameter but the sum does not. After weighted cross section information, the unweighted events statistics is reported. The user must pay attention to the "biases" cross sections: they account for the biases due to negative weights events and unweightening failure due to an under-estimated maximum of the differential cross section. The latter bias is usually negligible, its size is estimated by the corresponding cross section. -> distribution files: in these files some differential distribution are written. The file names should be self-explaining and the data are in the form (e.g. to be easily plotted with gnuplot): lower bin edge - differential cross section - corresponding error By default, the following distributions are saved: - lepton transverse momentum distribution, in different ranges (ptl1, ptl2, ptl3) - missing (or lepton) transverse momentum distribution, in different ranges (ptn1, ptn2, ptn3) - W or Z/gamma transverse mass distribution, in different ranges (mtv1, mtv2, mtv3) - lepton pseudorapidity distribution (etal) - neutrino (or lepton) pseudorapidity distribution (etan) - W or Z/gamma rapidity distribution (yv) - W or Z/gamma transverse momentum distribution (ptv) - most energetic photon transverse momentum distribution (ptg) - most energetic photon rapidity distribution (etag) - W or Z/gamma invariant mass distribution in different ranges (minv, mhi) Les-Houches-Accord-format event dumping --------------------------------------- If the option of saving events is set to 'y', a file .evts and a file .conf are saved in the output directory. The events are stored in a LHA compliant format (mainly stolen from ALPGEN). The events are dumped by the routine 'evdumpHORACE' (in the file storage.f). The weight corresponding to the events is +1 or -1 in case of unweighted generation or the event cross section in case of weighted generation (which can be also negative). In the directory 'leshouchesinterface', the files inithorace.F and usehorace.F are provided as template to fill LHA common block to pass Horace events to QCD showering Monte Carlo's like Herwig or Pythia. The files have been used to include Horace in the ATLAS ATHENA framework and have been written in close collaboration with Massimilano Bellomo (ATLAS - INFN, Sezione di Pavia). Enjoy Horace! Alessandro, Carlo, Guido, Oreste