FairShip

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->

Table of contents

• FairShip
  • Introduction
    • Branches
  • Build instructions using CVMFS
  • Local build, without access to CVMFS
  • Run instructions
  • Docker instructions
  • Troubleshooting information
  • Documentation
  • License
  • Contributing code

<!-- markdown-toc end -->

Introduction

FairShip is the software framework for the SHiP experiment which is based on FairRoot. The dependencies of FairShip are tracked and installed using alibuild. A wiki can be found here

Branches

<dl> <dt><code>master</code></dt> <dd>Main development branch. All python code is <b>required to be python 3</b>. Python 2 is no longer supported. Requires aliBuild default <code>release</code>.</dd> <dt><code>charmdet</code></dt> <dd>Branch for the charm cross-section measurement. Kept as reference for potential future studies.</dd> <dt><code>SHiP-2018</code></dt> <dd>Frozen branch for the CDS, kept for backward compatibility. Python 2 only. Requires aliBuild default <code>fairship-2018</code>.</dd> <dt><code>muflux</code></dt> <dd>Branch for the muon flux analysis. Python 2 only. Requires aliBuild default <code>fairship-2018</code>.</dd> </dl>

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.

Build Instructions using CVMFS

On lxplus this is the recommended way to use FairShip. CVMFS can also be setup on your own machine (please see the CVMFS documentation)

1. Download the FairShip software

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

   As we are using git-lfs to deal with large files for field maps etc., you might have to run

   git lfs install
   

   if you have never used git-lfs on your account before.

2. Make sure you can access the SHiP CVMFS Repository

   ls /cvmfs/ship.cern.ch
   

3. Source the setUp.sh script from the CVMFS release you want to use (replace $SHIP_RELEASE with the release you want to use):

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

   Info about different releases can be found in a dedicated repository. Please report issues with particular releases or the setup script there.

4. Build the software using aliBuild

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

   If you are not building master, you will need to select the appropriate default (see Branches).

If you exit your shell session and you want to go back working on it, make sure to re-execute the third step.

To load the FairShip environment, after you build the software you can simply use:

5. Load the environment

   alienv enter FairShip/latest
   

However, this won't work if you are using HTCondor. In such case you can do:

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

Local build, without access to CVMFS

Commands are similar to the previous case, but without access to CVMFS you need to build the required packages.

1. Install alibuild using pipx (recommended) or pip.

2. Clone the FairShip repository:

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

   As we are using git-lfs to deal with large files for field maps etc., you might have to run

   git lfs install
   

   if you have never used git-lfs on your account before.

3. Clone the shipdist repository, which contains the recipes to build the software stack:

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

4. Build the software using aliBuild:

   aliBuild build FairShip --config-dir $SHIPDIST --defaults release
   

   NB: Depending on the platform you might have to pass the --always-prefer-system or --force-unknown-architecture flags to aliBuild. For debugging, aliDoctor is very useful!

5. Load the environment

   alienv enter FairShip/latest
   

Run instructions

Set up the bulk of the environment from CVMFS (see the dedicated repository for information about the available releases):

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

Load your local FairShip environment.

alienv enter FairShip/latest

Now you can for example 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.