This is a short memo on how to run and use the program for the calculation of heavy quark cross-sections at the NLO in QCD. [M. Mangano, P. Nason and G. Ridolfi, Nucl. Phys. B 373 (1992) 295.] FILES IN THE PACKAGE The program is contained in the following files: hvq_lhc.f : commented user analysis routines, used in the preparation of the LHC workshop in 1999. Other sample user analysis files for different experimental setups are available from the authors hvqmnrx.f : driver hvqcrsx.f : cross sections formulae hvqint.f : integration package, histogram handling package hvqpdfpho.f: parton density package hvqpdflib.f: interface with the parton density package PDFLIB hvquti.f : if you cannot link to the CERNLIB, this file contains all the CERNLIB functions you need for this program hvqvax.f : system dependent routines: VAX version, to be linked when running on a vax hvqavi.f : system dependent routines: used a long time ago on an Avion (SGI); we don't know if it works on modern SGI machines. hvqaix.f : system dependent routines: IBM AIX risc (UNIX) hvqlinux.f : system dependent routines: Linux trapfpe.c : system dependent routines: On Linux systems, allows trapping of floating overflow and zero divide. dummies.f : contains dummy routines for the dflm parton densities, and for electron parton densities for electron-hadron collisions. hvqfixedv.h hvqlbvar.h hvqschemes.h system.h : common blocks Makefile : makefile that generate the executable The data files *mrs*.dat (MRS parton densities) and cteq*.tbl (CTEQ parton densities) are also needed. All these files occupy more than 7 megabytes. COMPILING THE PACKAGE We assume you have unpacked the files in a directory, which we will call the main directory. You need to use the GNU's make. This is the default on Linux systems, and it is also installed in all CERN Unix platforms under the name of gmake. It is free, so, if you don't have it you can easily get it. Assuming for example that you are using Linux, from the main directory do: > cd Linux > make mytarget The makefile is smart enough to choose the appropriate system files and compilation commands for the Linux, AIX, SunOS, HP-UX platforms. In the Linux subdirectory there is a symbolic link to the Makefile in the main directory. In this way, all object files and the executable end up in the Linux subdirectory. The targets are listed in the Makefile; a well commented example is the hvq_lhc target. The targets differ in the user analysis routine. By convention, the name of the executable is the name of the user analysis routine. RUNNING THE PACKAGE First of all, you should modify the analysis routine to suite your needs. Examine carefully the hvq_lhc.f sample file to understand how to do this. If you use the standard parton densities provided with the package, and need cteq or mrs sets, you must have the data files available. A simple way to do this is the following. Assume you are runnning the program in a subdirectory of the main directory, that we call run/. From the main directory do: > cd run > ../mrs/mrsdata or > ../cteq/cteqdata This will create symbolic links to the appropriate data files, with the appropriate names. A sample run is contained in the file input To understand the meaning of all of the options specified in this file, the user should first read the following sections. The program can calculate the following: 1. single-inclusive distributions ( d sigma / d pt / d y ) 2. double differential distributions ("correlations"). 3. total cross sections The sample user file hvq_lhc.f computes only correlations and total cross section distributions. The choice of 1,2,3 or combinations thereof is controlled by one of the input parameters, fed to the executable through an interactive talk-to during the run (more on this later). For each of the previous selections, the program will independently calculate the contributions from the following initial states: a. gg b. qqbar + qbarq c. gq + gqbar + qg + qbarg Each of these channels can be selected interactively at run time. The user can choose whether to generate the contribution from all of the different initial states, or from just one of then, or from all but one. This leaves the user the possibility of comparing the different contributions as well as excluding channels which are known to contribute only marginally, thus saving on CPU time. This is for example the case of the q-qbar channel for charm or even beauty production at energies equal or larger than the Tevatron's. Files will be written automatically containing the results of each contribution (histogram's content, Vegas integration grid, etc.) and can be added together as will be described. The user is then called to select the classes of diagrams to be evaluated: Born (order alpha^2), or NLO (order alpha^3). The implementation of the cancellation of the infrared and collinear singularities between virtual diagrams, real diagrams and NLO structure functions is explained in the Article. The program will write files containing the results of each contribution separately, so the user can -- for example -- compare the Born results with the full NLO+Born. For each of the processes (Born and NLO), the program asks how many iterations the user wants to generate. These iterations refer to VEGAS iterations, VEGAS being the routine developed by Lepage to perform multidimensional integrals (G.P. Lepage, J. Comp. Phys. 27 (1978) 192). There is a default for the number of events generated per iteration, but this can be changed interactively during the "talk-to". For the Born contribution, of the order of 4-5 iterations are usually sufficient to provide reasonably smooth distributions, while for the NLO contribution several tens of iterations are sometimes needed, depending on the histograms which are being plotted. At the end of each iteration the program will automatically write the files containing all of the information of the histograms accumulated till then, as well as the Vegas grid. In case of accidental crash during an iteration -- due for example to insufficient CPU time -- or in the case the distributions don't look smooth enough, a new run can be started using all of the information accumulated until that point and stored in the files mentioned above. This is done automatically, the program will open the old files, read and store the information there contained, and start from that point. In addition, there is the option of restarting the run keeping the information on the vegas grid but reinitialising the histograms. This is useful because the first one or two iterations, before the Vegas grid settles, might have anomalous fluctuations which would take a several iterations to smooth out. TOTAL CROSS SECTION When running with the total cross section option, files containing the results is created. They are named prefix + 't' + '.dat' for total prefix + 't' + 'gg.dat' partial gg prefix + 't' + 'qq.dat' partial qq prefix + 't' + 'qg.dat' partial qg Subsequent runs will append the new results to this file, without creating new ones. BOOKKEEPING OF THE HISTOGRAMS The program has a self-contained histogramming package -- similar to HBOOK -- which handles the bookkeeping and which produces at the end a topdrawer file. The user will initialise the histograms, fill them and process them by manipulating the following routines: for the double inclusive: INIDF2 OUTFUN TOPOUT for the single inclusive: INIDF1 OUTDF1 TOPDF1 for the total cross sections: INIDF0 OUTDF0 TOPDF0 These routines are contained in the user analysis routine. In the user analysis file also the following functions must be provided ZGMU2 ZGMUINC TAUSMP ZGMU2 will set the desired factorization and renormalization scales and will evaluate alpha_s for the double-differential distribution. We remind you that the renormalization scale mur enters in the evaluation of alpha_s=alpha_s(mur), while the factorization scale sets the scale for the evaluation of the structure functions. Usually the two scales are taken to be identical, but we left them independent to probe the range of variation of the cross sections. In the case of the double inclusive distributions one has a large spectrum of choices for mu, because several scales are available: the quark mass, the quark transverse mass, the ANTI quark transverse mass, the average transverse mass, the Q-Qbar invariant mass , the pt of the recoiling jet, ..... We wanted to leave the user the freedom of selecting his mu^2 scale, but we provide as a default the following: mu**2 = m**2 + avgpt**2 where m is the quark mass and avgpt**2 is the average between the quark pt**2 and the antiquark pt**2. In addition the user can select a scale factor to multiply mu by: mu -> scr * mu for the renormalization scale and mu -> scf * mu for the factorization scale. The value of these variables SCR and SCF is requested by the program during the initial interactive talk-to. Similarly for the single inclusive distributions the user has the choice between mu**2=m**2 or mu**2=pt**2+m**2 or linear combinations thereof. The provided default is muf**2= scf*(m**2+pt**2) and mur**2= scr*(m**2+pt**2). In order to improve the efficiency of the sampling in pt (for the single inclusive case) or in s_hat=s*tau (for the double inclusive case) the user has access to the functions TAUSMP(TAU) and DF1SMP(PT). Setting TAUSMP=1 will generate events for the double differential case sampling according to the differential distribution in shat: this means that fewer events will have large shat than small shat. To enhance the fraction of events with large shat the user can set, for example, TAUSMP=TAU**POW (POW>0) Similar function is performed by DF1SMP for the single inclusive pt distribution, where the sampling is in pt rather than in shat. Using TAUSMP or DF1SMP different from 1 has as a consequence that the cross sections reported at the end of the Vegas integration will NOT correspond to the real cross-section, because vegas will not be integrating Sigma but Sigma*X**pow (X being shat or pt). Nonetheless the weights provided to the user in the routine OUTFUN and OUTDF1 are correct, and therefore the integrals read from the histograms will be properly normalized. The program will give a warning at the end of the run in case a function TAUSMP.NE.1 was used. PARTON DENSITIES Many parton densities are included in the package. Most CTEQ and MRS sets are present. Pion distribution functions are also available from the latest Sutton, Martin Roberts and Stirling fit. The data files corresponding to the three sets are pion1.dat, pion2.dat and pion3.dat. The DFLM routines could be linked in, but, since they are obsolete, we don't include them in the package. If one needs them, one can get them from the authors, remove the dummy entries in the file dummies.f, and link them in. One can also use the PDFLIB package. To link it in automatically (in CERN platforms) just do make target PDF=pdflib E-mail addresses of the authors: michelangelo.mangano@cern.ch paolo.nason@mi.infn.it giovanni.ridolfi@ge.infn.it