kub-cli 0.12.0

// SPDX-FileCopyrightText: 2026 University of Strasbourg (Unistra)
// SPDX-FileContributor: Christophe Prud'homme <christophe.prudhomme@feelpp.org>
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
= 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.

[cols="1,3",options="header"]
|===
|Command |Purpose
|`kub-dataset` |Download and manage location datasets and FMUs.
|`kub-simulate` |Preprocess meshes, run simulations and launch coupled participants locally or with Slurm.
|`kub-img` |Download and inspect Docker/Apptainer images.
|`kub-dashboard` |Browse datasets and simulation results; optional preview tool.
|===

== Installation

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

[source,bash]
----
python -m pip install --upgrade 'kub-cli>=0.12.0'
----

For the optional dashboard:

[source,bash]
----
python -m pip install --upgrade 'kub-cli[dashboard]>=0.12.0'
----

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

== Download datasets and FMUs

[source,bash]
----
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 version; 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.

[source,bash]
----
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.

[source,bash]
----
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.

== Browse results

With the dashboard extra installed:

[source,bash]
----
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.