1.. _container_singularity:
2
3Singularity
4===========
5
6`Singularity <https://sylabs.io/singularity/>`_ containers are more suitable
7for use in traditional multi-user HPC environments, and are generally easier
8to use than Docker containers for running straightforward applications.
9Processes in a Singularity container run as the current user so there are fewer
10security concerns, and the current directory is mounted by default, so binding
11volumes is unnecessary.
12
13For convenience, a SIF-format Singularity container (for use with
14Singularity 3.0 and above) can be used to run Python scripts that make use of
15OSKAR without needing to compile or install any code.
16The SIF file can be downloaded from the
17`OSKAR release page <https://github.com/OxfordSKA/OSKAR/releases>`_
18and run with the ``singularity exec`` command, which takes the form:
19
20.. code-block:: bash
21
22   singularity exec [flags] <container_path> <app_name> <arguments>...
23
24Use the ``--nv`` flag to enable NVIDIA GPU support in Singularity, if
25applicable.
26
27Note also that Singularity will mount the home directory into the container by
28default, unless configured otherwise. If you have packages installed in your
29home area that should be kept isolated from those in the container (for
30example, because of conflicting packages or Python versions, or if you see
31other errors caused by trying to load wrong versions of shared libraries when
32starting the container) then it may be necessary to disable this either by
33using the ``--no-home`` flag, or re-bind the home directory in the container
34to somewhere other than your actual $HOME using the ``-H`` flag (for example,
35perhaps with ``-H $PWD``).
36
37As an example, to run the ``hello-world.py`` Python script
38(from the :ref:`"hello world" example <example_hello_world>`)
39and a container image file ``OSKAR-Python3.sif`` (both in the current
40directory) on a GPU use:
41
42.. code-block:: bash
43
44   singularity exec --nv ./OSKAR-Python3.sif python3 hello-world.py
45
46Similarly, to run the application ``oskar_sim_interferometer``
47with a parameter file ``settings.ini`` in the current directory, use:
48
49.. code-block:: bash
50
51   singularity exec --nv ./OSKAR-Python3.sif oskar_sim_interferometer settings.ini
52
53Running a Singularity container is conceptually similar to running a process,
54so this command can be included in a SLURM script and run on a GPU node using
55a standard scheduler.
56