chayanit/sndsw

SND experiment framework based on FairShip and FairRoot

sndsw

Table of Contents

• Introduction
  • Contact and communication
  • Branches
• Build instructions
  • On lxplus or systems with CVMFS
  • On systems without access to CVMFS
• Run Instructions
• Docker Instructions
• Contributing Code

Introduction

sndsw is the software framework of the SND@LHC collaboration. It is based on the FairShip framework developed by the SHiP collaboration which in turn is based on FairRoot, making use of the automatic python bindings provided by PyROOT.

Contact and communication

If you have questions or problems, please feel free to contact the @SND-LHC/core-developers. For troubleshooting and development, we plan to discuss on Mattermost.

The snd-software mailing list can be used to discuss the software and report issues. Important annoucements will be made there.

The snd-software-notifications mailing list will be used for automated notifications from Github and CI/CD etc..

Both mailing lists are self-subscribe CERN e-groups.

Branches

master

Main development branch. All python code is required to be compatible with 3 Requires aliBuild default release.

Build instructions

The aliBuild family of tools developed by ALICE is used to set up sndsw and its dependencies.

Introduction to aliBuild

The basic commands are the same regardless of whether CVMFS is used:

aliBuild build <package-name> -c snddist

Build the package <package-name> (e.g. sndsw) and its dependencies using the recipes and configuration provided by snddist. On CVMFS, it is recommended to add --always-prefer-system to ensure packages are used from CVMFS instead of being rebuilt.

aliDoctor <package-name> -c snddist

Provide troubleshooting information and hints on which packages can be used from the system for <package-name> and its dependencies.

alienv enter <package-name> /latest -c snddist

Enter an environment with <package-name> and its dependencies.

For more information on using aliBuild, see its documentation (note: some things are ALICE specific and will not apply to SND@LHC software).

On lxplus or systems with CVMFS

On lxplus or any CC7/CC8 machine with access to CVMFS, you can do the following:

1. Make sure you can access the SNDLHC CVMFS Repository

   ls /cvmfs/sndlhc.cern.ch

2. Source the setUp.sh script

   source /cvmfs/sndlhc.cern.ch/SNDLHC-2023/Jan22/setUp.sh (recommended latest version)

3. If you don't want to modify the sndsw package, skip step 3:

   git clone https://github.com/SND-LHC/sndsw

   This gives you by default the master branch of the software. In case, you want to use a specific branch:

   cd sndsw
   git checkout <branch>
   cd ..

4. Build the software using aliBuild

   aliBuild build sndsw -c $SNDDIST --always-prefer-system

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

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

5. Load the environment

   alienv enter sndsw/latest

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

eval alienv load sndsw/latest

If you modify sndsw, simply repeat step 4 from sndsw's parent directory.

Note for Ubuntu 20.04: currently there is a version (March 2022) of CVMFS built with Ubuntu 20.04. However, standard ubuntu 20.04 still have python2 has default, while we moved to python3. So, it is needed to do

sudo apt-get install python-is-python3

Then, the above procedure works

On systems without access to CVMFS

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

1. Clone the snddist, which containts the recipes to build sndsw and it's dependencies:

   git clone https://github.com/SND-LHC/snddist.git

2. If you don't want to modify the sndsw package, skip step 2:

   git clone https://github.com/SND-LHC/sndsw

   This gives you by default the master branch of the software. In case, you want to use a specific branch:

   cd sndsw
   git checkout <branch>
   cd ..

3. Install aliBuild

   pip3 install --user alibuild

   and make sure that it is in your $PATH, or if you are administrator:

   sudo pip3 install alibuild

4. Build the software using aliBuild

   aliBuild build sndsw -c snddist

   If you run into any problems, aliDoctor can help determine what the problem is.

5. Load the environment

   alienv enter sndsw/latest

Run Instructions

updated 11 October 2021 for the use with raw data

Set up the bulk of the environment from CVMFS.

source /cvmfs/sndlhc.cern.ch/latest/setUp.sh 

Load your local sndsw environment.

alienv enter (--shellrc) sndsw/latest 

python $SNDSW_ROOT/shipLHC/run_simSND.py  --Ntuple  -n 100 -f /eos/experiment/sndlhc/MonteCarlo/FLUKA/muons_up/version1/unit30_Nm.root  --eMin 1.0
>> Macro finished succesfully. 

Output files are sndLHC.Ntuple-TGeant4.root (events) and geofile_full.Ntuple-TGeant4.root (setup)

