Metadata-Version: 2.4
Name: aXqua
Version: 1.0.1
Summary: Automated setup, persistent execution and calibration of river models - TELEMAC-2D/3D with GAIA, and OpenFOAM interFoam - with a QGIS frontend.
Author: Sebastian Schwindt
License-Expression: BSD-3-Clause AND MIT AND GPL-3.0-or-later
Project-URL: Documentation, https://axqua.eu
Project-URL: Source, https://github.com/sschwindt/aXqua
Project-URL: Issues, https://github.com/sschwindt/aXqua/issues
Project-URL: Releases, https://github.com/sschwindt/aXqua/releases
Keywords: TELEMAC,OpenFOAM,river modeling,hydraulics,sediment transport,Bayesian calibration,QGIS,mesh generation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: src/axqua/install/vendor/OpenFOAM-installer/LICENSE
License-File: src/axqua/install/vendor/OpenFOAM-installer/LICENSES/GPL-3.0-or-later.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: pyyaml
Requires-Dist: pyproj
Requires-Dist: shapely>=2.0
Requires-Dist: geopandas
Requires-Dist: rasterio
Requires-Dist: gmsh>=4.13
Requires-Dist: openpyxl>=3.1
Requires-Dist: matplotlib
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: gui
Requires-Dist: streamlit>=1.30; extra == "gui"
Provides-Extra: calibration
Requires-Dist: hydrobayescal>=1.8.1; extra == "calibration"
Dynamic: license-file

# aXqua

**Automated setup, persistent execution and calibration of models of free-surface water bodies: rivers, lakes, reservoirs and hydraulic structures.**

aXqua builds a **TELEMAC-2D/3D** case (optionally with **GAIA**) or an **OpenFOAM** free-surface case from geodata, runs it as a job that outlives the shell or QGIS that started it, and calibrates it with [HydroBayesCal](https://github.com/Ecohydraulics/hydrobayescal) (surrogate-assisted Bayesian calibration with quantified uncertainty). A **QGIS plugin** drives the whole workflow; everything also works from a terminal.

**Documentation:** [axqua.eu](https://axqua.eu) (English), [axqua.eu/de](https://axqua.eu/de/) (Deutsch), [axqua.eu/fr](https://axqua.eu/fr/) (Français), and [axqua.readthedocs.io](https://axqua.readthedocs.io) (English).

## Install

```bash
pip install axqua                        # Python 3.10 or newer, best in an environment of its own
axqua profile init                       # find TELEMAC, OpenFOAM, ParaView, VisIt on this computer
```

`pip install "axqua[calibration]"` adds HydroBayesCal for the Bayesian calibration. For development, install from a clone of this repository:

```bash
mamba env create -f environment.yml      # the environment axqua-env
mamba activate axqua-env
pip install -e .
```

The QGIS plugin (QGIS 3.44 or newer) is `qgis_plugin/axqua/`; for development link it into a QGIS profile, or start `scripts/qgis_dev.sh`, which uses a QGIS of its own. The installation of the plugin and of the simulation software is described in the [documentation](https://axqua.eu/installation/index.html).

## Quick start

```bash
axqua example get --folder ~/aXqua-examples    # a small Isar case with its data (6 MB)
axqua submit <case-file> --kind preprocessing  # build the TELEMAC model, as a job
axqua submit <case-file> --kind steady         # the steady 2D run (waits for the build)
axqua list                                     # the jobs, with state and progress
axqua cleanup <case-file>                      # what the case could do without (frees disk space)
```

The example case and its guide are in [`cases/example-isar/`](https://github.com/sschwindt/aXqua/blob/main/cases/example-isar/README.md). Every command is listed in the [terminal syntax](https://axqua.eu/automation/terminal-syntax.html).

## Repository

| Folder | Content |
|---|---|
| `src/axqua/` | the library and the command `axqua` |
| `qgis_plugin/axqua/` | the QGIS plugin (GPL-2.0-or-later; it talks to `axqua` only through the command line) |
| `cases/` | the example cases and the template of a case; case data (`user-sources/`) and results (`axqua-case/`) are not tracked |
| `docs/` | the documentation (Sphinx); `docs/locale/` holds its German and French translations |
| `tests/`, `qgis_plugin/tests/` | the tests (`pytest tests qgis_plugin/tests`) |
| `scripts/` | tools: plugin archive, screenshots and UML diagrams of the documentation, data of the example case, backup of case data to Google Drive (`backup_cases_to_drive.sh`, rclone) |
| `deploy.sh` | publishes the documentation (below) |

## Documentation: build and publish

Build the English pages alone (Sphinx and the theme suffice; heavy dependencies are mocked):

```bash
pip install -r docs/requirements-docs.txt
sphinx-build -W -b html docs docs/_build/html
```

Build and publish all three languages on GitHub Pages:

```bash
mamba env create -f docs/i18n/environment.yml   # once: the environment axqua-docs (Sphinx + Argos Translate)
bash deploy.sh                                  # build into docs/_build/site and copy it into the gh-pages worktree
bash deploy.sh --push                           # ... then push main and gh-pages: the site is live within a minute
```

`deploy.sh` translates only the paragraphs that are new or changed since the last deploy (seconds; `--retranslate` translates everything again, about 4 minutes), commits the updated catalogs `docs/locale/**.po` on `main`, pushes `main` and then the branch `gh-pages`, which GitHub Pages serves at `https://axqua.eu`. It refuses to run with uncommitted changes. Read the Docs builds the English pages from `main` by itself. The glossaries of technical terms, corrections of a translation by hand and the other settings are described in [`docs/i18n/README.md`](https://github.com/sschwindt/aXqua/blob/main/docs/i18n/README.md).

## License

aXqua is BSD-3-Clause; the QGIS plugin is GPL-2.0-or-later. The data of the example case are CC BY 4.0 (`cases/example-isar/LICENSE.md`). Coordinates are EPSG:25832 throughout; see `CLAUDE.md` for the notes of the developers.
