New features for V2.0:

Running modes:
New documentation running modes are available:

• imode=3: prints to the screen the list of parameters relative to the chosen hard process, their default values, and the explanation of their meaning
• imode=4: same as imode=3, but prints to the file par.list
• imode=5: prints to file prc.list the list of ALL hard processes included in alpgen, with the global set of parameters and default values

Input structure:

The input files for all processes have now the same structure. There are 5 input items which are mandatory:

• the running mode
• the name of the files to be generated
• the choice of input grid (new generation, or use or existing grids)
• the number of events per warmup iteration, and the number of warmup iterations
• the number of events to be evaluated during the run after warmup

All other parameters required are already set to reasonable defualt values. The user can change them by entering a sequence of strings (representing a given parameter) and the corresponding value. For example:

njets 3
mb 4.75
ptbmin 25

would change the value of njets, b-mass and minimum pt of the b jets. The code will keep reading until an end of file is met (in interactive mode the end-of-file command can be issued with ctrl-D). The list of the strings correpsonding to the relevant parameters is obtained form the previously mentioned par.list or prc.list files, or can be generated on the fly by simply entering the string "print 1" (print tothe screen) or "print 2" (print to the par.list file). The same structure operates when running in imode=2. Parameters wich have already been set during the run in imode=1 do not need to be reinitialised, since they are automatically read in by the executable from the files written during the imode=1 run. Any attempt to alter them will be rejected. The list of parameters to be entered in imode=2 can agian be obtained with a "print 1" statement. these correspond typically to parameters controlling the decay modes of W, Z and top. In all case, whether imode=0,1 or 2, the code checks whether the parameter changes requierd by the user are compatible with the requirements of the code, so there is no risk to make mistakes.

Jet-parton matching:
A large set of processes allows for the matching of matrix-element hard partons and shower-generated jets, following the so-called MLM prescription. Jet-parton matching allows to generate inclusive samples of arbitrary jet multiplicity. This will be described in detail in a subsequent publication. A short summary of the use of this option is given here.

1. Create weighted event samples running in imode=1, assigning to the parameter ickkw the value 1 (default ickkw=0). With this setting, the code implements the CKKW scale prescription for the scale of alphas.
2. Generate the unweighted event sample running as usual in imode=2. The executable automatically recognizes the ickkw=1 setting, and performs the alphas-reweighting.
3. The above steps should be carried out for the full set of multiplicites one is interested in. For example, for an analysis which will extend up to W+4 jet final states, one should generate samples of W+0, W+1, W+2, W+3 and W+4 partons.
4. Each of the above samples of unweighted events should be processed through a shower code (Herwig or Pythia), using the interface provided in the package. The code will enforce the jet matching prescription, rejecting events which fail the matching. The parameters for the matching (e.g. the definition of the jet to be used in the matching) are selected automatically. The code requires as input a parameter specifying whether events passing the matching criterion and having extra jets due to the parton shower evolution can be kept (inclusive mode) or are rejected (exclusive mode). The inclsuive mode must be used only for the sample with the highest parton multiplcity (e.g. the W+4 jet sample in the example above).
5. The set of showered events which survived the matching should be combined to obtain a fully inclusive result. In other words: the distributions derived by applying the user analysis to each individual sample (W+0, +1, etc) should at the end be summed up. Each of the individual distributions will have its own absolute normalization, inherited from the cross-section information. Since the definition of jet used by the matching prescription will most likely not coincide with the jet definition used by the user analysis, events from a given partonic multiplicity will result in events with a spectrun of jet multiplicities. For example, the events obtained form the W+3 jet partonic sample after matching may result in events with jet multiplcity not necessarily identical to 3. This is the reason why even if we are interested in studying just W+3jet final states it is required to include samples obtained from lower, as well as higher, parton multiplicity.
6. Processes for which matching is available:
   • all hard processes, with the exception of 4Q, QQh, single top
   • in the case of Wbb/Wcc, Zbb/Zcc, bb+jets/cc+jets , it is assumed that the bottom of charm quarks are treated as jets, and as such are subject to the matching requirement. This will evolve in future updates, where heavy quarks will be protected from matching, thereby allowing te generation of configuration where the pair of heavy quarks reconstructs a single jet, or where one of the two is either too soft or at too large rapidity to reconstruct an independent jet.
   • The above point has been superseded in V2.03, as documented in the Remarks/bugs section for V2.03 below.

New hard processes
V2 includes the following new processes:

• hjet: Higgs production by gluon-gluon fusion, with possible extra jets: H+ N jet, with N up to 4.
• top: single top production, with a choice of the following channels:
  • top+light quark
  • top+b
  • top+W
  • top+b+W

Code validation utility:
After unpacking the source code, the user can validate its installation by issuing the following command in the main directory:

> make validate

This script will compile all executables for all hard processes, will run a test job for each of them and for each jet multiplicity, and will compare the results against templates already included in the package. The file val.summary in the /validation directory collects the differences encountered during this comparison. If the installation is fine (e.g. is there are no problems with the difference of operating system and architecture), no difference should be detected. Else please contact the authors. the script can be used to validate the herwig and pythia packages as well. Just run

> cd validation
> ./validate her

or

> cd validation
> ./validate pyt

In these cases, the validation might take some time due to the long compilation time for the herwig and pythia sources.
When you are done with the validation, you may want to clean up all the files created in the various subdirectories by the validatin itself. Just issue the command

> cd validation
> ./validate clean

Herwig/Pythia versions
We provide with this package the latest releases of herwig and pythia, namely Herwig6507 and Pythia 6.320 (6.322 as of Alpgen V2.03, 6.324 as of Alpgen V2.05, see below). There is backward compatibility with earlier verisons of herwig down to 6500, and with pythia>6227. Previous versions of pythia would not work, because of the lack of the infrastructure (the call to the routine UPVETO) necessary for the matching. In the case of both Herwig and Pythia the dummy routines relative to the Les Houches accord (UPINIT, UPEVNT and UPVETO) are removed, since they are present in the alpgen part of the code (alplib/alpsho.f)

