Running ShipReco: Digitise and Reconstruct MC Events

macro/ShipReco.py is the entry point for the FairShip reconstruction chain. It reads a simulation file produced by run_simScript.py, loads the matching geometry, and runs digitisation, pattern recognition, track fitting, and vertex finding for each event. The reconstructed data are written to a separate output file — the original simulation file is never modified. This page documents every command-line argument, explains how the output file is structured, and provides copy-paste usage examples for common workflows.

Quick start

# Reconstruct all events, default AR pattern recognition
python macro/ShipReco.py -f sim_my-run.root -g geo_my-run.root

# Reconstruct 500 events with debug output
python macro/ShipReco.py -f sim_my-run.root -g geo_my-run.root -n 500 --Debug

# Skip vertex fitting, start from event 100
python macro/ShipReco.py -f sim_my-run.root -g geo_my-run.root \
    --noVertexing -i 100

Command-line reference

-f / --inputFile

string

required

Path to the MC simulation ROOT file. The file must contain a cbmsim tree with ShipMCTrack, strawtubesPoint, and all sub-detector hit branches created by run_simScript.py.

-g / --geoFile

string

required

Path to the geometry ROOT file (geo_*.root). Must contain the FAIRGeom TGeo object and the ShipGeo configuration dictionary written by run_simScript.py.

-n / --nEvents

integer

default:"999999"

Maximum number of events to reconstruct. The actual number processed is min(tree.GetEntries(), nEvents).

-i / --firstEvent

integer

default:"0"

Index of the first event to process. Combine with -n to reconstruct a sub-range, e.g. -i 1000 -n 500 processes events 1000–1499.

--patRec

string

default:"AR"

Pattern recognition algorithm. Accepted values:

AR — Artificial Retina (default, recommended for production)
FH — Fast Hough Transform
TemplateMatching — template-based seed + window search

--noVertexing

flag

Skip the shipVertex.Task step entirely. Useful when only track-level quantities are needed and you want to reduce runtime. The Particles branch will be empty in the output file.

--noStrawSmearing

flag

Disable the drift-distance smearing of straw tube hits. By default, the true distance to wire is smeared with the detector spatial resolution σ. Pass this flag to use unsmeared (ideal) wire distances — useful for algorithm development but not for realistic performance studies.

--withT0

flag

Simulate an arbitrary T0 offset and apply a correction for it. Activates a time-calibration study mode inside ShipDigiReco.

--Debug

flag

Enable verbose per-event debug output. Sets global_variables.debug = True, which causes progress to be printed for every event rather than every 1000.

-dy

integer

Override the tank Y-height (cm). If not specified, ShipReco.py tries to parse the height from the input filename; if that also fails, it falls back to the value stored in the geometry file.

Output file

The output file is named by replacing .root with _rec.root in the input filename. If the input is already named *_rec.root the same file is updated in place. The file is written to the current working directory, not the location of the input file.

sim_my-run.root  →  sim_my-run_rec.root   (written to CWD)

Output tree: `ship_reco_sim`

The output file contains a single tree named ship_reco_sim. This name is fixed and required by downstream tools (ShipAna, analysis_toolkit, TrackingBenchmark) when they call AddFriend.

Branch	Type	Description
`ShipEventHeader`	`FairEventHeader`	Run/event number and event time
`Digi_strawtubesHits`	`TClonesArray<strawtubesHit>`	Digitised straw tube hits with drift-time smearing
`FitTracks`	`vector<genfit::Track*>`	Kalman-fitted tracks from GenFit2 DAF
`fitTrack2MC`	`vector<int>`	Maps fitted-track index → `MCTrack` index; `-1` for ghosts
`goodTracks`	`vector<int>`	Indices of tracks passing basic quality criteria
`Tracklets`	`vector<Tracklet>`	Short track segments (used internally by the fitter)
`Particles`	`vector<ShipParticle>`	Decay-vertex candidates from `shipVertex.Task`
`Digi_SBTHits`	`TClonesArray`	Scintillating Barrel Tracker digits (if present in MC)
`VetoHitOnTrack`	`vector<vetoHitOnTrack>`	SBT hit-on-track association
`Digi_TimeDetHits`	`TClonesArray`	TimeDet digits (if present in MC)

