How To Recipe for AlpGen event generation

Introduction

As of today (2008.08.29), the latest AlpGen release is 2.13 (ALPGEN homepage). If users want to run the stand alone AlpGen (up to matrix element outputs), the manual is the best guide line. The aim of this page is to provide the minimum short-cut instruction for new users, who want to generate the matrix element event files and read them in via Athena interface, i.e. AlpGen_i to produce evgen files (pool format).

(1st step) event generation at matrix element level

In the start up, users can get the source code of AlpGen from the web page or from the afs, i.e. /afs/cern.ch/sw/lcg/external/MCGenerators/alpgen/2.1.3/share/alpgen-author/. Here, let us use the source code from the author's web page. In users working directory,

 $ wget http://mlm.home.cern.ch/mlm/alpgen/V2.1/v213.tgz 
 $ tar zxvf v213.tgz 

Now users can find bunch of directories named "PROCESS"lib or "PROCESS"work, other than the directories for core libraries (alplib, herlib, pylib), Documentation (DOCS), exmaples (validation). In this page, let us chose the W+jets process. The user configuration files are in the wjetwork/ directory, all the user works are carried out in this directory.

 $ cd wjetwork

try running wjet out of the box

As a first test, let's run the alpgen without changing anything (if you have a problem here, you need to check what is wrong with your system, the instruction in this page does not include trouble shooting for different machine

compile the code (here we use f77 compiliation, if you want to use F90 see later section)

 $ make gen

now users find the executable file wjetgen. The alpgen sample production is carried out in twp step operations. The operation mode is defined in the input file (the line with comment "imode")

produce weighted events

set the imode value = 1 (the value already set by default), then run as

 $ ./wjetgen < input >& log_mode1 & 

after about 1min, the job finishes and users would see the files named w2j.* (explanations for the meaning of each file are omitted here, full detail can be found in the manual). w2j.wgt is the weighted event file, it basically contains the random seeds and event weights.

produce unweighted events

after just changing the imode to 2 in "input" file, try the same command

 $ ./wjetgen < input >&  log_mode2 & 

After this, users can find the unweighted event file, w2j.unw which is to be used as an input file for Herwig, or Pythia in the later section. The file w2j.par contains the information of configuration parameters and event generation (number of events, cross section, etc). There are other files created for monitering of generation, users are suggested to check the manual for their meanings.

Parton Shower (PS) and Hadronization by Herwig

General procedure for ATLAS users to do the parton shower and PS-ME matching (a la MLM scheme), and hadronization is in interface, i.e. AlpGen_i and Herwig_i would take care the rest (see the later section for procedure). However, users can perform the quick and light weighted checks with Herwig and Pythia packages included in the standalone ALPGEN package. go to the directory for Herwig library (in ALPGEN v213, Hewig 6.510 is used), and make the user code for herwig. Then just run this user executable from wjetwork directory.

 $ cd ../herlib ; make hwuser
 $ cd ../wjetwork; ../herlib/hwuser

Then the interactive session starts, which in this case just require file name of unweighted file (just enter "w2j" in this case). All the events path through the PS, Hadronization with a few events print out. Users are expected to modify the hwuser.f to their own purpose. Here all events passed, meaning the PS-ME matching did not happen. To run it with MLM matching, see the next section.

try running wjet in ATLAS (MC2008) style

Let's jump from "out of the box" to the current ATLAS default configuration. Before that, users may want to know what parameters could be configured by input file (the default entries in input file are not many, indicating there are many implicit default values behind. ) to see full list of parameters and their meanings, users should try above "wjetgen" run with imode=5. Then it does not create events but only creates prc.list, which contains all the list. See the general agreements for 2008 MC production Wiki. The example input file which follow the agreement is attached (input.ATLAS). Note that the parameter iewopt is set to 3 (default) which determines the W,Z masses internally in ALPGEN, thus the their masses are different from the PDG2007 values.

• The important change from the out-of-the-box run is the parameter ickkw which is set "1" here, by which the ME-PS matching will be performed with internal veto routine in Herwig.
• the link to the PDF library needs to be made before the run. The script pdflnk would create all the links for all available PDF sets. (To avoid having 30-40 unused links in the working area) It is recommended not to just issue this script, but just create one link to PDF which user is using (see the contents of pdflnk).

