FairShip Event Generators: Modes and Configuration

FairShip supports a wide range of primary event generators, each targeting a distinct physics programme of the SHiP experiment. All generators plug into the same FairPrimaryGenerator interface so that Geant4 receives a consistent list of primary particles regardless of how they were produced. The active generator is selected by a flag or subcommand passed to macro/run_simScript.py; at most one primary generator may be active in a single run, though --EvtGenDecayer can be layered on top of any of them.

Pythia8 (`--Pythia8`)

Pythia8 is the default generator and underpins the three main hidden-particle signal modes. The beam momentum is 400 GeV and the target is a proton. The concrete Pythia8 generator class depends on the scenario:

HNL signal
Dark photon
Charm-only

HNLPythia8Generator produces heavy neutral leptons from charm or beauty hadron decays. The ProcessLevel:all = off setting disables Pythia8’s own showering so that only the HNL decay kinematics are generated; Geant4 handles all subsequent propagation.

# Charm production (default), mass 1 GeV, TP benchmark couplings
# HNL mode is the default — no extra flag needed
python macro/run_simScript.py -A c -m 1.0 \
    -c "0.447e-9,7.15e-9,1.88e-9" -n 500 --tag hnl-charm

# Beauty production
python macro/run_simScript.py -A b -m 1.0 \
    -c "0.447e-9,7.15e-9,1.88e-9" -n 500 --tag hnl-beauty

# Bc meson production
python macro/run_simScript.py -A bc -m 1.0 \
    -c "0.447e-9,7.15e-9,1.88e-9" -n 500 --tag hnl-bc

The generator reads a pre-produced charm or beauty cascade file (set by -f or the inputFile default), re-decays the heavy hadrons in Pythia8, and applies geometric acceptance cuts based on the decay volume aperture.Production and decay couplings can be set independently for acceptance studies:

python macro/run_simScript.py -m 1.0 \
    -cp "1e-8,2e-8,1e-9" \
    -cd "0.447e-9,7.15e-9,1.88e-9" \
    -n 500 --tag hnl-split-couplings

DPPythia8Generator handles all dark photon production modes. The PDG ID used depends on the mode: 9900015 for meson and pbrem modes, 4900023 for QCD (ff̄ → DP).

# Meson decays (π⁰, η, ω, ...) — default mother: pi0
python macro/run_simScript.py --DarkPhoton -A meson \
    -m 0.2 -e 8e-8 --MesonMother pi0 -n 500 --tag dp-meson

# Proton bremsstrahlung
python macro/run_simScript.py --DarkPhoton -A pbrem \
    -m 0.2 -e 8e-8 -n 500 --tag dp-pbrem

# QCD: ff-bar → dark photon (uses PDG ID 4900023)
python macro/run_simScript.py --DarkPhoton -A qcd \
    -m 0.2 -e 8e-8 -n 500 --tag dp-qcd

The python/darkphoton.py module provides the DarkPhoton class, which computes the partial width and total cross section using interpolated R-ratio data from the PDG. Production rates by meson species are handled in python/dpProductionRates.py.

Setting -A charmonly activates a special mode that generates inclusive charm production (no HNL) for cross-section measurements. Beam smearing and uniform target illumination are applied:

python macro/run_simScript.py -A charmonly \
    -f my_charm_cascade.root -n 1000 --tag charm-xs

`-A` inclusive flag reference

Value	Generator class	Physics
`c`	`HNLPythia8Generator`	ccbar→HNL (default)
`b`	`HNLPythia8Generator`	bbbar→HNL
`bc`	`HNLPythia8Generator`	Bc⁺/Bc⁻→HNL
`meson`	`DPPythia8Generator`	Meson decay → DP
`pbrem`	`DPPythia8Generator`	Proton bremsstrahlung → DP
`qcd`	`DPPythia8Generator`	ff̄ → DP (PDG ID 4900023)
`inclusive`	`HNLPythia8Generator`	All processes

Pythia6 (`--Pythia6`)

