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.

This step also downloads and installs Ribasim core from GitHub releases to RIBASIM_HOME=‘bin/ribasim’

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
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
minio_access_key	MINIO_ACCESS_KEY	Access key for MinIO storage
minio_secret_key	MINIO_SECRET_KEY	Secret key for MinIO storage

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.