Program Manual and input-file guide for gamma2MC version 1.0 (beta)

This manual describes how to use the NLO di-photon production cross section program gamma2MC, by giving line-by-line instructions for the input file "gamma2MC.indat".


General Formatting Notes:

It should be fairly easy to use the input file, "gamma2MC.indat", just by modifying the example that came with the source distribution. However, there are a few general formatting requirements to be aware of.
The input file must have exactly 19 lines. Although some lines are ignored for certain choices of processes or cuts, the line must still be there in order for the program to function properly.
In the following explanations of the inputs, a list {a, b, c} indicates a choice of string inputs on a line, while an ordered list [x y z] indicates multiple numerical parameters input on a single line. Possible inputs are colored red.
If the input to a line is a string, then it MUST have trailing white spaces after the string (NOT TABS!). It is easiest to do this by keeping the explanatory comment after the input string (i.e, white spaces followed by #x Comment) from the example file.
Any input which is a string must be spelled exactly as given below, including capitalization and without quotation marks, or else the program will complain.
The program ignores anything in a line that comes after the expected input.


Line-by-line explanation of input file:

#1 Name of the output file.
Any file name will do, such as output/gamma2MC_MGG.out (without quotes). There is an empty directory "output/", which may be used for output files. Or you may organize as you desire.
#2 Type of collider.
Choose from {pp, ppbar}.
#3 Collider COM energy
Input in GeV, such as 14000.0
#4 Type of PDF set.
Choose from {cteq5, cteq6, mrst}. At the moment, the mrst set corresponds to MRST99. More up-to-date MRST PDFs will be included in the final program version.
#5 PDF individual set.
Input an integer, which specifies the specific PDF set to use.
For Cteq distributions this is the variable iset, which chooses among the various distributions in the set (iset=1..9 in cteq5, iset=1..4 in cteq6).
For MRST distributions this is the variable mode with mode=1..12.
Common choices are:
cteq6 :     iset=1 : CTEQ6M Standard MSbar scheme
  iset=3 : CTEQ6L Leading Order with NLO running
  iset=4 : CTEQ6L1 Leading Order with LO running
cteq5 : iset=3 : CTEQ5L Leading Order with LO running
  iset=8 :    CTEQ5M1 Standard MSbar scheme
mrst : mode=1 : COR01 central gluon, a_s (MSBAR)
  mode=2 :    COR01 higher gluon (MSBAR)

For more info on PDF distributions, look at the comments in the file "Cincludes/pdfqcd03.h" or in the specific PDF code files in the directories "PDFs/Cteq6", "PDFs/Cteq5", and "PDFs/MRST99".

#6 Process type.
Choose from {HIGGS, GG, QQ}.
You may calculate the contribution to p p(bar) --> gamma gamma X at LO and NLO from three distinct subprocesses:
HIGGS :     Through the Higgs resonance: g g --> H X, followed by H --> gamma gamma. The production cross section of the Higgs boson is through gluon-gluon fusion (with all associated channels at NLO) in the heavy top quark limit (top quark mass dependence is included only in the LO prefactor). The branching ratio to gamma gamma is not included. It can be obtained elsewhere, such as from the program HDECAY.
GG : Through the (formally NNLO) process g g --> gamma gamma X, which occurs at one loop. This box contribution is then treated as the LO part of a NLO calculation, where only gluon-gluon initial-states are considered.
QQ : Through q qbar --> gamma gamma X , as well as all associated channels through NLO. This process at NLO has a collinear singularity when the photon and a final-state quark are collinear. This singularity has been MSbar-subtracted, so that the calculation should be finite for any isolation cuts. However, no fragmentation processes are included, so only a calculation with an IR-safe isolation (such as Frixione's smooth isolation cut) has any physical meaning at NLO. (I.e, the calculation with the IR-safe isolation cut does not depend on the subtraction prescription and does not get any contribution from photon fragmentation processes.)
#7 QQ subprocess contribution.
Choose from {QQTOTAL, QQONLY, QGONLY}.
If the Process type is not QQ, then this line is ignored (ALTHOUGH IT STILL MUST BE HERE!).
If the Process type is QQ, then:
QQTOTAL :     Include both quark-antiquark and quark-gluon initiated contributions at LO or NLO.
QQONLY : Include only the quark-antiquark initiated contributions at LO or NLO. Note that these contributions have no collinear singularity with the final-state photons.
QGONLY : Include only the quark-gluon and antiquark-gluon initated contributions. These only occur at NLO. They contain collinear contributions with the final-state photons, which have been MSbar-subtracted.
#8 Order of the calculation.
Choices are {LO, NLO, EASYNLO, HARDNLO}.
LO and NLO are self-explanatory. (To be precise, NLO computes the sum of LO + NLO corrections.) EASYNLO and HARDNLO each compute part of the full NLO calculation, and were separated out for diagnostics. (They sum to the full NLO cross section.) HARDNLO computes the NLO piece with real gluon emission, minus subtraction terms. EASYNLO computes the LO + the remaining NLO corrections, which have LO kinematics. Of course, HARDNLO and EASYNLO are unphysical and are not needed by most users of the code. (HARDNLO may be useful for computations in which a visible hard jet is required.)

Lines #9, #10, #11 are used for implementing cuts on the events. The explanation of these three lines follows. More information about the cuts can be found in the file "Cuts.h".
#9 Cut type.
Choose from {none, standard, ptcut, hcut, frixione, noIsolation, jetveto, annulus, D0, userdefined}.
All choices have minimal pt and rapidity cuts on the photons (input in line #10), except for {none, hcut}. The remaining variables for each type of cut are input in line #11. Detailed descriptions are:
none :     As the name implies, no cuts are performed.
hcut :     The two-photons are reconstructed into a single particle, and a cut is performed on the rapidity yh of this particle. The event is cut if |yh|> yhcut. This is useful for calculations of Higgs production, without regard to the Higgs decay.
noIsolation :     Minimal photon cuts only.
standard :     Minimal photon cuts plus the following isolation cut. The event is cut if the amount of transverse hadronic energy in a cone of radius Rcut around either photon is greater than Etcut.
frixione :     Minimal photon cuts plus the following smooth isolation cut, suggested by Frixione. The event is cut if the amount of transverse hadronic energy in ANY cone of radius r<Rcut around either photon is greater than [pt_gamma*epsilon*(1-cos(r))/(1-cos(Rcut))].
D0 :     Minimal photon cuts plus the following isolation cut, used by the D0 collaboration. The event is cut if the amount of transverse hadronic energy in a cone of radius Rcut around either photon is greater than [epsilon*pt_gamma].
ptcut :     Minimal photon cuts plus standard isolation cuts plus an observed jet cut. The event is cut if the jet does not have transverse energy greater than Etjet.
jetveto :     Minimal photon cuts plus standard isolation cuts plus an additional cut on jets in a larger cone around the photon. The event is cut if there is a jet with transverse energy greater than Etjet within a cone of radius Rjet around either photon. It is assumed that Etjet>Etcut and Rjet>Rcut. Since at NLO, there is at most one colored parton in the final-state, there can be no dependence on the jet cone size in this calculation. (This would have to be corrected at NNLO and beyond.)
annulus :     Minimal photon cuts plus standard isolation cuts plus a cut to include at least one jet in an annulus around either photon. The event is cut if there is no jet with transverse energy greater than Etjet in an annulus of inner radius Rcut and outer radius Rjet around either photon. Note that if we remove the events passing the annulus cut from those passing the standard cut, this is equivalent to applying the jetveto cut.
userdefined :     Minimal photon cuts plus user-defined isolation cuts. The user can define a new set of isolation (or other) cuts by modifying the class function "cutUser::cutIsolation(p1,p2,p3)" in the file "Cuts.C". In this function p1 and p2 are the final-state photon four-vectors, while p3 is the final-state (colored) parton four-vector. Note that this set of cuts is always in addition to the minimal photon cuts. The new isolation cuts can depend on up to four variables (input in line #11), which are "cutUser::P1", "cutUser::P2", "cutUser::P3", and "cutUser::P4". (See the class definition in file "Cuts.h".) After modifying the class function, the program must be recompiled by typing "make gamma2MC" on the command line. (If this class function is not modified, then this set of cuts is the same as the standard isolation cuts by default.)
#10 Input parameters for minimal photon cuts.
Numerical input in format [ycut pt2 pt1], where pt1 is greater than or equal to pt2. For example, the input could be 2.5 25.0 40.0
Note that this line is ignored if the Cut type is {none, hcut}.
The cuts are:
ycut :     Require |y_gam|<ycut for each photon.
pt2 :     Require smaller photon pt satisfy pt>pt2 (in GeV).
pt1 :     Require larger photon pt satisfy pt>pt1 (in GeV).
#11 Input parameters for isolation or other cuts.
The input here depends on the specific type of cut, with details given above.
none :     Line is ignored.
hcut :     [yhcut]. For example, 2.5
noIsolation :     Line is ignored.
standard :     [Rcut Etcut] with Etcut in GeV. For example, 0.4 15.0
frixione :     [Rcut epsilon]. For example, 1.0 1.0
D0 :     [Rcut epsilon]. For example, 0.4 0.07
ptcut :     [Rcut Etcut Etjet] with Etcut, Etjet in GeV. For example, 0.4 15.0 30.0
jetveto :     [Rcut Etcut Rjet Etjet] with Etcut, Etjet in GeV. For example, 0.4 5.0 2.0 15.0
annulus :     [Rcut Etcut Rjet Etjet] with Etcut, Etjet in GeV. For example, 0.4 5.0 2.0 15.0
userdefined :     [P1 P2 P3 P4] as defined by user. For example, 1.0 2.0 3.0 4.0

#12 Range in M_gamgam
If the process is HIGGS, then input [M_Higgs] in GeV. For example, 120.0
Otherwise, input the range in M_gamgam: [M_gamgam(low) M_gamgam(high)] in GeV. For example, 80.0 140.0
#13 Input scale choices.
The input format is [chiR chiF chifr]. For example, 0.5 0.5 0.5
The scale factors are defined by:
fragmentation :
#14 Input Vegas Grid variables
The input format is [itmx ncallAdapt], where itmx is the number of iterations, and ncallAdapt is the number of function calls per iteration, used to build the Vegas Grid. Both are integers. For example, 5 50000
#15 Input integer number of events
Input is a single integer, the number of events called after the Vegas Grid is set up. For example, 1000000
#16 Input seed
Input is the seed for the random number generator, which must be a negative number (<0). For example, -328

Lines #17, #18, #19 are used for producing histograms of different event distributions. Currently, the code only can produce one histogram per run. I hope to allow for multiple histograms in the final program version. More information about the Distribution class can be found in the file "Distribution.h".
#17 Distribution type.
Choose from {COSTHETASTAR, YSTAR, TANHYSTAR, YGG, PHIGG, QT, MGG, USERDEFINED}.
The distribution variables are:
Renormalization :      mu_R=chiR*M_gamgam.
Factorization : mu_F=chiF*M_gamgam.
mu_fr=chifr*M_gamgam.
COSTHETASTAR :     Center-of-mass scattering angle of the photons.
YSTAR :     y^star = |y_gam1 - y_gam2|
TANHYSTAR :     tanh(y^star)
YGG :     Let q = p_gam1 + p_gam2. Then y_gg = rapidity of q.
PHIGG :     phi_gg = |phi_gam1 - phi_gam2| (defined in interval [0,PI]).
QT :     Let q = p_gam1 + p_gam2. Then q_T = transverse momentum of q.
MGG :     Let q = p_gam1 + p_gam2. Then M_gamgam= invariant mass of q.
USERDEFINED :     The user can define a new distribution to histogram by modifying the class function "distUser::Param(p1,p2)" in the file "Distribution.C". In this function p1 and p2 are the final-state photon four-vectors. (See the class definition in file "Distribution.h" for information.) After modifying the class function, the program must be recompiled by typing "make gamma2MC" on the command line. (If this class function is not modified, then this distribution is the same as MGG by default.)
#18 Input binning parameters
Input the binning parameters [nbins hmin hmax] = [Number of Bins, Lower limit of bins, Upper limit of Bins].
For example, for a MGG distribution with 15 80.0 140.0 as input, the program would produce a histogram in M_gamgam with 15 bins of 4.0 GeV each, running from 80.0 to 140.0 GeV.
#19 Should histogram be scaled to total cross section?
Choose from {scaled, unscaled}. If scaled, the distribution is divided by the cross section.