The legacy Pythia6 generator (tPythia6Generator) simulates 50 GeV gamma/muon interactions on a neutron target. It is provided for backward compatibility with older production workflows. The interaction vertex is placed at the downstream edge of the muon shield.

python macro/run_simScript.py --Pythia6 -n 200 --tag pythia6-run

EvtGen decayer (`--EvtGenDecayer`)

--EvtGenDecayer is not a standalone generator but an overlay that replaces Pythia8’s internal decayer for J/ψ and other quarkonium resonances with EvtGen’s TEvtGenDecayer. It activates DecayConfigTEvtGen.C and can be combined with any primary generator:

# HNL run with EvtGen handling J/ψ decays (HNL is the default mode)
python macro/run_simScript.py -n 500 --EvtGenDecayer --tag hnl-evtgen

--EvtGenDecayer overrides any earlier SetPythiaDecayer call, including those made by the GENIE mode. It should be the last decayer-related flag processed.

EventCalc (`--evtcalc`)

EventCalc is an external event generator that produces physics events in a text-based .dat format. FairShip converts these to ROOT with macro/convertEvtCalc.py and then reads them with EvtCalcGenerator.

Convert EventCalc output

python macro/convertEvtCalc.py -f my_evtcalc_output.dat -o test_folder/test_input.root

Run simulation from converted file

python macro/run_simScript.py \
    --evtcalc \
    -f test_folder/test_input.root \
    -n 1 \
    -o test_folder \
    --tag evtcalc-test

The generator calls EvtCalcGenerator.SetPositions(zTa, zDV) to correctly position events relative to the target (zTa) and the decay volume front face (zDV). When -n -1 is given, all events in the file are processed.

GENIE neutrino interactions (`Genie` subcommand)

GENIE events are read from a pre-produced GENIE output ROOT file via GenieGenerator. The subcommand form must be used:

python macro/run_simScript.py Genie \
    -f /path/to/genie-nu_mu.root \
    --z_start_nu 2844.285 \
    --z_end_nu 3180.435 \
    -n 500 \
    --tag genie-numu

--z_start_nu Z

float

default:"2844.2850"

Start z position (cm) for distributing neutrino interaction vertices.

--z_end_nu Z

float

default:"3180.4350"

End z position (cm) for neutrino interaction vertex distribution.

The gst TTree from the GENIE input is copied to sim_{tag}.root so that neutrino truth information is preserved alongside the Geant4 hits. GENIE configuration helpers live in python/configGenieGenerator.py. The Pythia decayer is set to DecayConfigNuAge.C for this mode.

Particle gun (`PG` subcommand)

The particle gun is activated with the PG positional subcommand. It is most useful for acceptance studies, detector calibration, and geometry validation runs.

# 10 GeV muon, point source at origin
python macro/run_simScript.py PG --pID 13 --Estart 10 --Eend 10 \
    --tag muon-gun-10gev -n 1000

# Uniform energy sweep 1–100 GeV photons, 5 per event
python macro/run_simScript.py PG --pID 22 --Estart 1 --Eend 100 \
    --multiplicity 5 --tag photon-sweep -n 500

# Spatially spread muons (±10 cm in x, ±5 cm in y at z=0)
python macro/run_simScript.py PG --pID 13 --Estart 50 \
    --multiplePG --Vx 0 --Dx 20 --Vy 0 --Dy 10 --Vz 0 \
    --tag spread-muons -n 200

# Both charges, 70% μ⁻ and 30% μ⁺
python macro/run_simScript.py PG --pID 13 --Estart 10 \
    --bothCharges --chargeFraction 0.7 --tag mixed-charges -n 500

To list all available vertex and momentum models:

python macro/run_simScript.py PG --showPGModels

Muon background (`--MuonBack`)

The muon background generator reads muon tracks from a file produced by a previous full Pythia8+Geant4 run with enhanced charm production:

python macro/run_simScript.py --MuonBack \
    -f /eos/ship/data/Mbias/pythia8_Geant4-withCharm_onlyMuons_4magTarget.root \
    -n 10000 \
    --SmearBeam 0.8 \
    --PaintBeam 5 \
    --tag muback-run

