[u/mrichter/AliRoot.git] / PWGLF / FORWARD / analysis2 / sim / README.md

# Simulation Files for PWGLF/FORWARD Production

Christian Holm Christensen
<cholm@nbi.dk>

## Introduction

The files in this archive represents a generic approach to running
AliROOT based simulations.  The idea is that the user/committer only
specifies the run number for which an anchor run is needed, and
possibly an event generator. 

## Considerations

The shell and ROOT scripts, JDLs, and so on are based on previous
"official" production files, but with some differences.  The main
difference comes about because we want to _automatically_ configure
the simulation based on the relevant GRP OCDB entry as possible.

To that end, I created the ROOT script `GRP.C` which will query the
OCDB for GRP for a specified run.  In this way, we can get the beam
species, energy, and center of mass energy simply by passing a run
number.  We can also select a default event generator based on these
settings.

* For pp, the default generator is *Pythia6*
* For PbPb, the default generator is *Hijing*
* For pPb/Pbp, the default generator is *DpmJet*

However, since all steps need to have access to the GRP data, it means
that all steering scripts must load `GRP.C`, and hence we can at no
point use any of previously used scripts. 

## The files

* `run.sh`: main steering executable (same as
  `/alice/bin/aliroot_new`)
* `AOD.C`: AOD Filter train set-up.  Derived from `AODtrainsim.C` but
  modified to automatically get GRP parameters from OCDB using the
  script `GRP.C` and set-up the train accordingly. Also, selection of
  which tasks to include is done through the script `AODConfig.C`.
  That means this script should never be modified by the user. 
* `AODConfig.C`: Read by `AOD.C` to configure which tasks to include
  in the train. 
* `Check.C`: Perform ESD check. Derived from `CheckESD.C`. 
* `Config.C`: Simulation configuration script.  Uses `GRP.C` to
  automatically load the proper parameters for the Anchor run.
* `Final.jdl.in`: Skeleton for final merging JDL.  This is used for
  both QA and AOD filtering.
* `GRP.C`: Script that defines the global variable `grp` which is
  filled with values from the appropriate OCDB GRP entry for the
  selected run.  This is used in `AOD.C`, `Config.C`, `QA.C`,
  `Reconstruct.C`, and `Simulate.C`. 
* `LHC10hPS.C`: Special Physics Selection set-up for LHC10h due to
  missing ZDC information to the trigger.  Not needed as far as I can
  tell. 
* `Merge.jdl.in`: Skeleton for intermediate merging JDL.  This is used for
  both QA and AOD filtering.
* `QA.C`: QA train set-up. Derived from `QAtrainsim.C` but
  modified to automatically get GRP parameters from OCDB using the
  script `GRP.C` and set-up the train accordingly. Also, selection of
  which tasks to include is done through the script `QAConfig.C`.
  That means this script should never be modified by the user. 
* `QAConfig.C`: Read by `QA.C` to configure which tasks to include
  in the train. 
* `Reconstruct.C`: Reconstruction steering script.  Derived from
  `rec.C` but modified to automatically get GRP parameters from OCDB
  using the script `GRP.C` and set-up the job accordingly. 
* `Run.jdl.in`: Skeleton for initial stage running.
* `simrun.sh`: Simulation shell script. Derived from basic `simrun.sh`
  but adapted to the files here, allows passing the number of events
  per job, pass the run number to relevant scripts, ignores
  meaningless options. 
* `Simulate.C`: Simulation steering script.  Derived from `sim.C` but
  modified to automatically get GRP parameters from OCDB using the
  script `GRP.C` and set-up the job accordingly.
* `Tag.C`: Tag ESD files.
* `merge.sh`: Shell script to steer merging jobs.  Used by both
  QA and AOD filtering. This is based on `/alice/bin/train_merge.sh`
  but modified to call either the QA or AOD train merging.

The shell script `doit.sh` is the omnipotent script that steers all
parts of the simulation. 

