Singularity is a container solution created for scientific and application workloads. The objective of this guide is to demonstrate how to use Singularity on the CHPC Lengau cluster.

The diagram below is a visual depiction of the Singularity work-flow process. This process can be categorised into two environments:

• Build environment: for testing and building containers (user needs sudo privileges). This would ideally be the user's workstation or VM.
• Production environment where users run containers. E.g (Lengau Cluster)

For more details please read the user manual: https://www.sylabs.io/guides/2.6/user-guide/index.html

Based on the image above, it is clear that the CHPC Lengau cluster will only provide a production (container execution) environment for the Singularity workflow. Therefore, users are only allowed to run already built containers images on this platform.

NB: Please note that the computes nodes on Lengau do not have access to the internet, which means that users will not be able to use the Singularity pull command. However, users can use the scp.chpc.ac.ca node to facilitate the transfer of images to and from the platform.

Using Singularity on Lengau can be summarised as a two-stage process:

1. Transferring images to the Lengau cluster: Users can use cp, SCP, rsync or FTP to copy their images on the cluster using the node: scp.chpc.ac.za. They can also use the Singularity pull command on the same node.
2. Container Execution Users can only interact with the computes nodes through the scheduler using the qsub command. Users also need to load the chpc/singularity module to enable execution of Singularity commands.

Below is an example of a recipe file for building a Centos-7 image and installing mpich-3.2.1 inside that image. This also includes an MPI example code for hello world programs.

BootStrap: yum
OSVersion: 7
MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/
Include: yum
UpdateURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/updates/$basearch/
%runscript
    echo "This build MPICH-3.2.1 onto the base Centos7"
%post
    echo -e "Installing vim, wget, bzip2, Development Tools and Infiniband Support"
    yum -y install vim wget bzip2 git unzip
    yum -y groupinstall "Development Tools"
    yum -y groupinstall "Infiniband Support"
    yum -y update
    echo -e "Compiling mpich-3.2.1"
    pushd /tmp
    if [ ! -f /tmp/mpich-3.2.1.tar.gz ]; then
        wget http://www.mpich.org/static/downloads/3.2.1/mpich-3.2.1.tar.gz
    fi
    tar -xf mpich-3.2.1.tar.gz
    cd mpich-3.2.1
    ./configure --prefix=/usr/local
    make -j 4
    make install
    mpicc examples/hellow.c -o /usr/local/bin/hellow
    popd
    rm -rf /tmp/mpich-3.2.1
    echo -e "Install another Hello work"
    cd /tmp
    if [ ! -f /tmp/gh-pages.zip ]; then
       wget https://github.com/wesleykendall/mpitutorial/archive/gh-pages.zip
    fi
    unzip gh-pages.zip
    cd  mpitutorial-gh-pages/tutorials/mpi-hello-world/code/
    make clean
    make
    cp mpi_hello_world /usr/local/bin/
%runscript
    # used with singularity run
    echo "Running hello world"
    exec hellow
    # Alternative mpi singularity run
    echo "Running hello world"
    exec mpi_hello_world

Using the definition file above we can build a Singularity image on a system with singularity install and we have sudo privileges (i.e personal work station or VM). Use the command below to build the image: sudo singularity build $image_name $definition_file where $image_name is the name of the image your building and $definition_file with the filename for code provided above.

Once we've built our image we can then transfer it to the Lengau cluster.

rsync -azP $image_name $username@lengau.chpc.ac.za:$DIR_PATH

where $DIR_PATH is the location you want to store your image.

1. Login to the cluster
2. Submit your job using the qsub command and the resources you need