Recovering the image

The GPUMD image is distributed as an Apptainer image (.sif file format). The image is a relocatable and renamable file, so we recommend putting it in a dedicated directory to easily find it. While it can be any directory, in this tutorial we will assume you put it in $HOME/apptainer-images:

mkdir -p $HOME/apptainer-images
apptainer pull $HOME/apptainer-images/gpumd.sif \
  oras://gricad-registry.univ-grenoble-alpes.fr/diamond/apptainer/apptainer-singularity-projects/gpumd.sif:latest

In the rest of this tutorial, we suppose that the image is available at:

$HOME/apptainer-images/gpumd.sif

Input files for the liquid Indium example

To illustrate the different commands, a set of GPUMD input files is provided for a molecular dynamics example in liquid Indium. The files can be downloaded via this link and are as follows:

• run.in is the main GPUMD input file. It defines the simulation protocol and the GPUMD commands to execute.
• model.xyz contains the initial atomic structure used by the simulation.
• nep.txt contains the NEP potential used to describe the interactions in the system.

In this tutorial, we will assume that these files are in the current directory:

ls
# expected files: nep.txt  model.xyz  run.in

Disclaimer

The commands presented here are for using the gpumd executable. To call another executable included in the image, such as nep, use apptainer exec <options> <image> <executable-name>.

One liner command

For impatient folks, here is how to launch the GPUMD liquid Indium example using the container image, previously downloaded and stored in $HOME/apptainer-images/gpumd.sif:

apptainer exec --nv $HOME/apptainer-images/gpumd.sif gpumd

The --nv flag gives the container access to NVIDIA GPU devices and drivers from the host. If you use this image on a system where GPU access is handled differently, adapt this flag to the local Apptainer/GPU configuration.

Detailed usage for the GPUMD container

This section presents different ways to use the GPUMD image. For more details about Apptainer commands, please look at this tutorial.

Using the GPUMD container

To run GPUMD without any container, one would use the following command:

gpumd

where all GPUMD input files, including run.in, model.xyz, and nep.txt, are stored in the current directory.

To do the same inside a container, we can use two equivalent approaches. In each case, we suppose the Apptainer image gpumd.sif can be found at $HOME/apptainer-images/gpumd.sif.

• One can use apptainer exec to execute a specific command in the container.

apptainer exec --nv $HOME/apptainer-images/gpumd.sif gpumd

• Alternatively, one can start an interactive shell inside the container environment.

apptainer shell --nv $HOME/apptainer-images/gpumd.sif
(env) gpumd
...
(env) exit

The exit command returns to the original shell once you are done using the container.

Accessing the other executables in the image

The image also contains nep. For example, to call the nep executable you can use:

apptainer exec --nv $HOME/apptainer-images/gpumd.sif nep

For the expected input files and options of gpumd and nep, please refer to the GPUMD documentation.

Display help and metadata

To display the container’s help message, supposing the image is stored at $HOME/apptainer-images/gpumd.sif:

apptainer run-help $HOME/apptainer-images/gpumd.sif

To display the container’s metadata, such as code owner, version, or image author:

apptainer inspect $HOME/apptainer-images/gpumd.sif

Partial or total isolation

By default, Apptainer does not fully isolate the container from the host system. One can either have partial or total isolation using respectively the flags --no-mount or --no-home and --containall (see this link for more information).

Whenever --containall is activated, the directory on the host machine containing the GPUMD input files cannot be accessed from the container unless it is explicitly mounted.

apptainer exec --nv --containall $HOME/apptainer-images/gpumd.sif gpumd # run.in not found!

It is then required to manually mount the directory containing run.in, model.xyz, and nep.txt using the --bind flag. For instance, if the input files are in the current directory:

apptainer exec \
  --nv \
  --containall \
  --bind $PWD:/work \
  --pwd /work \
  $HOME/apptainer-images/gpumd.sif \
  gpumd

Exercises

First exercise

How to recover the GPUMD container image from the registry and store it in $HOME/apptainer-images/gpumd.sif?

Data

• The image must be stored at: $HOME/apptainer-images/gpumd.sif
• The image is available from the ORAS registry address shown in this tutorial.

Example of a possible answer:

mkdir -p $HOME/apptainer-images
apptainer pull $HOME/apptainer-images/gpumd.sif \
  oras://gricad-registry.univ-grenoble-alpes.fr/diamond/apptainer/apptainer-singularity-projects/gpumd.sif:latest

Second exercise

How to use the container image to run the GPUMD liquid Indium example?

Data

• The image is located at: $HOME/apptainer-images/gpumd.sif
• Input files nep.txt, model.xyz, and run.in are located in the current directory: $PWD

Possible answer:

• apptainer exec --nv $HOME/apptainer-images/gpumd.sif gpumd

Third exercise

How to use the container image to run the GPUMD liquid Indium example while fully isolating the container from the host system?

Data

• The image is located at: $HOME/apptainer-images/gpumd.sif
• Input files nep.txt, model.xyz, and run.in are located at: $HOME/gpumd-examples/liquid-indium/

Example of a possible answer:

apptainer exec \
  --nv \
  --containall \
  --bind $HOME/gpumd-examples/liquid-indium:/work \
  --pwd /work \
  $HOME/apptainer-images/gpumd.sif gpumd

Fourth exercise

How to call the nep executable included in the same image?

Data

• The image is located at: $HOME/apptainer-images/gpumd.sif

Example of a possible answer:

apptainer exec --nv $HOME/apptainer-images/gpumd.sif nep