Prerequisites

Run these checks before starting dataset or simulation steps. The goal is to fail early on missing CLI tools, Apptainer runtime, or launcher commands.

1. Required Components

  • Python CLI entry points:

  • kub-dataset

  • kub-simulate

  • kub-dashboard

  • Apptainer runtime (required in this tutorial):

  • /opt/apptainer/latest/bin/apptainer (or a compatible apptainer executable)

  • local SIF image (kub-master.sif)

  • Slurm commands (optional, used when kub-simulate --launcher slurm):

  • sbatch

  • srun

  • MPI launcher for local parallel runs (kub-simulate --launcher local --np > 1):

  • mpiexec or mpirun

2. Pull Apptainer Image

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

3. Quick Environment Check

kub-dataset --help
kub-simulate --help
kub-dashboard --help

test -x /opt/apptainer/latest/bin/apptainer && echo "apptainer: OK"
which mpiexec || which mpirun
which sbatch
which squeue

4. CEMDB Root Defaults

--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.

5. Execution Context

  • HPC Login Node Recommended

  • Local Machine Apptainer Workflow

Use this when you plan to submit preprocessing and simulation jobs with the Slurm launcher.

which sbatch
which squeue
kub-simulate --help
test -x /opt/apptainer/latest/bin/apptainer

Use this when you plan to run with --launcher local and Apptainer runtime.

test -x /opt/apptainer/latest/bin/apptainer
test -f ./kub-master.sif
which mpiexec || which mpirun
kub-simulate run arz --version 0.1.0 --launcher local --runtime apptainer --apptainer-exec /opt/apptainer/latest/bin/apptainer --apptainer-image ./kub-master.sif --np 1 --dry-run
kub-dataset --help
kub-dashboard --help

6. Optional Environment Variables

export CEMDB_ROOT=cemdb
export APPTAINER=/opt/apptainer/latest/bin/apptainer
# Optional for dashboard defaults:
# export DASHBOARD_HOST=127.0.0.1
# export DASHBOARD_PORT=8050

7. Next Step

Proceed to Dataset Workflow.