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 FairShip reconstruction chain converts raw Monte Carlo hits stored in a simulation file into fitted tracks and decay-vertex candidates without ever writing back to the original MC file. The pipeline runs in three broad phases — digitisation, pattern recognition with track fitting, and vertex finding — each phase producing branches in a dedicated output tree. Downstream analysis then merges the MC and reconstruction data on-the-fly through ROOT’s friend-tree mechanism, keeping the two datasets cleanly separated on disk while making them appear as a single tree in code.

​
Pipeline at a glance

1

Digitisation

ShipDigiReco reads every MC hit branch from cbmsim in sim_*.root and converts true energy deposits into detector-realistic digitised hits. Straw tube hits are smeared by a drift-time model (drift velocity + spatial resolution σ) to produce Digi_*Hits branches. Other sub-detectors — SBT, TimeDet, UpstreamTagger, SplitCal, MTC — are digitised by their own dedicated detector classes.
2

Pattern Recognition

Digitised straw hits are passed to shipPatRec.execute(), which groups hits into track candidates. Two backends are available: the default AR (Artificial Retina) algorithm and the FH (Fast Hough transform), selectable via --patRec. A third experimental TemplateMatching method is also supported.
3

Track Fitting

Track candidates from pattern recognition are passed to the GenFit2 DAF (Deterministic Annealing Filter) Kalman fitter via shipStrawTracking. The fitter uses genfit::TGeoMaterialInterface for material effects and genfit::FairShipFields for the magnetic field map. Each fitted track is stored as a genfit::Track* in FitTracks; the integer vector fitTrack2MC maps each fitted track index to the originating MC particle index in MCTrack.
4

Vertex Finding

shipVertex.Task loops over all pairs of good fitted tracks and finds the point of closest approach, iterating the extrapolation until the vertex Z position converges to within 0.1 cm. Decay-vertex candidates are stored as ShipParticle objects in the Particles branch, each carrying the 4-momentum, DOCA, and vertex covariance matrix. Vertexing can be skipped with --noVertexing.
5

Output

ShipDigiReco.finish() writes and closes sim_*_rec.root. This file contains only the ship_reco_sim tree; the original MC file is never modified. The reco file is typically 5–20× smaller than the simulation file.

​
File conventions

File patternTreeContents
sim_*.rootcbmsimMC tracks (ShipMCTrack), straw points (strawtubesPoint), all sub-detector MC hit branches
geo_*.rootFAIRGeom, ShipGeoTGeo geometry + ShipGeo configuration dictionary
sim_*_rec.rootship_reco_simShipEventHeader, Digi_*Hits, FitTracks, fitTrack2MC, Particles, Tracklets
The reconstruction output tree is always named ship_reco_sim. ShipAna and the analysis toolkit rely on this exact name when calling AddFriend.

​
Friend-tree mechanism

Because simulation and reconstruction live in separate files, analysis code joins them with ROOT’s friend-tree API: 
f = ROOT.TFile.Open("sim_my-run.root")
sTree = f["cbmsim"]
sTree.AddFriend("ship_reco_sim", "sim_my-run_rec.root")

# After AddFriend, branches from both trees are visible on sTree:
for event in sTree:
    n_tracks = len(event.FitTracks)        # from ship_reco_sim
    n_mc     = len(event.MCTrack)          # from cbmsim
TChain is also supported for multi-file datasets: 
sTree    = ROOT.TChain("cbmsim")
recChain = ROOT.TChain("ship_reco_sim")
for f in file_list:
    sTree.AddFile(f)
    recChain.AddFile(f.replace(".root", "_rec.root"))
sTree.AddFriend(recChain)

​
Pattern recognition backends

The Artificial Retina algorithm (--patRec AR) is the production default. It processes hits in each of the four straw tube stations and uses a retina scoring function to identify track seeds, then extends seeds across stations. It is robust against high occupancy and produces low clone rates.

​
Tracking benchmark

Performance of the reconstruction chain is quantified by macro/run_tracking_benchmark.py, which fires a particle gun, runs the full sim → reco chain as subprocesses, and then calls python/tracking_benchmark.py to compute:
  • Track finding efficiency — fraction of reconstructible MC tracks matched to a reco track (Wilson score uncertainty)
  • Clone rate — fraction of reco tracks matched to an already-matched MC track
  • Ghost rate — fraction of reco tracks not matched to any MC track
  • Momentum resolution — σ(Δp/p) from a Gaussian fit
Results are written to a JSON metrics file and tracking_benchmark_histos.root. 
python macro/run_tracking_benchmark.py -n 200 --seed 42 --tag ci-benchmark \
    --output-json tracking_metrics.json

​
Further reading

Running ShipReco

Full reference for macro/ShipReco.py: arguments, output branches, and usage examples.

Running ShipAna

How to analyse reconstruction output with macro/ShipAna.py and the analysis_toolkit.

Tracking & Pattern Recognition

Deep dive into pattern recognition algorithms, GenFit track fitting, ACTS integration, and the tracking benchmark.

Build docs developers (and LLMs) love

Get started for freeTalk to us