FairShip automatically detects whether the input comes from the new production (has a PlaneHAPoint branch) and adjusts the target z offset accordingly. The --FastMuon flag restricts transport to muons only, while --FollowMuon additionally makes the muon shield active for muon tracking studies.

MCTracksWithHitsOnly is forced on when --MuonBack is used. All events with zero hits in every Point container are removed from sim_{tag}.root after the run completes.

Fixed target (`macro/run_fixedTarget.py`)

For minimum-bias inclusive production studies, a dedicated script is available:

python macro/run_fixedTarget.py -n 1000 -e 400.0 -r 1

Argument	Meaning
`-n NEVENTS`	Number of events
`-e ENERGY`	Beam energy in GeV
`-r RUNNR`	Run number (sets output directory)

The FixedTargetGenerator can also be activated within run_simScript.py via --FixedTarget. The z-offset of the interaction point relative to the target front face is controlled by --z-offset (default −84 mm).

HNL physics module (`python/hnl.py`)

The HNL class provides lifetime and branching-ratio calculations that the Pythia8 generator uses to weight events correctly:

from hnl import HNL

# Instantiate with mass (GeV) and mixing angles [U2e, U2mu, U2tau]
b = HNL(1.0, [1e-8, 2e-8, 1e-9], True)
# HNLbranchings instance initialized with couplings:
#      U2e   = 1e-08
#      U2mu  = 2e-08
#      U2tau = 1e-09
# and mass:
#      m = 1.0 GeV

# Compute proper lifetime in seconds
lifetime = b.computeNLifetime()
# e.g. 4.78e-05 s

# Branching ratio for a specific decay channel
br = b.findBranchingRatio('N -> pi mu')
# e.g. 0.118

The class uses PDG masses from ROOT.TDatabasePDG and CKM matrix elements to compute partial widths for all kinematically open channels. The True argument enables verbose output during initialisation.

Dark photon physics module (`python/darkphoton.py`)

The DarkPhoton class interpolates the PDG hadronic R-ratio table to compute the partial width into hadrons and the total production cross section as a function of centre-of-mass energy:

from darkphoton import DarkPhoton

dp = DarkPhoton(mass=0.2, eps=8e-8)
# Compute total decay width
width = dp.GammaTot()
# Compute branching ratio to muons
br_mumu = dp.BranchingRatio('mumu')

The python/dpProductionRates.py module handles meson-decay and proton-bremsstrahlung production rates used by DPPythia8Generator during event generation.

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

FairShip Event Generators: Modes and Configuration

Pythia8 (`--Pythia8`)

`-A` inclusive flag reference

Pythia6 (`--Pythia6`)

EvtGen decayer (`--EvtGenDecayer`)

EventCalc (`--evtcalc`)

GENIE neutrino interactions (`Genie` subcommand)

Particle gun (`PG` subcommand)

Muon background (`--MuonBack`)

Fixed target (`macro/run_fixedTarget.py`)

HNL physics module (`python/hnl.py`)

Dark photon physics module (`python/darkphoton.py`)

Build docs developers (and LLMs) love

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Documentation Index

​Pythia8 (--Pythia8)

​-A inclusive flag reference

​Pythia6 (--Pythia6)

​EvtGen decayer (--EvtGenDecayer)

​EventCalc (--evtcalc)

​GENIE neutrino interactions (Genie subcommand)

​Particle gun (PG subcommand)

​Muon background (--MuonBack)

​Fixed target (macro/run_fixedTarget.py)

​HNL physics module (python/hnl.py)

​Dark photon physics module (python/darkphoton.py)

Build docs developers (and LLMs) love

Pythia8 (`--Pythia8`)

`-A` inclusive flag reference

Pythia6 (`--Pythia6`)

EvtGen decayer (`--EvtGenDecayer`)

EventCalc (`--evtcalc`)

GENIE neutrino interactions (`Genie` subcommand)

Particle gun (`PG` subcommand)

Muon background (`--MuonBack`)

Fixed target (`macro/run_fixedTarget.py`)

HNL physics module (`python/hnl.py`)

Dark photon physics module (`python/darkphoton.py`)