Now when users retry the hwuser procedure, then it inquires the matching conditions after the input file specification.

• the first question is whether this sample is treated in exclusive (1) or inclusive (0) mode. In this particular case, w2j is not highest parton multiplicity, so select exclusive (1). (In case of w5j, you may want to choose inclusive mode).
• ET, Rseparation, Etamax of the cluster (e.g. jet) are required to be provided here. It is recommended to put those 3 values suggested in the interactive mode . Suggestion value of ET is MAX(PTJMIN+5,1.2*PTJMIN), i.e. if ptjmin is 25GeV, ET=30GeV (=ptjmin+5=1.2*ptjmin), if ptjmin is 20GeV, ET=25GeV (=ptjmin+5).
• N.B. up to ALPGEN v206, the 3rd argument, i.e. Etamax was not required, and the suggested value for ET was ptjmin.

after the interactive session, the users can see a Herwig output. At the end of this message, there are summary numbers for the process. Due to the MLM matching scheme, some fraction of events were rejected. MLM matching efficiency is calculated from the two numbers in the summary. It is given by A/B (A="NUMBER OF EVENTS", B="NUMBER OF WEIGHTS"). N.B. somehow the "EFFICIENCY PERCENT" is calculated with (A-1)/B.

Other topics

Fortran 90 compiler

ALPGEN can be speed up by using F90 version of the compiler. General usage of the code is exactly the same (user need to configure the path etc in Makfile). The improvement of the speed is about factor 2-5, even to 20. Interested users should consult with manul Appendix C.

Quality of the unweighting, integration

With imode=1,2, the alpgen program produces w2j.top and w2j_unw.top files. These are the TopDrawer format files, which can be read and dumped on postscript format by top drawer utility (interested user can download it from here). They contains basic distributions before and after the event unweighting.

produce multiple files in parallel

In ALPGEN, the random numbers are calculated by the function described in the paper, F.JAMES, COMP PHYS COMM 60(1990)329. (see alpgen.f in alplib). The users are supposed to provide two sets for random seeds in 5 digits (4 numbers in total), for example, for weighted event generation 12345/67890, for unweighted event generation 12345/67890. The numbers could be any from 1-99999 which would produce independent random numbers in a period of 2x10^18 for 32bit machine. When users want to accelerate the event production rate, it can be easily done by running multiple jobs with different random seeds. One practical example is to use seed1=12345+10*i, seed2=67890-10*i (i=0,1,2...) for i-th jobs.Seed 3,4 could be equal to Seed 1,2.

(2nd step) running ALPGEN Athena interface

Up to the previous step, the files named 'w2j_unw.par' and 'w2j.unw' are created. We start this section with these files (for other processes, N partons, the file names are of course different.). What is done in ALPGEN athena interface is more or less similar to what was done with internal herwig interface in ALPGEN package in the previous sections, i.e. carry out Parton showers and reject events following the MLM prescription.

prepare the input files

Here we think of using JobTransform script to process whole machinery of athena side. The input file is given to jobTranform in the form of tar.gz files, i.e. the parameter file and the event file are included. Just for temporal test purpose, we use CSC ID, 109999, and input file base name of "alpgen.109999.w2j._00001.tar.gz". The first thing we need to do is to prepare parameter file and event file.

parameter files

The parameter file is basically a "_unw.par" file, i.e. in this example, 'w2j_unw.par' with extra few lines added by user. There are two options,

4 additional lines (new feature) example for 4 parameter case

This is supported since ALPGEN ver2.10. Following lines should be added to 'w2j_unw.par' just before ************** end parameters line in the file.

          501    25.0                     ! ETCLUS    
          502    0.70                     ! RCLUS      
          503    6.0                       ! ETACLMAX 
          504    1                           ! IEXC 

recommended values for these are (501) 1.25 times ptjmin (502) same as drjmin (503) same as etajmax (504) 1 for exclusive samples, 0 for inclusive samples. For example, if users plan to produce samples with number of partons np=0,1,2,3,4,5, then user should use exclusive mode for np=0,1,2,3,4 and inclusive mode for np=5.

