Use Cases

Linux Administrator

If you are a linux administrator, you likely want to clone the repository directly (or use a release when they are available). Then you can install modules for your users from the local registry folder, create your own module files (and contribute them to the repository if they are useful!) and update the module_base to be where you install modules.

# an absolute path
$ shpc config module_base:/opt/lmod/shpc

If you pull or otherwise update the install of shpc, the module files will update as well. For example, if you start first by seeing what modules are available to install:

$ shpc show

And then install a module to your shpc modules directory:

$ shpc install tensorflow/tensorflow
Module tensorflow/tensorflow:2.2.2 was created.

Make sure that lmod knows about the folder

$ module use /opt/lmod/shpc

(And likely if you administer an Lmod install you have your preferred way of doing this). And then you can use your modules just as you would that are provided on your cluster.

$ module load tensorflow/tensorflow/2.2.2

You should then be able to use any of the commands that the tensorflow container provides, e.g., python and python-shell:

$ python
Python 3.6.9 (default, Oct 8 2020, 12:12:24)
[GCC 8.4.0] on linux
Type “help”, “copyright”, “credits” or “license” for more information.
>>> quit()

$ tensorflow-tensorflow-shell
________                _______________
___ __/__________________________________ ____/__ /________   __
__ / _ _ \_ __ \_ ___/ __ \_ ___/_ /_  __ /_ __ \_ | /| / /
_ /  / __/ / / /(__ )/ /_/ / /  _ __/  _ / / /_/ /_ |/ |/ /
/_/  \___//_/ /_//____/ \____//_/  /_/   /_/ \____/____/|__/
You are running this container as user with ID 34633 and group 34633,
which should map to the ID and group for your user on the Docker host. Great!
Singularity> quit()

If you want to inspect aliases available or singularity commands to debug:

$ module spider tensorflow/tensorflow/2.2.2/module
 tensorflow/tensorflow/2.2.2: tensorflow/tensorflow/2.2.2/module
  This module can be loaded directly: module load tensorflow/tensorflow/2.2.2/module
   This module is a singularity container wrapper for tensorflow/tensorflow v2.2.2
   Commands include:
    - tensorflow-tensorflow-shell:
           singularity shell -s /bin/bash /home/shpc-user/singularity-hpc/modules/tensorflow/tensorflow/2.2.2/tensorflow-tensorflow-2.2.2-sha256:e2cde2bb70055511521d995cba58a28561089dfc443895fd5c66e65bbf33bfc0.sif
    - python:
           singularity exec --nv /home/shpc-user/singularity-hpc/modules/tensorflow/tensorflow/2.2.2/tensorflow-tensorflow-2.2.2-sha256:e2cde2bb70055511521d995cba58a28561089dfc443895fd5c66e65bbf33bfc0.sif /usr/local/bin/python”)

Cluster User

If you are a cluster user, you can easily install shpc to your own space (e.g., in $HOME or $SCRATCH where you keep software) and then use the defaults for the lmod base (the modules folder that is created alongside the install) and the registry. You can also pull the repository to get updated registry entries. If you haven’t yet, clone the repository:

$ git clone
$ cd singularity-hpc

You can then see modules available for install:

$ shpc show

And install a module to your local modules folder.

$ shpc install python
Module python/3.9.2-slim was created.

Finally, you can add the module folder to those that lmod knows about:

$ module use $HOME/singularity-hpc/modules

And then you can use your modules just as you would that are provided on your cluster.

$ module load python/3.9.2-slim

An error will typically be printed if there is a conflict with another module name, and it’s up to you to unload the conflicting module(s) and try again. For this module, since we didn’t use a prefix the container python will be exposed as “python” - an easier one to see is “python-shell” - each container exposes a shell command so you can quickly get an interactive shell. Every installed entry will have it’s named suffixed with “shell” if you quickly want an interactive session. For example:

$ python-shell

And of course running just “python” gives you the Python interpreter. If you don’t know the command that you need, or want to see help for the module you loaded, just do:

$ module spider python/3.9.2-slim/module
python/3.9.2-slim: python/3.9.2-slim/module
  This module can be loaded directly: module load python/3.9.2-slim/module
   This module is a singularity container wrapper for python v3.9.2-slim
   Commands include:
    - python-shell:
       singularity shell -s /bin/bash /home/shpc-user/singularity-hpc/modules/python/3.9.2-slim/python-3.9.2-slim-sha256:85ed629e6ff79d0bf796339ea188c863048e9aedbf7f946171266671ee5c04ef.sif
    - python:
       singularity exec /home/shpc-user/singularity-hpc/modules/python/3.9.2-slim/python-3.9.2-slim-sha256:85ed629e6ff79d0bf796339ea188c863048e9aedbf7f946171266671ee5c04ef.sif /usr/local/bin/python”)

The above not only shows you the description, but also the commands if you need to debug. If you want to see metadata about the container (e.g., labels, singularity recipe) then you can do:

