1 Changelog

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog,

1.1 [Unreleased]

1.2 [v2025.5.0] - 2025-09-09

This release focuses on improving allocation capabilities and performance optimizations. We linearize the optimization problem, and Pump and Outlets can now listen to allocation to set the flow rate. NetCDF output has been added, as well as experimental support for NetCDF input. DiscreteControl now supports an upper and lower threshold to model hysteresis. Editing models in QGIS is no longer supported; the plugin widget has been reduced one button. The Ribasim Python installation section allows you to pick your favorite package manager. Lastly, Ribasim is now multithreaded!

Breaking changes: In the DiscreteControl / condition table, greater_than has been renamed to threshold_high, and the optional threshold_low column was added. The surface_runoff column was added to Basin / static and Basin / time. Note that Ribasim Python will migrate existing models automatically, see also the new guide on updating Ribasim.

1.2.1 Added

  • Add surface_runoff to Basin fluxes. #2402
  • Support NetCDF results. #2497
  • Support NetCDF input. #2542
  • Add multithreading. #2562
  • Implement hysteresis on DiscreteControl. #2564
  • Add FlowBoundary / area polygons. #2537
  • Native multi-objective optimization in allocation. #2522
  • Add control by allocation functionality. #2401
  • FlowDemand supports multiple priorities. #2500
  • Report cause of infeasibility in allocation problems. #2398 #2481
  • Add convergence and dt to results for performance monitoring. #2405
  • Warn when reading a new model with an old Ribasim Python version. #2410
  • Add instructions to install using Pixi. #2415
  • Add guide on updating Ribasim models. #2489
  • Support DiscreteControl listening to a Basin’s storage. #2573

1.2.2 Changed

  • Allow two incoming control links for Pump and Outlet. #2531
  • Use FlowDemand demand as minimum Pump/Outlet flow when allocation is not active. #2506
  • Expand and improve LevelDemand functionality with absolute error handling. #2386 #2515
  • Allocation optimization with warm start for better performance. #2466
  • Scale storage and flow in allocation for numerical stability. #2407
  • Switch from UMFPACK to KLU sparse linear solver for performance. #2391
  • Use pandera v0.25, and revert using pyarrow dtypes. #2450
  • QGIS: remove editing features for simplified workflow. #2472
  • Use smooth interpolation of ContinuousControl and TabulatedRatingCurve functions. #2446 #2458
  • Use a Reynolds based threshold for the ManningResistance relaxed root 2544
  • Demand nodes with timeseries now use block interpolation 2568

1.2.3 Fixed

  • Core model initialization speedup. #2548 #2533
  • Fix validation error on multiple incoming control links. #2535
  • Improve error message for DiscreteControl with no data. #2540
  • Make convergence finite to avoid numerical issues. #2534
  • Cache FlowDemand lookup to avoid expensive operations in water_balance!. #2523
  • Increase stacksize on Windows to 8 MB to prevent stack overflow. #2546
  • Align timestep allocated and realized results in allocation.arrow. #2554
  • Support GeoPandas 1.1. #2547

1.3 [v2025.4.0] - 2025-06-16

This release had a big push on the stability and performance for large models. Users can now also provide a level-storage relation in Basin / profile. This means old models need to be migrated by reading them into Ribasim Python, and writing them out. We are working on reformulating the allocation problem. Until this work is finished, allocation remains an experimental feature of Ribasim.

1.3.1 Added

  • Reload Ribasim model in QGIS. #2307
  • Support storage column in Basin / profile #2278
  • Allow Junction to Terminal links. #2295
  • Add model performance debugging guide #2308
  • Make FlowBoundary interpolation method configurable #2285
  • Output interpolated Basin / profile in debug mode #2344
  • Write log file via BMI #2370

1.3.2 Changed

  • Reformulate the allocation problem. #2266
  • Mark allocation as experimental. #2266
  • Low storage threshold based on 10 cm depth #2357
  • Stability: decrease relative tolerance over time. #2277
  • Use block interpolation for FlowBoundary by default #2285
  • Remove backtracking, add more caching #2359
  • More realistic smoothing around Δh = 0 in ManningResistance. #2365

1.3.3 Fixed

  • Fix writing results on saveat = 0 #2305
  • Fix error in flow limiter #2334
  • Fix cyclic Basin forcing #2313
  • BMI: return 1 on update if solve not successful #2341

1.4 [v2025.3.0] - 2025-04-14

The only breaking change in this release is to disallow connecting a single FlowBoundary to multiple Basins. There are large improvements in the ability to visualize results on the map in QGIS. We also welcome the Junction node to the family, which will help laying out networks in a recognizable manner.

1.4.1 Added

  • Add spatio-temporal results layers to QGIS. #2208
  • Add topological (straight line) link view toggle to QGIS. #2208
  • Added Junction node type. #2175
  • Write results and log bottlenecks also on an interrupt or crash. #2191 #2200
  • Log computation time and save it to solver_stats.arrow. #2209
  • Experimental support for writing the model network and results into files used by Delft-FEWS, model.to_fews. #2161
  • Document results/concentration.arrow. #2165

1.4.2 Changed

  • Allow max 1 outflow neighbour for FlowBoundary. #2192
  • Automatic differentiation is enabled by default again, autodiff = true, leading to better performance. #2137 #2183

1.5 [v2025.2.0] - 2025-03-10

In this release, time is of the essence. We now support dynamic Pumps and Outlets, as well as DiscreteControl thresholds. For each node, timeseries can be marked as cyclic, such that yearly recurring timeseries can be easily used without repetition. We also developed tools to compare model input in Python.

The most visible change is the renaming of Edge to Link. Like always, existing models are migrated to the new version by reading them with Ribasim Python, and writing out the updated version. For now in Python model.edge will continue to work to ease the transition.

1.5.1 Added

  • Check Model equality in Python. #2057
  • Compare two models in Python. #2080
  • Support cyclic input timeseries. #2081 #2102
  • Time dependent threshold_high thresholds in DiscreteControl. #2079
  • Validation error on connector nodes having the same from and to Basin. #2112
  • Support time dependent Pump and Outlet tables. #2110

1.5.2 Changed

  • Edges are now called links. #2023
  • All geometries are coerced to 2D. #2111

1.5.3 Fixed

  • Faster initialization of large tables. #2026
  • Declare incompatibility with Pandera v0.23+. #2120
  • Decrease the smoothing around Δh = 0 in ManningResistance. #2136

1.6 [v2025.1.0] - 2025-01-17

The first release of 2025 makes the Ribasim core more robust and stable, and speeds up initialization for large models. The biggest new feature is the experimental support for calculating tracers in Ribasim directly, which will hopefully make it easier to track where the water resources are heading.

1.6.1 Added

  • Remove Z coordinate on constructing Node in Python. #1986
  • Add “Basin / subgrid_time” table. #1975
  • Sign Ribasim binaries. #2007
  • Experimental: Calculate tracer concentrations internally. #1849
  • Document parsing Delwaq results. #1845

1.6.2 Removed

  • Drop Python 3.10 support. #2012

1.6.3 Changed

  • Allocation: optimize per source. #1927
  • The Edge table no longer supports subnetwork_id; this is automatically inferred. #1956

1.6.4 Fixed

  • ManningResistance is more stable around Δh=0. #1896
  • Fixes to Delwaq model generation. #1903 #1917 #1948
  • Add step limiter to avoid negative flows or too large flows. #1911 #1912
  • Fix README.md in builds. #1935 #1938
  • Speed up initialization. #1977
  • Automatically name index in Python. #1974
  • Table sorting related fixes. #2003

1.7 [v2024.11.0] - 2024-10-08

This major new release contains many improvements. A new formulation allows much smaller water balance errors, which is combined with several performance improvements. Ribasim Python does more validation that was previously only done in the core. The Ribasim QGIS plugin now sets the relations between tables for easier model inspection. Adding min_upstream_level and max_downstream_level to Pump and Outlet means DiscreteControl is often no longer needed. The most significant breaking change is making the node_id and edge_id the index of the Node and Edge table; these need to be globally unique.

Starting from this release Ribasim is labeled as beta software. Since development is currently mainly driven by applications in the Dutch water system, we expect that addition work needs to be done for general use outside the Netherlands.

For coupled simulation with MODFLOW and/or MetaSWAP, this release is part of the iMOD Coupler, specifically release v2024.4.0