FitTracks uses pointer storage (genfit::Track*) rather than value storage. This is required because GenFit Track objects contain circular back-pointers between TrackPoint and Track that would become dangling if the vector were reallocated. Do not attempt to change this to value storage.

Processing loop

After argument parsing and geometry initialisation, ShipReco.py runs a simple per-event loop:

SHiP = shipDigiReco.ShipDigiReco(options.inputFile, outFile, fgeo)
options.nEvents = min(SHiP.sTree.GetEntries(), options.nEvents)

for global_variables.iEvent in range(options.firstEvent, options.nEvents):
    if global_variables.iEvent % 1000 == 0 or global_variables.debug:
        print("event ", global_variables.iEvent)
    rc = SHiP.sTree.GetEvent(global_variables.iEvent)
    SHiP.digitize()
    SHiP.reconstruct()
    SHiP.recoTree.Fill()

SHiP.finish()

Each call to digitize() converts MC hits to detector-realistic digits. Each call to reconstruct() runs pattern recognition, track fitting, and (optionally) vertex finding, then clears the output vectors ready for the next Fill().

Geometry and field initialisation

Before the event loop, ShipReco.py performs several mandatory initialisation steps:

Load geometry

Opens geoFile, loads the ShipGeo dictionary via load_from_root_file, and calls shipDet_conf.configure(run, ShipGeo) to instantiate all detector modules.

Initialise material interface

Creates genfit.TGeoMaterialInterface() immediately after opening the geo file. This must happen before any GenFit track propagation.

Initialise magnetic field

Calls geomGeant4.addVMCFields(ShipGeo, "", True, withVirtualMC=False) to create the field map and stores the result in global_variables.fieldMaker.

Set global variables

Copies all options (patRec method, vertexing flag, smearing flag, debug flag, ShipGeo, modules, histograms) into global_variables so that all downstream modules can access them without being passed explicit arguments.

Diagnostic histograms

When withHists = True (the default), ShipReco.py books several per-run histograms that are printed to the terminal at the end:

Histogram	X-axis	Description
`distu`	distance / cm	Distance to wire for U-view straw hits
`distv`	distance / cm	Distance to wire for V-view straw hits
`disty`	distance / cm	Distance to wire for Y-view straw hits
`nmeas`	count	Number of measurements per fitted track
`chi2`	χ²/NDF	Reduced chi-squared of fitted tracks

Usage examples

# All events, AR pattern recognition, vertex finding enabled
python macro/ShipReco.py \
    -f sim_my-run.root \
    -g geo_my-run.root

Connecting reco output to analysis

After reconstruction completes, downstream analysis scripts access both MC and reco data through a friend-tree relationship. ShipAna does this automatically; when writing custom analysis code use:

import ROOT

f = ROOT.TFile.Open("sim_my-run.root")
sTree = f["cbmsim"]

# Attach reconstruction branches as a friend tree
sTree.AddFriend("ship_reco_sim", "sim_my-run_rec.root")

for event in sTree:
    # MC branches
    mc_tracks = event.MCTrack        # from cbmsim
    straw_pts = event.strawtubesPoint

    # Reco branches (from ship_reco_sim friend)
    fit_tracks  = event.FitTracks
    track2mc    = event.fitTrack2MC
    candidates  = event.Particles

When running batch jobs across many files, name each simulation with a unique tag (e.g. sim_run001.root, sim_run002.root) so that the automatically derived reco filenames (sim_run001_rec.root, sim_run002_rec.root) remain unique and can be collected into a TChain without collision.

ShipReco.py writes the output file to the current working directory, not to the directory containing the input file. If you run from a different directory than where your simulation files live, make sure the CWD has sufficient disk space and write permissions.

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Running ShipReco: Digitise and Reconstruct MC Events

Quick start

Command-line reference

Output file

Output tree: `ship_reco_sim`

Processing loop

Geometry and field initialisation

Diagnostic histograms

Usage examples

Connecting reco output to analysis

Build docs developers (and LLMs) love

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Documentation Index

​Quick start

​Command-line reference

​Output file

​Output tree: ship_reco_sim

​Processing loop

​Geometry and field initialisation

​Diagnostic histograms

​Usage examples

​Connecting reco output to analysis

Build docs developers (and LLMs) love

Quick start

Command-line reference

Output file

Output tree: `ship_reco_sim`

Processing loop

Geometry and field initialisation

Diagnostic histograms

Usage examples

Connecting reco output to analysis