Metadata-Version: 2.4
Name: swatpy
Version: 0.3.0
Summary: A Python package to run, control/manipulate and analyse SWAT2012 models
Author-email: Alexander Kmoch <alexander.kmoch@ut.ee>
License-Expression: MIT
Project-URL: Homepage, https://github.com/allixender/swatpy
Project-URL: Source, https://github.com/allixender/swatpy
Project-URL: Issues, https://github.com/allixender/swatpy/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.6322023
Keywords: SWAT,SWAT2012,hydrology,calibration,spotpy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: chardet
Provides-Extra: calibration
Requires-Dist: spotpy; extra == "calibration"
Requires-Dist: scipy; extra == "calibration"
Requires-Dist: pandas; extra == "calibration"
Provides-Extra: mpi
Requires-Dist: spotpy; extra == "mpi"
Requires-Dist: mpi4py; extra == "mpi"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# swatpy

A set of Python modules to work with the Soil and Water Assessment Tool (SWAT2012), including model runs, programmatic edits of the model input files, readout of simulation outputs and calibration with the SPOTPY package.

[![PyPI version](https://badge.fury.io/py/swatpy.svg)](https://badge.fury.io/py/swatpy) [![tests](https://github.com/allixender/swatpy/actions/workflows/tests.yml/badge.svg)](https://github.com/allixender/swatpy/actions/workflows/tests.yml) [![docs](https://github.com/allixender/swatpy/actions/workflows/docs.yml/badge.svg)](https://github.com/allixender/swatpy/actions/workflows/docs.yml) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6322023.svg)](https://doi.org/10.5281/zenodo.6322023)

## Installation

```sh
pip install swatpy                  # numpy and chardet only
pip install "swatpy[calibration]"   # plus spotpy, scipy and pandas for the calibration scripts
pip install "swatpy[mpi]"           # plus mpi4py for parallel spotpy samplers
```

swatpy requires Python 3.10 or newer. A SWAT2012 executable is not included; it is looked up on the `PATH` or in the model directory, or it can be set explicitly as `model.swat_exec`.

## Usage

A model is a working copy of an ArcSWAT `TxtInOut` folder with a small metadata file (`.swatmodel.json`):

```python
from swatpy import SwatModel, ReadOut

model = SwatModel.initFromTxtInOut("path/to/TxtInOut", copy=True, target_dir="work")
# later: model = SwatModel.loadModelFromDirectory("work")
model.enrichModelMeta()            # simulation period and printed years from file.cio

# calibration parameters: <v|r|a>__<PARAM>__<file type>
model.setParameter("r__CN2__mgt", -0.1)      # relative: CN2 * (1 - 0.1) in all .mgt files
model.setParameter("v__GW_DELAY__gw", 30.0)  # replace
model.setParameter("a__SOL_AWC__sol", 0.02)  # add, all soil layers

model.swat_exec = "/path/to/swat2012"
model.run(silent=True)

reach = ReadOut.rchOutputManipulator(["FLOW_OUT"], [1], "skip", True, 0, model.working_dir, iprint="month")
flow = reach.outValues["FLOW_OUT"][1]
```

The file manipulators in `swatpy.FileEdit` (`bsn`, `gw`, `mgt`, `sub`, `hru`, `rte`, `sol`, `file.cio`) read and write parameters at their fixed positions in the SWAT input files. Changes are always computed from the values read when the manipulator was created, so repeated calibration runs do not accumulate; changes of several parameters of the same file are all kept. The line endings of the files are preserved. The SWAT-CUP qualifiers of a parameter name (hydrologic group, soil texture, landuse, subbasin, slope; e.g. `v__CANMX__hru______FRSD`) are parsed but not evaluated, such a parameter is applied to all files of its type.

The output readers in `swatpy.ReadOut` take the column positions of the variables from the header line of `output.rch`, `output.sub` and `output.hru`, so a reduced selection of printed variables in `file.cio` is read correctly. The yearly summary rows of monthly output and the closing average-annual rows are skipped.

The folder `data/scripts` contains the calibration drivers used with SPOTPY on the University of Tartu HPC cluster (sequential and MPI), and `data/params` the corresponding parameter ranges.

## Changes in 0.3.0

Version 0.3.0 fixes several errors that affect calibration results produced with earlier versions:

- parameter changes of the same file with `finishChangePar()` in between (as in the calibration scripts) overwrote each other, only the last parameter per file type was applied;
- monthly readouts (`iprint="month"`) dropped December and kept the yearly summary row instead;
- `efficiency.nash()` and `agr()` returned a masked value when the observations contain nodata;
- changes of `SOL_ZMX` joined two lines of the `.sol` file, and `SOL_ZMX` was read without its first digit;
- `file.cio` values were written as decimals, and `solManipulationCorrection` doubled the clay content;
- `output.hru` was read from the wrong columns.

The packaging moved from `setup.py` to `pyproject.toml`; spotpy, scipy and pandas are optional dependencies now.

## Documentation

The user and API documentation lives in `docs/` and is published to GitHub Pages at https://allixender.github.io/swatpy/ (built by `.github/workflows/docs.yml`).

```sh
pip install -e ".[docs]"   # mkdocs-material + mkdocstrings
mkdocs serve               # live preview
```

## Development

```sh
pip install -e ".[dev]"
pytest -m "not swat"                        # unit tests on synthetic fixtures
SWATPY_TEST_DOWNLOAD=1 pytest -m swat -rs   # real SWAT2012 project, and model runs on linux x86_64
pytest tests/test_fileedit.py -k sol        # a subset
```

The unit tests use a small synthetic SWAT2012 model and synthetic output files in `tests/data`, generated by `tests/data/make_fixtures.py` in the fixed-width layout of SWAT2012 rev 637. The `swat` tests download the rev 637 demo project and Linux executable from [SWATdata](https://github.com/chrisschuerz/SWATdata) (GPL-3, therefore not included here) into `~/.cache/swatpy-tests`; `SWATPY_SWAT_EXE` points them to another SWAT2012 executable.

## Releasing

Releases are published to PyPI with trusted publishing from GitHub Actions (`.github/workflows/publish.yml`):

1. set `__version__` in `swatpy/__init__.py` and the version in `CITATION.cff`;
2. create a GitHub release with the tag `v<version>`, which builds, checks and uploads the package to PyPI;
3. a manual run of the workflow uploads to TestPyPI instead.

This requires a trusted publisher for the project `swatpy` on PyPI (and TestPyPI) with the repository `allixender/swatpy`, the workflow `publish.yml` and the environment `pypi` (`testpypi`), as well as these two environments in the GitHub repository settings.

## Citation

If you use swatpy, please cite it via the Zenodo DOI [10.5281/zenodo.6322023](https://doi.org/10.5281/zenodo.6322023), see also `CITATION.cff`.
