aquimodpy 1.0.0__tar.gz

aquimodpy-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Install dependencies
+        run: uv sync --group dev --group test
+      - name: Check formatting (Black)
+        run: uv run black --check src tests
+      - name: Type checking (Mypy)
+        run: uv run mypy src
+      - name: Run tests (Pytest)
+        run: uv run pytest tests

aquimodpy-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Pytest & MyPy
+.pytest_cache/
+.mypy_cache/
+.coverage
+
+# MkDocs
+site/
+EOF

aquimodpy-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

aquimodpy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 aquimodpy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aquimodpy-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: aquimodpy
+Version: 1.0.0
+Summary: Python wrapper for Aquimod 2
+Author: Arran Clarke
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Requires-Dist: pandas>=3.0.3
+Description-Content-Type: text/markdown
+
+# aquimodpy
+
+A Python wrapper for the British Geological Survey's **AquiMod 2**, a lumped parameter groundwater model.
+
+## Features
+
+- **IDE Support**: Full autocompletion and parameter validation in modern editors.
+- **Modular Design**: Support for all Soil Zone (FAO, NSSS, SMAP), Unsaturated Zone (Weibull), and Saturated Zone (Q3K3S1, VKD, SA1D, etc.) components.
+- **Automated Configuration**: Generates all required input files (`Input.txt`, `Observations.txt`, and component-specific parameter files) with correct Windows-style formatting for Wine compatibility.
+- **Simulation Modes**: Full support for Evaluation, Monte Carlo calibration, and SCE-UA global optimization.
+- **Cross-Platform**: Flexible execution support; specify your preferred command prefix (e.g., `["wine"]`, `["box86"]`) for running the Windows binary on non-Windows systems.
+- **Data Integration**: Seamless integration with Pandas for observation input and result parsing.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/aquimodpy.git
+cd aquimodpy
+
+# Install dependencies (using uv)
+uv pip install -e .
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from aquimodpy import Model, FAO, Weibull, Q3K3S1, Observations, EvaluationRunner
+
+# 1. Initialize the model
+model = Model(
+    model_name="MySimulation",
+    executable_path="~/Documents/AquiMod2/AquiMod2.exe",
+    working_directory="./simulation_results",
+    exec_prefix=["wine"]  # Use ["wine"] for Linux or [] for native Windows
+)
+
+# 2. Add components using named arguments
+# Units and special characters are handled automatically!
+FAO(
+    model, 
+    theta_fc=0.4, 
+    theta_wp=0.1, 
+    Z_r=1000, 
+    p=0.5, 
+    BFI=0.8
+)
+
+Weibull(
+    model, 
+    k=2.0, 
+    lambda_=5.0 # Use lambda_ as 'lambda' is a Python keyword
+)
+
+Q3K3S1(
+    model, 
+    dx=1000, 
+    K3=10, 
+    K2=5, 
+    K1=1, 
+    S=0.01, 
+    z3=50, 
+    z2=40, 
+    z1=30, 
+    alpha=1
+)
+
+# 3. Add observations and map column names
+df = pd.read_csv("my_data.csv")
+Observations(model, df, {
+    "DATE": "date_col",
+    "RAIN": "rainfall_mm",
+    "PET": "pet_mm",
+    "GWL": "gw_level_m"
+})
+
+# 4. Configure and run
+model.set_runner(EvaluationRunner(model))
+model.setup()
+model.run()
+
+# 5. Analyze results
+results = model.get_results()
+print(results['Sat'].head())
+```
+
+## Calibration and Optimization
+
+### Monte Carlo Calibration
+Provide `[min, max]` lists for parameters you wish to calibrate.
+```python
+from aquimodpy import CalibrationRunner
+model.set_runner(CalibrationRunner(model))
+model.set_simulation_mode('m', n_runs=10000, threshold=0.5, variable='g')
+
+# Calibrate Z_r and BFI, keep others fixed
+FAO(
+    model, 
+    theta_fc=0.35, 
+    theta_wp=0.1, 
+    Z_r=[500, 3000], 
+    p=0.5, 
+    BFI=[0.1, 0.99]
+)
+```
+
+### SCE-UA Optimization
+```python
+model.set_simulation_mode('s', n_loops=100, n_complexes=50, variable='g')
+```
+
+## License and Attribution
+
+This library is licensed under the **MIT License**.
+
+This project provides a wrapper for **AquiMod 2**, which is owned by the British Geological Survey (BGS) and is licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). 
+
+Please note that this library does not include the AquiMod 2 binary. You can download the AquiMod 2 software from the [official BGS website](https://www.bgs.ac.uk/technologies/software/aquimod/). Users are responsible for obtaining the binary independently and complying with the terms of the Open Government Licence as specified by the BGS.
+

aquimodpy-1.0.0/README.md

@@ -0,0 +1,120 @@
+# aquimodpy
+
+A Python wrapper for the British Geological Survey's **AquiMod 2**, a lumped parameter groundwater model.
+
+## Features
+
+- **IDE Support**: Full autocompletion and parameter validation in modern editors.
+- **Modular Design**: Support for all Soil Zone (FAO, NSSS, SMAP), Unsaturated Zone (Weibull), and Saturated Zone (Q3K3S1, VKD, SA1D, etc.) components.
+- **Automated Configuration**: Generates all required input files (`Input.txt`, `Observations.txt`, and component-specific parameter files) with correct Windows-style formatting for Wine compatibility.
+- **Simulation Modes**: Full support for Evaluation, Monte Carlo calibration, and SCE-UA global optimization.
+- **Cross-Platform**: Flexible execution support; specify your preferred command prefix (e.g., `["wine"]`, `["box86"]`) for running the Windows binary on non-Windows systems.
+- **Data Integration**: Seamless integration with Pandas for observation input and result parsing.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/aquimodpy.git
+cd aquimodpy
+
+# Install dependencies (using uv)
+uv pip install -e .
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from aquimodpy import Model, FAO, Weibull, Q3K3S1, Observations, EvaluationRunner
+
+# 1. Initialize the model
+model = Model(
+    model_name="MySimulation",
+    executable_path="~/Documents/AquiMod2/AquiMod2.exe",
+    working_directory="./simulation_results",
+    exec_prefix=["wine"]  # Use ["wine"] for Linux or [] for native Windows
+)
+
+# 2. Add components using named arguments
+# Units and special characters are handled automatically!
+FAO(
+    model, 
+    theta_fc=0.4, 
+    theta_wp=0.1, 
+    Z_r=1000, 
+    p=0.5, 
+    BFI=0.8
+)
+
+Weibull(
+    model, 
+    k=2.0, 
+    lambda_=5.0 # Use lambda_ as 'lambda' is a Python keyword
+)
+
+Q3K3S1(
+    model, 
+    dx=1000, 
+    K3=10, 
+    K2=5, 
+    K1=1, 
+    S=0.01, 
+    z3=50, 
+    z2=40, 
+    z1=30, 
+    alpha=1
+)
+
+# 3. Add observations and map column names
+df = pd.read_csv("my_data.csv")
+Observations(model, df, {
+    "DATE": "date_col",
+    "RAIN": "rainfall_mm",
+    "PET": "pet_mm",
+    "GWL": "gw_level_m"
+})
+
+# 4. Configure and run
+model.set_runner(EvaluationRunner(model))
+model.setup()
+model.run()
+
+# 5. Analyze results
+results = model.get_results()
+print(results['Sat'].head())
+```
+
+## Calibration and Optimization
+
+### Monte Carlo Calibration
+Provide `[min, max]` lists for parameters you wish to calibrate.
+```python
+from aquimodpy import CalibrationRunner
+model.set_runner(CalibrationRunner(model))
+model.set_simulation_mode('m', n_runs=10000, threshold=0.5, variable='g')
+
+# Calibrate Z_r and BFI, keep others fixed
+FAO(
+    model, 
+    theta_fc=0.35, 
+    theta_wp=0.1, 
+    Z_r=[500, 3000], 
+    p=0.5, 
+    BFI=[0.1, 0.99]
+)
+```
+
+### SCE-UA Optimization
+```python
+model.set_simulation_mode('s', n_loops=100, n_complexes=50, variable='g')
+```
+
+## License and Attribution
+
+This library is licensed under the **MIT License**.
+
+This project provides a wrapper for **AquiMod 2**, which is owned by the British Geological Survey (BGS) and is licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). 
+
+Please note that this library does not include the AquiMod 2 binary. You can download the AquiMod 2 software from the [official BGS website](https://www.bgs.ac.uk/technologies/software/aquimod/). Users are responsible for obtaining the binary independently and complying with the terms of the Open Government Licence as specified by the BGS.
+

aquimodpy-1.0.0/docs/api.md

@@ -0,0 +1,11 @@
+# API Reference
+
+::: aquimodpy.Model
+
+::: aquimodpy.Components
+
+::: aquimodpy.Runner
+
+::: aquimodpy.CalibrationRunner
+
+::: aquimodpy.EvaluationRunner

aquimodpy-1.0.0/docs/index.md

@@ -0,0 +1,41 @@
+# Welcome to aquimodpy
+
+`aquimodpy` is a Python wrapper for the British Geological Survey's **AquiMod 2**, a lumped parameter groundwater model. It provides a clean, Pythonic interface to define complex hydrogeological models.
+
+## Overview
+This library allows you to:
+- Define soil, unsaturated, and saturated zone components using intuitive named arguments.
+- Seamlessly integrate with Pandas for input data and model observation.
+- Manage simulation runs (evaluation, Monte Carlo calibration, and SCE-UA optimization) through dedicated runner classes.
+- Run the original AquiMod 2 Windows binary on Linux environments using Wine.
+
+## Quick Start
+```python
+import pandas as pd
+from aquimodpy import Model, FAO, Weibull, Q3K3S1, Observations, EvaluationRunner
+
+# Initialize the model
+model = Model("MySim", "~/path/to/AquiMod2.exe", "./results")
+
+# Configure components
+FAO(model, theta_fc=0.4, theta_wp=0.1, Z_r=1000, p=0.5, BFI=0.8)
+Weibull(model, k=2.0, lambda_=5.0)
+Q3K3S1(model, dx=1000, K3=10, K2=5, K1=1, S=0.01, z3=50, z2=40, z1=30, alpha=1)
+
+# Set observations and run
+df = pd.read_csv("data.csv")
+Observations(model, df, {"DATE": "date", "RAIN": "rain", "PET": "pet", "GWL": "gwl"})
+
+model.set_runner(EvaluationRunner(model))
+model.run()
+```
+
+## API Reference
+Navigate through the core components of the library:
+
+- [Model Configuration](api.md#aquimodpy.Model)
+- [Observation Handling](api.md#aquimodpy.Components.Observations)
+- [Soil Components](api.md#aquimodpy.Components.FAO)
+- [Unsaturated Zone](api.md#aquimodpy.Components.Weibull)
+- [Saturated Zone](api.md#aquimodpy.Components.Q3K3S1)
+- [Simulation Runners](api.md#aquimodpy.EvaluationRunner)

aquimodpy-1.0.0/mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: aquimodpy
+theme:
+  name: material
+
+nav:
+  - Home: index.md
+  - API Reference: api.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_source: true
+            show_root_heading: true
+            members_order: source
+            show_if_no_docstring: true
+            show_bases: true
+            show_source: true
+
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences

aquimodpy-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "aquimodpy"
+version = "1.0.0"
+description = "Python wrapper for Aquimod 2"
+authors = [{name = "Arran Clarke"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "pandas>=3.0.3",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aquimodpy"]
+
+[dependency-groups]
+dev = [
+    "black>=26.5.0",
+    "build>=1.5.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+    "mypy>=2.1.0",
+    "pandas-stubs>=3.0.0.260204",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "twine>=6.2.0",
+]
+test = [
+    "matplotlib>=3.10.9",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.14"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

aquimodpy-1.0.0/src/aquimodpy/CalibrationRunner.py

@@ -0,0 +1,48 @@
+from typing import TYPE_CHECKING
+from .Runner import Runner
+import os
+
+if TYPE_CHECKING:
+    from .Model import Model
+
+
+class CalibrationRunner(Runner):
+    """Runner for Monte Carlo and SCE-UA calibration simulations."""
+
+    def prepare(self) -> None:
+        """Prepares calibration simulation."""
+        super().prepare()
+        # Generate component calibration files
+        self.write_component_calib_files()
+
+    def write_component_calib_files(self) -> None:
+        """Writes *_calib.txt files in the Calibration directory."""
+        calib_dir = os.path.join(self.model.working_directory, "Calibration")
+
+        components = [self.model.soil_zone, self.model.unsat_zone, self.model.sat_zone]
+
+        for comp in components:
+            if comp:
+                comp_name = comp.__class__.__name__
+                file_path = os.path.join(calib_dir, f"{comp_name}_calib.txt")
+
+                # Ensure parameters are written in the correct order specified in REQUIRED_PARAMETERS
+                if isinstance(comp.parameters, dict):
+                    with open(file_path, "w", newline="") as f:
+                        for param_name in comp.REQUIRED_PARAMETERS:
+                            bounds = comp.parameters.get(param_name)
+                            if bounds is None:
+                                continue  # Should not happen due to validation
+
+                            # Ensure bounds is a list/tuple of two values
+                            if (
+                                not isinstance(bounds, (list, tuple))
+                                or len(bounds) != 2
+                            ):
+                                # If it's a single value, treat it as fixed
+                                b = [bounds, bounds]
+                            else:
+                                b = list(bounds)
+
+                            f.write(f"{param_name}\r\n")
+                            f.write(f"{b[0]} {b[1]}\r\n\r\n")