## Usage of `doit.sh`

    Usage: ./doit.sh [OPTIONS]
    
    Options:
    	-h,--help		     This help
    	-t|--tag     TAG	 Job tag (pp)
    	-i|--id      NAME	 Name of production 
    	-R|--run     RUN_NO  Run number 
    	-c|--copy		     Copy files to AliEn
    	-n|--jobs    JOBS	 Set number of jobs[**] (2)
    	-m|--events  EVENTS	 Set events/job[**] (1)
    	-s|--stage   STAGE	 Set the stage[***] (0)
    	-o|--output  DIR	 Set base output directory[*] ($ALIEN_HOME/test)
    	-d|--data    DIR     Set data directory ($ALIEN_HOME/mc)
    	-b|--bin     DIR	 Set base bin directory[*] ($ALIEN_HOME/bin)
    	-a|--aliroot RELEASE Set AliROOT release [*] (v5-04-Rev-20)
    	-r|--root    RELEASE Set ROOT release [*] ()
    	-g|--geant   RELEASE Set GEANT3 release [*] ()
    
    [*] Only make sense with option -c 
    [**] Only make sense for stage 0
    [***] If stage is set to 6, try to deduce the stage
          automatically. If less than zero, do not do anything but copy

Note, if the ROOT and GEANT release is not specified, it will be
deduced from the AliROOT version.

* Make JDLs and copy files to `/alice/cern.ch/user/a/aliprod/PWGLFforwardMC`,
  specifying that output should be based in `/alice/sim/2014`, and we
  should use AliROOT v5-05-Rev-11, but not submitting any jobs

    ./doit.sh -a v5-05-Rev-11 \
		      -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
			  -o /alice/sim/2014 \
			  -c \
			  -s -1

* Submit 100 jobs each with 10 events for run 118506 with the same
  parameters as above, using PhoJet

    ./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
	          -i LHC14z9a -r 118506 -s 0 -n 100 -m 10 -g PhoJet

  Output will end up in `/alice/sim/2014/LHC14z9a/118506`

* Submit merging jobs for the above production

    ./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
	          -i LHC14z9a -r 118506 -s 6

  Output will end up in `/alice/sim/2014/LHC14z9a/118506/`.  Repeat
  this until we hit the final merging. 

## `Config.C`

The `Config.C` configuration script has been trimmed down
considerably.  The script is now very generic since most settings are
derived from the GRP data.  The only thing that remains to be selected
in this script is the event generator.

When selecting the event generator, a more versatile and configurable
approach has been taken.  `Config.C` defines the class `Setup` with
the constructor `Setup::Setup(const char* genName)`.  Here `genName`
is passed verbatim from the `Run.jdl` JDL file. The method
`Setup::MakeGenerator()` then internally has a switch on this string
to find the chosen event generator.  If no suitable generator can be
found, the script will fail with a `Fatal` signal.

Generators are specified as

> _name_[_sub-type_[_sub-sub-type_]]

where _sub-type_ (and _sub-sub-type_) are optional.  Currently defined
event generators are (case insensitive)

* `pythia` Pythia6 Min.Bias. Optional sub-types
    * `perugia0` Perugia0 tune. Optional sub-sub-types
        * `chadr` Heavy flavour charm w/hadronic decay signals added
		* `bchadr` Heavy flavour beauty/charm w/hadronic decay signals added
		* `cele` Heavy flavour charm signals added
		* `bele` Heavy flavour beauty/charm signals added
		* `jspi2e` J/Psi to electrons signals added
		* `btojspi2e` Beauty to J/Psi to electrons signals added
	* `D6T` Rick Field's CDF Tune D6T
    * `atlas` Arthur Moraes' (new) ATLAS tune, possibly with
          sub-sub-type
    	* `_flat` for flat multiplicity probability from 0 to 200
	* `jets` Jets in central barrel
* `hijing` Hijing Min.Bias. Optional sub-types. For pPb and Pbp a
  cocktail with slow neutrons is made 
    * `2000` No quenching and hard pT cut at 2.3GeV. Possible
      sub-sub-types are
	    * `hf` Random heavy flavour signal added (see for pythia
          above).
* `ampt` AMPT min bias. Possible sub types are
    * `hf` Random heavy flavour signal added (see for pythia
          above).
* `dpmjet`
* `phojet` Same as `dpmjet`
* `hydjet` 

More generators can easily be added. 


## JDL Parameters

### `Run.jdl`

* _run number_:  The run number
* _n jobs_: Number of sub-jobs to commit
* _n events_: Number of events per sub-job
* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)

### `Merge.jdl`

* _run number_:  The run number
* _stage_: Stage number (1-4)
* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
* _what_: What to merge: either `AOD` or `QA`

### `Final.jdl`

* _run number_:  The run number
* _stage_: Stage number (1-4)
* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
* _what_: What to merge: either `AOD` or `QA`

## JDL Skeleton Substitutions

* _@out@_: The base of the output directory e.g., `/alice/sim/2014/`
* _@data@_: The directory where scripts, etc. are stored e.g.,
  `/alice/cern.sh/user/a/aliprod/PWGLFforwardMC`
