Metadata-Version: 2.4
Name: kub-cli
Version: 0.12.1
Summary: Native dataset, simulation, dashboard and image tools for Ktirio Urban Building
Keywords: simulation,urban,building,energy
Author-Email: Christophe Prud'homme <christophe.prudhomme@cemosis.fr>, Vincent Chabannes <vincent.chabannes@cemosis.fr>, Philippe Pinçon <philippe.pincon@cemosis.fr>, Javier Cladellas <javier.cladellas@cemosis.fr>, Gwennolé Chappron <gwennole.chappron@cemosis.fr>
License-Expression: GPL-3.0-or-later OR LicenseRef-Commercial
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/GPL-3.0-or-later.txt
License-File: LICENSES/LicenseRef-Commercial.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Project-URL: Homepage, https://feelpp.github.io/ktirio-urban-building
Project-URL: Documentation, https://feelpp.github.io/ktirio-urban-building
Project-URL: Repository, https://github.com/feelpp/ktirio-urban-building
Project-URL: Issues, https://github.com/feelpp/ktirio-urban-building/issues
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: requests
Requires-Dist: certifi>=2026.10.19
Requires-Dist: numpy>=2.4
Requires-Dist: pandas>=3.1
Requires-Dist: jinja2
Requires-Dist: PyYAML>=6.0
Requires-Dist: girder-client
Requires-Dist: tomli-w>=1.0
Provides-Extra: all
Requires-Dist: kub-cli[auth,dashboard,dev,dvc,fmu,hdfs,s3,test]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: dev
Requires-Dist: pipx; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: reuse>=1.1.0; extra == "dev"
Provides-Extra: fmu
Requires-Dist: feelpp-mo2fmu>=0.6.0; extra == "fmu"
Provides-Extra: dashboard
Requires-Dist: dash>=2.14; extra == "dashboard"
Requires-Dist: dash-bootstrap-components>=1.5; extra == "dashboard"
Requires-Dist: flask>=2.2; extra == "dashboard"
Requires-Dist: pyarrow>=26; extra == "dashboard"
Requires-Dist: cachetools>=5.3; extra == "dashboard"
Requires-Dist: plotly>=5.0; extra == "dashboard"
Requires-Dist: h5py>=3.8; extra == "dashboard"
Requires-Dist: tables>=3.8; extra == "dashboard"
Provides-Extra: dvc
Requires-Dist: dvc>=3.0; extra == "dvc"
Provides-Extra: s3
Requires-Dist: boto3>=1.26; extra == "s3"
Provides-Extra: hdfs
Requires-Dist: requests>=2.28; extra == "hdfs"
Provides-Extra: auth
Requires-Dist: keyring>=23.0; extra == "auth"
Description-Content-Type: text/markdown

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

Generated from src/python/README.adoc by scripts/generate_kub_cli_readme.py.
Edit the AsciiDoc source and regenerate this file.
-->

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

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

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

For the optional dashboard:

```bash
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

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

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

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

## 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
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:

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