Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShipSoft/FairShip/llms.txt

Use this file to discover all available pages before exploring further.

The fastest way to get familiar with FairShip is to run the standard three-step chain: simulation with run_simScript.py, reconstruction with ShipReco.py, and analysis with ShipAna.py. Each step reads the outputs of the previous one, and all three scripts live under $FAIRSHIP/macro/. The examples below use the --tag option to give output files a human-readable name instead of the default UUID identifier — ideal for interactive exploration.

​
Output File Naming Convention

Before running anything, it helps to understand how FairShip names its output files. The simulation step produces three ROOT files for each run:
File patternContents
sim_{identifier}.rootMCTrack tree (cbmsim) with simulated hits and MC truth
geo_{identifier}.rootFull detector geometry exported from TGeoManager
params_{identifier}.rootFairRoot runtime parameter database
The {identifier} is either a UUID generated automatically, or the value you pass with --tag. ShipReco.py reads the sim and geo files and writes a separate sim_{identifier}_rec.root containing only digitisation and reconstruction branches — the original simulation file is never modified. ShipAna.py then attaches the reconstruction file as a ROOT friend tree on the cbmsim tree, giving it simultaneous access to MC truth and reconstructed data.

​
The Standard Simulation → Reconstruction → Analysis Chain

1

Set up your environment

Choose the environment that matches your installation method:
Inside the FairShip clone, prefix every command with pixi run, or start a shell once:
cd FairShip
pixi shell
The activate.sh script automatically sets FAIRSHIP, GEOMPATH, PYTHONPATH, and LD_LIBRARY_PATH when the environment is activated.
2

Run the simulation

The simulation macro runs Pythia-based event generation followed by full Geant4 transport through the SHiP detector geometry. The default configuration simulates HNL signal events.
pixi run python macro/run_simScript.py --tag my-simulation
When the macro finishes you will see:
Macro finished successfully.
Output file is  sim_my-simulation.root
Geometry file is geo_my-simulation.root
Outputs:
  • sim_my-simulation.root — MC truth and hit data
  • geo_my-simulation.root — exported detector geometry
  • params_my-simulation.root — FairRoot parameter database
Pythia8 is the default generator back-end. Pass --Pythia6 to use Pythia6 instead, --EvtGenDecayer to enable TEvtGenDecayer for J/ψ and quarkonium decays, or the PG sub-command to run with a particle gun. Run with --help to see all options.
3

Run reconstruction

ShipReco.py performs hit digitisation, pattern recognition, and track fitting with GenFit. It reads the simulation and geometry files and writes a separate reconstruction file.
pixi run python macro/ShipReco.py -f sim_my-simulation.root -g geo_my-simulation.root
Successful completion prints:
finished writing tree
Exit normally
Output:
  • sim_my-simulation_rec.root — digitisation and reconstruction branches only; the original sim_my-simulation.root is untouched.
4

Run analysis

ShipAna.py opens the MC simulation file, attaches the reconstruction file as a friend tree (ship_reco_sim), and produces a set of diagnostic histograms and plots.
pixi run python -i macro/ShipAna.py \
  -f sim_my-simulation.root \
  -r sim_my-simulation_rec.root \
  -g geo_my-simulation.root
The -i flag keeps Python interactive after the script finishes, letting you inspect histograms in the ROOT session. Successful completion prints:
finished making plots
Exit normally
If you omit -r, ShipAna.py automatically looks for a file named sim_my-simulation_rec.root in the current directory. If the input file already has the _rec suffix it is used directly and the script derives the MC file name by stripping _rec.

​
Complete Command Reference

All steps together, for quick copying: 
# Step 1 — Simulation
pixi run python macro/run_simScript.py --tag my-simulation
# Outputs: sim_my-simulation.root  geo_my-simulation.root  params_my-simulation.root

# Step 2 — Reconstruction
pixi run python macro/ShipReco.py \
  -f sim_my-simulation.root \
  -g geo_my-simulation.root
# Output: sim_my-simulation_rec.root

# Step 3 — Analysis
pixi run python -i macro/ShipAna.py \
  -f sim_my-simulation.root \
  -r sim_my-simulation_rec.root \
  -g geo_my-simulation.root

​
EventCalc Signal Workflow

EventCalc is a dedicated tool for importing pre-generated signal event samples (for example, HNL decay kinematics computed externally) into the FairShip simulation chain. The workflow has two steps: first convert the input .dat file into a ROOT file, then run the standard simulation macro in EventCalc mode.
1

Convert the EventCalc input file

python $FAIRSHIP/macro/convertEvtCalc.py -f test_input.dat -o test_folder
This creates test_folder/test_input.root, a ROOT file containing the particle-level event records from the EventCalc generator.
2

Run the simulation in EventCalc mode

python $FAIRSHIP/macro/run_simScript.py \
  --evtcalc \
  -n 1 \
  -o test_folder \
  -f test_folder/test_input.root
The --evtcalc flag switches the generator back-end to EventCalc mode, -n limits the number of events (useful for quick checks), and -o sets the output directory.

​
Event Display

The interactive event display visualises simulated hits, reconstructed tracks, and the detector geometry simultaneously. It is useful for sanity-checking individual events after the reco step. 
python -i $FAIRSHIP/macro/eventDisplay.py \
  -f sim_my-simulation.root \
  -r sim_my-simulation_rec.root \
  -g geo_my-simulation.root
This opens the SHiP Event Display GUI. Navigate between events using the GUI controls. Exit with quit() or Ctrl-D.
The event display requires a graphical session (X11 or Wayland forwarding). On lxplus, connect with ssh -X or ssh -Y. Inside a Docker container, pass -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix to docker run.

​
Analysis Toolkit

For more structured pre-selection studies, FairShip includes an experimental analysis_toolkit module. An annotated example script is provided at $FAIRSHIP/examples/analysis_example.py and can be run after the reco step: 
python $FAIRSHIP/examples/analysis_example.py \
  -f sim_my-simulation.root \
  -r sim_my-simulation_rec.root \
  -g geo_my-simulation.root
The toolkit provides helper classes for applying fiducial cuts, looping over reconstructed vertices, and filling histograms in a consistent way across different signal hypotheses.

​
Next Steps

Simulation Overview

Configure the detector geometry, switch generator back-ends, and understand Geant4 transport options.

Reconstruction Overview

Learn about the digitisation pipeline, GenFit track fitting, and the experimental ACTS back-end.

Build docs developers (and LLMs) love

Get started for freeTalk to us