* _@aliroot@_: AliROOT version to use e.g., `v5-04-Rev-20`
* _@root@_: ROOT version to use e.g., `v5-34-08-6`
* _@geant@_: GEANT3 version to use e.g., `v1-15a-1`

## ROOT Script Prototypes

### `AOD.C(UInt_t run, const char* xmlfile, Int_t stage)`

* _run_: The run number
* _xmlfile_: Not used, compatibility with `QA.C`
* _stage_: Running stage (0: production, otherwise merge)

### `QA.C(UInt_t run, const char* xmlfile, Int_t stage)`

* _run_: The run number
* _xmlfile_: Current list of input files.  Must not contain `Stage`
  for final merging. 
* _stage_: Running stage (0: production, otherwise merge)

### `GRP.C(UInt_t run)`

* _run_: The run number

### `Reconstruct.C(UInt_t run)`

* _run_: The run number

### `Simulate.C(UInt_t run, Int_t nev)`

* _run_: The run number
* _nev_: Number of events per sub-job

## Shell Script Arguments

### `run.sh`

All arguments are passed on to other script e.g., `simrun.sh`

### `simrun.sh`

* _--run_ *RUN*: The Run number
* _--event_ *INTEGER*: Number of events per sub-job
* _--process_ *LABEL*: The Event Generator to use.  If not specified
  or equal to `default` then select default EG based on collision
  system. 
* _--field_ *VALUE*: Ignored - obtained from OCDB
* _--energy_ *VALUE*: Ignored - obtained from OCDB
* _--physicslist_ *VALUE*: Ignored
* _--bmin_ FERMI: Least imapact parameter
* _--bmax_ FERMI: Largest imapact parameter
* _--pthardbin_ *VALUE*: Ignored
* _--quench_ *VALUE*: Quenching type to use
* _--sdd_: Ignored
* _--number-- *INTEGER*: Sub-job number
* _--qa__: Also run QA train
* _--aod_: Also run AOD train

### `merge.sh`

* _which_: What to do merging of (either `QA` or `AOD`)
* _run_:   The run number
* _dir_:   Directory where intermediate data can be found
* _stage_: Stage to execute


Local Variables:
  mode: markdown
End:
Commit	Line	Data
f8b7a926	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	## The files
	35
	36	* `run.sh`: main steering executable (same as
	37	`/alice/bin/aliroot_new`)
	38	* `AOD.C`: AOD Filter train set-up. Derived from `AODtrainsim.C` but
	39	modified to automatically get GRP parameters from OCDB using the
	40	script `GRP.C` and set-up the train accordingly. Also, selection of
	41	which tasks to include is done through the script `AODConfig.C`.
	42	That means this script should never be modified by the user.
	43	* `AODConfig.C`: Read by `AOD.C` to configure which tasks to include
	44	in the train.
	45	* `Check.C`: Perform ESD check. Derived from `CheckESD.C`.
	46	* `Config.C`: Simulation configuration script. Uses `GRP.C` to
	47	automatically load the proper parameters for the Anchor run.
	48	* `Final.jdl.in`: Skeleton for final merging JDL. This is used for
	49	both QA and AOD filtering.
	50	* `GRP.C`: Script that defines the global variable `grp` which is
	51	filled with values from the appropriate OCDB GRP entry for the
	52	selected run. This is used in `AOD.C`, `Config.C`, `QA.C`,
	53	`Reconstruct.C`, and `Simulate.C`.
	54	* `LHC10hPS.C`: Special Physics Selection set-up for LHC10h due to
	55	missing ZDC information to the trigger. Not needed as far as I can
	56	tell.
	57	* `Merge.jdl.in`: Skeleton for intermediate merging JDL. This is used for
	58	both QA and AOD filtering.
	59	* `QA.C`: QA train set-up. Derived from `QAtrainsim.C` but
	60	modified to automatically get GRP parameters from OCDB using the
	61	script `GRP.C` and set-up the train accordingly. Also, selection of
	62	which tasks to include is done through the script `QAConfig.C`.
	63	That means this script should never be modified by the user.
	64	* `QAConfig.C`: Read by `QA.C` to configure which tasks to include
