Updating Ribasim

This guide explains how to update Ribasim models from older versions to newer versions. To update the Ribasim installation itself, follow the installation steps, ensuring that all installed components are the same. To see the most important changes in Ribasim, consult the changelog.

1 Version numbers and breaking changes

Ribasim uses version numbers like 2023.1.0, following YYYY.MINOR.MICRO from calver. It starts with the year the release was made, followed by the minor version number for normal releases, and a micro number for non-breaking, hotfix releases. This means that whenever the year or minor version changes, there is a possibility that the user has to make changes to the model for it to keep working. If this is the case, it will be highlighted in the changelog. When possible, we automate this process using model migration in Ribasim Python, see the section below.

2 Automatic model migration

Models are automatically migrated when read from file using Ribasim Python, and this is the recommended way to update your models.

The Ribasim Python package contains a set of migration functions that are applied automatically when you read a model file from an older version. When Ribasim developers make changes to the model structure (for example, adding new required columns to tables), these changes would normally break compatibility with existing models. To prevent this, migration functions automatically update your model data to match the current version’s requirements.

The core always expects models to be written by the same Ribasim Python version as itself, which is why it gives a warning whenever the ribasim_version in the TOML does not match ribasim --version.

When you read an older model, Ribasim Python will automatically apply all necessary migrations and update the model version accordingly. To migrate an existing model to the latest version, simply use the following script:

import ribasim

# Read the old model (migration happens automatically)
model = ribasim.Model.read("path/to/your/old_model.toml")

# Write the migrated model
model.write("path/to/your/migrated_model.toml")

If you have a script that builds your model from scratch, simply re-running that script with the new Ribasim Python version will produce a model with the updated version, making the above migration step unnecessary.