Geometry Configuration Reference for FairShip Detectors

The geometry configuration module (python/geometry_config.py) is the single source of truth for every detector position, dimension, and material choice in a FairShip simulation. Calling create_config() returns a Config object — a recursively accessible attribute dictionary — that is passed through the full detector construction chain in shipDet_conf.py. Every downstream detector class reads its parameters from this object, so changing a value here propagates automatically to the ROOT geometry builder, the field map loader, and the digitisation step.

Environment Variables

The following environment variables must be set before running any FairShip simulation. geometry_config.py expands $FAIRSHIP via os.path.expandvars at call time; FAIRSHIP_ROOT is not used by geometry_config.py itself but is required by shipRoot_conf.py, which is always imported before the geometry is built.

FAIRSHIP

string

required

Absolute path to the FairShip repository root. Used by geometry_config.py to locate geometry/target_config.yaml and geometry/veto_config_*.yaml at runtime via os.path.expandvars.

FAIRSHIP_ROOT

string

required

Signals that the FairShip environment is properly initialised. Checked by shipRoot_conf.py on import; the process exits immediately if absent. Not read by geometry_config.py directly.

GENFIT_ROOT

string

Path to the GenFit2 installation. If set, libgenfit2 is loaded and Cling is pointed at the GenFit headers. Falls back to the GENFIT variable if GENFIT_ROOT is not found.

`create_config()` — Primary Factory Function

from geometry_config import create_config

ship_geo = create_config(
    DecayVolumeMedium="helium",
    Yheight=6.0,
    strawDesign=10,
    muShieldGeo=None,
    shieldName="TRY_2025",
    nuTargetPassive=1,
    SND=True,
    SND_design=[2],
    TARGET_YAML=None,
)

Returns a Config instance (an AttrDict subclass) populated with every subsystem’s parameters. The object is designed for dot-access (ship_geo.decayVolume.length) and is safe to pickle for parallel jobs.

create_config() reads two YAML files from $FAIRSHIP/geometry/ at call time: target_config.yaml and veto_config_{DecayVolumeMedium}.yaml. Both files must exist before the function is invoked.

Parameters

DecayVolumeMedium

string

default:"helium"

Fill medium for the decay vessel. Accepted values are "helium" and "vacuums". The choice determines which veto YAML is loaded (veto_config_helium.yaml or veto_config_vacuums.yaml) and therefore the inner/outer support material and thickness of the vessel walls. Helium fill uses aluminium supports; vacuum fill uses thicker steel supports.

Yheight

float

default:"6.0"

Nominal height of the vacuum tank in metres. Converted internally to FairShip length units (u.m). Sets c.Yheight and is also used as the default aperture height for the spectrometer magnet field region (c.Bfield.y). The MISIS magnet design (selected when magnetDesign > 3) overrides this with a fixed 3.5 m half-aperture.

strawDesign

int

default:"10"

Straw tube frame material and geometry variant.

Value	Frame	Notes
`4`	Aluminium	Lighter frame, 2018-era design
`10`	Steel	Current default; also forces `cave.floorHeightMuonShield` to equal `cave.floorHeightTankA` to remove the floor gap

Any value other than 4 or 10 raises a ValueError at runtime.

muShieldGeo

str | None

default:"None"

Path to an external muon shield geometry file for expert overrides. When None (the default), the shield geometry is taken entirely from shield_db[shieldName]. Pass a file path only when testing custom field configurations outside the standard database.

shieldName

string

default:"TRY_2025"

Key into shield_db selecting the muon shield magnet configuration. Must not be empty (a ValueError is raised otherwise). The selected entry supplies the full parameter matrix for every magnet in the shield, the hybrid flag, and the WithConstField flag. See shield_db reference below.

nuTargetPassive

int

default:"1"

Controls whether the SND nuclear emulsion target includes active readout layers.

Value	Meaning
`0`	Target built with active (emulsion + readout) layers
`1`	Only passive absorber layers — faster simulation, no hit digitisation

SND

bool

default:"True"

Enable or disable construction of the SND (Scattering and Neutrino Detector) subsystem. When False, the c.SND flag is cleared and shipDet_conf.py skips all SND detector initialisation.

SND_design

list[int]

default:"[2]"

List of integer design variant numbers forwarded to the SND detector constructors. If a single integer is passed it is automatically wrapped in a list. Design numbers select different sensor layouts and tracker configurations within the SND geometry builder.

TARGET_YAML

str | None

default:"None"

Explicit path to the target YAML configuration file. When None the path defaults to $FAIRSHIP/geometry/target_config.yaml. Pass an absolute path to use a custom target configuration (e.g. for the silicon target or alternative tungsten stacking patterns).

Derived Config Fields

The following fields are computed inside create_config() and are available on the returned object. They are not constructor parameters.

Target sub-config (c.target)

Loaded from TARGET_YAML. The YAML file must contain a top-level target key. After loading, three flat lists are computed:

c.target.slices_length — per-slice absorber thickness (cm)
c.target.slices_gap — downstream gap after each slice (cm); the last entry is forced to 0
c.target.slices_material — material string for each slice (e.g. "tungsten")

The total target length c.target.length is the sum of all slices_length[i] + slices_gap[i]. The interaction point is at c.target.z0 = 0 (the SHiP coordinate-system origin); the target centre is at c.target.z = c.target.z0 + c.target.length / 2.

Muon shield (c.muShield)

Built from shield_db[shieldName]. Key fields:

Field	Description
`c.muShield.length`	Total shield length (sum of gaps and magnet half-lengths × 2)
`c.muShield.nMagnets`	Number of magnets in the shield
`c.muShield.Entrance`	List of upstream z positions (cm) for each magnet
`c.muShield.params`	Flattened parameter list forwarded to the ROOT magnet constructor
`c.muShield.WithConstField`	Whether a constant field approximation is used
`c.SC_mag`	`True` when `hybrid=True` in the selected shield entry

Decay volume (c.decayVolume)

Field	Value / formula
`c.decayVolume.length`	50 m (nominal EOI length)
`c.z`	89.57 m — absolute z of the spectrometer magnet
`c.decayVolume.z`	`c.z − 31.450 m` — decay vessel centre
`c.decayVolume.z0`	`c.decayVolume.z − c.decayVolume.length / 2` — vessel entrance
`c.decayVolume.xEndInner`	From veto YAML (`xendInner`, cm)
`c.decayVolume.yEndInner`	From veto YAML (`yendInner`, cm)

Tracking stations (c.TrackStation1–4)

All positions are absolute z values derived from the spectrometer magnet position c.z with a 3.5 m gap between magnet centre and the inner stations, and a further 2 m gap between inner and outer station pairs.

Station	z position
TrackStation1	`c.z − 5.5 m`
TrackStation2	`c.z − 3.5 m`
TrackStation3	`c.z + 3.5 m`
TrackStation4	`c.z + 5.5 m`

SplitCal calorimeter (c.SplitCal)

Starts at 38.450 m + c.decayVolume.z. Key parameters:

ECAL: 50 sampling layers, lead filter (0.28 cm), scintillator active (0.56 cm)
HCAL: disabled by default (nHCALSamplings = 0, ActiveHCAL = 0)
Strip geometry: 2 modules in X, 3 in Y, 50 strips per module
Total thickness computed from filter and active layer counts plus a 100 cm big gap

TimeDet timing detector (c.TimeDet)

Field	Value
`dzBarRow`	1.2 cm
`dzBarCol`	2.4 cm
`zBar`	1.0 cm
`DX` / `DY`	225 cm / 325 cm
z position	`37.800 m + c.decayVolume.z` (first bar layer relative to vessel centre)

Upstream Tagger (c.UpstreamTagger)

A simplified vacuum scoring plane located 25.4 m upstream of the decay vessel centre.

Field	Value
`BoxX`	4.4 m
`BoxY`	6.4 m
`BoxZ`	16 cm
`PositionResolution`	1.0 cm
`TimeResolution`	0.3 ns

`shield_db` Dictionary

The shield_db module-level dictionary maps named shield configurations to their full parameter sets. Pass the key as shieldName to create_config().

