Contributing

Ribasim-NL welcomes contributions.

Setting up the developer environment

Clone Ribasim-NL

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

Install Pixi

Install Pixi as described in the Pixi documentation. Pixi manages all dependencies; always run commands through it, for example pixi run python path/to/script.py.

Add your access key

The project data and the Ribasim core binary are stored on Deltares MinIO (S3) storage. To access them you need an access key. Ask a repository maintainer for a read-only key.

Copy the template .env.default in the root of the repository to .env:

cp .env.default .env

Then fill in your key, using single quotes around the values:

AWS_ACCESS_KEY_ID='<access key>'
AWS_SECRET_ACCESS_KEY='<secret key>'

The .env file is gitignored, since it contains secrets. Pixi loads it automatically for every pixi run command. The other variables can normally keep their defaults, see Other settings.

Install the environment

Set up the full development environment by running:

pixi run install

This installs the Python environment, the Git hooks, and the Ribasim core binary in bin/ribasim. It does not download project data; see Get data.

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 clean and running pixi run install again.

Get data

The data is versioned with DVC, a tool that works like Git for large data files. You don’t need to know DVC to get started: download only the data you need, for instance the latest nationwide coupled model:

pixi run dvc pull data/Rijkswaterstaat/modellen/lhm_coupled/

The DVC page explains how to get the data for a specific step of the pipeline, and how to rerun it.

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

Other settings

Besides the access key, .env can hold these optional settings, read in src/ribasim_nl/ribasim_nl/settings.py:

Environment variable	Description
RIBASIM_NL_DATA_DIR	Local directory for data files, data by default
D3D_HOME	Root of the Delft3D installation, only needed for Delwaq
RIBASIM_NL_CLOUD_PASS	Password for the legacy Good Cloud storage; most users can leave it empty
OVERWRITE_FILES_FROM_CLOUD	Whether legacy Good Cloud downloads overwrite local files, true by default

Values from .env take precedence over environment variables set in your OS or terminal.