Apptainer Runtime Workflow

This tutorial workflow runs kub-simulate with --runtime apptainer. Dataset layout and run management stay unchanged across local and Slurm launchers.

--cemdb-root can be omitted in many cases:

  • If the current directory contains ./cemdb, kub-dataset and kub-simulate use the default cemdb/locations.

  • kub-dashboard auto-detects ./cemdb.

CEMDB_ROOT environment variable:

  • kub-dashboard uses CEMDB_ROOT as its default CEMDB path.

  • For kub-dataset and kub-simulate, use --cemdb-root when your data is not under ./cemdb/locations.

1. 1. Pull the KUB Apptainer Image

APPT=/opt/apptainer/latest/bin/apptainer
$APPT pull kub-master.sif oras://ghcr.io/feelpp/ktirio-urban-building:master-sif

2. 2. Check Runtime Prerequisites

test -x /opt/apptainer/latest/bin/apptainer
test -f ./kub-master.sif
which kub-simulate
which mpiexec || which mpirun

3. 3. Configure Apptainer Profiles

Use kub-simulate config so launch commands stay short.

Do not store dataset version in config. Keep --version explicit when launching runs.

 
# Create .kub-simulate.toml in the current directory
kub-simulate config init

# Shared default for preprocess/run
kub-simulate config set cemdb_root cemdb/locations

# Apptainer Slurm profile
kub-simulate config set launcher slurm --profile-target apptainer-slurm
kub-simulate config set partition public --profile-target apptainer-slurm
kub-simulate config set runtime apptainer --profile-target apptainer-slurm
kub-simulate config set apptainer_exec /opt/apptainer/latest/bin/apptainer --profile-target apptainer-slurm
kub-simulate config set apptainer_image ./kub-master.sif --profile-target apptainer-slurm

# Apptainer local profile
kub-simulate config set launcher local --profile-target apptainer-local
kub-simulate config set runtime apptainer --profile-target apptainer-local
kub-simulate config set apptainer_exec /opt/apptainer/latest/bin/apptainer --profile-target apptainer-local
kub-simulate config set apptainer_image ./kub-master.sif --profile-target apptainer-local

# Review resulting config
kub-simulate config show

4. 4. Run Preprocessing with Apptainer Runtime

Slurm launcher (apptainer-slurm profile):

kub-simulate preprocess arz \
  --version 0.1.0 \
  --profile apptainer-slurm \
  --partitions 32 64 128

Local launcher (apptainer-local profile):

kub-simulate preprocess arz \
  --version 0.1.0 \
  --profile apptainer-local \
  --partitions 32 64 128

5. 5. Run Simulation with Apptainer Runtime

Slurm launcher (apptainer-slurm profile):

kub-simulate run arz \
  --version 0.1.0 \
  --profile apptainer-slurm \
  --np 128

Local launcher (apptainer-local profile):

kub-simulate run arz \
  --version 0.1.0 \
  --profile apptainer-local \
  --np 128

6. 6. Optional Runtime Flags

Add custom bind mounts and environment variables when needed:

kub-simulate run arz \
  --version 0.1.0 \
  --profile apptainer-local \
  --np 128 \
  --apptainer-bind /scratch/work:/work \
  --apptainer-env OMP_NUM_THREADS=1

--apptainer-mpi-tcp is available as an optional workaround for specific local MPI setups. It is disabled by default because TCP transport can reduce MPI performance.

7. 7. Inspect Status and Outputs

kub-simulate status arz \
  --version 0.1.0 \
  --cemdb-root cemdb/locations \
  --last 10

find cemdb/locations/arz/v0.1.0/simulations/single -maxdepth 2 -name manifest.json | sort

8. Next Step

Proceed to Dashboard Workflow.