Table of Contents

• Introduction
  • Contact and communication
  • Branches
• Build instructions
  • On lxplus or systems with CVMFS
  • On systems without access to CVMFS
• Run Instructions
• Development
  • How to keep branches up to date
  • How to contribute code
• Docker Instructions

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.

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.

master

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

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

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 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/Aug30/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 --default release

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 --no-refresh)

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

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 --default release

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

5. Load the environment

   alienv enter sndsw/latest

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

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 ...

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

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

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().

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 

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.

To update one's local copy of a branch with the latest modifications of that branch on the upstream repository do:

cd sndsw
git checkout <branch>
git pull --rebase
cd ..

and build the software as usual per the Build instructions.

While working on your local copy of a feature branch, it is possible that the upstream master software changes (e.g. because a pull request was merged into master). Then one propagates the updates of the upstream master to the local branch (master -> branch) doing:

cd sndsw
git checkout master
git pull --rebase
git checkout <branch>
git pull --rebase # skip this step if the branch only exists locally
git rebase -i master
cd ..

This will put all commits of the feature branch on top of the master commits. Note that before the rebase the local feature branch was updated via git pull --rebase too in case it changed on the upstream repository.

If the master and the local branch both change the same line(s) in a file(s), a conflict arises. Don't panic! Follow the command-line instructions to resolve them or seek help through the snd-software mailing list or the Software and Analysis Mattermost channel. One can verify the commit history reading the git log or inspecting via the graphical tool typing gitk.

After solving any encountered conflict, build the updated branch as per the Build instructions.

Following a rebase and after solving conflicts, to push one's local changes to the feature branch on the upstream repository do:

git push --force-with-lease --set-upstream origin <branch>

Follow the link for further reading why we use --force-with-lease flag.

Proposals for contributions to any target branch are made using Pull requests. Furthermore, all Pull requests to the master branch on the upstream repository go through a review process by the sndsw core-developers. To make a Pull request, follow the guidelines below:

1. Prepare you feature branch and commit all your updates/fixes.
2. Update the branch and take care of potential conflicts, as described above
3. Go online to the sndsw Pull request webpage and click on New pull request. Follow through the fields and verify the request goes from branch to the desired branch of SND-LHC/sndsw, i.e. base:target_branch <- compare:branch
4. Leave a message explaining your changes, the need for them, etc. For Pull requests to the master branch:
5. On the right panel, under the Reviewers heading one can chose who should review the code, e.g. the expert for a syb-system or topic, or someone who you have discussed the changes with. Otherwise, the default is core-developers.
6. Create the Pull request.

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.