FairShip integrates the FairRoot framework with Geant4 to provide a complete Monte Carlo simulation chain for the SHiP experiment at CERN. A single run ofDocumentation 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.
macro/run_simScript.py takes you from primary event generation — whether that is an HNL signal, dark photon, muon background, or a simple particle gun — through Geant4 propagation of every secondary particle, into hit collection on sensitive detector volumes, and finally into a set of three ROOT output files ready for reconstruction and analysis.
The simulation pipeline
FairRunSim. The detector geometry is built from the ShipGeo configuration object (produced by python/geometry_config.py), passed to python/shipDet_conf.py which instantiates every FairModule, and then handed to Geant4 through the VMC interface configured in gconfig/g4Config.C.
Output file types
Every simulation run writes three files whose names share a common tag (a user-supplied string or an auto-generated UUID):sim_{tag}.root
MC truth and detector hits. Contains the
cbmsim TTree with MCTrack, MCEventHeader, and per-subsystem *Point branches (e.g. vetoPoint, strawtubesPoint, TimeDetPoint).geo_{tag}.root
Full TGeo geometry exported by
run.CreateGeometryFile(). Stores FAIRGeom (the ROOT TGeoManager) and ShipGeo (the serialised Python config) for use in reconstruction and analysis.params_{tag}.root
FairRoot runtime-database parameters written by
FairParRootFileIo. Required by the reconstruction chain (macro/ShipReco.py).Supported physics scenarios
HNL signal
Heavy neutral lepton produced from charm (
-A c) or beauty (-A b) decays via HNLPythia8Generator. Mass and mixing angles are fully configurable.Dark photon
Dark photon signal via
DPPythia8Generator. Supports meson decay (-A meson), proton bremsstrahlung (-A pbrem), and QCD (-A qcd) production modes.Muon background
Secondary muons from upstream proton interactions, read from a pre-produced
MuonBack file. Empty events are filtered automatically after the run.Fixed target
Minimum-bias 400 GeV proton–proton interactions at the fixed target using
FixedTargetGenerator, for inclusive production studies.Particle gun
Single or multiple configurable particles via the
PG subcommand. Useful for detector calibration studies, acceptance maps, and quick geometry checks.GENIE neutrino
Neutrino interactions read from GENIE output files via
GenieGenerator. The gst TTree is copied to the output for cross-reference.MC track storage modes
FairShip offers three strategies that trade output file size against MC truth completeness. The active mode is set inrun_simScript.py before run.Init():
| Flag | SetMinPoints | SetEnergyCut | Use case |
|---|---|---|---|
MCTracksWithHitsOnly | 1 (must hit detector) | −100 MeV (disabled) | Muon background — smallest files |
MCTracksWithEnergyCutOnly | −1 (disabled) | 100 MeV | Default for signal simulations |
MCTracksWithHitsOrEnergyCut | 1 | 100 MeV | OR of above; ~2× larger files |
For muon background (
--MuonBack) simulations, MCTracksWithHitsOnly is forced on automatically to keep output files manageable.Main entry point
All simulation scenarios are driven by a single script:--tag flag sets the shared identifier used in all three output file names. If omitted, a random UUID is generated.
Explore further
run_simScript.py Reference
Complete argument reference, output naming conventions, and worked examples for every simulation mode.
Event Generators
Pythia8, EvtGen, EventCalc, GENIE, particle gun, and muon background — how each generator is configured and what physics it covers.
Geometry System
How FairShip builds, stores, and inspects the detector geometry, including the muon shield database and YAML-based subsystem configs.