docs/singularity.md

   1 # What is a container?
   2
   3 When running in a container, you have access to your files as usual, but the operating system and intstalled software are replaced by those in the container.
   4
   5 Container is somewhat like a different computer just for you, similar to a virtual machine.
   6
   7 # How do we use containers?
   8
   9 A system administrator can build a containter with installed software instead of installing it directly on the system. This allows to keep everything the software needs nicely together, and to run the software on different nodes, even with different versions of linux, without reinstalling anything.
  10
  11 We are using a type of containers called Singularity, which was developed with HPC in mind. You may have heard about Docker, which is similar.
  12
  13 Software with complicated dependencies is often distributed as singularity containters, with their own runtime environment. Singularity containers are **large** files, many GB. If you bring any containters of your own, pleasee put them in your project directory and **do not store singularity containers in your home directory.**
  14
  15 We often install software requested by users in singularity containers rather than on the system itself to provide the required versions of dependencies, avoid software conflicts, and allow them to run on all of our clusters.
  16
  17 # How do I put software in a container?
  18
  19 Ask and we may be able to build a container for you if we do not have one already. Most of our containers originated this way.
  20
  21 Building a Singularity container requires root privileges, so you can't build a container directly on our systems yourself.
  22 But nothing stops you from setting up your own linux machine with the same version of Singularity we have, building a container, and copying it here.
  23
  24 ## How to use a Singularity container interactively
  25
  26 **Please do not run computationally intensive jobs on the front end machines, math-alderaan or clas-compute.**
  27
  28 So, if you plan to do anything of substance, first ssh to an interactive node (recommended math-colibri-i01 with 1TB memory, or math-score-i01 with a faster and newer cpu). Or, start an [interactive batch job](../clusters_guide/#interactive-jobs), e.g.,
  29
  30     srun -p math-alderaan --time=2:00:0 -n 1 --pty bash -i
  31
  32 will start a slurm job with one code reserved for 2 hours and return with a standard shell prompt. Then start a shell in a container, for example
  33
  34      singularity shell /storage/singularity/tensorflow.sif
  35
  36 and start exploring.
  37
  38 ## How to run Singularity in a slurm batch job
  39
  40 Prepare the commands you want to execute inside the container as a file, say `mycode.sh`, and make the file executable
  41
  42      chmod +x mycode.sh
  43
  44 Then, write a batch job script file that executes your code inside the container,
  45 say `singularity_alderaan_shell.slurm`, like this:
  46
  47      #!/bin/bash
  48      #SBATCH --job-name=singularity
  49      #SBATCH --partition=math-alderaan
  50      #SBATCH --nodes=1                   # Number of requested nodes
  51      #SBATCH --time=1:00:00              # Max wall-clock time
  52      #SBATCH --ntasks=1                  # Total number of tasks over all nodes, max 64*nodes
  53
  54      singularity exec /storage/singularity/container.sif ./mycode.sh
  55
  56 where `container` is the container name. Instead of a shell script, you can use an executable binary such as compiled C code, or call python from inside the container like `python3 mycode.py`, etc. You can also copy your shell script inside the batch script si that you can deal with only one file, like this:
  57
  58      #!/bin/bash
  59      #SBATCH --job-name=singularity
  60      #SBATCH --partition=math-alderaan
  61      #SBATCH --nodes=1                   # Number of requested nodes
  62      #SBATCH --time=1:00:00              # Max wall-clock time
  63      #SBATCH --ntasks=1                  # Total number of tasks over all nodes, max 64*nodes
  64
  65      singularity shell /storage/singularity/container.sif << EOF
  66      echo This is a shell command which gets executed in the singularity container
  67      EOF
  68
  69 Finally, submit the job as usual:
  70
  71      sbatch singularity_alderaan_shell.slurm
  72
  73 If the commands you invoke inside the singularity container can take advantage of
  74 more than one core, you can increase the job parameter `--ntasks` to reserve and use
  75 more cores. **If your singularity job uses lot of memory, please increase --ntasks to
  76 about 8 GB per core even if you may not use the cores. Otherwise, node memory may get
  77 overloaded with unfortunate consequences such as jobs stuck and
  78 nodes down until someone resets them.**
  79
  80 ## How to run Singularity with MPI and on multiple nodes
  81
  82 Not so easy for MPI over the fast interconnect InfiniBand. In future.
  83
  84 ## What containers we have
  85
  86 Containers we have built are in `/storage/singularity`. For convenience, `/storage/singularity/container.sif` points to a sample container.
  87
  88 To see what is in a container, start with a short description which should be provided by every container:
  89
  90      singularity run-help /storage/singularity/container.sif
  91
  92 For more details, you can look how the software in the container was built. This is was done by a script, called definition file, which you can see by
  93
  94      singularity inspect --deffile /storage/singularity/container.sif
  95
  96 You can see that the script is exactly like installing your own Linux machine after you installed a base system from distribution media.
  97
  98 Then start a shell in the container as above, and you can do whatever you normally do to examine softwares and their versions.
  99
 100 Note: Rebuilding a container usually picks up current version of software, so the versions listed below may change when containers are rebuilt.
 101
 102 ### bfctools.sif
 103
 104 Bioinformatics sofware bfctools 1.15.1 for processing and analyzing sequencing data. Based on Ubuntu 20.04 with Development Tools.
 105
 106 ### bio-lowry.sif
 107
 108 Ubuntu 20.04 with Development Tools and biology packages bbmap megahit megabat checkm gtdbtkUbuntu 20.04 with Development Tools and biology packages bbmap megahit megabat checkm gtdbtk.
 109
 110 ### biopython.sif
 111
 112 Biopython 1.78 in Anacoda 3 Python 3.9.13 based on Ubuntu 20.04.
 113
 114 ### cactus-gpu.sif
 115
 116 Imported Docker quay.io/comparative-genomics-toolkit/cactus:v2.5.2-gpu
 117
 118 ### CentOS8-DevelopmentTools.sif
 119
 120 CentOS Linux 8.4.2105, gcc 8.4.1 and standard Development Tools from Centos.
 121
 122 ### cuda-116.sif
 123
 124 Imported Docker nvidia/cuda:11.6.1-devel-ubuntu20.04
 125
 126 ### cuda-120.sif
 127
 128 Ubuntu 22.04 with cuda 12.0, NVIDIA compilers, tensorflow, pytorch, and other common machine learning packages
 129
 130 ### go.sif
 131
 132 The Go language with gcc/gfortran 9 and development tools, based on Ubuntu 20.04
 133
 134 ### mixtures.sif
 135
 136 Custom container for the mixtures project. R 4.1.2 with  raresim, plink2, Python with  regenie, bcftools, pliknk,hapgen2, bedtools. etc., and datasets. Based on Ubuntu 22.04
 137
 138 ### poppler.sif
 139
 140 Container with python3-poppler-qt5, tensorflow, sklearn, matplotlib, keras, keras-tuner, tensorflow_datasets, pdf2image, jupyterhub, jupyter and pandas. No CUDA. Based on Ubuntu 22.04
 141
 142 ### pyscipopt-geopandas.sif
 143
 144 Optimization software [PySCIPOpt](https://pypi.org/project/PySCIPOpt) pyscipopt 4.2.0, ipopt, glpk, pyomo, gurobi, with geopandas in miniconda and Ubuntu 21.04
 145
 146 ### qvina.sif
 147
 148 Modecular chemistry software [QuickVina](https://github.com/QVina/qvina), gcc, gfortran, python3 on Ubuntu 21.04
 149
 150 ### sagemath.sif
 151
 152 [SageMath](https://www.sagemath.org) mathematical sofrware, SAGE 9.5 with R 4.2.1 and Python 3.10.6 on Ubuntu 22.04.
 153
 154 ### saige.sif
 155
 156 Genomic software [saige](https://saigegit.github.io/SAIGE-doc/docs/Installation.html) container from docker image wzhou88/saige:1.1.6, comes with R 3.6.3.
 157
 158 ### tensorflow-1.4-new.sif
 159
 160 Cuda 11, tensorflow 1.4, sklearn, matplotlib, keras, keras-tuner, tensorflow_datasets, pdf2image and pandas, on Ubuntu 20.04
 161
 162 Note: Tensorflow will run with or without GPU, but it will crash python on most colibri nodes because their CPUs and GPUs are too old.
 163
 164 ### tensorflow-v1.4.sif
 165
 166 cuda 11, tensorflow 1.4, sklearn, matplotlib, keras, keras-tuner, tensorflow_datasets, pdf2image and pandas.
 167
 168 ### tensorflow-2.6.0-cuda-1.1.2.sif
 169
 170 NVIDIA nvidia/cuda:11.2.2-base-ubuntu20.04 with Anaconda and cuDNN 8 added.
 171
 172 ### tensorflow.sif
 173
 174 Cuda 11, tensorflow, sklearn, matplotlib, keras, keras-tuner, tensorflow_datasets, pdf2image, jupyterhub, jupyter and pandas.
 175
 176 ### tensorflow_latest-gpu-jupyter.sif
 177
 178 Cuda 11, tensorflow 1.4, sklearn, matplotlib, keras, keras-tuner, tensorflow_datasets, pdf2image and pandas.