How to Use Singularity
===================================

`Singularity <https://docs.sylabs.io/guides/4.2/user-guide/index.html>`_ is a container platform designed for High Performance Computing (HPC) environments. It allows non-root users to run applications using existing container images from container registries such as Docker Hub and NVIDIA NGC.

Creating Container Images (pull)
------------------------------------

You can pull container images from container registries like Docker Hub to create a single-file format ``.sif`` (Singularity Image Format).

- Example of pulling an image from Docker Hub:

.. code-block:: none

   # Pull Ubuntu 24.04 image from Docker Hub to create a .sif file
   $ singularity pull ubuntu_2404.sif docker://ubuntu:24.04

Once completed successfully, ``ubuntu_2404.sif`` is created in the current working directory.

.. attention::

   * Please pull or build container images on the frontend node in advance.
   * Please also download necessary datasets on the frontend node in advance.


.. _singularity_cache_clean_en:

Cleaning the Cache (cache clean)
------------------------------------

When pulling or building container images with Singularity, downloaded layers and metadata are stored in the cache directory under your home directory ( ``~/.singularity/cache`` ).
To prevent exhausting the home directory quota, clean the cache every time after pulling images.

Checking Cached Images
++++++++++++++++++++++++++++++++++++++++++++++++++++++

You can check the current cache usage and stored entries with the ``singularity cache list`` command.

.. code-block:: none

   $ singularity cache list

To see a detailed list, specify the ``-v`` (verbose) option:

.. code-block:: none

   $ singularity cache list -v

Cleaning the Cache
++++++++++++++++++++++++++++++++++++++++++++++++++++++

To remove cached files, use the ``singularity cache clean`` command.

- Interactive cleanup of all cache:

.. code-block:: none

   $ singularity cache clean

When prompted ( ``Do you want to continue? [y/N]`` ), enter ``y`` to proceed.

- Force cleanup of all cache without confirmation:

You can clean all cache entries at once without confirmation by passing the ``--all`` ( ``-a`` ) and ``--force`` ( ``-f`` ) options:

.. code-block:: none

   $ singularity cache clean --all --force


How to Run Containers
------------------------------------

Common commands to execute containers:

.. list-table::
   :header-rows: 1
   :widths: 35, 65

   * - Command
     - Description
   * - ``singularity exec <image.sif> <command>``
     - Executes the specified command inside the container.
   * - ``singularity shell <image.sif>``
     - Starts an interactive shell inside the container.
   * - ``singularity run <image.sif>``
     - Executes the default runscript defined in the container.


Key options:

* ``--nv`` : Enables NVIDIA GPU access inside the container (required on Accelerator Server).
* ``-B <host_path>:<container_path>`` (or ``--bind``): Binds host directories into the container.


Job Script Examples
------------------------------------

Below are job script examples for submitting batch jobs.

Large-scale Parallel Computing Server (CPU)
++++++++++++++++++++++++++++++++++++++++++++++++++++++

Example of running commands inside an Ubuntu container pulled from Docker Hub.

.. code-block:: none

   #!/bin/sh
   #PBS -l select=1:ncpus=4:mem=16gb
   #PBS -q CP_001
   #PBS -N singularity_cpu

   cd $PBS_O_WORKDIR

   singularity exec ubuntu_2404.sif cat /etc/os-release > result.out 2> result.err


Accelerator Server (GPU)
++++++++++++++++++++++++++++++++++++++++++++++++++++++

When running a container that utilizes GPUs, specify the ``--nv`` option.

.. code-block:: none

   #!/bin/sh
   #PBS -l select=1:ncpus=2:ngpus=1:mem=32gb
   #PBS -q CA_001
   #PBS -N singularity_gpu

   cd $PBS_O_WORKDIR

   singularity exec --nv nvidia_container.sif nvidia-smi > result.out 2> result.err