hydroBayesCal 0.1.0__tar.gz

hydrobayescal-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Sebastian Schwindt, Eduardo Acuna Espinoza, Kilian Mouris, Farid Mohammadi, Sergey Oladyshkin
+All rights reserved.
+
+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.

hydrobayescal-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: hydroBayesCal
+Version: 0.1.0
+Summary: Surrogate-assisted Bayesian calibration for hydrodynamic and morphodynamic models (Telemac, OpenFOAM).
+Author: Sebastian Schwindt, Andres Heredia, Eduardo Acuna
+License-Expression: BSD-3-Clause
+Project-URL: Documentation, https://hydrobayescal.readthedocs.io
+Project-URL: Source, https://github.com/sschwindt/hydrobayescal
+Keywords: Bayesian calibration,Gaussian process emulator,surrogate model,Bayesian active learning,Telemac,OpenFOAM
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: h5py>=3.10
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.13
+Requires-Dist: corner>=2.2
+Requires-Dist: tqdm>=4.66
+Requires-Dist: rich>=13
+Requires-Dist: joblib>=1.3
+Requires-Dist: pyvista>=0.43
+Requires-Dist: torch>=2.2
+Requires-Dist: gpytorch>=1.11
+Requires-Dist: linear-operator>=0.5
+Requires-Dist: emcee>=3.1
+Requires-Dist: chaospy>=4.3
+Requires-Dist: bayesvalidrox>=2.1
+Provides-Extra: mesh
+Requires-Dist: vtk>=9.2; extra == "mesh"
+Requires-Dist: meshio>=5.3; extra == "mesh"
+Requires-Dist: rasterio>=1.3; extra == "mesh"
+Requires-Dist: affine>=2.4; extra == "mesh"
+Provides-Extra: server
+Requires-Dist: umbridge>=1.2; extra == "server"
+Provides-Extra: mpi
+Requires-Dist: mpi4py>=3.1; extra == "mpi"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# HydroBayesCal
+
+**Surrogate-assisted Bayesian calibration for computationally expensive
+hydro- and morphodynamic models.**
+
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://hydrobayescal.readthedocs.io)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)
+
+HydroBayesCal calibrates expensive numerical models without running them
+thousands of times. It trains a **Gaussian Process Emulator (GPE)** as a fast
+surrogate from a small set of strategically sampled simulations, then refines it
+with **Bayesian Active Learning (BAL)** — iteratively adding the training points
+that maximise the information gain (relative entropy) and Bayesian model
+evidence for the calibration. Single- and multi-output GPEs are supported.
+
+The package couples to open-source modelling software through a common binding
+layer:
+
+* **TELEMAC** (2D/3D) — fully supported
+* **OpenFOAM** (interFoam) — binding under active development
+
+Experimental design and parameter sampling are delegated to
+[BayesValidRox](https://pages.iws.uni-stuttgart.de/inversemodeling/bayesvalidrox/);
+the GP emulators and the Bayesian active-learning logic are implemented in-tree.
+
+## Installation
+
+HydroBayesCal targets **Python 3.10–3.11** (the upper bound is imposed by the
+`bayesvalidrox` dependency). It is developed and tested on Linux.
+
+```bash
+pip install hydroBayesCal
+```
+
+or, for a development/editable install from a clone:
+
+```bash
+git clone https://github.com/sschwindt/hydrobayescal.git
+cd hydrobayescal
+pip install -e ".[dev,docs,mesh]"
+```
+
+A calibration additionally requires a working installation of the numerical
+solver (e.g. TELEMAC) on the system. See the
+[installation guide](https://hydrobayescal.readthedocs.io/en/latest/installation.html)
+for the full environment setup, including coupling HydroBayesCal with TELEMAC.
+
+## Quick start
+
+Configure a calibration in a Python config file and run the TELEMAC driver:
+
+```bash
+python bal_telemac.py --config config.py
+```
+
+See the [documentation](https://hydrobayescal.readthedocs.io) for the
+end-to-end workflow, the configuration parameters, the code architecture, and
+worked examples.
+
+## Citing / scientific background
+
+HydroBayesCal builds on the Bayesian active-learning framework of Oladyshkin et
+al. (2020) and on Gaussian-process regression (Rasmussen & Williams, 2006). Its
+application to reservoir sedimentation and 3D reservoir hydrodynamics is
+documented in Mouris et al. (2023) and Schwindt et al. (2023). Full references
+with DOIs are on the
+[references page](https://hydrobayescal.readthedocs.io/en/latest/references.html).
+
+## License
+
+Distributed under the BSD 3-Clause License. See [LICENSE](LICENSE).

hydrobayescal-0.1.0/README.md

@@ -0,0 +1,71 @@
+# HydroBayesCal
+
+**Surrogate-assisted Bayesian calibration for computationally expensive
+hydro- and morphodynamic models.**
+
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://hydrobayescal.readthedocs.io)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)
+
+HydroBayesCal calibrates expensive numerical models without running them
+thousands of times. It trains a **Gaussian Process Emulator (GPE)** as a fast
+surrogate from a small set of strategically sampled simulations, then refines it
+with **Bayesian Active Learning (BAL)** — iteratively adding the training points
+that maximise the information gain (relative entropy) and Bayesian model
+evidence for the calibration. Single- and multi-output GPEs are supported.
+
+The package couples to open-source modelling software through a common binding
+layer:
+
+* **TELEMAC** (2D/3D) — fully supported
+* **OpenFOAM** (interFoam) — binding under active development
+
+Experimental design and parameter sampling are delegated to
+[BayesValidRox](https://pages.iws.uni-stuttgart.de/inversemodeling/bayesvalidrox/);
+the GP emulators and the Bayesian active-learning logic are implemented in-tree.
+
+## Installation
+
+HydroBayesCal targets **Python 3.10–3.11** (the upper bound is imposed by the
+`bayesvalidrox` dependency). It is developed and tested on Linux.
+
+```bash
+pip install hydroBayesCal
+```
+
+or, for a development/editable install from a clone:
+
+```bash
+git clone https://github.com/sschwindt/hydrobayescal.git
+cd hydrobayescal
+pip install -e ".[dev,docs,mesh]"
+```
+
+A calibration additionally requires a working installation of the numerical
+solver (e.g. TELEMAC) on the system. See the
+[installation guide](https://hydrobayescal.readthedocs.io/en/latest/installation.html)
+for the full environment setup, including coupling HydroBayesCal with TELEMAC.
+
+## Quick start
+
+Configure a calibration in a Python config file and run the TELEMAC driver:
+
+```bash
+python bal_telemac.py --config config.py
+```
+
+See the [documentation](https://hydrobayescal.readthedocs.io) for the
+end-to-end workflow, the configuration parameters, the code architecture, and
+worked examples.
+
+## Citing / scientific background
+
+HydroBayesCal builds on the Bayesian active-learning framework of Oladyshkin et
+al. (2020) and on Gaussian-process regression (Rasmussen & Williams, 2006). Its
+application to reservoir sedimentation and 3D reservoir hydrodynamics is
+documented in Mouris et al. (2023) and Schwindt et al. (2023). Full references
+with DOIs are on the
+[references page](https://hydrobayescal.readthedocs.io/en/latest/references.html).
+
+## License
+
+Distributed under the BSD 3-Clause License. See [LICENSE](LICENSE).

hydrobayescal-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hydroBayesCal"
+version = "0.1.0"
+description = "Surrogate-assisted Bayesian calibration for hydrodynamic and morphodynamic models (Telemac, OpenFOAM)."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+# bayesvalidrox currently declares python < 3.12 upstream, and the tested
+# environment is CPython 3.11. Keep the upper bound aligned with that until
+# the bayesvalidrox dependency boundary is resolved (see refactor item #3).
+requires-python = ">=3.10,<3.12"
+authors = [
+    { name = "Sebastian Schwindt" },
+    { name = "Andres Heredia" },
+    { name = "Eduardo Acuna" },
+]
+keywords = [
+    "Bayesian calibration",
+    "Gaussian process emulator",
+    "surrogate model",
+    "Bayesian active learning",
+    "Telemac",
+    "OpenFOAM",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering",
+    "Intended Audience :: Science/Research",
+]
+
+# Core runtime stack. These are the dependencies required to import the
+# package and run a surrogate-assisted Bayesian calibration. Floors track the
+# versions the code is currently tested against; upper bounds are intentionally
+# omitted (the previous contradictory caps across requirements*.txt were the
+# source of unresolvable environments).
+dependencies = [
+    # scientific python
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "pandas>=2.0",
+    "scikit-learn>=1.3",
+    # data IO
+    "h5py>=3.10",
+    "openpyxl>=3.1",       # pandas.to_excel engine (function_pool)
+    "pyyaml>=6.0",         # utils.configuration
+    # plotting
+    "matplotlib>=3.7",
+    "seaborn>=0.13",
+    "corner>=2.2",
+    # CLI / utilities
+    "tqdm>=4.66",
+    "rich>=13",
+    "joblib>=1.3",
+    # mesh / result-file IO (imported by function_pool on the core path)
+    "pyvista>=0.43",
+    # Gaussian process surrogate stack
+    "torch>=2.2",
+    "gpytorch>=1.11",
+    "linear-operator>=0.5",
+    # uncertainty quantification / sampling (numpoly comes in transitively via chaospy)
+    "emcee>=3.1",
+    "chaospy>=4.3",
+    # coupling: experimental design / sampling
+    "bayesvalidrox>=2.1",
+]
+
+[project.urls]
+Documentation = "https://hydrobayescal.readthedocs.io"
+Source = "https://github.com/sschwindt/hydrobayescal"
+
+[project.optional-dependencies]
+# Extra mesh / geospatial IO used by some post-processing utilities only.
+mesh = [
+    "vtk>=9.2",
+    "meshio>=5.3",
+    "rasterio>=1.3",
+    "affine>=2.4",
+]
+# UM-Bridge model-server coupling protocol (used by the bayesvalidrox layer).
+server = [
+    "umbridge>=1.2",
+]
+# Parallel execution on HPC clusters.
+mpi = [
+    "mpi4py>=3.1",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=2.0",
+    "sphinxcontrib-mermaid>=0.9",
+]
+dev = [
+    "pytest>=7.4",
+    "build>=1.0",
+    "twine>=5.0",
+    "ruff>=0.5",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ship the non-Python data files the package reads at runtime (Telemac
+# parameter templates, etc.).
+[tool.setuptools.package-data]
+"hydroBayesCal" = [
+    "telemac/templates/*.csv",
+    "telemac/templates/*",
+]

hydrobayescal-0.1.0/setup.cfg

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

hydrobayescal-0.1.0/src/hydroBayesCal/__init__.py

@@ -0,0 +1 @@
+"""hydroBayesCal: surrogate-assisted Bayesian calibration for hydrodynamic models."""

hydrobayescal-0.1.0/src/hydroBayesCal/delft3d/__init__.py

@@ -0,0 +1,5 @@
+# Delft3D-FLOW bindings for hydroBayesCal (planned -- not yet implemented).
+#
+# This sub-package is a placeholder that defines the intended interface for
+# coupling HydroBayesCal to Delft3D-FLOW (Deltares). See
+# ``control_delft3d.Delft3DModel`` and the ``usage-delft3d`` documentation page.

hydrobayescal-0.1.0/src/hydroBayesCal/delft3d/control_delft3d.py

@@ -0,0 +1,106 @@
+"""
+Delft3D-FLOW binding for HydroBayesCal -- **planned, not yet implemented**.
+
+This module is a placeholder that mirrors the TELEMAC
+(:mod:`hydroBayesCal.telemac.control_telemac`) and OpenFOAM
+(:mod:`hydroBayesCal.openfoam.control_openfoam`) bindings. It defines the
+intended public interface for coupling HydroBayesCal to the structured-grid
+**Delft3D-FLOW** engine (Deltares) so that the coupling can be implemented
+incrementally without changing the surrogate / Bayesian-active-learning layer.
+
+The :class:`Delft3DModel` class subclasses
+:class:`hydroBayesCal.hysim.HydroSimulations`; the Python attribute names are
+shared across solvers, while the *string and file conventions* below are
+Delft3D-specific and must be preserved when the binding is filled in:
+
+* ``<case>.mdf`` -- master definition FLOW file (the control file); the engine
+  is launched through ``config_d_hydro.xml`` and the ``d_hydro`` executable.
+* Bed roughness via Chézy / Manning / White-Colebrook (``.rgh`` file or
+  ``Roughness`` keywords in the ``.mdf``); eddy viscosity/diffusivity
+  ``Vicouv`` / ``Dicouv``.
+* ``trim-<case>.dat`` / ``trim-<case>.def`` -- NEFIS map (field) output.
+* ``trih-<case>.dat`` / ``trih-<case>.def`` -- NEFIS history (monitoring-point)
+  output.
+
+See the :doc:`usage-delft3d <usage-delft3d>` page for the planned workflow.
+"""
+
+from hydroBayesCal.hysim import HydroSimulations
+
+#: Marker so callers / tests can detect that the binding is not ready yet.
+DELFT3D_BINDING_IMPLEMENTED = False
+
+_NOT_IMPLEMENTED_MSG = (
+    "The Delft3D-FLOW binding is planned but not yet implemented. "
+    "Use the TELEMAC (hydroBayesCal.telemac.control_telemac.TelemacModel) or "
+    "OpenFOAM (hydroBayesCal.openfoam.control_openfoam.OpenFOAMModel) bindings, "
+    "or contribute the Delft3D-FLOW implementation in "
+    "hydroBayesCal.delft3d.control_delft3d."
+)
+
+
+class Delft3DModel(HydroSimulations):
+    """
+    Placeholder Delft3D-FLOW model wrapper (planned).
+
+    Defines the intended constructor signature and interface but raises
+    :class:`NotImplementedError`. Instantiating it documents the Delft3D-specific
+    configuration the binding will need; it does not run a simulation.
+
+    Parameters
+    ----------
+    control_file : str
+        Master definition FLOW file, default ``"control.mdf"`` (Delft3D-FLOW
+        convention ``<case>.mdf``).
+    d_hydro_config : str
+        Runtime configuration passed to the ``d_hydro`` launcher, default
+        ``"config_d_hydro.xml"``.
+    flow_executable : str
+        Name of the Delft3D-FLOW launcher on ``PATH``, default ``"d_hydro"``.
+    roughness_formulation : str
+        Bed-roughness law used for the calibration parameters
+        (``"Chezy"``, ``"Manning"`` or ``"WhiteColebrook"``).
+    map_file_base, history_file_base : str
+        Base names of the NEFIS map (``trim-<case>``) and history
+        (``trih-<case>``) output files.
+    **kwargs
+        Common :class:`~hydroBayesCal.hysim.HydroSimulations` parameters
+        (``model_dir``, ``res_dir``, ``calibration_pts_file_path``,
+        ``calibration_parameters``, ``param_values``, ``calibration_quantities``,
+        ``init_runs``, ``max_runs`` ...).
+
+    Raises
+    ------
+    NotImplementedError
+        Always -- the binding is not implemented yet.
+    """
+
+    def __init__(
+        self,
+        control_file="control.mdf",
+        d_hydro_config="config_d_hydro.xml",
+        flow_executable="d_hydro",
+        roughness_formulation="Manning",
+        map_file_base="trim",
+        history_file_base="trih",
+        *args,
+        **kwargs,
+    ):
+        # Keep the Delft3D-specific configuration on the instance so the intended
+        # interface is documented, then make the not-yet-implemented state
+        # explicit instead of silently constructing a non-functional model.
+        self.control_file = control_file
+        self.d_hydro_config = d_hydro_config
+        self.flow_executable = flow_executable
+        self.roughness_formulation = roughness_formulation
+        self.map_file_base = map_file_base
+        self.history_file_base = history_file_base
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+    def run_multiple_simulations(self, *args, **kwargs):
+        """Run the Delft3D-FLOW experimental-design simulations (planned)."""
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)
+
+    def output_processing(self, *args, **kwargs):
+        """Extract calibration quantities from NEFIS map/history output (planned)."""
+        raise NotImplementedError(_NOT_IMPLEMENTED_MSG)