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,
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.
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