iMOD Coupler

May 8, 2026 · View on GitHub

imod_coupler couples hydrological kernels. It currently focuses on groundwater and supports coupling between MetaSWAP, MODFLOW 6, and Ribasim.

It is a command-line application that can be run via:

imodc /path/to/imod_coupler.toml

For usage information, run:

imodc --help

Issues

Deltares colleagues can find the issue tracker on Jira.

Contributing

Setting up your machine

To develop imod_coupler locally:

Download and install pixi.
Clone the repository and navigate to the project root.
Create the development environment:
```
pixi install -e dev
```
Install the test dependencies:
```
pixi run -e dev install-test-dependencies
```
This command:
- Downloads the kernel dependencies (MetaSWAP, MODFLOW 6 & Ribasim) and the regression imod_coupler
- Downloads the MetaSWAP lookup table
- Generates a .env file in the project root with environment variables pointing to the downloaded binaries in the .pixi folder
Run the tests:
```
pixi run -e dev tests
```
Lint the codebase:
```
pixi run -e dev lint
```

Tip: When developing with Visual Studio Code, open the project via open-vscode.bat to launch a new window with the correct environment variables set.

Running acceptance tests

The user acceptance tests currently use the LHM model. More models may be added in the future. These tests can only be run locally on Windows.

Pull the data from the Minio/DVC remote:
```
pixi run -e user-acceptance fetch_lhm
```
This unpacks the LHM model data and the MetaSWAP database required for the tests.
Run the user acceptance tests:
```
pixi run -e user-acceptance user_acceptance_test
```
The tests take approximately 60 minutes to complete.

Various versions of test data are tracked using DVC, which allows different data versions to exist across branches. The storage bucket is read-only for the public. To push new or updated data, contact one of the project maintainers.

Debugging

When debugging unit tests in Visual Studio Code using the Test Explorer, you may encounter issues because MODFLOW 6 and MetaSWAP can behave unpredictably when initialized and finalized multiple times in the same process.

This does not occur when running (not debugging) unit tests, because a conditional check determines whether to call subprocess.run() or stay within the main thread. See the run_coupler_function fixture for details.

Troubleshooting

If you encounter errors after pulling the latest changes, your pip dependencies may be outdated. Update them by running:

pixi run update-git-dependencies

Creating a release

Update the version number in imod-coupler/__init__.py.
Update the version number in pre-processing/primod/__init__.py.
Add all notable changes to the [Unreleased] section in CHANGELOG.md, using the existing subsections (Added, Fixed, Changed, Removed).
In CHANGELOG.md, rename ## [Unreleased] to ## [vYYYY.MM.X] and add a fresh empty ## [Unreleased] section above it:
```
## [Unreleased]

### Added

### Fixed

### Changed

### Removed

## [vYYYY.MM.X]
...
```
You can verify the notes that will be used for the release with:
```
python scripts/extract_changelog_notes.py vYYYY.MM.X
```

Commit the changelog and the init file updates:

git add CHANGELOG.md imod_coupler/__init__.py pre-processing/primod/__init__.py 
git commit -m "Release vYYYY.MM.X"

When the commit has been merged to main or a release branch, switch to that branch and tag the commit:
```
git tag vYYYY.MM.X
```
Push the tag:
```
git push origin vYYYY.MM.X
```
In TeamCity, select the Deploy project and trigger the Deploy All build, selecting the tag vYYYY.MM.X as the branch. TeamCity will build the artifacts and create the GitHub release using the notes from CHANGELOG.md.