README.md 6.49 KB
Newer Older
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
1
2
3
4
# ALICE Open Data Blender animation

## Project Description

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
5
This project has the purpose of generating 3D animations of ALICE particle collision events using data obtained from CERN's Open Data Portal. ALICE stands for "A Large Ion Collider Experiment" and it is a particle detector inside the LHC - Large Hadron Collider -, the world's largest and highest-energy particle collider, located beneath the France–Switzerland border. CERN stands for *Organisation européenne pour la recherche nucléaire*, which is French for European Organization for Nuclear Research, and it is the home of LHC. CERN's Open Data Portal is an open online platform that contains data files from particle physics; those include the ESDs - Event Summary Data files -, which hold information about ALICE events and are of great help making the animations look like real representations of such events.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
6
7
8
9

## How it all works

Before diving into how to run this project, it is important to develop some intuition on how the pieces all fit together to make the whole thing work out just right.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
10

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
11
The animation of a particle collision event is generated through 3D modeling software, which sets the position of all the particles at any given time - until the animation is over - with the help of their respective mass, charge and initial linear momentum values, plus the value of the magnetic field and the collision vertex, a spot from which we consider all the particles originate.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
12

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
13
All this information must be obtained from somewhere - that somewhere is the above-mentioned ESD files, which contain data about several events each. The ESDs come in a *.root* extension and may only be interpreted by ROOT, CERN's official software for particle physics analysis. This is done through C++ code, which is written in order to specifically refer to the ESD desired data, in accordance with the available libraries, and run by ROOT to export this data to textual format. That is why the download of Aliroot, ROOT's version for ALICE events analysis, is required.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
14

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
15
The text files containing all the physics data are then read by the Python scripts responsible for generating the animation, completing the procedure.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
16

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
17
18
19
20
21
The whole process is a lot more user-friendly than it may seem at first glance; except for installing a couple of programs - ROOT and Blender -, the only thing left for the user to do is run a line of code from the terminal, which executes a script that automatizes everything from running ROOT to rendering and saving every animation *.mp4* file. The final result is a directory inside of which is a series of animation clips, each one corresponding to a different event in the chosen ESD file.

## Laying the groundwork

This project was developed in Ubuntu 18.04 version of Linux, therefore this is the recommended OS for running it.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
22

23
ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE, and they should be somehow referenced along the process, as explained further.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
24

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
25
The software used for animating events is Blender, which is free and open source. Blender's 2.79b version should be downloaded for this project, and can be found on https://www.blender.org/download/releases/2-79/
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
26
27
28
29
30
31
32
33
34
35

Before starting, you must also clone this repository:
```bash
mkdir -p ~/alice
cd ~/alice
git clone https://git.cta.if.ufrgs.br/ALICE-open-data/alice-blender-animation.git
```

The animation making can be summarized in three basic steps:

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
36
1) Installing Aliroot;
37
2) Getting an ESD file;
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
38
3) Running script to process ESD data and generate Blender animations using its results.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
39
40
41

In case you are not conCERNed about the data being used for the animation and only wish to generate a standard one, skip to the Default Animation section below. For detailed steps on how to make the animation from ESDs, as described above, read the following sections.

42
## Step 1 - Installing aliRoot
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
43

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
44
Here is the sequence of steps for installing Aliroot, CERN's official software for ALICE physics analysis, so you are able to process the relevant information for the project.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

1) Install aliBuild. Follow instructions on https://alice-doc.github.io/alice-analysis-tutorial/building/custom.html

2) Initialize AliPhysics

```bash
cd ~/alice
aliBuild init AliPhysics@master
```
3) Verify dependencies (Optional)

```bash
$ aliDoctor AliPhysics
```
4) Build AliPhysics with aliroot5 (this may take a long time)
```bash
aliBuild build AliPhysics --defaults user -z aliroot5
```

64
## Step 2 - Getting an ESD file
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
65

66
ESD files regarding the ALICE experiment can be found on http://opendata.cern.ch/search?page=1&size=20&experiment=ALICE. If you have doubts on which file to pick for a test, you can select any file on this list: http://opendata.cern.ch/record/1102.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
67

68
Here, there are two options from which you can choose:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
69

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
70
### Manual Download
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
71
Manually download your ESD file and save it in the `alice-blender-animation` directory, which was cloned from the git repository. Make sure you save it on the same path as this `README.md` file and the `workflow_sketch.sh` script, not inside the "aliRoot" or "animate" directories. Also make sure the file is named `AliESDs.root`.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
72

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
73
74
### Automatic Download
Have your ESD be downloaded automatically; just copy the URL for the chosen ESD file (the address you would access to download it) so you can paste it on the command line when you run the script that generates the animation, according to the next section.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
75

76
## Step 3 - Generating animation
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
77

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
78
Once you are all set, all there is left to do is run the `workflow_sketch.sh` script through your terminal. This script offers several options regarding parameters such as animation time duration and resolution. For more information, run it as
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
79
80

```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
81
./workflow_sketch.sh --help
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
82
83
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
84
Standard values to all these parameters are set so the minimum code required is simply
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
85

86
```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
87
./workflow_sketch.sh
88
89
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
90
If you have chosen the automatic ESD download option above, the code becomes
91
92

```bash
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
93
./workflow_sketch.sh --url <URL> --download
94
95
```

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
96
where ``<URL>`` is the copied ESD URL.
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
97

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
98
After running the script, it may take a long time to generate all the animations, but as soon as it is done, they will be available inside a new directory uniquely identified according to the chosen ESD file. Each clip is also identified by event number. Enjoy!
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
99
100
101
102


# Default Animation

103
For generating a default animation, simply run the script `workflow_sketch.sh` in your terminal as below:
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
104
105

```bash
106
./workflow_sketch.sh -a
Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
107
```
108

Breno Rilho Lemos's avatar
Breno Rilho Lemos committed
109
After this, a single default animation should be ready. It will be available inside the `blender` directory, in *.mp4* format. Enjoy!