You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The general idea is to run the same analysis using AliPhysics and O<sup>2</sup>(Physics) and produce comparison plots.
11
31
32
+
However, it can be used without AliPhysics as well to run O<sup>2</sup> analyses locally, similar to running trains on AliHyperloop.
33
+
This makes it a convenient framework for local development, testing and debugging of O<sup>2</sup>(Physics) code.
34
+
12
35
## Overview
13
36
14
37
The validation framework is a general configurable platform that gives user the full control over what is done.
15
-
Its flexibility is enabled by strict separation of its specialised components into a system of bash scripts.
38
+
Its flexibility is enabled by strict separation of its specialised components into a system of Bash scripts.
16
39
Configuration is separate from execution code, input configuration is separate from task configuration, execution steps are separate from the main steering code.
17
40
18
41
* The steering script [`runtest.sh`](exec/runtest.sh) provides control parameters and interface to the machinery for task execution.
19
-
* User provides configuration bash scripts which:
42
+
* User provides configuration Bash scripts which:
20
43
* modify control parameters,
21
44
* produce modified configuration files,
22
45
* generate step scripts executed by the framework in the validation steps.
23
46
24
-
###Execution
47
+
## Execution
25
48
26
49
Execution code can be found in the [`exec`](exec) directory.
27
50
51
+
**The user should not touch anything in this directory!**
52
+
28
53
The steering script [`runtest.sh`](exec/runtest.sh) performs the following execution steps:
54
+
29
55
* Load input specification.
30
56
* Load tasks configuration.
31
57
* Print out input description.
32
58
* Clean before running. (activated by `DOCLEAN=1`)
33
-
* Deletes specified files.
59
+
* Deletes specified files (produced by previous runs).
34
60
* Generate list of input files.
35
61
* Modify the JSON file.
36
62
* Convert `AliESDs.root` to `AO2D.root`. (activated by `DOCONVERT=1`)
@@ -51,46 +77,107 @@ The steering script [`runtest.sh`](exec/runtest.sh) performs the following execu
51
77
* Executes the postprocessing step script.
52
78
* This step typically compares AliPhysics and O<sup>2</sup> output and produces plots.
53
79
* Clean after running. (activated by `DOCLEAN=1`)
54
-
* Deletes specified files.
80
+
* Deletes specified (temporary) files.
55
81
* Done
56
82
* This step is just a visual confirmation that all steps have finished without errors.
57
83
58
84
All steps are activated by default and some can be disabled individually by setting the respective activation variables to `0` in user's task configuration.
59
85
60
-
###Configuration
86
+
## Configuration
61
87
62
88
The steering script [`runtest.sh`](exec/runtest.sh) can be executed with the following optional arguments:
`<input-configuration>` Input specification script. See [Input specification](#input-specification).
69
95
70
-
`-d` (Debug mode) Prints out more information about settings and execution.
71
-
72
-
`<input config>` Input specification
73
-
* Bash script that modifies input parameters.
74
-
* This script defines which data will be processed.
75
96
* Defaults to `config_input.sh` (in the current directory).
76
97
77
-
`<task config>` Task configuration
78
-
* Bash script that cleans the directory, deactivates steps, modifies the JSON file, generates step scripts.
79
-
* This script defines what the validation steps will do.
98
+
`<task-configuration>` Task configuration script. See [Task configuration](#task-configuration).
99
+
80
100
* Defaults to `config_tasks.sh` (in the current directory).
81
-
* Provides these mandatory functions:
82
-
*`Clean` Performs cleanup before and after running.
83
-
*`AdjustJson` Modifies the JSON file. (e.g. selection cut activation)
84
-
*`MakeScriptAli` Generates the AliPhysics step script.
85
-
*`MakeScriptO2` Generates the O<sup>2</sup> step script.
86
-
*`MakeScriptPostprocess` Generates the postprocessing step script. (e.g. plotting)
87
-
* The `Clean` function takes one argument: `$1=1` before running, `$1=2` after running.
88
-
* The AliPhysics and O<sup>2</sup> step scripts take two arguments: `$1="<input file>"`, `$2="<JSON file>"`.
89
-
* The postprocessing step script takes two arguments: `$1="<O2 output file>"`, `$2="<AliPhysics output file>"`.
90
101
91
-
Implementation of these configuration scripts is fully up to the user.
102
+
`-d` Debug mode. Prints out more information about settings and execution.
103
+
104
+
`-h` Help. Prints out the usage specification above.
105
+
106
+
### Input specification
107
+
108
+
The input specification script is a Bash script that sets input parameters used by the steering script.
109
+
110
+
**This script defines which data will be processed and how.**
111
+
112
+
These are the available input parameters and their default values:
113
+
114
+
*`INPUT_LABEL="nothing"` Input description
115
+
*`INPUT_DIR="$PWD"` Input directory
116
+
*`INPUT_FILES="AliESDs.root"` Input file pattern
117
+
*`INPUT_SYS="pp"` Collision system (`"pp"`, `"PbPb"`)
118
+
*`INPUT_RUN=2` LHC Run (2, 3, 5)
119
+
*`INPUT_IS_O2=0` Input files are in O<sup>2</sup> format.
120
+
*`INPUT_IS_MC=0` Input files are MC data.
121
+
*`INPUT_PARENT_MASK=""` Path replacement mask for the input directory of parent files in case of linked derived O<sup>2</sup> input. Set to `";"` if no replacement needed.
This allows you to define several input datasets and switch between them easily by setting the corresponding value of `INPUT_CASE`.
125
+
126
+
Other available parameters allow you to specify how many input files to process and how to parallelise the job execution.
127
+
128
+
### Task configuration
92
129
93
-
Dummy examples can be found in: [`config/config_input_dummy.sh`](config/config_input_dummy.sh), [`config/config_tasks_dummy.sh`](config/config_tasks_dummy.sh).
130
+
The task configuration script is a Bash script that modifies the task parameters used by the steering script.
131
+
132
+
**This script defines which validation steps will run and what they will do.**
133
+
134
+
* It cleans the directory, deactivates incompatible steps, modifies the JSON file, generates step scripts.
135
+
* The body of the script has to provide these mandatory functions:
136
+
*`Clean` Performs cleanup before and after running.
137
+
*`AdjustJson` Modifies the JSON file (e.g. selection cut activation).
138
+
*`MakeScriptAli` Generates the AliPhysics step script `script_ali.sh`.
139
+
*`MakeScriptO2` Generates the O<sup>2</sup> step script `script_o2.sh`.
140
+
*`MakeScriptPostprocess` Generates the postprocessing step script `script_postprocess.sh` (e.g. plotting).
141
+
* The `Clean` function takes one argument: `$1=1` for cleaning before running, `$1=2` for cleaning after running.
142
+
* The AliPhysics and O<sup>2</sup> step scripts take two arguments: `$1="<input-file>"`, `$2="<JSON-file>"`.
143
+
* The postprocessing step script takes two arguments: `$1="<O2-output-file>"`, `$2="<AliPhysics-output-file>"`.
144
+
145
+
Configuration that should be defined in the task configuration includes:
146
+
147
+
* Deactivation of the validation steps (`DOCLEAN`, `DOCONVERT`, `DOALI`, `DOO2`, `DOPOSTPROCESS`)
148
+
* Customisation of the commands loading the AliPhysics, O2Physics and postprocessing environments (`ENV_ALI`, `ENV_O2`, `ENV_POST`). By default the latest builds of AliPhysics, O2Physics and ROOT are used, respectively.
149
+
* Any other parameters related to "what should run and how", e.g. `SAVETREES`, `MAKE_GRAPH`, `USEALIEVCUTS`
150
+
151
+
### Workflow specification
152
+
153
+
The full O<sup>2</sup> command, executed in the O<sup>2</sup> step script to run the activated O<sup>2</sup> workflows, is generated in the `MakeScriptO2` function using a dedicated Python script [`make_command_o2.py`](exec/make_command_o2.py).
154
+
This script generates the command using a **YAML database (`workflows.yml`) that specifies workflow options and how workflows depend on each other**.
155
+
You can consider a workflow specification in this database to be the equivalent of a wagon definition on AliHyperloop, including the definition of the wagon name, the workflow name, the dependencies and the derived data. The main difference is that the device configuration is stored in the JSON file.
156
+
157
+
The workflow database has two sections: `options` and `workflows`.
158
+
The `options` section defines `global` options, used once at the end of the command, and `local` options, used for every workflow.
159
+
The `workflows` section contains the "wagon" definitions.
160
+
The available parameters are:
161
+
162
+
*`executable` Workflow command, if different from the "wagon" name
163
+
* This allows you to define multiple wagons for the same workflow.
164
+
*`dependencies`**Direct** dependencies (i.e. other wagons **directly** needed to run this wagon)
165
+
* Allowed formats: string, list of strings
166
+
* Direct dependencies are wagons that produce tables consumed by this wagon. You can figure them out using the [`find_dependencies.py`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/find_dependencies.py) script in O2Physics.
167
+
*`requires_mc` Boolean parameter to specify whether the workflow can only run on MC
168
+
*`options` Command line options. (Currently not supported on AliHyperloop.)
169
+
* Allowed formats: string, list of strings, dictionary with keys `default`, `real`, `mc`
170
+
*`tables` Descriptions of output tables to be saved as trees
171
+
* Allowed formats: string, list of strings, dictionary with keys `default`, `real`, `mc`
172
+
173
+
The `make_command_o2.py` script allows you to generate a topology graph to visualise the dependencies defined in the database, using [Graphviz](https://graphviz.org/).
174
+
Generation of the topology graph can be conveniently enabled with `MAKE_GRAPH=1` in the task configuration.
175
+
176
+
Dummy examples of the configuration files can be found in:
Do not load ROOT, AliPhysics, O<sup>2</sup>, O<sup>2</sup>Physics or any other aliBuild package environment before running the framework!**
141
228
142
229
Enter any directory and execute the steering script `runtest.sh`.
@@ -156,12 +243,25 @@ If any step fails, the script will display an error message and you should look
156
243
157
244
If the main log file of a validation step mentions "parallel: This job failed:", inspect the respective log file in the directory of the corresponding job.
158
245
246
+
## How to add a new workflow
247
+
248
+
To add a new workflow in the framework configuration, you need to follow these steps.
249
+
250
+
* Add the workflow in the [task configuration](#task-configuration):
251
+
* Add the activation switch: `DOO2_...=0 # name of the workflow (without o2-analysis)`.
252
+
* Add the application of the switch in the `MakeScriptO2` function: `[ $DOO2_... -eq 1 ] && WORKFLOWS+=" o2-analysis-..."`.
253
+
* If needed, add lines in the `AdjustJson` function to modify the JSON configuration.
254
+
* Add the [workflow specification](#workflow-specification) in the workflow database:
255
+
* See the dummy example `o2-analysis-workflow` for the full list of options.
256
+
* Add the device configuration in the default JSON file.
257
+
159
258
## Job debugging
160
259
161
260
If you run many parallelised jobs and some of them don't finish successfully, you can make use of the debugging script [`debug.sh`](exec/debug.sh) in the [`exec`](exec) directory
162
261
which can help you figure out what went wrong, where and why.
163
262
164
263
You can execute the script from the current working directory using the following syntax (options can be combined):
JSONRUN3="dpl-config_run3.json"# Run 3 tasks parameters
20
-
# Run 5 tasks parameters for open HF study
21
-
JSONRUN5_HF="dpl-config_run5_hf.json"
22
-
# Run 5 tasks parameters for onia studies:
23
-
# J/psi and X (higher pt cut on 2-prong decay tracks and no DCA cut on single track)
24
-
JSONRUN5_ONIAX="dpl-config_run5_oniaX.json"
25
-
JSON="$JSONRUN3"
26
-
27
19
# Default settings:
28
-
# INPUT_FILES="AliESDs.root"
29
-
# INPUT_SYS="pp"
30
-
# INPUT_RUN=2
31
-
# INPUT_IS_O2=0
32
-
# INPUT_IS_MC=0
33
-
# JSON="$JSONRUN3"
20
+
# INPUT_LABEL="nothing" # Input description
21
+
# INPUT_DIR="$PWD" # Input directory
22
+
# INPUT_FILES="AliESDs.root" # Input file pattern
23
+
# INPUT_SYS="pp" # Collision system ("pp", "PbPb")
24
+
# INPUT_RUN=2 # LHC Run (2, 3, 5)
25
+
# INPUT_IS_O2=0 # Input files are in O2 format.
26
+
# INPUT_IS_MC=0 # Input files are MC data.
27
+
# INPUT_PARENT_MASK="" # Path replacement mask for the input directory of parent files in case of linked derived O2 input. Set to ";" if no replacement needed.
0 commit comments