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.  The only thing that remains to be selected
 209 in this script is the event generator.
 210
 211 When selecting the event generator, a more versatile and configurable
 212 approach has been taken.  `Config.C` defines the class `Setup` with
 213 the constructor `Setup::Setup(const char* genName)`.  Here `genName`
 214 is passed verbatim from the `Run.jdl` JDL file. The method
 215 `Setup::MakeGenerator()` then internally has a switch on this string
 216 to find the chosen event generator.  If no suitable generator can be
 217 found, the script will fail with a `Fatal` signal.
 218
 219 Generators are specified as
 220
 221 > _name_[_sub-type_[_sub-sub-type_]]
 222
 223 where _sub-type_ (and _sub-sub-type_) are optional.  Currently defined
 224 event generators are (case insensitive)
 225
 226 * `pythia` Pythia6 Min.Bias. Optional sub-types
 227     * `perugia0` Perugia0 tune. Optional sub-sub-types
 228         * `chadr` Heavy flavour charm w/hadronic decay signals added
 229                 * `bchadr` Heavy flavour beauty/charm w/hadronic decay signals added
 230                 * `cele` Heavy flavour charm signals added
 231                 * `bele` Heavy flavour beauty/charm signals added
 232                 * `jspi2e` J/Psi to electrons signals added
 233                 * `btojspi2e` Beauty to J/Psi to electrons signals added
 234         * `D6T` Rick Field's CDF Tune D6T
 235     * `atlas` Arthur Moraes' (new) ATLAS tune, possibly with
 236           sub-sub-type
 237         * `_flat` for flat multiplicity probability from 0 to 200
 238         * `jets` Jets in central barrel
 239 * `hijing` Hijing Min.Bias. Optional sub-types. For pPb and Pbp a
 240   cocktail with slow neutrons is made
 241     * `2000` No quenching and hard pT cut at 2.3GeV. Possible
 242       sub-sub-types are
 243             * `hf` Random heavy flavour signal added (see for pythia
 244           above).
 245 * `ampt` AMPT min bias. Possible sub types are
 246     * `hf` Random heavy flavour signal added (see for pythia
 247           above).
 248 * `dpmjet`
 249 * `phojet` Same as `dpmjet`
 250 * `hydjet`
 251
 252 More generators can easily be added.
 253
 254
 255 ## JDL Parameters
 256
 257 ### `Run.jdl`
 258
 259 * _run number_:  The run number
 260 * _n jobs_: Number of sub-jobs to commit
 261 * _n events_: Number of events per sub-job
 262 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 263
 264 ### `Merge.jdl`
 265
 266 * _run number_:  The run number
 267 * _stage_: Stage number (1-4)
 268 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 269 * _what_: What to merge: either `AOD` or `QA`
 270
 271 ### `Final.jdl`
 272
 273 * _run number_:  The run number
 274 * _stage_: Stage number (1-4)
 275 * _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
 276 * _what_: What to merge: either `AOD` or `QA`
 277
 278 ## JDL Skeleton Substitutions
 279
 280 * _@out@_: The base of the output directory e.g., `/alice/sim/2014/`
 281 * _@data@_: The directory where scripts, etc. are stored e.g.,
 282   `/alice/cern.sh/user/a/aliprod/PWGLFforwardMC`
 283 * _@aliroot@_: AliROOT version to use e.g., `v5-04-Rev-20`
 284 * _@root@_: ROOT version to use e.g., `v5-34-08-6`
 285 * _@geant@_: GEANT3 version to use e.g., `v1-15a-1`
 286
 287 ## ROOT Script Prototypes
 288
 289 ### `AOD.C(UInt_t run, const char* xmlfile, Int_t stage)`
 290
 291 * _run_: The run number
 292 * _xmlfile_: Not used, compatibility with `QA.C`
 293 * _stage_: Running stage (0: production, otherwise merge)
 294
 295 ### `QA.C(UInt_t run, const char* xmlfile, Int_t stage)`
 296
 297 * _run_: The run number
 298 * _xmlfile_: Current list of input files.  Must not contain `Stage`
 299   for final merging.
 300 * _stage_: Running stage (0: production, otherwise merge)
 301
 302 ### `GRP.C(UInt_t run)`
 303
 304 * _run_: The run number
 305
 306 ### `Reconstruct.C(UInt_t run)`
 307
 308 * _run_: The run number
 309
 310 ### `Simulate.C(UInt_t run, Int_t nev)`
 311
 312 * _run_: The run number
 313 * _nev_: Number of events per sub-job
 314
 315 ## Shell Script Arguments
 316
 317 ### `run.sh`
 318
 319 All arguments are passed on to other script e.g., `simrun.sh`
 320
 321 ### `simrun.sh`
 322
 323 * _--run_ *RUN*: The Run number
 324 * _--event_ *INTEGER*: Number of events per sub-job
 325 * _--process_ *LABEL*: The Event Generator to use.  If not specified
 326   or equal to `default` then select default EG based on collision
 327   system.
 328 * _--field_ *VALUE*: Ignored - obtained from OCDB
 329 * _--energy_ *VALUE*: Ignored - obtained from OCDB
 330 * _--physicslist_ *VALUE*: Ignored
 331 * _--bmin_ FERMI: Least imapact parameter
 332 * _--bmax_ FERMI: Largest imapact parameter
 333 * _--pthardbin_ *VALUE*: Ignored
 334 * _--quench_ *VALUE*: Quenching type to use
 335 * _--sdd_: Ignored
 336 * _--number-- *INTEGER*: Sub-job number
 337 * _--qa__: Also run QA train
 338 * _--aod_: Also run AOD train
 339
 340 ### `merge.sh`
 341
 342 * _which_: What to do merging of (either `QA` or `AOD`)
 343 * _run_:   The run number
 344 * _dir_:   Directory where intermediate data can be found
 345 * _stage_: Stage to execute
 346
 347 Local Variables:
 348   mode: markdown
 349 End: