bacf4551dd9314bf7447ead683960e4dfebb5d5b
[u/mrichter/AliRoot.git] / 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
348 Local Variables:
349   mode: markdown
350 End:
351
352