Instructions to run MFT simulations [Wiki post]

Running MFT Simulations

This wiki post describes the basic steps to run MFT simulations, pointing to some relevant configuration options.

To execute simulations, ensure that you have O2 properly installed and configured. See “Install ALICE software directly with aliBuild (recommended option for O2 development)”.

1. Enter O2 environment

$ alienv enter O2/latest-dev-o2

2. Generate events and simulate detector

$ o2-sim -m MFT -e TGeant3 -g fwmugen -n 10

The simulation output is saved to o2sim.root. See bellow for additional generator options.

3. Convert simulated hits to detector digits

$ o2-sim-digitizer-workflow -b

This will generate mftdigits.root. To skip digitization of a detector, use --skipDet such as

$ o2-sim-digitizer-workflow -b --skipDet TPC,ITS,TOF,FT0,EMC,HMP,ZDC,TRD,MCH,MID,FDD,PHS,FV0,CPV

4. Run reconstruction workflow: clusterization and track reconstruction

The reconstruction worflow requires the cluster dictionary. See how to generate it on the next section .

$ ln -s ~/alice/MFTdictionary.bin

$ o2-mft-reco-workflow -b

This will save the mft clusters and mft tracks on mftclusters.root and mfttracks.root, respectively.

Configure Generators in O2

The above example employs the forward muon generator fwmugen, a simple and lightweight generator where each event contains a single muon. The full list of generators can be found here. Bellow a summary of possible generators.


fwmugen is a simple “box” generator for forward muons (1 muon / event)

o2-sim -m MFT -e TGeant3 -g fwmugen -n 10


o2-sim -m PIPE ITS MFT -e TGeant3 -g boxgen -n 10 --configKeyValues 'BoxGun.pdg=13 ; BoxGun.eta[0]=-3.6 ; BoxGun.eta[1]=-2.45; BoxGun.number=100'


Configures pythia8 for min.bias pp collisions at 14 TeV

o2-sim -m PIPE ITS MFT -g pythia8pp -n 50 

Configure vertexes positions with Interaction Diamond

This option will configure the dispersion of the vertex position distribution
See InteractionDiamond parameter source here.


Generate cluster topology dictionary: MFTdictionary.bin

ITS and MFT cluster topology dictionaries are interchangeable, but differ significantly on the cluster uncertainties. MFT cluster dictionary generation requires a considerably larger sample than ITS. It can be obtained by running a MFT simulation followed by O2 macro CheckTopologies.C. In this example, MFTdictionary.bin is created and copied to ~/alice/ for later use.

$ o2-sim -n 5000 -g pythia8pp -m PIPE MFT

$ o2-sim-digitizer-workflow -b

$ o2-mft-reco-workflow -b

$ root -l -q -b ~/alice/O2/Detectors/ITSMFT/MFT/macros/test/CheckTopologies.C+

$ cp MFTdictionary.bin ~/alice/

Extra: Produce AODs

To produce AODs an extensive simulation and reconstruction producing vertices is necessary. The complete workflow is available at AliceO2/ at dev · AliceO2Group/AliceO2 · GitHub.

This is really helpful, especially the Generators configuration paragraph (I had been looking how to set up a simulation using BoxGen). Maybe this could be added to the documentation in AliceO2/doc on Github?

Yes. In principle, the documentation is meant to be a collaborative document. Please feel free to make a pull request.

I was hesitating to do so as I didn’t write it myself. I can look into doing that if that is not an issue.


Thanks for your post. I’m a beginner in O2.
I just tried your instructions from a fresh O2 installation for developers in Catalina 10.15.3 and I got

[O2/latest-dev-o2] ~/cern/testO2/simulation %> o2-sim -m MFT -e TGeant3 -g fwmugen -n 10
dyld: Library not loaded: @rpath/libLLVMMCJIT.dylib
Referenced from: /Users/dy/cern/alice/sw/osx_x86-64/arrow/v0.14.1-1/lib/libgandiva.14.1.0.dylib
Reason: image not found
zsh: abort o2-sim -m MFT -e TGeant3 -g fwmugen -n 10

My installation was successful .

Also in lxplus I got

[O2/nightly-20200225-1] O2test > o2-sim -m MFT -e TGeant3 -g fwmugen -n 10

o2-sim: error while loading shared libraries: cannot open shared object file: No such file or directory

What could be the problem? Maybe I’m missing something. Thanks.

Kind Regards, Mario

Just for completeness. I used the same instructions for a very old O2 version (o2sim instead of o2-sim) and it worked.

[INFO] Macro finished succesfully.
[INFO] Real time 0.312591 s, CPU time 0.18s
[INFO] Memory used 313.578 MB
[INFO] Simulation process took 6.48187 s

Any hint is appreciated. Thanks

Concering the lxplus error with I believe this comes from an incompatibility of the build server environment (where glfw was installed as a system package) and the runtime server where you load the environment from cvmfs (glfw not installed).

@eulisse : I think this is a common recurring problem. How can we make sure that the cvmfs installation works everywhere? In principle we should avoid system packages as much as possible and build deeply for cvmfs.

We should ship our own glfw3, so the problem is somewhere else (cmake files / environment modules). I’ve it on my list, will try again.

