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.

Installation

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):

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

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

Development

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 (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, see also CITATION.cff.