Skip to content

Commit 595bdb7

Browse files
vkuceravkucera
committed
Add glossary
1 parent 3bcae91 commit 595bdb7

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎docs/glossary/README.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
sort: 11
3+
title: Glossary
4+
---
5+
6+
# Glossary
7+
8+
```warning
9+
Work in progress. Help wanted.
10+
```
11+
12+
## General
13+
14+
O<sup>2</sup> <a id="o2" />
15+
: acronym which stands for "online–offline" which refers to the online and offline reconstruction
16+
17+
DPL <a id="dpl" />
18+
: Data Processing Layer
19+
: core [O<sup>2</sup>](#o2) framework for data processing, built on top of [FairMQ](https://helmholtz.software/software/fairmq)
20+
21+
Arrow <a id="arrow" />
22+
: the [Apache Arrow](https://arrow.apache.org/) format in which [tables](#table) are processed in [O<sup>2</sup>](#o2)
23+
24+
JSON <a id="json" />
25+
: format used for [configuration](#configurable) of [devices](#device)
26+
27+
## Data reconstruction
28+
29+
timeframe, TF <a id="timeframe" />
30+
: snapshot of detector data over a given time window
31+
32+
dataframe, DF <a id="dataframe" />
33+
: self-contained unit of processing
34+
35+
FLP <a id="flp" />
36+
: First Level Processor
37+
38+
EPN <a id="epn" />
39+
: Event Processing Node
40+
41+
PDP <a id="pdp" />
42+
: Physics Data Processing
43+
44+
particle collision <a id="particle-collision" />
45+
: interaction of energetic particles (real or simulated).
46+
Simulated particle collisions are stored in the `McCollisions` [table](#table).
47+
Simulated particles are stored in the `McParticles` table.
48+
49+
reconstructed collision <a id="reconstructed-collision" />
50+
: primary vertex reconstructed from an observed activity in the detector suspected to be associated with a [particle collision](#particle-collision).
51+
Reconstructed collision are stored in the `Collisions` [table](#table).
52+
Reconstructed charged particles are stored in the `Tracks` table.
53+
54+
## Data structures
55+
56+
AO2D <a id="ao2d" />
57+
: format of saving [tables](#table) in ROOT files (typically called `AO2D.root`)
58+
59+
table <a id="table" />
60+
: data format storing a collection of columns for each entry (table row).
61+
Rows represent objects of the given table type and columns represent properties of these objects.
62+
A table definition defines a C++ type and therefore must be unique.
63+
Declared with the `DECLARE_SOA_TABLE(...)` macros.
64+
Stored in [AO2D](#ao2d) as `TTree`.
65+
66+
## Data processing
67+
68+
task <a id="task" />
69+
: C++ `struct` which can process and produce [tables](#table) and produce other output (e.g. histograms).
70+
A task is executed as a [device](#device) of a [workflow](#workflow).
71+
72+
configurable <a id="configurable" />
73+
: [task](#task) parameter, whose value can be set without editing the code of the task.
74+
Implemented as a task member of type `Configurable(...)`.
75+
Can be set via [JSON](#json) configuration.
76+
77+
process function <a id="process-function" />
78+
: [task](#task) method, which subscribes to [tables](#table) (i.e. consumes them as input) and performs some operations with their content (e.g. fills output tables or histograms).
79+
80+
process function switch <a id="process-function-switch" />
81+
: `PROCESS_SWITCH` macro which defines a [configurable](#configurable) which allows to enable and disable the execution of a given [process function](#process-function).
82+
83+
device (DPL device) <a id="device" />
84+
: execution sub-unit of a [workflow](#workflow).
85+
Implemented as a [task](#task).
86+
Can be configured via [configurables](#configurable).
87+
The device name is generated from the task name, unless it is provided explicitly, using `TaskName("device-name")` as an argument of `adaptAnalysisTask`.
88+
89+
workflow (DPL workflow) <a id="workflow" />
90+
: execution unit in [DPL](#dpl), consisting of one or several [devices](#device).
91+
Implemented as a C++ `.cxx` file, compiled into a single executable binary file.
92+
The workflow name is generated from the arguments of the `o2physics_add_dpl_workflow` function in the `CMakeLists.txt` file.
93+
For workflows files located in `PWG..` directories, a corresponding prefix is added: `o2-<component>-[<pwg>-]<name>`.
94+
: Example: `o2-analysis-hf-task-d0`
95+
96+
- `<component>` is `analysis`, derived from `COMPONENT_NAME Analysis`,
97+
- `<pwg>` is `hf`, derived from the `PWGHF` directory name,
98+
- `<name>` is `task-d0`, provided in `o2physics_add_dpl_workflow(task-d0`.
99+
100+
workflow topology <a id="workflow-topology" />
101+
: the connection between running [workflows](#workflow), based on their [inputs](#table) and outputs
102+
103+
## Table content
104+
105+
static column <a id="static-column" />
106+
: [table](#table) column which stores a value provided when it is filled.
107+
Declared with the `DECLARE_SOA_COLUMN(...)` macros.
108+
: Example: The `Collisions` table of collisions has a static column `PosZ` which stores the value of the _z_ coordinate of the primary vertex.
109+
The value has to be provided when a new collision row is being added in the table.
110+
111+
dynamic column <a id="dynamic-column" />
112+
: [table](#table) column which behaves as a function of other (static or expression) columns of the same table.
113+
Declared with the `DECLARE_SOA_DYNAMIC_COLUMN(...)` macros.
114+
The value is calculated only when the [column getter](#column-getter) is called.
115+
: Dynamic column definitions can have free parameters, which have to be provided as arguments of the getter.
116+
Values of dynamic columns are not written in [AO2D](#ao2d) files and cannot be used for table [filtering](#filter).
117+
Additional dynamic columns can be attached to a table inside a [process function](#process-function) with `Attach`.
118+
: Example: The `Tracks` table of tracks has a dynamic column `Px`, representing the _x_ component of the track momentum, defined as a function of other static columns.
119+
It's value is calculated every time the corresponding `px` getter is called.
120+
121+
expression column <a id="expression-column" />
122+
: [table](#table) column which stores a value which is calculated by evaluating an expression when the table is written.
123+
Declared with the `DECLARE_SOA_EXPRESSION_COLUMN(...)` macros.
124+
Values of expression columns are written in [AO2D](#ao2d) files and can be used for table [filtering](#filter).
125+
: Additional expression columns can be attached to a table inside a [process function](#process-function) with `Extend`.
126+
: Example: The `Tracks` table of tracks has an expression column `Phi`, representing the azimuth of the track momentum, defined as a function of other static columns.
127+
All values of the `Phi` column are calculated for all tracks together (in bulk) when the `Tracks` table is written in the [AO2D](#ao2d) file.
128+
129+
index column <a id="index-column" />
130+
: [table](#table) column which stores the index of a table row.
131+
Declared with the `DECLARE_SOA_INDEX_COLUMN(...)` macros.
132+
: Example: The `Tracks` table of tracks has an index column pointing to rows of the `Collisions` table, which links each track to its collision.
133+
Calling the `collision` getter returns an iterator pointing to a given collision.
134+
Calling the `collisionId` getter returns the value of the index itself (i.e. the position of the row in the `Collisions` table).
135+
136+
column getter <a id="column-getter" />
137+
: method that returns the value stored in the column.
138+
: Example: The value of the transverse momentum of a given `track` in the `Tracks` table is stored in the `Pt` column.
139+
This value can be obtained by calling the corresponding `pt` getter as `track.pt()`.
140+
141+
data model <a id="data-model" />
142+
: collection of [table](#table) definitions.
143+
Defined in header files in [`DataModel`](../gettingstarted/theo2physicsrepo.md#folder-structure) directories.
144+
145+
extended table <a id="extended-table" />
146+
: [table](#table) consisting of [expression columns](#expression-column) which extends another table.
147+
Declared with the `DECLARE_SOA_EXTENDED_TABLE(...)` macros.
148+
149+
index table <a id="index-table" />
150+
: [table](#table) consisting of [index columns](#index-column).
151+
Declared with the `DECLARE_SOA_INDEX_TABLE(...)` macros.
152+
153+
## Table production
154+
155+
`Produces` <a id="produces" />
156+
: A `Produces<...>` [task](#task) member defines a [table](#table) cursor which creates a new table row when called.
157+
158+
`Spawns` <a id="spawns" />
159+
: A `Spawns<...>` [task](#task) member defines a handle to an [extended table](#extended-table).
160+
The extended table is created before the execution of the [process functions](#process-function).
161+
162+
`Builds` <a id="builds" />
163+
: A `Builds<...>` [task](#task) member defines a handle to an [index table](#index-table).
164+
The index table is created before the execution of the [process functions](#process-function).
165+
166+
## Table manipulation
167+
168+
`Join` <a id="join" />
169+
: Declaration of a `Join<...>` object defines a [table](#table) view which joins columns of matching rows in multiple tables of the same length.
170+
171+
grouping <a id="grouping" />
172+
: Subscription to the iterator of a [table](#table) defines a loop over that table where the rows of other tables are grouped by the index of the iterated table.
173+
For each iteration only the subset of the other tables linked to the given iterator (via the [index column](#index-column)) is available.
174+
175+
`SmallGroups` <a id="small-groups" />
176+
: TODO
177+
178+
`Filter` <a id="filter" />
179+
: Definition of a `Filter` [task](#task) member applies the corresponding condition to all compatible [tables](#table) subscribed using `Filtered<...>`.
180+
Only the filtered subsets of the tables are available.
181+
: Filter definitions can reference [configurables](#configurable).
182+
Filter definitions cannot reference [dynamic columns](#dynamic-column).
183+
Filter definitions can contain conditional expressions with `ifnode`.
184+
: Filtered tables can be [grouped](#grouping).
185+
Filtered tables can be created inside [process functions](#process-function) with `select`.
186+
187+
`Partition` <a id="partition" />
188+
: Definition of a `Partition<...>` [task](#task) member creates a [table](#table) view for a subset of a table according to the corresponding condition.
189+
: Multiple partitions of the same table can co-exist together with the full table.
190+
Partitions can be [filtered](#filter).
191+
Partitions cannot be [grouped](#grouping) and have to be [sliced](#slicing) instead.
192+
Partitions can be created inside [process functions](#process-function).
193+
194+
slicing <a id="slicing" />
195+
: A [partition](#partition) slice corresponding to a given value of a given [index column](#index-column) can be created using the `sliceBy(...)` methods of the partition.
196+
197+
`Preslice` <a id="preslice" />
198+
: TODO
199+
200+
## AliHyperloop
201+
202+
wagon <a id="wagon" />
203+
: instance of a [workflow](#workflow) on AliHyperloop, defined by its dependencies, [configuration](#configurable) of [devices](#device) and [outputs](#derived-data)
204+
205+
train <a id="train" />
206+
: collection of [wagons](#wagon) executed on AliHyperloop
207+
208+
derived data <a id="derived-data" />
209+
: [AO2D](#ao2d) file with [tables](#table) produced as a result of processing another [AO2D](#ao2d) file (parent)
210+
211+
linked derived data <a id="linked-derived-data" />
212+
: [derived data](#derived-data) containing [tables](#table) with [index columns](#index-column) pointing to tables in its parent files.
213+
Processing of linked derived data requires access to the parent files.
214+
215+
self-contained derived data <a id="self-contained-derived-data" />
216+
: [derived data](#derived-data) containing [tables](#table) without [index columns](#index-column) pointing to tables in other files.

0 commit comments

Comments
 (0)