Other notable features:

• The set of available scale options (iqopt) has been rationalised, with new scales added and some removed. The various options for each process are listed in the par.list files, or can be displayed at run time with the "print 1" input. the default is always iqopt=1
• The definition of "njets" follows the following criterion:
  • aside form the expections listed below, njets=0 corresponds to the most elementary final state in a given hard process. For example, for wbb njets=0 corresponds to the final state W+b+bbar and no extra jets. In the case of wjet, njets=0 means production of a single W.
• exceptions:
  • Njet: njets=2 is the defualt, correpsonding to 2 final state jets
  • phjet: njets=1 is the defualt, correpsonding to a single photon recoiling against a jet

Remarks/Bugs for V2.0: This section contains comments and/or bug reports. The source library linked above contains the most up-to-date version, with all bugs reported below fixed. It is advised to check this section from time to time, to ensure you are running the most up-to-date version. Only the program elements explicitly listed have been updated with respect to the previous version.

• Enabled shower evolution for H+jet processes
• Fixed bug in colour flows for 4Q proceses
• Missing F90 files added to the package

• Enabled access to variables ptlmin,etalmax,metmin,drlmin and iwdecmod in wcjet process (thanks to G.Grenier for pointing out their absence) (File affected: alplib/alpgen.f )
• Changed slightly the algorithm defining the ICKKW scale, to cope with processes like wqq and configurations where the heavy quarks are allowed to be arbitrarily close (e.g. drbmin=0). These configurations had scale arbitrarily small, leading to unphysical alphaQCD. Now the mass squared of the clusters has been added to the value of the scale. (thanks to G.Grenier for pointing out this bug) (File affected: alplib/alpgen.f )
• Dynamical setting of the maximum number of allowed code.gt.100 errors in Herwig. Runs gracefully terminated by Herwig for excess of errors did not report the correct cross-section. (thanks to B.Quayle for pointing out this problem) (Files affected: alplib/alpsho.f and herlib/atoher.f)
• Added information on the W charge (variable wchrg) to the common blocks accessible to the user when running in imode=0,1. wchrg added to the files wjet.inc and wqq.inc, and removed declaration from wqqlib/wqq.f and wjetlib/wjet.f. (Files affected: wqqlib/wqq.f wjetlib/wjet.f wqqlib/wqq.inc wjetlib/wjet.inc; no impact of data sets generated with previous versions.)

• Thanks to the release of a new version of PYTHIA, the matching requirement for jets of heavy quarks (c/b) has been removed. This means that in processes like Wbb+jets, Wcc+jets, bb+jets, cc+jets etc only the "jets" are subject to the matching condition. Likewise, the jets from the decay of heavy objects (top, W) are not subject to the matching requirement. When PYTHIA is used as a shower generator, this demands the use of the PYTHIA version 6.322 (released July 12) or higher. 6.322 is now the new default provided with the ALPGEN package. Relative to the version available from the PYTHIA web page, the file included in the ALPGEN release had the dummy routines UPINIT, UPEVNT and UPVETO removed, since these are part of the ALPGEN part of the code. Previous versions of PYTHIA can be used by replacing the routine PYVETO with the one present in 6.322. Use of the new kt parton-shower algorithm available in PYTHIA6.3 is however not possible at this time, since the routine PYVETO will not record properly parton motherhood codes. (File affected: alplib/alpsho.f . New file: pylib/pythia6322.f)
• Slight modifications to the files vbjetlib/vbjet.f, zjetlib/zjet.f, AH90.f90, hjetlib/77/* and hjetwork/Makefile, necessary to remove accidental denominator zeros.

• Bug in the V2.03 interface to HERWIG/PYTHIA for the vbjet process with one or more Higgses. The code was assigning the wrong number of final state particles. Previous versions were OK. (File affected: alplib/alpsho.f)
• Added in ini_*.f90 for single top and phjet (they had been accidentally left out of the package).
• Fixed a potential "out-of-bounds" in vbjet (only affected processes with 8 (eight) Z bosons).

• Jet-parton matching:
  • Enabled user access to the parameters controlling the matching: the transverse energy and the cone size of the jets used in the matching. These parameters are now requested as inputs at the beginning of the Herwig or Pythia shower evolution. Their default and recommended values are Etclus=ptjmin and Rclus=drjmin, respectively
  • Introduced two alternative choices for the functional form of the CKKW scale. They are controlled by the parameter cluopt: Q^2=dR^2 min(q1^2,q2^2) where q=pt (mt) for clupot=1(2), and with mt^2=pt^2+m^2, m being the cluster mass.
  • Introduced an overall parameter to rescale the renormalization scale used when running in ickkw=1 mode. This rescaling factor is controlled by the same parameter qfac which controls the scale factor when ickkw=0. Its default value is 1.
• Included in the package the latest Pythia release, 6.324. (File affected: pylib/pythia6324.f)
• The parameter "ilep", controlling the Z->nu nubar mode in zjet and zqq processes was not active and has been re-enabled (thanks to Shoji Asai)
• Removed file alplib/AH90.f90, whose functionality has been absorbed into alplib/A90.f90
• Fixed some system-dependence in I/O, as well as some arravy dimensionalities potentially leading to out-of-bounds in teh case of generation and decay of large numbers of gauge bosons (replaced decmax=20 with decmax=40 in alplib/alpgen.f and *lib/*.f for all *=proc)
• fixed single vs double precision assignement in routine rndint of alplib/alputi.f