run_simScript.py: Complete Argument and Usage Reference

macro/run_simScript.py is the single entry point for all FairShip Monte Carlo simulations. It wires together the geometry configuration, event generator, FairRoot simulation run, and Geant4 transport, then writes the three output ROOT files. Understanding its arguments lets you configure any physics scenario supported by FairShip without touching the source code.

Quick-start examples

# 1 000 HNL events, charm production, output tagged "hnl-run"
# HNL is the default mode — no extra flag needed
python macro/run_simScript.py -A c -n 1000 --tag hnl-run

Output file naming

The three output files share a common {tag} identifier:

{outputDir}/sim_{tag}.root      ← MC truth + hits  (cbmsim TTree)
{outputDir}/geo_{tag}.root      ← TGeo geometry + ShipGeo config
{outputDir}/params_{tag}.root   ← FairRoot runtime-database parameters

If --tag is not provided, a random UUID v4 is generated at startup and used for all three files.

Generator selection flags

Exactly one primary generator must be active. If no generator flag is given on the command line, Pythia8 is enabled by default.

--Pythia8

flag

Use Pythia8 as the primary generator (default when no other generator flag is set). Handles HNL signal, dark photon, RPV-SUSY, and charm-only modes. Sets 400 GeV proton beam momentum.

--Pythia6

flag

Use the legacy Pythia6 generator (tPythia6Generator). Simulates 50 GeV gamma/mu interactions on a neutron target. Provided for backward compatibility.

--evtcalc

flag

Read pre-generated events from an EventCalc .root file (converted from .dat via macro/convertEvtCalc.py). Requires -f to specify the input file. The number of events is capped at the file content unless overridden with -n.

--MuonBack

flag

Generate events from a muon background file produced by a previous Pythia8+Geant4 run. Requires -f. Forces MCTracksWithHitsOnly to control output size. Empty events (no hits) are stripped after the run.

--FixedTarget

flag

Use FixedTargetGenerator for minimum-bias proton–proton interactions at the SHiP fixed target. See also the dedicated macro/run_fixedTarget.py.

subcommand

Activate the particle gun. Must be passed as a positional subcommand, e.g. python macro/run_simScript.py PG --pID 13. See the Particle gun parameters section below.

Genie

subcommand

Read neutrino interactions from a GENIE output file. Must be passed as a positional subcommand. Requires -f for the input file path. The gst TTree is copied to the simulation output.

--EvtGenDecayer

flag

Load TEvtGenDecayer to handle J/ψ and other quarkonium decays via EvtGen. Activates DecayConfigTEvtGen.C as the Pythia decayer configuration. Can be combined with any primary generator.

Physics scenario flags

HNL simulation is the default mode. If neither --DarkPhoton nor --RpvSusy is given, the script runs in HNL mode automatically — there is no --HNL flag to pass.

--DarkPhoton

flag

Simulate dark photon signal using DPPythia8Generator. Default mass 0.2 GeV, default ε = 8×10⁻⁸. Production mode is set via -A.

-A MODE

string

default:"c"

Controls which production process is active. For HNL: c = ccbar→HNL (default), b = bbbar→HNL, bc = Bc⁺/Bc⁻ → HNL, inclusive = all. For dark photons: meson = meson decays, pbrem = proton bremsstrahlung, qcd = ff̄ → DP.

-m MASS

float

Mass of the hidden particle in GeV. Defaults to 1.0 GeV for HNL and 0.2 GeV for dark photon if not specified.

-c COUPLINGS

string

default:"0.447e-9,7.15e-9,1.88e-9"

HNL mixing angles as a comma-separated string U2e,U2mu,U2tau. Sets both production and decay couplings simultaneously. Use -cp and -cd to set them independently.

-cp COUPLINGS

string

HNL production-only couplings U2e,U2mu,U2tau. Must be combined with -cd; cannot be used alone.

-cd COUPLINGS

string

HNL decay-only couplings U2e,U2mu,U2tau. Must be combined with -cp.

-e EPSILON

float

default:"8e-8"

Dark photon kinetic mixing parameter ε.

--MesonMother MODE

string

default:"pi0"

Dark photon production meson source. Options: pi0, eta, omega, eta1, eta11.

Run control

-n NEVENTS

int

default:"100"

Number of events to generate. For file-backed generators (EventCalc, MuonBack, GENIE), the actual count is min(n, file_entries).

-i FIRSTEVENT

int

default:"0"

First event index within the input file. Useful for splitting large files across jobs.

-o OUTPUTDIR

string

default:"."

Output directory for all three ROOT files. Created automatically if it does not exist.

--tag TAG

string

Custom string tag for output file names (sim_{TAG}.root, etc.). If omitted, a UUID v4 is generated.

-f INPUTFILE

string

Input file path. Repeat -f for multiple files. Accepts glob patterns. Required for --evtcalc, --MuonBack, --Ntuple, and Genie modes.

-s SEED

int

default:"0"

Random seed. A value of 0 triggers a time-based seed, automatically clamped to Pythia8’s allowed range (≤ 900 000 000).

--debug LEVEL

int

default:"0"

FairLogger console verbosity. 0 = INFO, 1 = DEBUG, 2 = DEBUG1, 3 = DEBUG2.

-t / --test

flag

Quick-test mode. Overrides the input file with a small bundled file ($FAIRSHIP/files/Cascade-parp16-MSTP82-1-MSEL4-76Mpot_1_5000.root).

--dry-run

flag

Initialise the run and then exit immediately. Useful for checking that geometry and generator configuration succeed without running any events.

--check-overlaps

flag

After the run, invoke TGeo overlap checking at 0.1 mm tolerance and print any overlaps found. A finer per-subsystem check (0.1 μm) is run on each top-level node.

