swatplus-bmi 0.1.0__tar.gz

swatplus_bmi-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.cache/
+build/
+bin/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+tests/runs/
+examples/runs/

swatplus_bmi-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Changes that matter to someone using swatplus-bmi. Versions follow semantic versioning; the
+SWAT+ releases each version supports are in COMPATIBILITY.md.
+
+## 0.1.0 (2026-11-04)
+
+First release, for SWAT+ 62.0.1.
+
+- Exchange mode for SWAT+, off unless started with `--exchange`: SWAT+ pauses before each day
+  and takes commands on standard input. Six calls in three SWAT+ files, one Fortran module, and
+  a C helper for branching (Mac, Linux).
+- Python BMI 2.0 wrapper (`SwatPlusBmi`): one-day steps, time in days since the start date, one
+  grid of points per object type, CSDMS-style names.
+- Reading: channel outflow, inflow and storage; aquifer storage, depth to water, outflow and
+  recharge; point source flow; water allocation demand and withdrawal.
+- Setting, for the next day: point source flow, water allocation demand.
+- Snapshots:
+  - `branch()` forks the paused process (Mac, Linux);
+  - `save_state`/`load_state` and `get_state`/`set_state` work on every platform, with the
+    serializer generated from SWAT+'s module declarations;
+  - saved locals that carry state are listed per release and saved too.
+- `swatplus-bmi build` fetches, patches and builds SWAT+ from an installed package.
+- Tests against unpatched SWAT+: every output file byte for byte, every variable against SWAT+'s
+  daily output, water balances, branching and saving against unbroken runs.
+- Example marimo notebook (`examples/tour.py`).

swatplus_bmi-0.1.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use swatplus-bmi in your work, please cite it as below."
+title: "swatplus-bmi: stepping the SWAT+ watershed model one day at a time through the Basic Model Interface"
+type: software
+authors:
+  - family-names: Sommerlot
+    given-names: Andrew
+    affiliation: Northline Hydrology
+    # orcid: https://orcid.org/0000-0000-0000-0000
+version: 0.1.0
+license:
+  - BSD-3-Clause
+  - LGPL-2.1-only
+repository-code: "https://github.com/northlinehydrology/swatplus-bmi"
+keywords:
+  - hydrology
+  - watershed modeling
+  - SWAT+
+  - Basic Model Interface
+  - BMI
+  - model coupling
+references:
+  - type: article
+    title: "Introduction to SWAT+, a completely restructured version of the Soil and Water Assessment Tool"
+    authors:
+      - family-names: Bieger
+        given-names: Katrin
+      - name: "and others"
+    journal: "Journal of the American Water Resources Association"
+    year: 2017
+    doi: 10.1111/1752-1688.12482

swatplus_bmi-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and constructive, assume good faith, and keep discussion about the
+work. Harassment and personal attacks aren't tolerated in issues, pull requests or any other
+project space.
+
+Report a problem to the maintainer, Andrew Sommerlot, at andrew@northlinehydrology.com. Reports
+are kept confidential. The maintainer will respond, and may warn, suspend or remove anyone who
+doesn't follow this code, as the Contributor Covenant's enforcement guidelines describe.

swatplus_bmi-0.1.0/COMPATIBILITY.md

@@ -0,0 +1,39 @@
+# SWAT+ versions
+
+swatplus-bmi patches a specific SWAT+ release. A version is supported only if
+it has a folder in `patches/` and passes the full test suite. `build.sh`
+refuses any other version.
+
+| SWAT+ | Released | Status | Tested on |
+|---|---|---|---|
+| 62.0.1 | 2026-10-19 | **Supported** | CI on every push: Ubuntu (gfortran from apt) and macOS 14 (Homebrew gcc). Locally: macOS 14 arm64, gfortran 16.1. |
+| main | rolling | Watched: built and tested nightly with the 62.0.1 patch, as an early warning. Not supported. | nightly build |
+| 62.0.0 | 2026-06-18 | Not supported: the patch doesn't apply (`time_control.f90` differs) | — |
+| 61.x and earlier | 2024–2026 | Not supported: no water allocation places of use, and the patch doesn't apply | — |
+
+Checked Nov 4, 2026: the patch applies unchanged to SWAT+ main as of commit
+6f51536 (Oct 16, 2026). `time_control.f90`, `command.f90` and `main.f90.in`
+are identical to 62.0.1 there.
+
+## How SWAT+ versions work
+
+SWAT+ numbers its releases by model revision (the "Revision" line in
+`simulation.out`), not semantic versioning: the 60.x series came before 61.x,
+and 62 is the current series. Full releases are infrequent: 61.0.1 (Jul 2024),
+61.0.2 (Aug 2024), 62.0.0 (Jun 2026), 62.0.1 (Oct 2026). Between them the
+SWAT+ team tags prereleases (twelve 61.0.2.x tags, Nov 2024 to Jan 2026),
+and the main branch takes merged pull requests continuously.
+
+## Policy
+
+- Each supported release gets its own `patches/<tag>/` folder. A new SWAT+
+  release is added when the patch is moved onto it and the full suite
+  passes, including the byte-for-byte comparisons with stock SWAT+.
+- Only full releases are supported, not prereleases or main.
+- The nightly build tests main with the newest supported patch. When it
+  fails, a new SWAT+ release is likely to need a new patch.
+- An older release stays supported as long as its patch still builds and
+  passes. It isn't fixed for new features.
+- If the exchange mode is merged into SWAT+ itself, the patch is no longer
+  needed from that release on, and this table records which SWAT+ release
+  has it built in.