3 additional lines (conventional way) example for 3 parameter case

This was used till ALPGEN ver 2.06, but still supported and generally used in current ATHENA interface.

          501    20.0                     ! ETCLUS    
          502    0.70                     ! RCLUS      
          503    1                           ! IEXC 

Here (501) equal to ptjmin (502) same as drjmin (503) 1 for exclusive samples, 0 for inclusive samples. In this mode, ETACLMAX===etajmax + drjmin.

Both modes are supported in current ATLAS AlpGen interface (it judges the mode from how many extra lines added in the parameter files).

event files

The event file should contain enough events, so that remaining events after the MLM matching exceeds the N events defined by job definition. For AlpGen, the default event amount per file is 500 which is defined in JobTranform. Of course, you need to know the MLM efficiency before hand. In order to create proper sized files, People in ATLAS used to either create large number of files and added them together, or create big files and cut them in pieces. This is up to users which way to take.

running athena

See this page (LesHouches format input files) for detail rule/instruction of file preparations. Also users can check the instruction for how to use jobTranform here ( CSC jobTransform). In our particular case, we can submit as,

source ~/cmthome/setup.sh -tag=14.2.20.1,AtlasProduction,releases,setup
csc_evgen08_trf.py 109999 1 500 1 MC8.109999.AlpgenJimmy.py evgen.pool.root NONE NONE alpgen.109999.w2j._00001.tar.gz >& log.txt

which will produce evgen pool file evgen.pool.root, and log file log.txt. At the end of log file, users can see the summary of AlpGen/Herwig job, as

 END OF RUN LOG:
 NUMBER OF INPUT PROCESSED: 1254
 NUMBER OF EVENTS GENERATED: 527
 MATCHING EFFICIENCY:  0.421051121
 FINAL CROSS SECTION (PB):  611.338965
 INTEGRATED LUMINOSITY (PB-1):  0.862042222

          OUTPUT ON LES HOUCHES EVENTS


      PROC CODE  XSECT(pb)        XERR(pb)      Max wgt(nb) No. of events


          OUTPUT ON ELEMENTARY PROCESS

          N.B. NEGATIVE WEIGHTS NOT ALLOWED

          NUMBER OF EVENTS   =         527
          NUMBER OF WEIGHTS  =        1254
          MEAN VALUE OF WGT  =  6.1134E-01
          RMS SPREAD IN WGT  =  7.1686E-01
          ACTUAL MAX WEIGHT  =  1.4519E+00
          ASSUMED MAX WEIGHT =  1.4519E+00

          PROCESS CODE IPROC =       -1400
          CROSS SECTION (PB) =   611.3
          ERROR IN C-S  (PB) =   20.24
          EFFICIENCY PERCENT =   42.11

          MODIFIED OUTPUT ON ELEMENTARY PROCESS

          MULTIPLE SCATTERS USED FOR UNDERLYING EVENT
          NO CHANGE TO TOTAL CROSS SECTION.
          NUMBER OF SCATTERS =                 2218
MetaData: cross-section (nb)= 0.611339
Tauola               INFO  ATLAS TAUOLA Ending.

Photos               INFO  ATLAS PHOTOS Ending...

TestHepMC            INFO >>> TestHepMC from finalize
TestHepMC            INFO  Events passed = 527    Events Failed = 0
AANTupleStream       INFO finalize
Stream1              INFO Records written: 527

The ratio NUMBER OF EVENTS/NUMBER OF WEIGHTS is slightly different from MLM matching efficiency MATCHING EFFICIENCY, due to the additional event vetos from Herwig fragmentation. (see the explanation here for detailed description). N.B. in the current Herwig interface (as of 2008/10/20, Herwig_i-00-03-09), this output information is simply missing in AlpGen task, when job is forced to finalize by jobTransform. This will expected to be fixed very soon.

The rest are the same basically, users need nice scripts to do these automatically for multiple files.

-- OsamuJinnouchi - 29 Aug 2008