MoSDeF Containers

This repository includes Docker files for the Molecular Simulation Design Framework (MoSDeF)

Pre-built Docker containers can be pulled from DockerHub.

Notes

The mosdef_stable image provides the complete MoSDeF software stack and its depdencies plus signac, but does not include the simulation engines that MoSDeF interfaces with. We provide images that build on top of mosdef_stable and also package a single simulation engine.

A summary of of the Docker images are as follows:

Image	Main Software	Notes
mosdef_stable	mBuild, GMSO, Foyer, Signac, Jupyter	Includes the latest conda-forge releases for each MoSDeF package. Uses Python 3.12
mosdef_hoomd_gpu	mosdef_stable + Hoomd v5.2	Compiled for Nvidia GPUs and single-precision. HPMC, DPCD, and MPI are disabled.
mosdef_lammps_gpu	mosdef_stable + Lammps	Compiled for Nvidia GPUs and single-precision. MPI is disabled, and only basic Lammps plugins and features are included.
mosdef_gromacs_gpu	mosdef_stable + Gromacs	Compiled from latest release for Nvidia GPUs and single-precision. MPI is disabled
mosdef_cassandra	mosdef_stable + Cassandra v1.3.1	Cassandra is installed from conda-forge.
mosdef_gomc_gpu	Coming Soon

Quick Examples

Using Docker or Podman

   

Docker Install | Docker Get Started | Podman Install | Podman Get Started

If you want to use these containers on a personal computer (as opposed to a compute cluster), using Docker or an equivalent, such as Podman, would be best.

🐳 Docker Example

Pull the container from DockerHub

docker pull chrisjonesbsu/mosdef-containers:mosdef_stable-2025-04-02

See docker images available locally

docker images

Start an interactive shell with the container

docker run -it chrisjonesbsu/mosdef-containers:mosdef_stable-2025-04-02

🦭 Podman Example

The Podman commands are typically the same as Docker. However, Podman doesn't automatically look to DockerHub for hosted images when using the pull command. You can add docker.io to Podman's registres, or you can explicitly pull from docker.io.

Pull the container from DockerHub

podman pull docker.io/chrisjonesbsu/mosdef-containers:mosdef_stable-2025-04-02

See docker images available locally

podman images

Start an interactive shell with the container

podman run -it chrisjonesbsu/mosdef-containers:mosdef_stable-2025-04-02

Note: Often times, Docker requires running with root privleges (i.e., using sudo).

Using apptainer

Apptainer (formely Singularity) will allow use of these containers in high-performance computer clusters. Using containers for computational scientific research ensures you are following best practices for reproducibility. Apptainer is often available as a module on computer clusters and can be used to pull and run Docker containers. If you only have Singularity available, the commands should be the same, except replace apptainer with singularity.

Pull the container from DockerHub and use it to run a python file

module load apptainer/1.2.5
apptainer pull mosdef_hoomd_gpu.sif docker://chrisjonesbsu/mosdef-containers:mosdef_hoomd_gpu-2025-04-03
apptainer exec --nv mosdef_hoomd_gpu.sif python hoomd_simulation.py

To create a local image file (.sif) the command is apptainer pull name-of-local-image-file source-of-image. The apptainer pull command grabs an image hosted on DockerHub and creates a new file stored locally.

Next, to use the image file, the command is apptainer exec --nv path-to-image-file executable path-to-script where mosdef_hoomd_gpu.sif is the file created by apptailer pull, python hoomd_simulation.py is the command to be ran in the container. The --nv flag is only needed to ensure apptainer passes Nvidia information and resources to the containerized environment.

More HPC and Research-based Examples

The above are simple examples to illustrate how to pull an image and run a command with the image. Examples that are more applicable to performing research are provided in examples. These show how to use apptainer within a slurm submission script or within a signac project. See the README.md files within the examples for each for more information.