Metadata-Version: 2.4
Name: aquimodpy
Version: 1.0.1
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

[![PyPI version](https://img.shields.io/pypi/v/aquimodpy.svg)](https://pypi.org/project/aquimodpy/)
[![Python versions](https://img.shields.io/pypi/pyversions/aquimodpy.svg)](https://pypi.org/project/aquimodpy/)
[![CI status](https://github.com/afc98/aquimodpy/actions/workflows/ci.yml/badge.svg)](https://github.com/afc98/aquimodpy/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/aquimodpy.svg)](https://github.com/afc98/aquimodpy/blob/master/LICENSE)

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
# Using pip
pip install aquimodpy

# Using uv
uv add aquimodpy
```

## Documentation
* [Latest release](https://afc98.github.io/aquimodpy/)

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