1.7.1 Added

  • Support discrete control based on an external concentration condition. #1660
  • Add results/solver_stats.arrow with solver statistics over time. #1677
  • Add icon to ribasim.exe on Windows. #1712
  • Save QGIS styling in the model database. #1713
  • Add Delwaq coupling guide. #1619
  • Solver speedup due to backtracking relaxation. #1761
  • Reject adding a duplicate edge in Python. #1719
  • Support transient UserDemand return factor. #1727
  • Document the interpolation of input data. #1720
  • Automate Jacobian sparsity detection. #1606
  • Support specifying the edge_id as model.edge.add(a, b, edge_id=5). #1737
  • Use https://ribasim.org/ to host our documentation. #1736
  • Validate geometry types in Python. #1760
  • Add relationships between tables in QGIS. #1755
  • Support migrating from older Ribasim versions in Python. #1764
  • Add quick start guide to docs. #1787
  • Add min_upstream_level and max_downstream_level to Pump and Outlet. #1792
  • Add max_downstream_level to TabulatedRatingCurve. #1795
  • Validate edge connections in Python. #1765
  • Add low storage reduction factor to ManningResistance. #1796

1.7.2 Changed

  • Refactor of the core to ensure smaller water balance errors. #1819
  • Make node_id globally unique. #1717
  • Make the Node ID the index of the Node table, and Edge ID for Edge. #1737
  • Make more Python functions private. #1702
  • Put the contents of the CLI zips in a folder. #1722
  • Changed water balance error definition. #1767
  • Disallow missing priority parameter when using allocation. #1745
  • Rename Outlet’s min_crest_level to min_upstream_level. #1788
  • Only allow flow under gravity in TabulatedRatingCurve. #1795
  • Use dtype_backend="pyarrow" for Pandas DataFrames. #1781

1.7.3 Fixed

  • Remove oscillations in ManningResistance. #1750
  • Fix GeoPandas CRS warning. #1810

1.8 [v2024.10.0] - 2024-07-23

For this release we said goodbye to the problematic FractionalFlow node, but welcome the ContinuousControl as a long requested feature.

1.8.1 Added

  • Control: Add ContinuousControl node type. #1602
  • Control: Support listening to flow through connector nodes. #1594
  • Validate that TabulatedRatingCurve levels are above Basin bottom. #1607
  • Validate that Outlet minimum upstream levels are above Basin bottom. #1607
  • Always show convergence bottlenecks. #1636
  • Docstrings for Ribasim Python. #1643
  • Allocate to UserDemand from directly connected Basin if possible. #1581
  • Add basin_state.arrow results. #1626
  • Also write stacktraces to ribasim.log. #1653

1.8.2 Changed

  • Require QGIS 3.34 (LTR) or newer for Ribasim QGIS plugin.

1.8.3 Fixed

  • Compatibility with latest NumPy, Pandera and PyArrow releases. #1618
  • LevelDemand can now be without min_level or max_level. #1629

1.8.4 Removed

  • Removed unused urban runoff variable from Basin. #1611
  • Removed unneeded static table from Terminal. #1624
  • Removed FractionalFlow node. #1616

1.9 [v2024.9.0] - 2024-06-20

1.9.1 Added

  • Support for concentration state and time for Delwaq coupling.
  • Show exact commit on ribasim --version if it is not a release. #1479

1.9.2 Changed

  • Optimized performance.
  • Documentation has been overhauled to be more user-friendly.
  • Stricter TabulatedRatingCurve validation. #1469
  • Stricter Basin / profile validation. #1486
  • Allocation objective function now gives equal ratios during shortage. #1386

1.9.3 Fixed

  • Don’t require unique node IDs. #1513
  • Fix QGIS crash on plugin initialization. #1580

1.10 [v2024.8.0] - 2024-05-14

1.10.1 Added

  • There is more validation on the edges. #1434
  • If the model does not converge and the used algorithm supports it, we log which Basins don’t converge. #1440

1.10.2 Changed

  • If negative storages inadvertently happen, we now throw an error. #1425
  • Users of the QGIS plugin need to remove the old version to avoid two copies due to #1453.

1.10.3 Fixed

  • Performance improvements have been a focus of this release, giving up to 10x faster runs. #1433, #1436, #1438, #1448, #1457
  • The CLI exe is now always in the root of the zip and makes use of the libribasim shared library. #1415