QGIS plugin

1 Opening a model

This guide assumes you have already installed the Ribasim core and QGIS plugin as described in the install page.

Use any running Ribasim model to follow this guide. For ready-made example models download and unzip generated_testmodels.zip from the release assets, and use for instance the basic test model.

You can open a model by clicking on the Ribasim icon on the toolbar, selecting Open Ribasim model, and choosing a TOML file.

Alternatively, drag a TOML file into QGIS.

If the Ribasim icon on the toolbar is hidden, click View > Toolbars, and enable the Ribasim toolbar. The same options are also available under the Plugins menu.

When the model is opened, the network is shown on the map. The model is loaded as a layer group, consisting of an Input layer group and, if available, a Results layer group. The input consists of the spatial layers for the network, and data tables that are loaded as attribute tables.

2 Running a model

Click on the Ribasim icon on the toolbar, select Run Ribasim model.

This will run the simulation in the background, showing progress in the QGIS task manager and a live output dialog. When the simulation completes successfully, the model results are automatically reloaded.

QGIS resolves the Ribasim executable in this order:

  1. Set Ribasim home (QGIS → Plugins → Ribasim → Set Ribasim home)
  2. The RIBASIM_HOME environment variable (if set)
  3. The system PATH
  4. %LOCALAPPDATA%\Microsoft\WindowsApps (on Windows)

See the install section for details.

3 Inspect model tables

For larger models the node tables can grow quite large. To facilitate inspection, the tables are linked via the node_id field to the Node table, and react to the selection of the Node layer. That is, on selection of certain nodes—either via the map or the attribute table—the selection is also made in all related tables. This is also the case for the Link layer. It helps to set the attribute table of a table of interest to show selected features only (using the dropdown button on the bottom left).

Selection change

4 Timeseries results

Click on the Ribasim icon on the toolbar, select Timeseries results.

This will open a plotting pane. If you have results, it will select the level and flow_rate variables by default. You can select other variables in the dropdown menu. Clicking the node or link buttons allows you to select what you want to plot on the map.

Select the link button. Now select the links that you want to see the timeseries of. Whenever the selection changes, the plot updates. You can use to select multiple links, or ( on macOS) to toggle links on and off.

Flow rates can also be plotted from the nodes. Depending on the node type, you will see a simple flow rate (e.g. Pump), or separate inflow and outflow rates, summed if there are multiple incoming or outgoing links (e.g. Basin).

You can select multiple variables to plot at the same time, they are grouped by unit. Note that Basin results are only available on Basins, which means you have to select the node button first, and then select the Basin nodes you wish to see. Select one Basin, and choose the variable water balance to see:

Select one link, and if you have concentration results, you can choose the variable fractional flow to see which tracers the flow consists of:

Under the variable → concentration dropdown menu you can select another set of tracers if they are available.

If your model has Observation nodes, select the node button and click an Observation node to compare its observed and simulated timeseries. The observed series (read from the input) is drawn in black, and the corresponding simulated series in red.

5 Spatial results

The timeseries results show the change of selected nodes and links over time. To get more insight into the model at a selected time, you can show the results on the map. In the Layers panel, the Results group shows a Basin layer that by default shows water levels, and a Flow layer that shows flow rates on links by default. If you ran with concentration enabled, a Concentration layer can show concentrations on the map.

By selecting layers and configuring layer properties you can control how you want to present results. For instance in the figure below, the Input / Node is shown with the Results / Flow. By clicking the clock icon, you can open the QGIS Temporal Controller Panel. That allows you to select the time, or animate through time.

By default, the values are shown as labels, and the line thickness increases with the flow rate. These styling options can be configured just like regular QGIS layers.

6 Reloading models

If you made changes to your model outside of QGIS, and want to see the new version in QGIS, the quickest way is to click Reload Ribasim model. This reloads both the model and the results.

This avoids the need to remove the group and open the same model again via the plugin. It can be convenient when iteratively building your model via Python, or running new simulations. If no model is loaded, the most recently opened model is loaded.

7 Network topology

Link geometries can be either straight lines connecting nodes, or curved lines that follow waterbodies. Curved geometries can be more recognizable on the map, but when inspecting the connections in the network, it can be useful to view the curved lines as straight lines. This can be done by the “Show topology” toggle in the context menu, seen when right-clicking the Input / Link or Results / Flow layers.

The effect on a curved river segment can be seen below. The Basin / area polygons are not affected by this change.