KUB command-line tools

kub-cli provides native Python commands for Ktirio Urban Building. Python 3.11 or newer is required. Simulations use a separately installed KUB solver or an Apptainer image; Feel++ Python bindings are not required.

Installation

Install into a Python virtual environment. Version 0.12.0 introduces the native commands, replacing the older container wrapper.

python -m pip install --upgrade 'kub-cli>=0.12.1'

For the optional dashboard:

python -m pip install --upgrade 'kub-cli[dashboard]>=0.12.1'

A supplied wheel can also be installed with python -m pip install /path/to/kub_cli-VERSION-py3-none-any.whl. Use COMMAND --help for available options and COMMAND --version for the installed CLI version.

Download datasets and FMUs

kub-dataset pull arz --version 0.1.0
kub-dataset pull-simulator --version 0.20.0

Data are stored under cemdb/locations and cemdb/simulators by default. The --version option after a dataset subcommand selects the dataset version; CLI and solver releases share a major/minor compatibility line; patch versions can differ. Datasets and FMUs have their own versions.

Download an image and run a simulation

Replace IMAGE_TAG with the image version matching your MPI setup. Apptainer must be installed on the host.

kub-img pull oras://ghcr.io/feelpp/ktirio-urban-building:IMAGE_TAG-sif \
    --runtime apptainer --image ./kub.sif
kub-img info --runtime apptainer --image ./kub.sif

kub-simulate preprocess arz --version 0.1.0 --partitions 4 \
    --launcher local --runtime apptainer --apptainer-exec apptainer \
    --apptainer-image ./kub.sif
kub-simulate run arz --version 0.1.0 --np 4 \
    --launcher local --runtime apptainer --apptainer-exec apptainer \
    --apptainer-image ./kub.sif
kub-simulate status arz --version 0.1.0

For Slurm, select --launcher slurm and the site’s partition and resources. For an installed solver, use --runtime native --binary /path/to/feelpp_kub_cem. Use --config-file /path/to/case.cfg to select a different simulation CFG.

Launch coupled participants

A coupling plan lists each participant’s image, executable, MPI ranks, arguments and mounts, plus a new output directory for the run.

kub-simulate couple --plan /path/to/plan.json --launcher local --dry-run
kub-simulate couple --plan /path/to/plan.json --launcher local

Use --launcher slurm for cluster execution. That mode requires one node per participant, equal rank counts, and images and case files on shared storage.

Station replay

Use kub-cli 0.12.1 or newer with scripts/station-replay.sh from a KUB source checkout. The script is not installed by pip. Copy it to a writable working directory and run it there:

bash station-replay.sh

The script downloads the OpenMPI 5 KUB image, Wolfisheim v0.1.0 and FMUs v0.20.0, preprocesses the geometry, and launches KUB and StationReplay. Check completion.json, the participant logs, and station-ensight/station-replay.case in the printed run directory. Set mpi=mpich at the top of the script for the MPICH variant.

Apptainer solver commands default to TMPDIR=/tmp inside the image, so a host scratch directory need not exist inside the container. Override this with --apptainer-env TMPDIR=/your/container/path when needed. The host’s temporary directory for Apptainer image downloads is unchanged.

Browse results

With the dashboard extra installed:

kub-dashboard serve --cemdb-root ./cemdb --host 127.0.0.1 --port 8050

Open http://127.0.0.1:8050 in a browser. Use --host 0.0.0.0 when serving from another machine.

Full documentation: https://feelpp.github.io/ktirio-urban-building/.

License

GPL-3.0-or-later OR LicenseRef-Commercial. Imported kub-img utilities retain their Apache-2.0 license. See LICENSE and LICENSES/ for the terms.