65	in the train.
66	* `Reconstruct.C`: Reconstruction steering script. Derived from
67	`rec.C` but modified to automatically get GRP parameters from OCDB
68	using the script `GRP.C` and set-up the job accordingly.
69	* `Run.jdl.in`: Skeleton for initial stage running.
70	* `simrun.sh`: Simulation shell script. Derived from basic `simrun.sh`
71	but adapted to the files here, allows passing the number of events
72	per job, pass the run number to relevant scripts, ignores
73	meaningless options.
74	* `Simulate.C`: Simulation steering script. Derived from `sim.C` but
75	modified to automatically get GRP parameters from OCDB using the
76	script `GRP.C` and set-up the job accordingly.
77	* `Tag.C`: Tag ESD files.
78	* `merge.sh`: Shell script to steer merging jobs. Used by both
79	QA and AOD filtering. This is based on `/alice/bin/train_merge.sh`
80	but modified to call either the QA or AOD train merging.
81
82	The shell script `doit.sh` is the omnipotent script that steers all
83	parts of the simulation.
84
85	## Usage of `doit.sh`
86
87	Usage: ./doit.sh [OPTIONS]
88
89	Options:
90	-h,--help This help
91	-t\|--tag TAG Job tag (pp)
92	-i\|--id NAME Name of production
93	-R\|--run RUN_NO Run number
94	-c\|--copy Copy files to AliEn
95	-n\|--jobs JOBS Set number of jobs[**] (2)
96	-m\|--events EVENTS Set events/job[**] (1)
97	-s\|--stage STAGE Set the stage[***] (0)
98	-o\|--output DIR Set base output directory[*] ($ALIEN_HOME/test)
99	-d\|--data DIR Set data directory ($ALIEN_HOME/mc)
100	-b\|--bin DIR Set base bin directory[*] ($ALIEN_HOME/bin)
101	-a\|--aliroot RELEASE Set AliROOT release [*] (v5-04-Rev-20)
102	-r\|--root RELEASE Set ROOT release [*] ()
103	-g\|--geant RELEASE Set GEANT3 release [*] ()
104
105	[*] Only make sense with option -c
106	[**] Only make sense for stage 0
107	[***] If stage is set to 6, try to deduce the stage
108	automatically. If less than zero, do not do anything but copy
109
110	Note, if the ROOT and GEANT release is not specified, it will be
111	deduced from the AliROOT version.
112
113	* Make JDLs and copy files to `/alice/cern.ch/user/a/aliprod/PWGLFforwardMC`,
114	specifying that output should be based in `/alice/sim/2014`, and we
115	should use AliROOT v5-05-Rev-11, but not submitting any jobs
116
117	./doit.sh -a v5-05-Rev-11 \
118	-d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
119	-o /alice/sim/2014 \
120	-c \
121	-s -1
122
123	* Submit 100 jobs each with 10 events for run 118506 with the same
124	parameters as above, using PhoJet
125
126	./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
127	-i LHC14z9a -r 118506 -s 0 -n 100 -m 10 -g PhoJet
128
129	Output will end up in `/alice/sim/2014/LHC14z9a/118506`
130
131	* Submit merging jobs for the above production
132
133	./doit.sh -d /alice/cern.ch/user/a/aliprod/PWGLFforwardMC \
134	-i LHC14z9a -r 118506 -s 6
135
136	Output will end up in `/alice/sim/2014/LHC14z9a/118506/`. Repeat
137	this until we hit the final merging.
138
139	## `Config.C`
140
141	The `Config.C` configuration script has been trimmed down
142	considerably. The script is now very generic since most settings are
143	derived from the GRP data. The only thing that remains to be selected
144	in this script is the event generator.
145
146	When selecting the event generator, a more versatile and configurable
147	approach has been taken. `Config.C` defines the class `Setup` with
148	the constructor `Setup::Setup(const char* genName)`. Here `genName`
149	is passed verbatim from the `Run.jdl` JDL file. The method
150	`Setup::MakeGenerator()` then internally has a switch on this string
151	to find the chosen event generator. If no suitable generator can be
152	found, the script will fail with a `Fatal` signal.
153
154	Generators are specified as
155
156	> _name_[_sub-type_[_sub-sub-type_]]
157
158	where _sub-type_ (and _sub-sub-type_) are optional. Currently defined
159	event generators are (case insensitive)
160
161	* `pythia` Pythia6 Min.Bias. Optional sub-types
162	* `perugia0` Perugia0 tune. Optional sub-sub-types
163	* `chadr` Heavy flavour charm w/hadronic decay signals added
164	* `bchadr` Heavy flavour beauty/charm w/hadronic decay signals added
165	* `cele` Heavy flavour charm signals added
166	* `bele` Heavy flavour beauty/charm signals added
167	* `jspi2e` J/Psi to electrons signals added
168	* `btojspi2e` Beauty to J/Psi to electrons signals added
169	* `D6T` Rick Field's CDF Tune D6T
170	* `atlas` Arthur Moraes' (new) ATLAS tune, possibly with
171	sub-sub-type
172	* `_flat` for flat multiplicity probability from 0 to 200
173	* `jets` Jets in central barrel
174	* `hijing` Hijing Min.Bias. Optional sub-types. For pPb and Pbp a
175	cocktail with slow neutrons is made
176	* `2000` No quenching and hard pT cut at 2.3GeV. Possible
177	sub-sub-types are
178	* `hf` Random heavy flavour signal added (see for pythia
179	above).
180	* `ampt` AMPT min bias. Possible sub types are
181	* `hf` Random heavy flavour signal added (see for pythia
182	above).
183	* `dpmjet`
184	* `phojet` Same as `dpmjet`
185	* `hydjet`
186
187	More generators can easily be added.
188
189
190	## JDL Parameters
191
192	### `Run.jdl`
193
194	* _run number_: The run number
195	* _n jobs_: Number of sub-jobs to commit
196	* _n events_: Number of events per sub-job
197	* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
198
199	### `Merge.jdl`
200
201	* _run number_: The run number
202	* _stage_: Stage number (1-4)
203	* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
204	* _what_: What to merge: either `AOD` or `QA`
205
206	### `Final.jdl`
207
208	* _run number_: The run number
209	* _stage_: Stage number (1-4)
210	* _tag_: The tag to put in produced files under (e.g., `LHC14z9a`)
211	* _what_: What to merge: either `AOD` or `QA`
212
213	## JDL Skeleton Substitutions
214
215	* _@out@_: The base of the output directory e.g., `/alice/sim/2014/`
216	* _@data@_: The directory where scripts, etc. are stored e.g.,
217	`/alice/cern.sh/user/a/aliprod/PWGLFforwardMC`
218	* _@aliroot@_: AliROOT version to use e.g., `v5-04-Rev-20`
219	* _@root@_: ROOT version to use e.g., `v5-34-08-6`
220	* _@geant@_: GEANT3 version to use e.g., `v1-15a-1`
221
222	## ROOT Script Prototypes
223
224	### `AOD.C(UInt_t run, const char* xmlfile, Int_t stage)`
225
226	* _run_: The run number
227	* _xmlfile_: Not used, compatibility with `QA.C`
228	* _stage_: Running stage (0: production, otherwise merge)
229
230	### `QA.C(UInt_t run, const char* xmlfile, Int_t stage)`
231
232	* _run_: The run number
233	* _xmlfile_: Current list of input files. Must not contain `Stage`
234	for final merging.
235	* _stage_: Running stage (0: production, otherwise merge)
236
237	### `GRP.C(UInt_t run)`
238
239	* _run_: The run number
240
241	### `Reconstruct.C(UInt_t run)`
242
243	* _run_: The run number
244
245	### `Simulate.C(UInt_t run, Int_t nev)`
246
247	* _run_: The run number
248	* _nev_: Number of events per sub-job
249
250	## Shell Script Arguments
251
252	### `run.sh`
253
254	All arguments are passed on to other script e.g., `simrun.sh`
255
256	### `simrun.sh`
257
258	* _--run_ RUN: The Run number
259	* _--event_ INTEGER: Number of events per sub-job
260	* _--process_ LABEL: The Event Generator to use. If not specified
261	or equal to `default` then select default EG based on collision
262	system.
263	* _--field_ VALUE: Ignored - obtained from OCDB
264	* _--energy_ VALUE: Ignored - obtained from OCDB
265	* _--physicslist_ VALUE: Ignored
266	* _--bmin_ FERMI: Least imapact parameter
267	* _--bmax_ FERMI: Largest imapact parameter
268	* _--pthardbin_ VALUE: Ignored
269	* _--quench_ VALUE: Quenching type to use
270	* _--sdd_: Ignored
271	* _--number-- INTEGER: Sub-job number
272	* _--qa__: Also run QA train
273	* _--aod_: Also run AOD train
274
275	### `merge.sh`
276
277	* _which_: What to do merging of (either `QA` or `AOD`)
278	* _run_: The run number
279	* _dir_: Directory where intermediate data can be found
280	* _stage_: Stage to execute
281
282
283	Local Variables:
284	mode: markdown
285	End:
286
287