$ module whatis python/3.9.2-slim
python/3.9.2-slim/module             : Name    : python/3.9.2-slim
python/3.9.2-slim/module             : Version   : module
python/3.9.2-slim/module             : URL     :
python/3.9.2-slim/module             : Singularity Recipe  : bootstrap: docker
from: python@sha256:85ed629e6ff79d0bf796339ea188c863048e9aedbf7f946171266671ee5c04ef
python/3.9.2-slim/module             :  : amd64
python/3.9.2-slim/module             :  : Sunday_4_April_2021_19:56:56_PDT
python/3.9.2-slim/module             : org.label-schema.schema-version  : 1.0
python/3.9.2-slim/module             : org.label-schema.usage.singularity.deffile.bootstrap  : docker
python/3.9.2-slim/module             : org.label-schema.usage.singularity.deffile.from  : python@sha256:85ed629e6ff79d0bf796339ea188c863048e9aedbf7f946171266671ee5c04ef
python/3.9.2-slim/module             : org.label-schema.usage.singularity.version  : 3.7.1-1.el7

If your workflow requires knowledge of the local path to the sif image, this information can be output by using the “container” suffixed alias:

$ python-container

or equivalently by accessing the value of the SINGULARITY_CONTAINER environment variable (or PODMAN_CONTAINER for each of Podman and Docker).

Adding Options

By default, some of the commands will come with singularity options. For example, a container intended for gpu will have a features: gpu set to true, and this will add the --nv flag given that the user or cluster settings file has that feature enabled. However, it could be the case that you want to define custom options at the time of use. In this case, you can export the following custom environment variables to add them:

SINGULARITY_OPTS: will provide additional options to the base Singularity command, such as --debug SINGULARITY_COMMAND_OPTS: will provide additional options to the command (e.g., exec), such as --cleanenv or --nv.

Custom Images that are Added

If you add a custom image, the interaction is similar, whether you are a cluster user or administrator. First, let’s say we pull a container:

$ singularity pull docker://vanessa/salad

And we add it to our unique namespace in the modules folder:

$ shpc add salad_latest.sif vanessa/salad:latest

We can again load the custom module:

$ module load vanessa/salad/latest

Since we didn’t define any aliases via a registry entry, the defaults provided are to run the container (the squashed unique resource identifier, vanessa-salad-latest or the same shell, vanessa-salad-latest-shell. Of course you can check this if you don’t know:

$ module spider vanessa/salad/latest/module
 vanessa/salad/latest: vanessa/salad/latest/module
  This module can be loaded directly: module load vanessa/salad/latest/module
   This module is a singularity container wrapper for vanessa-salad-latest vNone
   Commands include:
    - vanessa-salad-latest-shell:
       singularity shell -s /bin/bash /home/shpc-user/singularity-hpc/modules/vanessa/salad/latest/vanessa-salad-latest-sha256:71d1f3e42c1ceee9c02295577c9c6dfba4f011d9b8bce82ebdbb6c187b784b35.sif
    - vanessa-salad-latest: singularity run /home/shpc-user/singularity-hpc/modules/vanessa/salad/latest/vanessa-salad-latest-sha256:71d1f3e42c1ceee9c02295577c9c6dfba4f011d9b8bce82ebdbb6c187b784b35.sif

And then use them! For example, the command without -shell just runs the container:

$ vanessa-salad-latest
 You think you have problems? I’m a fork.
           // \\
         ^  \\ //  ^
        / \  ) (  / \
        ) (  ) (  ) (
        \ \_/ /\ \_/ /
         \__ _)(_ __/
          \ \ / /
           ) \/ (
           | /\ |
           | )( |
           | )( |
           | \/ |
          /   \

And the command with shell does exactly that.

$ vanessa-salad-latest-shell
Singularity> exit

If you need more robust commands than that, it’s recommended to define your own registry entry. If you think it might be useful to others, please contribute it to the repository!

Pull Singularity Images

Singularity Registry HPC tries to support researchers that cannot afford to pay for a special Singularity registry, and perhaps don’t want to pull from a Docker URI. For this purpose, you can use the Singularity Deploy template to create containers as releases associated with the same GitHub repository, and then pull them down directly with the shpc client with the gh:// unique resource identifier as follows:

$ shpc pull gh://singularityhub/singularity-deploy/0.0.1:latest
$ shpc pull gh://singularityhub/singularity-deploy/0.0.1:salad
$ shpc pull gh://singularityhub/singularity-deploy/0.0.1:pokemon

In the example above, our repository is called singularityhub/singularity-deploy, and in the root we have three recipes:

  • Singularity (builds to latest)
  • Singularity.salad
  • Singularity.pokemon

And in the VERSION file in the root, we have 0.0.1 which corresponds with the GitHub release. This will pull to a container. For example:

$ shpc pull gh://singularityhub/singularity-deploy/0.0.1:latest
singularity pull --name /home/vanessa/Desktop/Code/singularity-hpc/singularityhub-singularity-deploy.latest.sif

And then you are ready to go!

$ singularity shell singularityhub-singularity-deploy.latest.sif

See the Singularity Deploy repository for complete details for how to set up your container! Note that this uri (gh://) can also be used in a registry entry.