Use singularity

Install singularity

Eic image require singularity > 3.0

The oficial installation instructions have many steps.

If you have ubuntu, there is a debian repo with 3.5.2 version, which works pretty nicely (You will have to install dependencies, it will print them…)

sudo apt install containernetworking-plugins
sudo dpkg -i singularity-container_3.5.2+ds1-1_amd64.deb

Please don’t install NeuroDebian repo from the repo as it holds v2.6 and eic image require singularity > 3.0.

Install work environment

The below command automatically creates the right working environment for detector development and running the reconstruction. It checks if there are CVMFS images available (which is true for JLab and BNL farms) and links them or downloads images (which is a scenario for users laptops). It also creates eic_shell with the right environment setup, prepares the current dir to work with detector or etc.

# Easy to remember link:
curl -L | bash

# Which is an alias to:
curl | bash checks if it is run on BNL or JLab farms, so existing CVMFS images are used and installation is almost instant. On local systems singularity images will be downloaded.

It might be handy to copy locally and control where singularity images are being copied, disable CVMFS behaviour, and other parameters:

curl -L -o
chmod +x
./ --help




Working directory to deploy the environment (D: /home/romanov/anl)


Change tmp directory (D: /tmp)


Disable check for local CVMFS (D: enabled)


Container version (D: jug_xl)


Version to install (D: nightly)


Print this message

Example of controlling the container version and image location:

# installs testing variant and stores image at /mnt/work/images
# (!) one has to create <prefix>/local/lib for images
mkdir -p /mnt/work/images/local/lib/
./ -v testing -p /mnt/work/images

Detector simulation

After the installation you should have an executable script named eic-shell which basically just runs singularity setting the proper environment (more information about the script is below)

Precompiled detector

The jug_xl container comes with precompiled detecor repository. It could be used out of the box for simulations or even changing detector parameters that doesn’t require recompilation.

The precompiled detector is installed in /opt/detector directory. And can be used like this:

# Setup the proper detector environemnt
source /opt/detector/

# Run particle gun simulation
npsim -N2 --compactFile=$DETECTOR_PATH/athena.xml --random.seed 1 --enableGun 2*GeV --gun.thetaMin 0*deg --gun.thetaMax 90*deg --gun.distribution uniform --outputFile ~/test.root

Clone detector from repository

git clone
git clone
ln -s ../ip6/ip6 athena/ip6

# Build athena
mkdir athena/build && cd athena/build
cmake --build ./ --target all -- -j 8
cmake --install ./
cd -

# Build IP6
mkdir ip6/build && cd ip6/build
cmake --build ./ --target all -- -j 8
cmake --install ./
cd -

# Test run geometry browser:
dd_web_display athena/athena.xml

# Test run particle gun:
npsim -N2 --compactFile=athena/athena.xml --random.seed 1 --enableGun 2*GeV --gun.thetaMin 0*deg --gun.thetaMax 90*deg --gun.distribution uniform --outputFile ~/test.root

Advanced information


For farms like at BNL or JLab the images are automatically replicated to CVMS:


# example to run
singularity run /cvmfs/

eic-shell explained

There are actually two eic-shell scripts. One is created by the install scripts and the other lives in the container.

The one outside the container just sets ATHENA_PREFIX and runs singularity like:

# $PREFIX here is where you installed everything (by default where executed)
singularity exec $PREFIX/local/lib/jug_xl-nightly.sif eic-shell [email protected]

The eic-shell inside the container loads the proper environemnt and SHELL look correctly

## Properly setup environment
. /etc/

# What eic-env does in the end is

# Run bash shell