MC/DC Container Guide¶
What Are Containers?¶
A container is a lightweight, portable package that bundles an application together with everything it needs to run: code, libraries, system tools, and settings. Think of it like a shipping container — no matter what ship (computer) carries it, the contents inside stay the same.
Why does this matter for MC/DC?
Installing MC/DC requires Python, MPI, Numba, and many other dependencies. Getting all of these working together — especially on HPC systems where you don’t have admin access — can be painful. A container solves this by giving you a pre-built environment where everything is already installed and tested.
Tested Platforms¶
System |
OS |
Arch |
Container Tool |
Status |
|---|---|---|---|---|
MacBook Pro |
macOS 26.3 |
arm64 |
Docker 29.2.0 |
✓ |
Tuolumne |
RHEL 8.10 |
x86_64 |
Podman 4.9.4 |
✓ |
Dane |
RHEL 8.10 |
x86_64 |
Podman 4.9.4 |
✓ |
Tioga |
RHEL 8.10 |
x86_64 |
Podman 4.9.4 |
✓ |
COE (OSU) |
Rocky 8.10 |
x86_64 |
Apptainer 1.4.5 |
✓ |
All platforms produce identical containers: Debian 13, Python 3.11, MPICH 4.2.1, MC/DC 0.12.0.
Getting Started (New Users)¶
This section is for anyone who just wants to run MC/DC in a container. No prior container experience needed.
Step 1: Pull the Pre-Built Image¶
You don’t need to build anything. A ready-to-use image is available on the GitHub Container Registry.
Local Machine (Docker)
First, install Docker Desktop if you haven’t already. Then open a terminal and run:
docker pull ghcr.io/cement-psaap/mcdc:dev
docker run --rm -it ghcr.io/cement-psaap/mcdc:dev
You are now inside the container. Try:
python -c "import mcdc; print('MC/DC OK')"
Type exit to leave the container.
LLNL Systems — Tuolumne, Tioga, Dane (Podman)
Podman is already installed on LLNL systems. It works just like Docker.
podman pull ghcr.io/cement-psaap/mcdc:dev
podman run --rm -it ghcr.io/cement-psaap/mcdc:dev
Note
If you see lsetxattr: operation not supported,
see LLNL Storage Setup in Part 2.
OSU Systems — COE (Apptainer)
Apptainer is already installed on COE.
apptainer build --sandbox mcdc_sandbox docker://ghcr.io/cement-psaap/mcdc:dev
apptainer exec mcdc_sandbox python -c "import mcdc; print('MC/DC OK')"
Note
If apptainer pull fails with “Out of memory”, use --sandbox.
Step 2: Run Your Simulation¶
Docker / Podman
docker run --rm -v $(pwd):/work -w /work mcdc:dev python input.py
docker run --rm mcdc:dev mpirun -n 4 python input.py
For Podman, replace docker with podman.
Flags explanation
--rm: Automatically clean up container.-it: Interactive terminal.-v $(pwd):/work: Share current folder.-w /work: Start inside shared folder.
Apptainer (OSU)
apptainer exec mcdc_sandbox python input.py
apptainer exec mcdc_sandbox mpirun -launcher fork -n 4 python input.py
Note
Apptainer automatically shares your home directory.
Step 3: Docker Compose (Optional)¶
From MC/DC repo root:
docker compose -f containers/docker-compose.yml run --rm dev bash
docker compose -f containers/docker-compose.yml run --rm test
docker compose -f containers/docker-compose.yml run --rm mpi mpirun -n 4 python input.py