PWGLF/FORWARD/analysis2/sim/README.md

   1 # Simulation Files for PWGLF/FORWARD Production
   2
   3 Christian Holm Christensen
   4 <cholm@nbi.dk>
   5
   6 ## Introduction
   7
   8 The files in this archive represents a generic approach to running
   9 AliROOT based simulations.  The idea is that the user/committer only
  10 specifies the run number for which an anchor run is needed, and
  11 possibly an event generator.
  12
  13 ## Considerations
  14
  15 The shell and ROOT scripts, JDLs, and so on are based on previous
  16 "official" production files, but with some differences.  The main
  17 difference comes about because we want to _automatically_ configure
  18 the simulation based on the relevant GRP OCDB entry as possible.
  19
  20 To that end, I created the ROOT script `GRP.C` which will query the
  21 OCDB for GRP for a specified run.  In this way, we can get the beam
  22 species, energy, and center of mass energy simply by passing a run
  23 number.  We can also select a default event generator based on these
  24 settings.
  25
  26 * For pp, the default generator is *Pythia6*
  27 * For PbPb, the default generator is *Hijing*
  28 * For pPb/Pbp, the default generator is *DpmJet*
  29
  30 However, since all steps need to have access to the GRP data, it means
  31 that all steering scripts must load `GRP.C`, and hence we can at no
  32 point use any of previously used scripts.
  33
  34 ## Setting up a simulation
  35
  36 The idea of these scripts are that we only change things in one
  37 well-defined place, and that the scripts react to JDL parameters so
  38 that we can re-use the scripts (and settings) for many kinds of
  39 simulation passes.
  40
  41 ### Configuring which detectors to include
  42
  43 Create a class called `DetCfg` deriving from `VirtualDetCfg` and
  44 have it return true/false for the detectors you want to have on/off.
  45 The class _must_ be declared in `DetConfig.C` and the function
  46 `DetConfig()` _must_ set the global object pointer `detCfg` to point
  47 to a new instance of the class `DetCfg`.
  48
  49 The script `DetConfig.C` is executed by both `Simulate.C` and
  50 `Reconstruct.C` to get the list of enabled detectors.  The script is
  51 also executed by `AOD.C` and `QA.C` to ensure that we do not add tasks
  52 for which we have no data because the needed detectors was turned
  53 off.
  54
  55 ### Configuring OCDB specific storage locations
  56
  57 Create a class called `OCDBCfg` deriving from `VirtualOCDBCfg` and put
  58 it in the script `OCDBConfig.C`.  The function `OCDBConfig` _must_ set
  59 the global object pointer `ocdbCfg` to point to a new instance of the
  60 class `OCDBCfg`.
  61
  62 The script `OCDBConfig.C` is executed by both `Simulate.C` and
  63 `Reconstruct.C` to set the list of specific storage locations.
  64
  65 One can override `VirtualOCDBCfg::Prefix()` to return the default
  66 prefix for specific storage locations.  The member function
  67 `VirtualOCDBCfg::Init(bool forSim)` _must_ declare all specific storage
  68 locations.  The parameter `forSim` is true when executed from
  69 `Simulate.C` and false when executed from `Reconstruct.C`
  70
  71 ### Configuring the QA tasks
  72
  73 Create the class `QACfg` deriving from `VirtualQACfg`, and override
  74 member functions from `VirtualQACfg` to enable/disable specific QA
  75 tasks and options.  Put the class `QACfg` in the script `QAConfig.C`.
  76 The function `QAConfig` _must_ set the global object pointer
  77 `qaCfg` to point to a new instance of the class `QACfg`.
  78
  79 The script `QAConfig.C` is executed by `QA.C` to set which tasks and
  80 features to include.
  81
  82 ### Configuring the AOD tasks
  83
  84 Create the class `AODCfg` deriving from `VirtualAODCfg`, and override
  85 member functions from `VirtualAODCfg` to enable/disable specific AOD
  86 tasks and options.  Put the class `AODCfg` in the script `AODConfig.C`.
  87 The function `AODConfig` _must_ set the global object pointer
  88 `aodCfg` to point to a new instance of the class `AODCfg`.
  89
  90 The script `AODConfig.C` is executed by `AOD.C` to set which tasks and
  91 features to include.
  92
  93
  94 ## The files
  95
  96 * `run.sh`: main steering executable (same as
  97   `/alice/bin/aliroot_new`)
  98 * `AOD.C`: AOD Filter train set-up.  Derived from `AODtrainsim.C` but
  99   modified to automatically get GRP parameters from OCDB using the
 100   script `GRP.C` and set-up the train accordingly. Also, selection of
 101   which tasks to include is done through the script `AODConfig.C`.
 102   That means this script should never be modified by the user.
 103 * `AODConfig.C`: Read by `AOD.C` to configure which tasks to include
 104   in the train.
 105 * `Check.C`: Perform ESD check. Derived from `CheckESD.C`.
 106 * `Config.C`: Simulation configuration script.  Uses `GRP.C` to
 107   automatically load the proper parameters for the Anchor run.
 108 * `DetConfig.C`: Configuration script that sets which detectors to
 109   turn on. This is used by all passes to ensure consistency.
 110 * `Final.jdl.in`: Skeleton for final merging JDL.  This is used for
 111   both QA and AOD filtering.
 112 * `GRP.C`: Script that defines the global variable `grp` which is
 113   filled with values from the appropriate OCDB GRP entry for the
 114   selected run.  This is used in `AOD.C`, `Config.C`, `QA.C`,
 115   `Reconstruct.C`, and `Simulate.C`.
 116 * `LHC10hPS.C`: Special Physics Selection set-up for LHC10h due to
 117   missing ZDC information to the trigger.  Not needed as far as I can
 118   tell.
 119 * `Merge.jdl.in`: Skeleton for intermediate merging JDL.  This is used for
 120   both QA and AOD filtering.
 121 * `OCDBConfig.C`: Set-up specific storage locations for simulation
 122   and reconstruction.  It defines the global object ocdbCfg which is
 123   used in the `Simulate.C` and `Reconstruct.C` scripts.
 124 * `QA.C`: QA train set-up. Derived from `QAtrainsim.C` but
 125   modified to automatically get GRP parameters from OCDB using the
 126   script `GRP.C` and set-up the train accordingly. Also, selection of
 127   which tasks to include is done through the script `QAConfig.C`.
 128   That means this script should never be modified by the user.
 129 * `QAConfig.C`: Read by `QA.C` to configure which tasks to include
 130   in the train.
 131 * `Reconstruct.C`: Reconstruction steering script.  Derived from
 132   `rec.C` but modified to automatically get GRP parameters from OCDB
 133   using the script `GRP.C` and set-up the job accordingly.
 134 * `Run.jdl.in`: Skeleton for initial stage running.
 135 * `simrun.sh`: Simulation shell script. Derived from basic `simrun.sh`
 136   but adapted to the files here, allows passing the number of events
 137   per job, pass the run number to relevant scripts, ignores
 138   meaningless options.
 139 * `Simulate.C`: Simulation steering script.  Derived from `sim.C` but
 140   modified to automatically get GRP parameters from OCDB using the
 141   script `GRP.C` and set-up the job accordingly.
 142 * `Tag.C`: Tag ESD files.
 143 * `merge.sh`: Shell script to steer merging jobs.  Used by both
 144   QA and AOD filtering. This is based on `/alice/bin/train_merge.sh`
 145   but modified to call either the QA or AOD train merging.
 146
 147 The shell script `doit.sh` is the omnipotent script that steers all
 148 parts of the simulation.
 149
 150 ## Usage of `doit.sh`
 151
 152     Usage: ./doit.sh [OPTIONS]
 153
 154     Options:
 155         -h,--help                    This help
 156         -t|--tag     TAG         Job tag (pp)
 157         -i|--id      NAME        Name of production
 158         -R|--run     RUN_NO  Run number
 159         -c|--copy                    Copy files to AliEn
 160         -n|--jobs    JOBS        Set number of jobs[**] (2)
 161         -m|--events  EVENTS      Set events/job[**] (1)
 162         -s|--stage   STAGE       Set the stage[***] (0)
 163         -o|--output  DIR         Set base output directory[*] ($ALIEN_HOME/test)
 164         -d|--data    DIR     Set data directory ($ALIEN_HOME/mc)
 165         -b|--bin     DIR         Set base bin directory[*] ($ALIEN_HOME/bin)
 166         -a|--aliroot RELEASE Set AliROOT release [*] (v5-04-Rev-20)
 167         -r|--root    RELEASE Set ROOT release [*] ()
 168         -g|--geant   RELEASE Set GEANT3 release [*] ()
 169
 170     [*] Only make sense with option -c
 171     [**] Only make sense for stage 0
 172     [***] If stage is set to 6, try to deduce the stage
 173           automatically. If less than zero, do not do anything but copy
 174
 175 Note, if the ROOT and GEANT release is not specified, it will be
 176 deduced from the AliROOT version.
 177
 178 * Make JDLs and copy files to `/alice/cern.ch/user/a/aliprod/PWGLFforwardMC`,
 179   specifying that output should be based in `/alice/sim/2014`, and we
 180   should use AliROOT v5-05-Rev-11, but not submitting any jobs
 181
 182     ./doit.sh -a v5-05-Rev-11 \
 183                       -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
 184                           -o /alice/sim/2014 \
 185                           -c \
 186                           -s -1
 187
 188 * Submit 100 jobs each with 10 events for run 118506 with the same
 189   parameters as above, using PhoJet
 190
 191     ./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
 192                   -i LHC14z9a -r 118506 -s 0 -n 100 -m 10 -g PhoJet
 193
 194   Output will end up in `/alice/sim/2014/LHC14z9a/118506`
 195
 196 * Submit merging jobs for the above production
 197
 198     ./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
 199                   -i LHC14z9a -r 118506 -s 6
 200
 201   Output will end up in `/alice/sim/2014/LHC14z9a/118506/`.  Repeat
 202   this until we hit the final merging.
 203
 204 ## `Config.C`
 205
 206 The `Config.C` configuration script has been trimmed down
 207 considerably.  The script is now very generic since most settings are
 208 derived from the GRP data.
 209
 210 ## `EGConfig.C`
 211
 212 When selecting the event generator, a more versatile and configurable
 213 approach has been taken.  `Config.C` defines the class `Setup` with
 214 the constructor `Setup::Setup(const char* genName)`.  Here `genName`
 215 is passed verbatim from the `Run.jdl` JDL file. The string is then
 216 passed to method `VirtualEGCfg::MakeGenerator` which in turn calls the
 217 virtual `VirtualEGCfg::CreateGenerator`.  This can be overwritten in a
 218 derived class to make particular event generators.  The provided
 219 implementation in `EGConfig.C` (loaded by `Config.C`) internally has a
 220 switch on this string to find the chosen event generator.  If no
 221 suitable generator can be found, the script will fail with a `Fatal`
 222 signal.
 223
 224 Generators are specified as
 225
 226 > _name_[_sub-type_[_sub-sub-type_]]
 227
 228 where _sub-type_ (and _sub-sub-type_) are optional.  Currently defined
 229 event generators are (case insensitive)
 230
 231 * `pythia` Pythia6 Min.Bias. Optional sub-types:
 232     * `perugia0` Perugia0 tune. Optional sub-sub-types:
 233         * `chadr` Heavy flavour charm w/hadronic decay signals added
 234                 * `bchadr` Heavy flavour beauty/charm w/hadronic decay signals added
 235                 * `cele` Heavy flavour charm signals added
 236                 * `bele` Heavy flavour beauty/charm signals added
 237                 * `jspi2e` J/Psi to electrons signals added
 238                 * `btojspi2e` Beauty to J/Psi to electrons signals added
 239         * `D6T` Rick Field's CDF Tune D6T
 240     * `atlas` Arthur Moraes' (new) ATLAS tune, possibly with
 241           sub-sub-type
 242         * `_flat` for flat multiplicity probability from 0 to 200
 243         * `jets` Jets in central barrel
 244 * `hijing` Hijing Min.Bias. For pPb and Pbp a
 245   cocktail with slow neutrons is made.  Optional sub-types:
 246     * `2000` No quenching and hard pT cut at 2.3GeV. Possible
 247       sub-sub-types are:
 248             * `hf` Random heavy flavour signal added (see for pythia
 249           above).
 250 * `ampt` AMPT min bias. Possible sub types are:
 251     * `hf` Random heavy flavour signal added (see for pythia
 252           above).
 253 * `dpmjet`
 254 * `phojet` Same as `dpmjet`
 255 * `hydjet`
 256
 257 More generators can easily be added.  The idea is to have a standard
 258 `EGConfig.C` which can be expanded upon, but if a user has very
 259 special requirements it is possible to provide ones own `EGConfig.C`
 260 script.
 261
 262
 263 ## JDL Parameters
 264
 265 ### `Run.jdl`
 266
 267 * _run number_:  The run number
 268 * _n jobs_: Number of sub-jobs to commit
 269 * _n events_: Number of events per sub-job
 270 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 271 * _other_: A colon (:) separated list of options and arguments for
 272   `simrun.sh`. These can include
 273    * `bmin`:_LEAST_B_ The smallest impact parameter to make
 274    * `bmax`:_LARGEST_B_ The largest impact parameter to make
 275    * `process`:_EG_STRING_ The event generator to use.
 276   that is, to specify using DpmJet with an impact parameter range of 0
 277   to 5fm, one must pass `process:dpmjet:bmin:0:bmax:5`
 278
 279 ### `Merge.jdl`
 280
 281 * _run number_:  The run number
 282 * _stage_: Stage number (1-4)
 283 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 284 * _what_: What to merge: either `AOD` or `QA`
 285
 286 ### `Final.jdl`
 287
 288 * _run number_:  The run number
 289 * _stage_: Stage number (1-4)
 290 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 291 * _what_: What to merge: either `AOD` or `QA`
 292
 293 ## JDL Skeleton Substitutions
 294
 295 * _@out@_: The base of the output directory e.g., `/alice/sim/2014/`
 296 * _@data@_: The directory where scripts, etc. are stored e.g.,
 297   `/alice/cern.sh/user/a/aliprod/PWGLFforwardMC`
 298 * _@aliroot@_: AliROOT version to use e.g., `v5-04-Rev-20`
 299 * _@root@_: ROOT version to use e.g., `v5-34-08-6`
 300 * _@geant@_: GEANT3 version to use e.g., `v1-15a-1`
 301
 302 ## ROOT Script Prototypes
 303
 304 ### `AOD.C(UInt_t run, const char* xmlfile, Int_t stage)`
 305
 306 * _run_: The run number
 307 * _xmlfile_: Not used, compatibility with `QA.C`
 308 * _stage_: Running stage (0: production, otherwise merge)
 309
 310 ### `QA.C(UInt_t run, const char* xmlfile, Int_t stage)`
 311
 312 * _run_: The run number
 313 * _xmlfile_: Current list of input files.  Must not contain `Stage`
 314   for final merging.
 315 * _stage_: Running stage (0: production, otherwise merge)
 316
 317 ### `GRP.C(UInt_t run)`
 318
 319 * _run_: The run number
 320
 321 ### `Reconstruct.C(UInt_t run)`
 322
 323 * _run_: The run number
 324
 325 ### `Simulate.C(UInt_t run, Int_t nev)`
 326
 327 * _run_: The run number
 328 * _nev_: Number of events per sub-job
 329
 330 ## Shell Script Arguments
 331
 332 ### `run.sh`
 333
 334 All arguments are passed on to other script e.g., `simrun.sh`
 335
 336 ### `simrun.sh`
 337
 338 * _--run_ *RUN*: The Run number
 339 * _--event_ *INTEGER*: Number of events per sub-job
 340 * _--process_ *LABEL*: The Event Generator to use.  If not specified
 341   or equal to `default` then select default EG based on collision
 342   system.
 343 * _--field_ *VALUE*: Ignored - obtained from OCDB
 344 * _--energy_ *VALUE*: Ignored - obtained from OCDB
 345 * _--physicslist_ *VALUE*: Ignored
 346 * _--bmin_ FERMI: Least imapact parameter
 347 * _--bmax_ FERMI: Largest imapact parameter
 348 * _--pthardbin_ *VALUE*: Ignored
 349 * _--quench_ *VALUE*: Quenching type to use
 350 * _--sdd_: Ignored
 351 * _--number-- *INTEGER*: Sub-job number
 352 * _--qa__: Also run QA train
 353 * _--aod_: Also run AOD train
 354
 355 ### `merge.sh`
 356
 357 * _which_: What to do merging of (either `QA` or `AOD`)
 358 * _run_:   The run number
 359 * _dir_:   Directory where intermediate data can be found
 360 * _stage_: Stage to execute
 361
 362 Local Variables:
 363   mode: markdown
 364 End: