Testing and CI Pipeline for FairShip Simulation

FairShip ships a comprehensive test and CI pipeline that covers everything from C++ unit tests to end-to-end physics simulation chains. All of these steps are reproducible locally through pixi run tasks, so you can catch failures before pushing and understand exactly what GitHub Actions does when it evaluates your pull request. The tasks are defined in pixi.toml and mirror the steps in the .github/workflows/build-run.yml workflow, ensuring there is no gap between what runs locally and what runs in CI.

Pre-commit style checks run on a separate CI service. See the live status badge at results.pre-commit.ci/latest/github/ShipSoft/FairShip/master. These checks run automatically on every pull request; you can also run them locally with pre-commit run --all-files.

Build Tasks

Before running tests or CI tasks, the project must be configured, built, and optionally installed. These foundational pixi tasks are defined in pixi.toml:

Task	Command	Description
`configure`	`cmake -S . -B build -G Ninja …`	Runs CMake configuration, generates `build/compile_commands.json` for clang-tidy
`build`	`cmake --build build -j$(nproc)`	Compiles FairShip (depends on `configure`)
`install`	`cmake --install build`	Installs built libraries and executables into `$CONDA_PREFIX` (depends on `build`)
`test`	`ctest --test-dir build --output-on-failure`	Runs the CTest suite (depends on `build`)

pixi run configure   # configure CMake
pixi run build       # compile (implies configure)
pixi run install     # install into environment (implies build)
pixi run test        # run CTest suite (implies build)

Unit Tests

The C++ unit test suite lives in the tests/ directory and is built and run via CTest:

tests/
├── CMakeLists.txt
├── test_data_class_io.cxx
└── test_rntuple_io.cxx

Run all unit tests after building:

pixi run test

This executes ctest --test-dir build --output-on-failure, which prints the full output of any failing test. The build task is a dependency, so if the build is stale it will be rebuilt automatically.

Full Simulation Chain

The CI simulation chain reproduces the complete SHiP analysis pipeline: geometry setup, simulation, overlap checking, reconstruction, and analysis. Each step is an independent pixi run task that reads the output files of the previous step by tag name. The sim-chain tasks use the tag ci-test.

Simulate events

Run the simulation with the TRY_2025 muon shield, vacuum vessel geometry, and all SND designs:

pixi run ci-sim

This calls macro/run_simScript.py and produces sim_ci-test.root and geo_ci-test.root. The task accepts optional arguments to override defaults:

Argument	Default	Description
`vessel`	`vacuums`	Vessel geometry variant
`snd_design`	`all`	SND detector design
`muon_shield`	`TRY_2025`	Muon shield configuration name

Override arguments like this:

pixi run ci-sim --vessel vacuums --muon_shield TRY_2025

Check geometry overlaps

Validate the geometry for unintended volume overlaps:

pixi run ci-overlap-check

Runs python/experimental/check_overlaps.py against geo_ci-test.root and fails the task if any overlap is detected in the log.

Print geometry information

Inspect the detector hierarchy to a depth of two levels:

pixi run ci-geo-info

Reconstruct events

Run digitisation and reconstruction on the simulated events using the Artificial Retina pattern recognition:

pixi run ci-reco

Produces sim_ci-test_rec.root containing digitisation and reconstruction branches. The original simulation file is not modified.

Produce analysis histograms

Run the standard analysis macro over both simulation and reconstruction output:

pixi run ci-ana

Run analysis example

Exercise the analysis_toolkit pre-selection with the example script:

pixi run ci-analysis-example

Additional CI Tasks

Tracking Benchmark

Evaluates tracking performance on 200 simulated events with a fixed seed, producing a JSON metrics file:

pixi run ci-tracking-benchmark

Runs with -n 200 --seed 42 --tag ci-benchmark --output-json tracking_metrics.json. Output files use the ci-benchmark tag.

Fixed-Target Neutrino Simulation

Runs the fixed-target neutrino simulation for 10 events:

pixi run ci-fixed-target

Calls macro/run_fixedTarget.py -n 10 -e 10.0 -r 1.

Plot Rendering

After running the simulation chain or benchmarks, render diagnostic plots to PNG using the dedicated rendering tasks. Plots are written to subdirectories under plots/.

# Sim chain plots (sim, reco, ana outputs)
pixi run ci-render-plots-sim-chain

# Tracking benchmark plots
pixi run ci-render-plots-tracking-benchmark

# Fixed-target simulation plots
pixi run ci-render-plots-fixed-target

The sim-chain rendering task accepts a config argument (default pixi-default) that determines the subdirectory name under plots/sim-chain/.

Static Analysis

Static analysis tasks take file lists through environment variables so you can target only the files you have changed, mirroring exactly how the CI workflow passes file lists.

C++ (clang-tidy)
Python (pyrefly)

Set CPP_FILES to a space-separated list of C++ source files and run:

CPP_FILES="passive/ShipMuonShield.cxx strawtubes/StrawTubes.cxx" pixi run ci-clang-tidy

The task pipes clang-tidy output through .github/scripts/annotate_build.py, which formats diagnostics as GitHub Actions annotations when running in CI. Locally you see the raw clang-tidy output.

The build/compile_commands.json database (generated by CMake with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON) is used automatically by clang-tidy via -p build/. Run pixi run build at least once to generate it.

Set PY_FILES to a space-separated list of Python files and run:

PY_FILES="python/hnl.py python/ShipGeoConfig.py" pixi run ci-pyrefly

pyrefly uses the configuration in pyproject.toml — Python 3.12 target, python/ and stubs/ on the search path, and several physics-specific packages replaced with Any stubs:

[tool.pyrefly]
python-version = "3.12"
search-path = ["python", "stubs"]
replace-imports-with-any = [
    "rootUtils", "rootUtils.*",
    "cppyy", "cppyy.*",
    "shipRoot_conf", "shipRoot_conf.*",
    "global_variables", "global_variables.*",
]

CI Output File Naming

The pipeline relies on consistent file naming so each step can find the previous step’s output without configuration:

Task group	Tag used	Example output file
Simulation chain	`ci-test`	`sim_ci-test.root`, `geo_ci-test.root`, `sim_ci-test_rec.root`
Tracking benchmark	`ci-benchmark`	`tracking_benchmark_histos.root`, `tracking_metrics.json`

If you run the tasks manually with a custom --tag, update downstream task invocations accordingly or use the pixi task arguments to override the defaults.

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Testing and CI Pipeline for FairShip Simulation

Build Tasks

Unit Tests

Full Simulation Chain

Additional CI Tasks

Tracking Benchmark

Fixed-Target Neutrino Simulation

Plot Rendering

Static Analysis

CI Output File Naming

Build docs developers (and LLMs) love

Getting Started

Simulation

Reconstruction & Analysis

Detector Systems

Developer Guide

Documentation Index

​Build Tasks

​Unit Tests

​Full Simulation Chain

​Additional CI Tasks

Tracking Benchmark

Fixed-Target Neutrino Simulation

​Plot Rendering

​Static Analysis

​CI Output File Naming

Build docs developers (and LLMs) love

Build Tasks

Unit Tests

Full Simulation Chain

Additional CI Tasks

Plot Rendering

Static Analysis

CI Output File Naming