You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There are three main components of the Ribasim software package.
51
-
They are the Ribasim core (written in Julia language), the Ribasim Python package and the Ribasim QGIS plugin.
48
+
They are the Ribasim core, the Ribasim Python package and the Ribasim QGIS plugin.
52
49
53
-
The kernel of Ribasim is written in the [Julia programming language](https://julialang.org/) and is built on top of the [SciML: Open Source Software for Scientific Machine Learning](https://sciml.ai/) libraries, notably [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/).
50
+
The [core](/reference/usage.qmd) is a command line interface (CLI) that runs Ribasim simulations.
51
+
It is written in the [Julia programming language](https://julialang.org/) and is built on top of the [SciML: Open Source Software for Scientific Machine Learning](https://sciml.ai/) libraries, notably [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/).
54
52
55
53
The [Ribasim Python package](/reference/python/index.qmd) is available to build, update and analyze Ribasim models programmatically.
56
-
For runtime data exchange and coupling with other kernels, the Julia kernel is wrapped in a Python API (`ribasim_api`) which implements the Basic Model Interface [BMI](https://bmi-spec.readthedocs.io/en/latest/).
54
+
One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible.
57
55
58
56
Ribasim uses [GeoPackage](https://www.geopackage.org/) files to store the model database (`database.gpkg`).
59
-
[QGIS](https://qgis.org/) works well with GeoPackage files.
60
-
This makes QGIS the perfect application to inspect and make edits to Ribasim models.
61
-
Deltares also provides the iMOD QGIS plugin, which can be used to inspect the results of a Ribasim model too.
62
-
For larger edits using Python is recommended.
63
-
One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible.
57
+
[QGIS](https://qgis.org/) works well with GeoPackage files, making it a good application to visualize Ribasim models.
58
+
Deltares also provides the iMOD QGIS plugin, which can be used to view the timeseries in the Ribasim results.
64
59
65
-
Users can choose to use Ribasim Python or QGIS plugin or a combination of them to build a Ribasim model.
66
-
And then use the Ribasim core to run the simulation.
60
+
::: {.callout-note}
61
+
The components don't depend on each other, so you can install what you need.
62
+
When using multiple components, all component versions must be the same.
63
+
If you receive a model, the Ribasim version used to create it is written in the TOML file. Older releases can be found in the Release assets [on GitHub](https://github.com/Deltares/Ribasim/releases).
64
+
:::
67
65
68
-
# Install Ribasim core
66
+
# Install Ribasim core {#sec-install-core}
69
67
70
68
Ribasim is typically used as a command-line interface (CLI). It is distributed as a `.zip`
71
69
archive, that must be downloaded and unpacked. It can be placed anywhere, however it is
@@ -74,16 +72,15 @@ executable is in the main folder.
74
72
75
73
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.
81
79
82
80
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\`.
83
81
If you are using cmd.exe type `ribasim`, or for PowerShell `./ribasim`.
84
82
85
-
This will give the following message:
86
-
83
+
This will give the following message if it is installed correctly:
87
84
```
88
85
error: the following required arguments were not provided:
89
86
<TOML_PATH>
@@ -93,43 +90,103 @@ Usage: ribasim <TOML_PATH>
93
90
For more information, try '--help'.'
94
91
```
95
92
96
-
# Install Ribasim Python
93
+
## Adding Ribasim to Path on Windows
94
+
95
+
To use Ribasim from any directory without specifying the full path, you can add the Ribasim executable directory to your Windows Path environment variable.
96
+
97
+
The Path environment variable tells Windows where to look for programs when you type their name in a terminal. By adding Ribasim to your Path, you can type `ribasim` from any folder instead of having to navigate to the Ribasim folder first or typing the full path like `C:\bin\ribasim\ribasim.exe`.
98
+
99
+
- Search "Environment Variables" in the Windows search bar
100
+
- Click "Edit the system environment variables"
101
+
- Click on the "Advanced" tab
102
+
- Click the "Environment Variables..." button at the bottom
103
+
- In the top section "User variables", scroll down and find "Path", then click "Edit..."
104
+
- Click "New" and enter the full path to your Ribasim directory (e.g., `C:\bin\ribasim`, not `C:\bin\ribasim\ribasim.exe`)
105
+
- Click "OK" three times to close all dialogs
106
+
- Close any open terminals/command prompts and open a new one
107
+
108
+
# Install Ribasim Python {#sec-install-python}
97
109
98
110
The Ribasim Python package (named `ribasim`) aims to make it easy to build, update and analyze Ribasim models
99
111
programmatically.
100
112
101
-
The Ribasim QGIS plugin allows users to construct a model from scratch without programming.
102
-
For specific tasks, like adding observed rainfall timeseries, it can be faster to use
103
-
Python instead.
113
+
The Ribasim Python package is [registered in PyPI](https://pypi.org/project/ribasim/) and [conda-forge](https://prefix.dev/channels/conda-forge/packages/ribasim) and can therefore be installed with [pixi](https://pixi.sh/), [uv](https://docs.astral.sh/uv/), [pip](https://docs.python.org/3/installing/index.html) or [conda](https://docs.conda.io/).
114
+
We recommend Pixi, but installation instructions for all are provided below.
115
+
116
+
::: {.panel-tabset}
104
117
105
-
One can also use Ribasim Python to build entire models from base data, such that your model
106
-
setup is fully reproducible.
118
+
## pixi
107
119
108
-
The Ribasim Python package is [registered in PyPI](https://pypi.org/project/ribasim/) and [conda-forge](https://prefix.dev/channels/conda-forge/packages/ribasim) and can therefore be installed with [pip](https://docs.python.org/3/installing/index.html), [conda](https://docs.conda.io/) or [pixi](https://pixi.sh/):
120
+
Install Pixi following the [Pixi installation documentation](https://pixi.sh/latest/installation/).
121
+
Note that if the recommended installation methods don't work due to restriction on your PC, the [zipped executable](https://pixi.sh/latest/installation/#download-from-github-releases) is likely to still work.
109
122
123
+
Open a terminal in your project directory, and create an empty pixi environment:
110
124
```sh
111
-
pip install ribasim
125
+
pixi init
112
126
```
113
-
or create a pixi environment in your modeling project with:
127
+
Now add Ribasim Python:
114
128
```sh
115
-
pixi init
129
+
pixi add ribasim==2025.4.0
130
+
```
131
+
To start Python, run:
132
+
```sh
133
+
pixi run python
134
+
```
135
+
136
+
If you wish to check what is installed in your workspace, run `pixi list`.
137
+
When you run into what seems like installation issues, try `pixi clean`, followed by `pixi install`.
138
+
139
+
If your editor does not automatically detect the right Python environment, point it to `.pixi/envs/default/python.exe`.
140
+
Starting your editor via Pixi will also help it find the environment since it will already be active.
141
+
For Visual Studio Code, you can run `pixi run code .` to open your workspace.
142
+
143
+
## uv
144
+
145
+
Install `uv` following the [instructions in the uv documentation](https://docs.astral.sh/uv/getting-started/installation/).
146
+
147
+
Open a terminal in your project directory, and create an empty uv project:
148
+
```sh
149
+
uv init
150
+
```
151
+
Now add Ribasim Python:
152
+
```sh
153
+
uv add ribasim==2025.4.0
154
+
```
155
+
To start Python, run:
156
+
```sh
157
+
uv run python
158
+
```
159
+
160
+
## pip
161
+
162
+
```sh
163
+
pip install ribasim==2025.4.0
116
164
```
117
-
and install ribasim:
165
+
166
+
## conda
167
+
168
+
Ribasim is available in the [conda-forge](https://conda-forge.org/) channel.
169
+
[Miniforge](https://conda-forge.org/download/) is the preferred conda-forge installer and includes `conda`, `mamba`, and their dependencies.
170
+
It may not work well when combined with the Anaconda default channel, see [transitioning from defaults](https://conda-forge.org/docs/user/transitioning_from_defaults/).
171
+
118
172
```sh
119
-
pixi add ribasim
173
+
conda install -c conda-forge ribasim=2025.4.0
120
174
```
121
-
For documentation please see the [examples](/guide/examples.qmd) and [API reference](/reference/python/index.qmd).
122
175
123
-
# Install Ribasim QGIS plugin
176
+
:::
177
+
178
+
For Ribasim Python documentation please see the [examples](/guide/examples.qmd) and [API reference](/reference/python/index.qmd).
0 commit comments