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.gitTo continue with the following steps, make the root of the repository your working directory by running
cd Ribasim-NLInstall 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. Maintainers create one key per institute in the MinIO console, restricted with this policy.
Copy the template .env.default in the root of the repository to .env:
cp .env.default .envThen 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 installThis installs the Python environment, the Git hooks, and the Ribasim core binary in bin/ribasim. It does not download project data; see Get data.
In a new git worktree, run pixi run setup-worktree instead. It shares the .env and the DVC cache of the main checkout, and installs the Ribasim core. Do not run pixi run install there: it points the Git hooks, which all worktrees share, to that worktree.
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 and its results:
pixi run dvc pull run_lhm_coupledThis fills data/Rijkswaterstaat/runs/lhm_coupled with the model input and its results. Open data/Rijkswaterstaat/runs/lhm_coupled/lhm_coupled.toml to see the model together with its results.
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 -fTo run all hooks on all files manually:
pixi run checkSee Testing for the tests, and Documentation for this website.
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, which holds bin, for the delwaq stage of the reproductions |
RIBASIM_NL_CLOUD_PASS |
Password for the legacy Good Cloud storage, which 9 parameterized stages use to download GKW data that is not local; 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.