shield_db = {
    "TRY_2025": {
        "hybrid": False,
        "WithConstField": False,
        "params": [
            [gap, half_length, dXIn, dXOut, dYIn, dYOut,
             gapIn, gapOut, ..., polarity],
            # one list per magnet
        ],
    },
}

hybrid

bool

When True, the shield uses a hybrid superconducting/normal-conducting magnet design. Sets c.SC_mag = True on the config object.

WithConstField

bool

When True, the field in the hadron absorber and muon shield is approximated as a constant value rather than interpolated from a field map. Copied to both c.hadronAbsorber.WithConstField and c.muShield.WithConstField.

params

list[list[float]]

One sub-list per magnet, in upstream → downstream order. The format of each sub-list is:

Index	Quantity
0	Upstream gap before this magnet (cm)
1	Magnet half-length along z (cm)
2	Inner horizontal half-aperture at entrance, dXIn (cm)
3	Inner horizontal half-aperture at exit, dXOut (cm)
4	Inner vertical half-aperture at entrance, dYIn (cm)
5	Inner vertical half-aperture at exit, dYOut (cm)
6	Horizontal coil gap at entrance, gapIn (cm)
7	Horizontal coil gap at exit, gapOut (cm)
…	Additional shape parameters
last	Field polarity flag (+1 / −1 / 1.9 / −1.91)

The TRY_2025 entry defines six magnets. The total shield length is computed as Σ (gap[i] + 2 × half_length[i]) across all entries.

Available shield keys

Key	Magnets	Hybrid	Const field
`TRY_2025`	6	No	No

To add a custom shield geometry, insert a new key into shield_db before calling create_config(), following the same list format. The muon shield builder in MuonShield.cxx reads the flattened c.muShield.params list directly, so the number of elements per magnet must be consistent.

`configure_snd_old()` — Legacy SND Configuration

This function lives in python/shipDet_conf.py and is called by the main detector configuration routine when SND=True and a legacy YAML path is provided. It reads the SND geometry from a YAML file and instantiates the ROOT Target and TargetTracker detector objects.

def configure_snd_old(
    yaml_file: str,
    emulsion_target_z_end: float,
    cave_floorHeightMuonShield: float,
) -> None:

yaml_file

str

required

Path to the SND geometry YAML file. The legacy reference file is geometry/snd_config_old.yaml.

emulsion_target_z_end

float

required

Downstream z edge of the emulsion target volume (in FairShip length units). Used to place the target centre at z_end − snd_nuTarget_zdim / 2.

cave_floorHeightMuonShield

float

required

Floor height in the muon shield region, taken from ship_geo.cave.floorHeightMuonShield. Used to compute the support pillar height so the target clears the cavern floor.

SND YAML structure

The YAML file must contain two top-level keys:

nuTarget
nuTauTT

nuTarget:
  n_plates: 36       # Number of lead + emulsion plate pairs per brick
  LeadTh: 0.1        # Lead plate thickness (cm)
  EmTh: 0.0070       # Emulsion film thickness (cm)
  PBTh: 0.0175       # Plastic base thickness (cm)
  BrPackZ: 0.0       # Brick packaging thickness along z (cm)
  BrPackX: 0.0       # Brick packaging thickness along x (cm)
  BrPackY: 0.0       # Brick packaging thickness along y (cm)
  col: 1             # Number of brick columns
  row: 1             # Number of brick rows
  wall: 5            # Number of target walls (emulsion walls)
  EmX: 40.           # Emulsion film x dimension (cm)
  EmY: 40.           # Emulsion film y dimension (cm)
  nuTargetPassive: true
  SingleEmFilm: false
  Design: 4
  Ydist: 0.0

nuTauTT:
  n_hor_planes: 4    # Number of horizontal SciFi planes per tracker station
  n_vert_planes: 4   # Number of vertical SciFi planes per tracker station
  scifimat_width: 13.06   # SciFi mat width (cm)
  scifimat_z: 0.145       # SciFi mat thickness along z (cm)
  support_z: 0.55         # Support structure thickness along z (cm)
  honeycomb_z: 2.01       # Honeycomb (Airex/Nomex) core thickness (cm)
  design: 4

