aXqua 1.0.1__tar.gz

axqua-1.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Sebastian Schwindt
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

axqua-1.0.1/NOTICE

@@ -0,0 +1,43 @@
+axqua
+Copyright (c) 2026, Sebastian Schwindt
+Licensed under the BSD 3-Clause License (see LICENSE).
+
+--------------------------------------------------------------------------------
+Third-party acknowledgements
+--------------------------------------------------------------------------------
+
+axqua.sortie / axqua.flux_convergence
+---------------------------------------------
+The TELEMAC listing (".sortie") reader and the boundary-flux convergence analysis
+were adopted from the `pythomac` package (https://github.com/hydro-informatics/
+pythomac), lead author Sebastian Schwindt, who is also the author of axqua and
+authorized the adoption. The analysis reproduces pythomac's behavior and writes the
+same four output files (extracted-fluxes.csv, flux-convergence.png,
+convergence-rate.csv, convergence-rate.png).
+
+The implementation here is an independent one written against TELEMAC's output
+format, not a copy. That is deliberate: pythomac's own listing parser
+(`parser_output.py`) and its `utils/files.py` / `utils/exceptions.py` are adapted
+from TELEMAC-MASCARET's `HOMETEL/scripts/python3/postel` under the GNU GPL v3 and
+carry the TELEMAC-MASCARET Consortium's copyright, which is not axqua's or
+pythomac's to relicense. axqua therefore reimplements the parsing rather than
+vendoring those files, and the GAIA / tracer mass-balance field lists in
+axqua.sortie were re-derived from the FORTRAN FORMAT statements in TELEMAC
+v9.1.1 (`sources/gaia/mass_balance.f`, `sources/telemac3d/bil3d.f`).
+
+TELEMAC-MASCARET (http://www.opentelemac.org) is a separate program, invoked by
+axqua as an external solver; none of its source is included or linked here.
+
+docs/img/active-layer.jpg
+-------------------------
+The illustration of the active layer in the documentation is taken unchanged from the
+eBook Hydro-Informatics (https://hydro-informatics.com, file
+`img/telemac/active-layers-web.jpg`), author Sebastian Schwindt, who is also the author
+of axqua and authorized its use here. The image carries a Creative Commons
+BY-NC-ND mark and is NOT covered by the BSD 3-Clause License of this repository.
+
+src/axqua/install/vendor/OpenFOAM-installer/
+---------------------------------------------
+A copy of the OpenFOAM installer of https://github.com/Ecohydraulics/numerical-software-installers (commit 12fcb7e, MIT License, see its LICENSE), with the changes listed in its VENDORED.md. It is NOT covered by the BSD 3-Clause License of this repository.
+
+Its folder olsen-sources/ holds the source files of the sediment solvers sediDriftFoam and sediDriftFoam2 by Nils Reidar B. Olsen, unchanged, under the GNU General Public License version 3 or later (text in LICENSES/GPL-3.0-or-later.txt), as is cpp/olsenRatingCurve.H. They are shipped as an aggregate: aXqua neither links nor imports them, the installer compiles them into separate programs, and aXqua runs those programs as external solvers. The GPL therefore applies to these files and the programs built from them, not to aXqua.

axqua-1.0.1/PKG-INFO

@@ -0,0 +1,118 @@
+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.

axqua-1.0.1/README.md

@@ -0,0 +1,71 @@
+# 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.

axqua-1.0.1/pyproject.toml

@@ -0,0 +1,130 @@
+[build-system]
+# 77: the license expression and license-files of PEP 639.
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Branded on PyPI; the import package is plain lowercase `axqua`, because a mixed-case
+# module name resolves differently on case-insensitive filesystems. PyPI normalizes the
+# two to the same project, so `pip install aXqua` and `pip install axqua` both work.
+name = "aXqua"
+version = "1.0.1"
+description = "Automated setup, persistent execution and calibration of river models - TELEMAC-2D/3D with GAIA, and OpenFOAM interFoam - with a QGIS frontend."
+readme = "README.md"
+requires-python = ">=3.10"
+# aXqua is BSD-3-Clause. The wheel also carries the vendored OpenFOAM installer (MIT) and
+# Olsen's solver sources (GPL-3.0-or-later), which aXqua runs as separate programs and
+# never imports or links (NOTICE); PyPI shows this expression, so it names all three.
+license = "BSD-3-Clause AND MIT AND GPL-3.0-or-later"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+    "src/axqua/install/vendor/OpenFOAM-installer/LICENSE",
+    "src/axqua/install/vendor/OpenFOAM-installer/LICENSES/*",
+]
+authors = [{ name = "Sebastian Schwindt" }]
+keywords = ["TELEMAC", "OpenFOAM", "river modeling", "hydraulics", "sediment transport",
+            "Bayesian calibration", "QGIS", "mesh generation"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Hydrology",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "numpy",
+    "pandas",
+    "scipy",
+    "pyyaml",
+    "pyproj",
+    "shapely>=2.0",
+    "geopandas",
+    "rasterio",
+    "gmsh>=4.13",
+    "openpyxl>=3.1",
+    # flux-convergence + cross-section plots and the P1 triangle interpolation
+    # (axqua.flux_convergence, axqua.sections); previously pulled in
+    # transitively by pythomac, which the flux analysis no longer uses.
+    "matplotlib",
+]
+
+[project.urls]
+Documentation = "https://axqua.eu"
+Source = "https://github.com/sschwindt/aXqua"
+Issues = "https://github.com/sschwindt/aXqua/issues"
+Releases = "https://github.com/sschwindt/aXqua/releases"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+gui = ["streamlit>=1.30"]
+# Surrogate-assisted Bayesian calibration (axqua.bayescal / axqua.calibration).
+# An EXTRA rather than a core dependency: it pulls in bayesvalidrox, gpytorch and
+# scikit-learn, none of which is needed to build or run a TELEMAC case, which is what
+# most of axqua does.
+#
+# VERSION POLICY: a floor, never a ceiling. HydroBayesCal is developed alongside
+# axqua by the same group, and its releases are bugfixes plus ADDITIVE features -
+# nothing is removed. So the newest release is always the one to want, and an upper
+# bound would only stop a user getting a fix. `pip install 'axqua[calibration]'`
+# therefore resolves to the latest, and that is intended, not an oversight.
+#
+# The floor is the oldest release carrying a capability axqua actually uses, so a
+# too-old install fails at install time rather than halfway through a calibration.
+# What each step added, for the record:
+#   1.4.2  ships the calibration drivers WITH the package (hydroBayesCal.copy_driver);
+#          before it they lived only in a source checkout that axqua had to be told
+#          the location of, which broke whenever it moved.
+#   1.4.3  hoists save_calibration_data into HydroSimulations, fixing the "truth
+#          value of an array is ambiguous" crash on BAL's first iteration once for
+#          every binding, and writing the restart CSV that --resume relies on.
+#   1.4.4  makes the MULTI-FLOW driver honor the config's `extraction` block;
+#          before it, multi-flow silently averaged the last frames while single-flow
+#          on the same config did not, so the two were fitted to different data.
+#
+# Beyond the floor, axqua does NOT check versions: `hbc.require_hbc` tests for the
+# capability it needs (hasattr(hydroBayesCal, "copy_driver")). On an additive-only
+# upstream that is the right test - a version comparison would need editing on every
+# release, and would reject a valid newer one the moment the scheme changed.
+calibration = ["hydrobayescal>=1.8.1"]
+
+[project.scripts]
+axqua = "axqua.cli:main"
+axqua-gui = "axqua.gui.launch:main"
+
+# Solver backends are discovered through this group, so a third solver is a
+# `pip install axqua-<name>` rather than a fork. The built-ins register through the
+# same mechanism they document, with a hard-coded fallback in core/registry.py for a
+# source checkout that has not been re-installed.
+[project.entry-points."axqua.solvers"]
+telemac = "axqua.solvers.telemac.spec:SPEC"
+openfoam = "axqua.solvers.openfoam.spec:SPEC"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+axqua = ["install/vendor/**/*"]
+
+# The vendor glob above takes everything, also the bytecode a run of the installer's own
+# tests leaves in a working tree. A wheel built from such a tree must not carry it.
+[tool.setuptools.exclude-package-data]
+axqua = ["**/__pycache__/*", "*.pyc"]
+
+[tool.ruff]
+line-length = 100
+# A copy of another project, kept as close to its original as possible (VENDORED.md).
+extend-exclude = ["src/axqua/install/vendor"]
+
+[tool.ruff.lint]
+# Pinned EXPLICITLY rather than left to ruff's defaults: those defaults widened in
+# ruff 0.16, so the same `ruff check src/` went from clean to 88 findings purely by
+# upgrading ruff on one machine (all of them style nits - intentional multi-line
+# prose flagged as ISC004, deliberate `except Exception` reporting as BLE001).
+# Naming the rule set makes the lint contract the same on every machine and in CI.
+select = ["E4", "E7", "E9", "F"]

axqua-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

axqua-1.0.1/src/aXqua.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+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.