docs/howto/use_singularity.md

0001 # Use singularity
0002
0003
0004 ## Install singularity
0005
0006
0007 Eic image require singularity \> 3.0
0008
0009 If you use Debian sid, you may be able to install `singularity-container`. If you use Ubuntu or Red Hat, the `deb` and `rpm` packages at https://github.com/sylabs/singularity/releases/ may be useful.
0010
0011 The [official installation instructions](https://docs.sylabs.io/guides/latest/user-guide/quick_start.html#quick-installation-steps) may be useful for other operating systems.
0012
0013 ## Install work environment
0014
0015 The below command automatically creates the right working environment
0016 for detector development and running the reconstruction. It checks if
0017 there are CVMFS images available (which is true for JLab and BNL farms)
0018 and links them or downloads images (which is a scenario for users
0019 laptops). It also creates eic\_shell with the right environment setup,
0020 prepares the current dir to work with detector or etc.
0021
0022 ```bash
0023 curl -L https://get.epic-eic.org | bash
0024 ```
0025
0026 This checks if it is run on BNL or JLab farms, so existing
0027 CVMFS images are used and installation is almost instant. On local
0028 systems singularity images will be downloaded.
0029
0030 It might be handy to copy install.sh locally and control where
0031 singularity images are being copied, disable CVMFS behaviour, and other
0032 parameters:
0033
0034 ```bash
0035 curl -L https://get.epic-eic.org > install.sh
0036 chmod +x install.sh
0037 ./install.sh --help
0038 ```
0039
0040 | Flag            | Description                                                        |
0041 |-----------------|--------------------------------------------------------------------|
0042 | -p,\--prefix    | Working directory to deploy the environment (D: /home/romanov/anl) |
0043 | -t,\--tmpdir    | Change tmp directory (D: /tmp)                                     |
0044 | -n,\--no-cvmfs  | Disable check for local CVMFS (D: enabled)                         |
0045 | -c,\--container | Container version (D: jug\_xl)                                     |
0046 | -v,\--version   | Version to install (D: nightly)                                    |
0047 | -h,\--help      | Print this message                                                 |
0048
0049 Example of controlling the container version and image location:
0050
0051 ```bash
0052 # installs testing variant and stores image at /mnt/work/images
0053 # (!) one has to create <prefix>/local/lib for images
0054 mkdir -p /mnt/work/images/local/lib/
0055 ./install.sh -v testing -p /mnt/work/images
0056 ```
0057
0058 ## Select detector
0059
0060 After the installation you should have an executable script named
0061 **eic-shell** which basically just runs singularity setting the proper
0062 environment (more information about the script is below)
0063
0064 ### Precompiled detector
0065
0066 The jug\_xl container comes with precompiled detecor repository. It
0067 could be used out of the box for simulations or even changing detector
0068 parameters that doesn\'t require recompilation.
0069
0070 The precompiled detector is installed in **/opt/detector** directory.
0071 And can be used like this:
0072
0073 ```bash
0074 # Setup the proper detector environment
0075 source /opt/detector/epic-main/bin/thisepic.sh
0076
0077 # Run particle gun simulation
0078 ddsim -N2 --compactFile=$DETECTOR_PATH/epic.xml --random.seed 1 --enableGun --gun.energy 2*GeV --gun.thetaMin 0*deg --gun.thetaMax 90*deg --gun.distribution uniform --outputFile ~/test.root
0079 ```
0080
0081
0082 ## Advanced information
0083
0084
0085 ### CVMFS
0086
0087 For farms like at BNL or JLab the images are automatically replicated to
0088 CVMS:
0089
0090 ```bash
0091 /cvmfs/singularity.opensciencegrid.org/eicweb/eic_xl*
0092
0093 # example to run
0094 singularity run /cvmfs/singularity.opensciencegrid.org/eicweb/eic_xl:nightly
0095 ```
0096
0097 ### eic-shell explained
0098
0099 There are actually two eic-shell scripts. One is created by the install
0100 scripts and the other lives in the container.
0101
0102 The one outside the container just sets ATHENA\_PREFIX and runs
0103 singularity like:
0104
0105 ```bash
0106 # $PREFIX here is where you installed everything (by default where install.sh executed)
0107 export EIC_SHELL_PREFIX=...
0108 export SINGULARITY_BINDPATH=/home
0109 singularity exec $PREFIX/local/lib/eic_xl-nightly.sif eic-shell $@
0110 ```
0111
0112 The **eic-shell** inside the container loads the proper environment and
0113 SHELL look correctly
0114
0115 ```bash
0116 ## Properly setup environment
0117 . /etc/eic-env.sh
0118
0119 # What eic-env does in the end is
0120 export LD_LIBRARY_PATH=$EPIC_PREFIX/lib:$LD_LIBRARY_PATH
0121 export PATH=$EPIC_PREFIX/bin:$PATH
0122 ```