swatplus_bmi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+swatplus-bmi is meant to be used in studies whose results feed public decisions about water,
+so a change has to keep the one promise the project makes: **SWAT+ stepped, branched or loaded
+through swatplus-bmi gives exactly the output SWAT+ gives on its own.** Every rule below follows
+from that.
+
+## Ways to contribute
+
+- **Report a bug.** Open an issue with the SWAT+ version, your platform and compiler, what you
+  ran, and what happened. A SWAT+ project that shows the problem is the most useful thing you
+  can attach.
+- **Share a test project.** The tests run on the two example projects that ship with SWAT+, and
+  those exercise about half of SWAT+'s code. A project that uses reservoirs, pesticides, salts,
+  gwflow or calibration, and can be made public, would widen the tests more than anything else.
+- **Ask for a variable.** Say what you want to read or set, which SWAT+ variable holds it, and
+  what you'd check it against.
+- **Pull requests** are welcome for fixes, variables, tests and documentation. For a larger
+  change (a new SWAT+ release, a protocol change), open an issue first.
+- **Questions:** open an issue with the `question` label.
+
+## Rules for changes
+
+1. **Identical output.** The comparison tests against unpatched SWAT+ must pass. If a change
+   can't keep SWAT+'s output identical, it doesn't go in.
+2. **A test for every variable.** A new variable is checked against SWAT+'s own output files,
+   every day, in `tests/test_reading.py` or `tests/test_setting.py`.
+3. **Only fluxes can be set.** Storage, land use, soils and parameters stay scenario inputs.
+4. **The patch stays small.** Changes to SWAT+'s own files go in `patches/<tag>/`, and as few as
+   possible. Everything else goes in new files in `fortran/`.
+5. **Generated code is generated.** Don't edit `bmi_state_module.f90` or `bmi_locals_module.f90`;
+   change the generators in `tools/`.
+6. **A new SWAT+ release** gets its own `patches/<tag>/` folder, a `carried-locals.toml` checked
+   with `build.sh --nosave` and `pytest -m full`, and a line in COMPATIBILITY.md.
+7. **Plain writing.** Documentation and comments say what the code does and why, plainly.
+
+## Running the checks
+
+```bash
+uv sync
+uv run ./build.sh --stock --nosave
+uv run pytest            # about two minutes
+uv run pytest -m full    # about fifteen minutes more
+```
+
+## Conduct
+
+Everyone taking part follows the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License of contributions
+
+Contributions to `fortran/` and `patches/` are under the GNU LGPL 2.1, like SWAT+. Everything
+else is under the BSD 3-Clause license. By opening a pull request you agree to license your
+contribution that way.

swatplus_bmi-0.1.0/LICENSE

@@ -0,0 +1,10 @@
+swatplus-bmi is under two licenses.
+
+- fortran/ and patches/ (the exchange mode added to SWAT+) and any SWAT+
+  built with them: GNU Lesser General Public License, version 2.1, the
+  license of SWAT+ itself. See LICENSES/LGPL-2.1.txt.
+
+- Everything else, including the Python wrapper in src/swatplus_bmi/, the
+  tests, tools and documentation: BSD 3-Clause. See LICENSES/BSD-3-Clause.txt. The wrapper is
+  a separate program: it starts SWAT+ as its own process and talks to it
+  over standard input and output, and is not linked with it.

swatplus_bmi-0.1.0/LICENSES/BSD-3-Clause.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andrew Sommerlot
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.