Detector and geometry flags

--shieldName NAME

string

default:"TRY_2025"

Muon shield geometry to use, looked up from the shield_db dictionary in python/geometry_config.py. Currently TRY_2025 is the only supported value.

-Y HEIGHT

float

default:"6.0"

Maximum height of the decay vacuum tank in metres.

--strawDesign DESIGN

int

default:"10"

Straw tube tracker frame material. 4 = aluminium frame, 10 = steel frame.

--vacuums

flag

Set the decay volume medium to vacuum (changes vessel structural parameters). Mutually exclusive with --helium.

--helium

flag

Set the decay volume medium to helium (default). This is a no-op unless you explicitly need to override a previous --vacuums on the same command line.

--SND

flag

Activate the SND (Scattering and Neutrino Detector) subsystem.

--SND_design DESIGN [DESIGN ...]

string

default:"2"

SND design variant(s). 1 = EmulsionTarget, 2 = MTC + SiliconTarget. Pass all to enable every available design. Multiple values are space-separated.

--target-yaml PATH

string

Path to the YAML file defining the target geometry. Defaults to $FAIRSHIP/geometry/target_config.yaml.

--field_map PATH

string

Path to the spectrometer magnetic field map ROOT file, relative to files/. Overrides the default set in geometry_config.py.

Beam smearing flags

--SmearBeam SIGMA

float

default:"0.8"

Standard deviation of Gaussian beam smearing at the target, in cm.

--PaintBeam RADIUS

float

default:"5"

Radius for beam painting (uniform circular smearing), in cm.

--phiRandom

flag

Randomise the azimuthal angle φ for the muon background generator.

Particle gun parameters

The PG subcommand exposes a dedicated set of arguments. All position and size quantities are in centimetres.

--pID ID

int

default:"22"

PDG particle ID for the gun (e.g. 13 = μ⁻, -13 = μ⁺, 22 = photon, 11 = e⁻).

--Estart ENERGY

float

default:"10"

Start of the kinetic energy (or momentum) range in GeV.

--Eend ENERGY

float

default:"10"

End of the kinetic energy range in GeV. Set equal to --Estart for a mono-energetic gun.

--multiplePG

flag

Enable multiple particle gun sources spread across an x–y plane at a fixed z, or in a 3D volume (controlled by --smearMode).

--multiplicity N

int

default:"1"

Number of particles to generate per event.

--Vx, --Vy, --Vz

float

default:"0"

Vertex position of the particle gun in cm.

--Dx, --Dy

float

Full spread of the gun vertex in x and y: position is drawn uniformly from (V − D/2, V + D/2). Only used with --multiplePG.

--smearMode MODE

string

default:"uniform"

Vertex smearing model name. Passed to ParticleGunGenerator::SetVertexModel().

--bothCharges

flag

Generate both charge signs of the given particle ID within a single run.

--chargeFraction FRAC

float

default:"0.5"

Fraction of events to generate with the positive sign when --bothCharges is active. Must be in [0, 1].

--momentumModel MODEL

int

default:"0"

Index of the momentum model to use. Model 0 is flat between --Estart and --Eend. Use --showPGModels to print all available models.

--histoFile PATH

string

ROOT file containing a histogram to sample the gun kinematics from. Repeat for multiple histograms. Must be paired with --histoName and --histoX.

Muon background options

--FollowMuon

flag

Make the muon shield active so that muon trajectories are followed through the iron. Implies --FastMuon.

--FastMuon

flag

Transport only muons, skipping other secondaries, for a fast muon-only background estimate.

Step-by-step: running an HNL simulation

Build or install FairShip

pixi run install   # builds with CMake and installs into $CONDA_PREFIX

Run the simulation

python macro/run_simScript.py \
    -A c \
    -m 1.0 \
    -c "0.447e-9,7.15e-9,1.88e-9" \
    -n 1000 \
    --tag hnl-1gev \
    -o output/hnl

This generates 1 000 HNL events with mass 1 GeV from charm decays and writes output to output/hnl/. HNL is the default mode — no extra flag is required.

Check the output

ls output/hnl/
# sim_hnl-1gev.root   geo_hnl-1gev.root   params_hnl-1gev.root

Inspect geometry information

python macro/getGeoInformation.py \
    --geometry output/hnl/geo_hnl-1gev.root \
    --level 2

Run reconstruction

python macro/ShipReco.py \
    -f output/hnl/sim_hnl-1gev.root \
    -g output/hnl/geo_hnl-1gev.root \
    --patRec AR

HNL mode (default), --DarkPhoton, and --RpvSusy are mutually exclusive. Combining --DarkPhoton and --RpvSusy, or either with the default HNL mode, will print an error and exit with code 2.

Use --dry-run to verify that your geometry and generator configuration initialise without errors before committing to a long production run.

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

run_simScript.py: Complete Argument and Usage Reference

Quick-start examples

Output file naming

Generator selection flags

Physics scenario flags

Run control

Detector and geometry flags

Beam smearing flags

Particle gun parameters

Muon background options

Step-by-step: running an HNL simulation

Build docs developers (and LLMs) love

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Documentation Index

​Quick-start examples

​Output file naming

​Generator selection flags

​Physics scenario flags

​Run control

​Detector and geometry flags

​Beam smearing flags

​Particle gun parameters

​Muon background options

​Step-by-step: running an HNL simulation

Build docs developers (and LLMs) love

Quick-start examples

Output file naming

Generator selection flags

Physics scenario flags

Run control

Detector and geometry flags

Beam smearing flags

Particle gun parameters

Muon background options

Step-by-step: running an HNL simulation