Installation

In this document, we describe how to install the different components of Ribasim. First the components and their relation are introduced, then installation instructions per component follow.

1 Components

The figure below illustrates the relation between the various components of Ribasim.

flowchart TB
modeler([Modeler]):::user

api["Ribasim Python\n[python]"]
modeler-->|prepare model|api

ribasim["Ribasim\n[julia]"]
modeler-->|start|ribasim

subgraph qgisBoundary[QGIS]
    QGIS[QGIS Application]:::system_ext
    qgisPlugin["Ribasim QGIS plugin\n[python]"]
    QGIS-->qgisPlugin
end
modeler-->|prepare model|qgisBoundary

model[("input model data\n[toml + geopackage + arrow]")]
qgisPlugin-->|read/write|model
api-->|read/write|model
ribasim-->|simulate|model

output[("simulation results\n[arrow]")]
ribasim-->|write|output

class qgisBoundary boundary

%% class definitions for C4 model
classDef user fill:#ABD0BC
classDef system_ext fill:#D2D2D2
classDef boundary fill:transparent,stroke-dasharray:5 5

There are three main components of the Ribasim software package. They are the Ribasim core (written in Julia language), the Ribasim Python package and the Ribasim QGIS plugin.

The kernel of Ribasim is written in the Julia programming language and is built on top of the SciML: Open Source Software for Scientific Machine Learning libraries, notably DifferentialEquations.jl.

The Ribasim Python package is available to build, update and analyze Ribasim models programmatically. For runtime data exchange and coupling with other kernels, the Julia kernel is wrapped in a Python API (ribasim_api) which implements the Basic Modelling Interface BMI.

Ribasim uses GeoPackage files to store the model database (database.gpkg). QGIS works well with GeoPackage files. This makes QGIS the perfect application to inspect and make edits to Ribasim models. Deltares also provides the iMOD QGIS plugin, which can be used to inspect the results of a Ribasim model too. For larger edits using Python is recommended. One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible.

Users can choose to use Ribasim Python or QGIS plugin or a combination of them to build a Ribasim model. And then use the Ribasim core to run the simulation.

2 Install Ribasim core

Ribasim is typically used as a command-line interface (CLI). It is distributed as a .zip archive, that must be downloaded and unpacked. It can be placed anywhere, however it is important that the contents of the zip file are kept together in a directory. The Ribasim executable is in the main folder.

To download the Ribasim core, download the appropriate zip file for your operating system:

Note that we currently only support and provide binaries for Windows and Linux, for the x86_64 architecture.

To check whether the installation was performed successfully, open a terminal and go to the path where the executable is for example C:\bin\ribasim\. If you are using cmd.exe type ribasim, or for PowerShell ./ribasim.

This will give the following message:

error: the following required arguments were not provided:
  <TOML_PATH>

Usage: ribasim <TOML_PATH>

For more information, try '--help'.'

3 Install Ribasim Python

The Ribasim Python package (named ribasim) aims to make it easy to build, update and analyze Ribasim models programmatically.

The Ribasim QGIS plugin allows users to construct a model from scratch without programming. For specific tasks, like adding observed rainfall timeseries, it can be faster to use Python instead.

One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible.

The Ribasim Python package is registered in PyPI and conda-forge and can therefore be installed with pip, conda or pixi:

pip install ribasim

For documentation please see the examples and API reference.

4 Install Ribasim QGIS plugin

The Ribasim QGIS plugin requires QGIS 3.34 or higher. The Ribasim QGIS plugin is only distributed as a .zip archive and must be downloaded and installed in QGIS.

4.1 Install Ribasim plugin

Firstly, download ribasim_qgis.zip:

In QGIS, go to Plugins menu > Manage and Install Plugins…

Select “Install from ZIP”:

  • Browse to the ribasim_qgis.zip file containing the plugin that was downloaded earlier
  • Click “Install Plugin”

Open the Ribasim plugin panel.

4.2 Install iMOD plugin

In QGIS, navigate to “Plugins > Manage and Install Plugins > All”. In the search bar, type: “iMOD”. Select the iMOD plugin, and click “Install”.

At least version 0.5.2 of the iMOD plugin is required.

The Time Series widget from the iMOD plugin is used for visualizing Ribasim results, which is described in the results section. Documentation on the Time Series widget can be found in the iMOD documentation.