Documentation 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.
FairShip can be installed three ways, and the right choice depends on where you are working. Pixi is the simplest path on any modern Linux machine and manages every dependency automatically. On CERN’s lxplus cluster, building against pre-compiled libraries from CVMFS is fastest. If you have neither pixi nor CVMFS available, a fully local aliBuild covers the remaining cases. All methods ultimately produce the same runtime environment with the same macro entry points.
FairShip uses git-lfs to store large files such as magnetic field maps. If you have never used git-lfs on your account, run git lfs install once before cloning — otherwise those files will be missing and geometry initialisation will fail. Key Dependencies
Whichever installation method you choose, the following core packages are required. These versions are tracked in pixi.toml and the aliBuild release defaults:
| Package | Minimum version |
|---|
| ROOT | ≥ 6.38 |
| Geant4 | ≥ 11.3 |
| Pythia8 | ≥ 8.312 |
| FairRoot | ≥ 19.0 |
| GenFit | ≥ 2.3 |
| EvtGen | ≥ 2.2 |
Pixi
CVMFS / lxplus
Local Build
Pixi reads the pixi.toml and activate.sh already present in the repository and resolves every dependency from the ship channel on prefix.dev and conda-forge. No manual environment management is needed.The pixi project root must be the FairShip clone itself. The activate.sh script exports FAIRSHIP, GEOMPATH, and related variables to PIXI_PROJECT_ROOT, which must point to the directory that contains the geometry/ and files/ sub-directories. Do not run pixi from a parent directory.
Build from Source (Recommended)
Clone the repository
git clone https://github.com/ShipSoft/FairShip.git
cd FairShip
git lfs install
git lfs pull
Build FairShip
This runs the full CMake configure → build sequence defined in pixi.toml. On first run pixi also downloads and installs all declared conda dependencies into an isolated environment under .pixi/. Run a command
Prefix any command with pixi run to execute it inside the activated environment:pixi run python macro/run_simScript.py --tag my-simulation
pixi shell
python macro/run_simScript.py --tag my-simulation
Using the Pre-Built Package
If you do not need to modify the C++ source, you can use the pre-built fairship package from the ship channel. You still need the clone for the geometry/ and files/ directories:git clone https://github.com/ShipSoft/FairShip.git
cd FairShip
pixi add fairship
pixi run python macro/run_simScript.py --tag my-simulation
pixi add fairship appends fairship to pixi.toml under [dependencies] and fetches the pre-built binary, skipping the CMake build entirely. On CERN’s lxplus, building against libraries pre-compiled and cached on CVMFS is the recommended workflow. CVMFS can also be configured on personal machines — see the CVMFS documentation.Clone the repository
git clone https://github.com/ShipSoft/FairShip.git
Verify CVMFS access
If this command returns a directory listing, CVMFS is accessible. If it hangs or fails, contact your system administrator. Source the setup script
Replace $SHIP_RELEASE with the release tag you want to use. Available releases and their changelogs are documented in the cvmfs_release repository.source /cvmfs/ship.cern.ch/$SHIP_RELEASE/setUp.sh
SHIPDIST, ALIBUILD_WORK_DIR, and other aliBuild variables.You must re-run this source command every time you open a new shell session before loading the FairShip environment.
Build with aliBuild
aliBuild build FairShip --always-prefer-system --config-dir $SHIPDIST --defaults release
--always-prefer-system flag tells aliBuild to use system (CVMFS) libraries wherever possible, drastically reducing build time. If you are building a branch other than master, replace release with the appropriate default (see the Branches table).Load the environment
After the build completes:alienv enter FairShip/latest
eval $(alienv load FairShip/latest --no-refresh)
If you exit your shell and want to continue working, you only need to re-run the source step and then alienv enter FairShip/latest. You do not need to rebuild unless the source has changed.
If neither pixi nor CVMFS is available, you can build the entire software stack from source using aliBuild. This takes significantly longer on first build since all dependencies (ROOT, Geant4, FairRoot, etc.) are compiled from scratch.Install alibuild
The recommended installation method is via pipx:Alternatively, use pip install alibuild in a virtual environment. Clone FairShip
git clone https://github.com/ShipSoft/FairShip.git
Clone the build recipes
The shipdist repository contains the aliBuild recipes for the full software stack:git clone https://github.com/ShipSoft/shipdist.git
export SHIPDIST=$(pwd)/shipdist
Build FairShip
cd FairShip
aliBuild build FairShip --config-dir $SHIPDIST --defaults release
- On many platforms: add
--always-prefer-system to use installed system libraries and avoid rebuilding them.
- On architectures not explicitly recognised by aliBuild: add
--force-unknown-architecture.
- For diagnosing dependency issues: run
aliDoctor FairShip --config-dir $SHIPDIST --defaults release before building.
Load the environment
alienv enter FairShip/latest
eval $(alienv load FairShip/latest --no-refresh)
A full local build from scratch can take several hours depending on your hardware, since it compiles ROOT, Geant4, FairRoot, and all other dependencies. Use CVMFS or pixi where possible to avoid this.
Docker
Docker is not the recommended way to run FairShip locally, but it is useful for reproducible, stateless environments — for example in HTCondor batch jobs or when strict isolation from the host is required.
# Build the image
git clone https://github.com/ShipSoft/FairShip.git
cd FairShip
docker build -t fairship .
# Run interactively
docker run -i -t --rm fairship /bin/bash
# With graphics forwarding and a mounted working directory
docker run -i -t --rm \
-e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
-v /local_workdir:/image_workdir \
fairship /bin/bash
Troubleshooting
Consult the FAQ and common issues page on the FairShip wiki for solutions to frequently encountered problems. For issues specific to a particular CVMFS release, open an issue in the cvmfs_release repository.