FairShip

Table of contents

• FairShip
  • Introduction
    • Branches
  • Using pixi
  • Run instructions
  • Docker instructions
  • Troubleshooting information
  • Documentation
  • License
  • Contributing code
  • Legacy releases (CVMFS + aliBuild, ≤26.04)

Introduction

FairShip is the software framework for the SHiP experiment which is based on FairRoot. Its dependencies are managed with pixi — see Using pixi below. See the FairShip wiki for additional documentation.

Branches

master

Main development branch. All python code is required to be python 3. Python 2 is no longer supported.

charmdet

Branch for the charm cross-section measurement. Kept as reference for potential future studies.

SHiP-2018

Frozen branch for the CDS, kept for backward compatibility. Python 2 only. Builds via the legacy aliBuild path only.

muflux

Branch for the muon flux analysis. Python 2 only. Builds via the legacy aliBuild path only.

All packages are managed in Git and GitHub. Please read the Git tutorial for SHiP first, even if you already know Git, as it explains how development is done on GitHub.

Using pixi

Pixi manages all dependencies via the pixi.toml and activate.sh already included in this repository. The activation script sets FAIRSHIP and GEOMPATH (among others) to PIXI_PROJECT_ROOT, so the pixi project root must be the FairShip clone itself — it contains the required geometry/ and files/ directories.

Build from source (recommended)

1. Install pixi if you haven't already.

2. Clone and build:

   git clone https://github.com/ShipSoft/FairShip.git
   cd FairShip
   pixi run build

3. Run commands inside the environment:

   pixi run python macro/run_simScript.py --tag my-simulation

   Or start a shell:

   pixi shell
   python macro/run_simScript.py --tag my-simulation

Using the pre-built package

Pre-built FairShip packages are available from the ship channel. Because activate.sh expects geometry/, files/, and other data directories at PIXI_PROJECT_ROOT, the simplest approach is to add fairship directly to the clone:

git clone https://github.com/ShipSoft/FairShip.git
cd FairShip
pixi add fairship
pixi run python macro/run_simScript.py --tag my-simulation

Run instructions

Start a shell with the FairShip environment activated:

pixi shell

(Or prefix individual commands with pixi run.) Then you can simulate some events, run reconstruction and analysis:

python $FAIRSHIP/macro/run_simScript.py --tag my-simulation
>> [...]
>> Macro finished successfully.
>> [...]
>> Output file is  sim_my-simulation.root
>> Geometry file is geo_my-simulation.root
>> [...]

python $FAIRSHIP/macro/ShipReco.py -f sim_my-simulation.root -g geo_my-simulation.root
>> [...]
>> finished writing tree
>> Exit normally
>> (This creates sim_my-simulation_rec.root with digitisation and reconstruction data)

python -i $FAIRSHIP/macro/ShipAna.py -f sim_my-simulation.root -r sim_my-simulation_rec.root -g geo_my-simulation.root
>> finished making plots
>> Exit normally

Note: Simulation output files use the naming convention {sim,geo,params}_{identifier}.root, where the identifier is either a UUID (auto-generated) or a custom tag specified with --tag. ShipReco creates a separate reconstruction file (*_rec.root) containing only digitisation and reconstruction branches. The original simulation file is not modified. ShipAna uses both files via ROOT's friend tree mechanism to access both MC truth and reconstruction data.

Alternatively, you can make use of the experimental analysis_toolkit to run a simple pre-selection check on the events. An example script can be found in $FAIRSHIP/examples/analysis_example.py.

Simulate MC signal events with EventCalc:

python $FAIRSHIP/macro/convertEvtCalc.py -f test_input.dat -o test_folder

and then:

python $FAIRSHIP/macro/run_simScript.py --evtcalc -n 1 -o test_folder -f test_folder/test_input.root

Run the event display:

python -i $FAIRSHIP/macro/eventDisplay.py -f sim_my-simulation.root -r sim_my-simulation_rec.root -g geo_my-simulation.root
// use SHiP Event Display GUI
Use quit() or Ctrl-D (i.e. EOF) to exit

Docker instructions

Docker is not the recommended way to run FairShip locally. It is ideal for reproducing reproducible, stateless environments for debugging, HTCondor and cluster use, or when a strict separation between FairShip and the host is desirable.

1. Build an docker image from the provided Dockerfile:

   git clone https://github.com/ShipSoft/FairShip.git
   cd FairShip
   docker build -t fairship .

2. Run the FairShip docker image:

   docker run -i -t --rm fairship /bin/bash

3. Advanced docker run options:

   docker run -i -t --rm \
   -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
   -v /local_workdir:/image_workdir \
   fairship /bin/bash

   The option -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix forwards graphics from the docker to your local system (similar to ssh -X). The option -v /local_workdir:/image_workdir mounts /local_workdir on the local system as /image_workdir within docker.

Troubleshooting information

Please see the wiki for FAQs and common issues.

Documentation

An automatic class reference is built using Doxygen from comments in the C++ code. Improving the comments will improve this documentation.

License

FairShip is distributed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). See the LICENSE file for details.

Copyright is held by CERN for the benefit of the SHiP Collaboration. Some components are distributed under different licenses and copyrights - see the individual file headers and the LICENSES directory for details. This project follows the REUSE specification for licensing information.

Contributing code

• Any and all contributions are welcome!
• Contributions via pull requests are preferred, but if you require help with git, don't hesitate to write reach out to us.
• Please split your work into small commits with self-contained changes to make them easy to review and check.
• To help us consistently improve the quality of our code, please try to follow the C++ and Python guidelines.

Legacy releases (CVMFS + aliBuild, ≤26.04)

These instructions are kept for users running existing CVMFS releases up to 26.04 and for legacy branches (SHiP-2018, muflux). New work should use Using pixi instead; the shipdist repository (aliBuild recipes) is no longer maintained.

With CVMFS (lxplus and similar)

1. Clone the FairShip software (initialise git-lfs first if you've never used it):

   git lfs install
   git clone https://github.com/ShipSoft/FairShip.git

2. Make sure CVMFS is mounted:

   ls /cvmfs/ship.cern.ch

3. Source the chosen release (≤ 26.04; see the cvmfs_release repo for the list):

   source /cvmfs/ship.cern.ch/$SHIP_RELEASE/setUp.sh

4. Build with aliBuild:

   aliBuild build FairShip --always-prefer-system --config-dir $SHIPDIST --defaults release

   For legacy branches, swap --defaults release for --defaults fairship-2018.
5. Load the environment:

   alienv enter FairShip/latest

   Or, in non-interactive contexts (e.g. HTCondor):

   eval $(alienv load FairShip/latest --no-refresh)

Without CVMFS

1. Install aliBuild via pipx or pip.
2. Clone shipdist alongside FairShip:

   git clone https://github.com/ShipSoft/shipdist.git

3. Build:

   aliBuild build FairShip --config-dir ./shipdist --defaults release

   Pass --always-prefer-system or --force-unknown-architecture if needed; aliDoctor helps when something doesn't resolve.
4. Load the environment:

   alienv enter FairShip/latest