Metadata-Version: 2.4
Name: mf6pqc
Version: 1.0.0
Summary: Reactive-transport coupling between MODFLOW 6 and PhreeqcRM
Author-email: Zitao Wang <zitao.wang@aust.edu.cn>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/wangzitao21/mf6pqc
Project-URL: Issues, https://github.com/wangzitao21/mf6pqc/issues
Keywords: groundwater,hydrogeology,MODFLOW 6,PhreeqcRM,reactive transport
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: modflowapi<2,>=1.0.1
Requires-Dist: phreeqcrm<0.1,>=0.0.18
Provides-Extra: examples
Requires-Dist: flopy<4,>=3.9; extra == "examples"
Requires-Dist: scipy<2,>=1.11; extra == "examples"
Requires-Dist: pandas<3,>=2.0; extra == "examples"
Requires-Dist: matplotlib<4,>=3.7; extra == "examples"
Requires-Dist: seaborn<1,>=0.12; extra == "examples"
Requires-Dist: gstools<2,>=1.6; extra == "examples"
Requires-Dist: jupyterlab<5,>=4; extra == "examples"
Requires-Dist: nbformat<6,>=5.9; extra == "examples"
Provides-Extra: test
Requires-Dist: coverage<8,>=7.6; extra == "test"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: coverage<8,>=7.6; extra == "dev"
Requires-Dist: ruff<1,>=0.16; extra == "dev"
Requires-Dist: twine<8,>=6; extra == "dev"
Dynamic: license-file

# MF6PQC v1.0

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](pyproject.toml)

MF6PQC couples MODFLOW 6 flow and solute transport with PhreeqcRM chemistry.
It supports sequential non-iterative (SNIA), sequential iterative (SIA), and
Strang splitting, with optional reaction-driven porosity, hydraulic
conductivity, diffusion, and density feedback. An opt-in thermal pathway
couples MODFLOW GWE/VSC temperature and viscosity with chemistry.

This is research software. A converged calculation and a validated conceptual
model are separate requirements. See the [scientific contracts](docs/scientific-contracts.md)
and the [verification history](docs/release-readiness.md) for tested
behavior and known limitations, including the E13 reference-comparison discrepancy.
The Python distribution and software citation use version `1.0.0`.

## Installation

Python 3.11 or newer is required. From a source checkout:

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install -e ".[examples]"
```

Once v1.0.0 is published on PyPI, install it with
`python -m pip install mf6pqc==1.0.0`.
The core dependencies are NumPy, modflowapi, and phreeqcrm. FloPy, plotting,
notebook, and example-specific dependencies are in the `examples` extra.

MODFLOW's shared library is installed separately; a standalone `mf6` executable
is insufficient for API coupling. The package does not redistribute native
MODFLOW binaries. The source examples use `bin/mf6.7.0/` or `bin/mf6.8.0/`
according to their existing benchmark configuration. To use another installation:

```powershell
$env:MF6PQC_BIN = "C:\tools\modflow6"
# Or specify the full shared-library path:
$env:MF6PQC_LIBMF6 = "C:\tools\modflow6\libmf6.dll"
```

On Linux use `export MF6PQC_BIN=/path/to/modflow6`; the helper selects
`libmf6.so` (`libmf6.dylib` on macOS). Native-library availability and
compatibility must be checked on the target platform. See
[installation and troubleshooting](docs/installation.md).

## First example

```bash
python examples/PHT3D_E01/run.py
python examples/PHT3D_E01/validate.py
jupyter lab examples/PHT3D_E01/plot.ipynb
```

Each case contains `input_data/`, `simulation/`, `output/`, `modflow_model.py`,
`run.py`, and `plot.ipynb`. Optional `validate.py` and `plot.py` contain quantitative
checks and reusable plotting functions. Paths are anchored to the case; commands
can also be launched from another working directory using an absolute script path.
Importing an example does not start a simulation.

For an integrated porosity/density/K example:

```bash
python examples/SaltLake_Brine3D/run.py --profile smoke --scenario feedback
python examples/SaltLake_Brine3D/validate.py --profile smoke --scenario feedback
```

The [example catalog](examples/README.md) identifies slow cases and available
validators. Long benchmarks are deliberately excluded from automated checks.

## Python API

Use `MF6PQC` and `SimulationConfig` for new applications. The historical
`mf6pqc` class name and keyword constructor remain supported.

1. Define a PHREEQC database, chemical input, and initial-condition map.
2. Construct the simulator and call `setup()` to obtain component concentrations.
3. Build a MODFLOW simulation with one GWT model for each returned component.
4. Call `run(method="SNIA")`, then `save_results()` inside a context manager.

See [the API guide](docs/api.md), the working
[E01 driver](examples/PHT3D_E01/run.py), and [architecture](docs/architecture.md).
All current coupling paths require **TDIS time units DAYS**. PhreeqcRM receives
seconds. Unsupported time units and ATS are rejected before native initialization.

Results include selected-output headings, the actual retained time axis, optional
physical-property arrays, and a JSON manifest with solver settings, software
versions, and input/library fingerprints. Concentrations use component-major
ordering; result arrays use `(time, selected_output, cell)`.

## Development and verification

```bash
python -m pip install -e ".[dev,examples]"
python -m unittest discover -s tests -v
python -m ruff check mf6pqc tests examples scripts
python -m ruff format --check mf6pqc tests examples scripts
python scripts/check_examples.py
python scripts/check_examples.py --native PHT3D_E01 GWE_VSC_Reactive
python -m build
python -m twine check --strict dist/*
```

The native-check tool uses an explicit short-case allowlist and isolated output
folders. It cannot run Xie2015 B1–B4, PHT3D E11, or Hamann2015.
See [validation](docs/validation.md), [contributing](CONTRIBUTING.md), and
[release procedure](docs/releasing.md).

## License and attribution

MF6PQC is distributed under GPL-3.0-only. MODFLOW 6, PhreeqcRM, their databases,
and the cited benchmark studies remain independently authored software/data.
Retain source attribution when reusing reference data. The software citation
metadata is in [CITATION.cff](CITATION.cff); cite the original solver and
benchmark publications as appropriate for your study.