I was following the wiki post and I was able to simulate data and reconstruct clusters and tracks. However, when producing the complete_dictionary.bin I get an error. But even with the error the dictionary is produced. Nevertheless, I thought I would report it here.

The error occurs in the third step:

o2-its-reco-workflow -b
[ERROR] Child 1977 had at least one message above severity ERROR: 
[13:06:36][ERROR] Cannot open the complete_dictionary.bin file, compact clusters cannot be produced

And in the fourth step I get just a warning:

root -l -q -b ~/alice/O2/Detectors/ITSMFT/ITS/macros/test/CheckTopologies.C+
Warning in <TROOT::Append>: Replacing existing TH1: mHdist (Potential memory leak).

I have O2 and QC updated on 24.2.2020.

In the one year old presentation

page 73 it is explained how to obtain the cluster dictionary. One has only to update the names of the

To complete the discussion from the meeting, these are the other (I thought outdated) instructions we used before. And I believe they are the same instructions as in the presentation from Bogdan.

o2-sim -n 50 -g pythia8 -m PIPE ITS 
ln -s ~/alice/O2/macro/run_clus_itsSA.C 
root -l -q -b run_clus_itsSA.C+ 
mv clr.root o2clus_its.root 
ln -s ~/alice/O2/Detectors/ITSMFT/ITS/macros/test/CheckTopologies.C 
root.exe -l -q -b CheckTopologies.C+   

And here the problem is segmentation violation error when trying to run root -l -q -b run_clus_itsSA.C+

@therman by default the macro assumes raw data input (e.g. converted using O2/macro/run_digi2raw_its.C from digits), to clusterize digits use:
root -b -q 'run_clus_itsSA.C+("itsdigits.root","itsclusters.root",false)'

Hi @therman, it seems the cluster dictionary can be generated from the cluster file created by the usual reconstruction workflow, even without the dictionary and the error message you pointed above does not prevent the creation of the cluster dictionary.

My O2 is not brand new, but I confirm that I get the same error as you pointed:
[ERROR] Cannot open the complete_dictionary.bin file, compact clusters cannot be produced
but the cluster file is generated anyway and the dictionary can be generated from it. I used the following sequence on a clean directory:

o2-sim -n 50 -g pythia8 -m PIPE ITS
o2-sim-digitizer-workflow -b
o2-its-reco-workflow -b
root.exe -l -q -b  ~/alice/O2/Detectors/ITSMFT/ITS/macros/test/CheckTopologies.C

Yes, in absence of the complete_dictionary.bin the clusters are created, even compact ones (if they are not suppressed with --no-compact-clusters) though instead of the pattern ID they will contain a dummy number. The [ERROR] Cannot open the complete_dictionary.bin file can be ignored.
Once the full clusters are created (either with the workflow or SA macro), the root.exe -l -q -b ~/alice/O2/Detectors/ITSMFT/ITS/macros/test/CheckTopologies.C+ allows to create the dictionary

Thank you for clarification. I am able to produce the dictionary both ways now.

Hello everyone,

I am also a bit new to O2 software and did not know if I should have started a new topic therefore, i am writing here.
I am currently working on the ITS3 performance studies, analyse charged particles and
have a rather banal question: is it possible to switch the magnetic field during the o2-sim simulation step? Or is it set to a fixed value (and if so, what is the value)?
It is not easy to find an answer to this on the page for me.


Hi @gskorodu ,
There are 5 options for the magnetic field: +-2,+-5 and 0, configurable by --field. One can find this information with o2-sim --help:

  --field arg (=-5)                     L3 field rounded to kGauss, allowed 
                                        values +-2,+-5 and 0
1 Like

Dear @pezzi ,

thank you for the reply, it helped quiet nicely!
May I ask another set of little questions at this point? (Or is it better to start a new topic?)
Another question which i have to address in my work is the interaction rate in the forward region including interactions induced by the beam pipe (e.g. Bremsstrahlung from the pipe).

(1) I have used hepmc file (STARlight) and propagated particles

o2-sim -j 10 -n 1000 -g hepmc -m PIPE ITS -o sim --configKeyValues “HepMC.fileName=starlight.hepmc; HepMC.version=2; Diamond.position[2]=0.1; Diamond.width[2]=0.05”.

If I then plot the spatial distribution of all interactions taking place (from o2sim_Kine.root) I see that there is a strict boundary at |z| < 3 m. Can this range be changed?

(2) Is the magnetic field global in the o2 simulation (i.e. reaching up to z = 3 m )? Can one set a local magnetic field (e.g. within |z| < 2 m, this could be helpful for ALICE3 studies)?

(3) Can the length of the beam pipe module ( -m PIPE ) be changed in the simulation? If I plot the 3D spatial distribution of the produced Bremsstrahlung photons at r < 1.6 cm (its3), I get a picture like this:

The ring is exactly the pipe with a width dz ~ 1 m. The scattering points are interactions at r < 1.55 cm.

I presume that there could be some kind of suitable --configKeyValues , but I could not find anything that would make sense.

Thank you in advance!
Best regards,

Hi @gskorodu , indeed it is preferable to start new topics for different subjects.
Anyway, the beampipe geometry is hard coded in O2, but is adapted according to the upgrade module called. See build_geometry.C . If one loads modules IT3 or TRK one gets different beam pipes.