Geometry YAML Files

All YAML files are located in $FAIRSHIP/geometry/. They are loaded at runtime — none are compiled into the binary.

File	Purpose
`target_config.yaml`	Main proton target: tungsten slice thicknesses, gaps, and material per plate
`veto_config_helium.yaml`	Decay vessel veto geometry for helium fill; aluminium inner/outer supports, sensitive scintillator layer
`veto_config_vacuums.yaml`	Decay vessel veto geometry for vacuum fill; thicker steel supports
`strawtubes_config.yaml`	Straw Tube Tracker (SST) aperture, wire and wall thicknesses, stereo angles
`snd_config_old.yaml`	Legacy SND emulsion target and SciFi tracker tracker geometry
`MTC_config.yaml`	MuonTagger Calorimeter: sandwich layers, iron/SciFi/scintillator thicknesses, field strength
`SiliconTarget_config.yaml`	Silicon active target: sensor size, layer count, spacing
`cave.geo`	FairRoot cave medium definition (no air)
`caveWithAir.geo`	FairRoot cave medium definition (with air)
`media.geo`	Material/medium definitions for the full detector

`load_from_root_file()` — Loading Config from a ROOT File

Defined in python/ShipGeoConfig.py. Reads a previously serialised Config object back from a ROOT file — useful when reproducing a simulation from an existing output file without re-running create_config().

from ShipGeoConfig import load_from_root_file

ship_geo = load_from_root_file("ship.conical.Pythia8-TGeant4.root")

# Or pass an already-opened TFile:
import ROOT
f = ROOT.TFile.Open("simulation_output.root")
ship_geo = load_from_root_file(f, key="ShipGeo")

root_file

str | ROOT.TFile

required

Either a string path to a ROOT file or an already-opened ROOT.TFile object. When a string is passed the function opens and closes the file automatically.

key

str

default:"\"ShipGeo\""

Key name under which the Config object was stored in the ROOT file. FairShip simulation jobs write the geometry config under "ShipGeo" by default.

The function auto-detects the storage format:

New format (JSON string): parsed with Config.loads_json().
Old format (pickled Python object): deserialised with Config.loads().

The returned object is a Config instance identical to what create_config() produces and can be passed directly to detector constructors.

Usage Examples

from geometry_config import create_config

ship_geo = create_config()

# Spectrometer magnet absolute z position
print(ship_geo.z)                          # 89570.0 mm

# Decay vessel centre and entrance
print(ship_geo.decayVolume.z)              # ~58120.0 mm
print(ship_geo.decayVolume.z0)             # vessel entrance z

# Total muon shield length
print(ship_geo.muShield.length)            # sum of all magnet gaps + lengths

# Straw tube design in use
print(ship_geo.strawDesign)                # 10 (steel frame)

Passing SND_design as a bare integer (e.g. SND_design=2) is allowed — create_config() wraps it in a list automatically — but always check downstream detector constructors that iterate over ship_geo.SND_design, as they expect a list.

Python Modules

Configuration

Geometry Configuration Reference for FairShip Detectors

Environment Variables

`create_config()` — Primary Factory Function

Parameters

Derived Config Fields

`shield_db` Dictionary

Available shield keys

`configure_snd_old()` — Legacy SND Configuration

SND YAML structure

Geometry YAML Files

`load_from_root_file()` — Loading Config from a ROOT File

Usage Examples

Build docs developers (and LLMs) love

Python Modules

Configuration

Documentation Index

​Environment Variables

​create_config() — Primary Factory Function

​Parameters

​Derived Config Fields

​shield_db Dictionary

​Available shield keys

​configure_snd_old() — Legacy SND Configuration

​SND YAML structure

​Geometry YAML Files

​load_from_root_file() — Loading Config from a ROOT File

​Usage Examples

Build docs developers (and LLMs) love

Environment Variables

`create_config()` — Primary Factory Function

Parameters

Derived Config Fields

`shield_db` Dictionary

Available shield keys

`configure_snd_old()` — Legacy SND Configuration

SND YAML structure

Geometry YAML Files

`load_from_root_file()` — Loading Config from a ROOT File

Usage Examples