Run the event display:

python -i $SNDSW_ROOT/macro/eventDisplay.py -f sndLHC.Ntuple-TGeant4.root -g geofile_full.Ntuple-TGeant4.root 
// use SHiP Event Display GUI 
Use quit() or Ctrl-D (i.e. EOF) to exit 

a) Use the GUI to display events: SHiP actions / next event

b) Hoovering over trajectory will display additional information :

c) At python prompt: sTree.MCTrack.Dump() will display info about all MC particles

Use cases covered by run_simSND.py:

1. Transport muons, output of FLUKA simulation, to TI18 and the detector. Positive and negative muons, up and down crossing angles, exist. Possible options are setting minimum energy for transporting particles, transport only muons, increase EM cross sections of muons.

python $SNDSW_ROOT/shipLHC/run_simSND.py  --Ntuple  -n nEvents  -f /eos/experiment/sndlhc/MonteCarlo/FLUKA/muons_up/version1/unit30_Nm.root  --eMin ecut

2. Muon deep inelastic scattering events, produced with pythia6, and then positioned in T18 and transported by Geant4:

python  $SNDSW_ROOT/shipLHC/run_simSND.py  -F --MuDIS -n nEvents -f  /eos/experiment/sndlhc/MonteCarlo/Pythia6/MuonDIS/muonDis_1001.root  --eMin ecut

3. WORK ONGOING: Neutrino events, produced by GENIE, sndsw/macro/makeSNDGenieEvents.py, and then positioned in T18 and transported by Geant4:

python  $SNDSW_ROOT/shipLHC/run_simSND.py  --Genie -n nEvents -f ...

Digitization of MC data:

1. Convert MC points to detector hits. Input required, data from simulation together with the geometry file created when running simulation. New objects created are Digi_ScifiHits together with Cluster_Scifi and Digi_MuFilterHit, and in parallel objects to make the link to the original MC points, Digi_MuFilterHits2MCPoints and Digi_ScifiHits2MCPoints.

python $SNDSW_ROOT/shipLHC/run_digiSND.py   -f sndLHC.Ntuple-TGeant4.root -g geofile_full.Ntuple-TGeant4.root

Converting raw data to sndsw format:

1. Runs the calibration procedure and creates Digi_ScifiHits and Digi_MuFilterHit with signal and time information from SiPM channels.

python $SNDSW_ROOT/shipLHC/rawData/convertRawData.py -p /eos/experiment/sndlhc/testbeam/scifi-cosmic/ -r 35

2. For the MuFilter testbeam in H8, a specialized script needs to be used to also synchronize the readout boards.

python $SNDSW_ROOT/shipLHC/rawData/convertRawData_convertRawData_muTestbeam.py -p /eos/experiment/sndlhc/testbeam/MuFilter/TB_data_commissioning/ -n 5000000  -r 91

Example scripts for accessing the raw data and making histograms:

1. For scifi data:

python $SNDSW_ROOT/shipLHC/rawData/scifiHitMaps.py -p /eos/experiment/sndlhc/testbeam/scifi/sndsw/ -r 1 -g geofile_full.Ntuple-TGeant4.root 

2. For MuFi data:

python $SNDSW_ROOT/shipLHC/rawData/mufiHitMaps.py -p /eos/experiment/sndlhc/testbeam/MuFilter/TB_data_commissioning/sndsw/ -r 90 -g geofile_full.Ntuple-TGeant4.root 

Two methods implemented, hitMaps(Nev = -1) and eventTime().

simple 2d event display with Scifi tracking:

1. Use method loopEvents(start=0,save=False,goodEvents=False,withTrack=False)

python $SNDSW_ROOT/shipLHC/scripts/scifiHitMaps.py -p /eos/experiment/sndlhc/testbeam/scifi/sndsw/ -r 1 -g geofile_full.Ntuple-TGeant4.root 

Docker Instructions

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

1. Build an docker image from the provided Dockerfile:

   git clone https://github.com/SND-LHC/sndsw.git
   cd sndsw
   docker build -t sndsw .

2. Run the sndsw docker image:

   docker run -i -t --rm sndsw /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 \
   sndsw /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.

Contributing Code

All packages are managed in Git and GitHub. Please either use the web interface to create pull requests or issues, or send patches via email.

If your changes would also benefit FairShip, please consider making a pull-request for your changes there. We can then pick up the changes from FairShip automatically.