Contributing

Ribasim-NL welcomes contributions.

Setting up the developer environment

Clone Ribasim

In order to have the Ribasim-NL repository locally available, you can clone it with Git. Git can be installed from git-scm.com. Once installed, run the following command at a directory of your choice:

git clone https://github.com/Deltares/Ribasim-NL.git

To continue with the following steps, make the root of the repository your working directory by running

cd Ribasim-NL

Setting up Pixi

First, install Pixi as described in the Pixi documentation.

Then set up the full development environment by running:

pixi run install

This installs git hooks and pulls data. You can run Python scripts using pixi run python path/to/script.py.

The first time you open the Ribasim-NL repo in Visual Studio Code, the pixi-code extension should automatically detect the Pixi environment and configure the Python interpreter.

If you encounter issues, try running pixi cleanand running pixi install again.

Git hooks

We use prek instead of pre-commit for git hooks. It is installed as part of pixi run install, but you can also install hooks manually:

pixi run prek install -f

To run all hooks on all files manually:

pixi run check

To skip the slower DVC hooks and only run Python linting, formatting, and type checking:

pixi run pycheck

Co-development with Ribasim

Ribasim-NL pins to a specific Ribasim version in pixi.toml. Generally this will be the latest release. During development sometimes you may want to test out the latest unreleased development version of Ribasim.

To do so, open pixi.toml in your editor. Find the [pypi-dependencies] section and change the ribasim git source:

[pypi-dependencies]
ribasim = { git = "https://github.com/Deltares/Ribasim", branch = "main", subdirectory = "python/ribasim" }

You can change the branch name if needed, or use a specific commit with rev = "0075d4a".

If you are making changes to the Ribasim repository yourself, it will be more convenient to point to a local clone rather than GitHub. This can be done using this syntax:

[pypi-dependencies]
ribasim = { path = "../Ribasim/python/ribasim", editable = true }

This path will work if you clone Ribasim next to Ribasim-NL.

After you are done modifying pixi.toml, run pixi install to ensure the dependencies are installed.

For Ribasim developer documentation see ribasim.org/dev.

Environment variables

Several settings need to be configured via environment variables, managed by pydantic-settings in src/ribasim_nl/ribasim_nl/settings.py.

Setting	Environment variable	Description
ribasim_home	RIBASIM_HOME	Root of the Ribasim core installation
d3d_home	D3D_HOME	Root of the Delft3D installation
ribasim_nl_cloud_pass	RIBASIM_NL_CLOUD_PASS	Password for cloud storage access
ribasim_nl_data_dir	RIBASIM_NL_DATA_DIR	Local directory for data files
overwrite_files_from_cloud	OVERWRITE_FILES_FROM_CLOUD	Whether cloud downloads overwrite local files

In the root of the repository is a .env.default file with the defaults that can serve as a template. Copy it to .env and fill in RIBASIM_NL_CLOUD_PASS with the actual password, and adjust the other paths as needed. The .env file is gitignored because it is different per developer, and to avoid leaking the password. Make sure to use single quotes around values. The defaults below come from src/ribasim_nl/ribasim_nl/settings.py:

Values from the .env file take precedence over environment variables, so you can override system-wide settings per project. If you prefer to set these environment variables in your OS or terminal instead, that will also work.

OVERWRITE_FILES_FROM_CLOUD is true by default. When using cloud.synchronize or cloud.download_content, this determines if local files will be overwritten when the overwrite keyword argument is not explicitly passed. Whilst updating datasets locally, you can set this to false to ensure your modifications are not lost. After uploading the new dataset, set it back to true.

Type checking

We use Pyrefly for static type checking. Pyrefly is configured in the [tool.pyrefly] section of pyproject.toml.

Running Pyrefly

To check for type errors, run:

just pycheck

This runs all hooks except DVC, including Pyrefly type checking. This is also run in CI via the pyrefly job in .github/workflows/python_lint.yml.

Baseline file

Existing type errors are stored in a baseline.json file. Pyrefly’s baseline feature suppresses these known errors and only reports new errors. This way, pyrefly check passes cleanly without requiring ignore comments on every line.

The baseline is configured in pyproject.toml:

[tool.pyrefly]
baseline = "baseline.json"

Updating the baseline

After fixing existing type errors, regenerate the baseline to remove the fixed entries:

pixi run pyrefly check --update-baseline

If you introduce code that triggers new errors (e.g. from incomplete stubs) that cannot be reasonably fixed, you can add them to the baseline by running the same command. Prefer fixing the error or adding a targeted # pyrefly: ignore[error-code] comment when possible.

Suppressing individual errors

For specific lines where the type checker is wrong, use a targeted ignore comment:

x = some_expression  # pyrefly: ignore[error-code]

For lines that would exceed 120 characters with the comment appended, place the comment on the line above:

# pyrefly: ignore[error-code]
x = some_very_long_expression_that_would_be_too_long_with_an_inline_comment