Write ribasim_version to TOML and warn in core if it is different (#…

…1181)

Fixes #1178

At first I tried to add `ribasim_version` to the Python data model, but
struggled to get it to write to the TOML even if it had its default
values. But then I thought, when we `model.write`, with Ribasim Python
version X, we should always set that key to X. Therefore there is no
point in having it be part of the data model.

This does some hardcoded current version numbers in our test TOML files.
I guess we could script a way around that, but updating the version
number is a documented find and replace action already anyway, so it
doesn't matter much.

The warning from the core looks like this:

```
┌ Warning: The Ribasim version in the TOML config file does not match the used Ribasim CLI version.
│   config.ribasim_version = "2024.2.1"
│   ribasim_version = "2024.2.0"
└ @ Ribasim d:\Ribasim\core\src\main.jl:63
```

core/src/config.jl

@@ -111,6 +111,7 @@ end
 @option @addnodetypes struct Toml <: TableOption
     starttime::DateTime
     endtime::DateTime
+    ribasim_version::String
     input_dir::String
     results_dir::String
     database::String = "database.gpkg"

core/src/main.jl

@@ -57,16 +57,19 @@ function main(ARGS::Vector{String})::Cint
             logger =
                 Ribasim.setup_logger(; verbosity = config.logging.verbosity, stream = io)
             with_logger(logger) do
-                ribasim_version = pkgversion(Ribasim)
+                cli = (; ribasim_version = string(pkgversion(Ribasim)))
                 (; starttime, endtime) = config
-                @info "Starting a Ribasim simulation." ribasim_version starttime endtime
+                if config.ribasim_version != cli.ribasim_version
+                    @warn "The Ribasim version in the TOML config file does not match the used Ribasim CLI version." config.ribasim_version cli.ribasim_version
+                end
+                @info "Starting a Ribasim simulation." cli.ribasim_version starttime endtime
                 model = Ribasim.run(config)
                 if successful_retcode(model)
                     @info "The model finished successfully"
                     return 0
                 end
 
-                t = Ribasim.datetime_since(model.integrator.t, model.config.starttime)
+                t = Ribasim.datetime_since(model.integrator.t, starttime)
                 retcode = model.integrator.sol.retcode
                 @error "The model exited at model time $t with return code $retcode.\nSee https://docs.sciml.ai/DiffEqDocs/stable/basics/solution/#retcodes"
                 return 1

core/test/data/config_test.toml

@@ -1,11 +1,8 @@
 starttime = 2019-01-01
 endtime = 2019-12-31
-
-# optional, default is the path of the TOML
 input_dir = "../../generated_testmodels/lhm"
 results_dir = "../../generated_testmodels/lhm"
-
-database = "database.gpkg"
+ribasim_version = "2024.2.0"
 
 [basin]
 time = "basin/time.arrow"

core/test/data/logging_test_loglevel_debug.toml

@@ -2,6 +2,7 @@ starttime = 2019-01-01
 endtime = 2019-12-31
 input_dir = "."
 results_dir = "results"
+ribasim_version = "2024.2.0"
 
 [logging]
 verbosity = "debug"

core/test/data/logging_test_no_loglevel.toml

@@ -2,3 +2,4 @@ starttime = 2019-01-01
 endtime = 2019-12-31
 input_dir = "."
 results_dir = "results"
+ribasim_version = "2024.2.0"

core/test/docs.toml

@@ -7,6 +7,8 @@ endtime = 2021-01-01   # required
 input_dir = "."         # required
 results_dir = "results" # required
 
+ribasim_version = "2024.2.0" # required
+
 # Specific tables can also go into Arrow files rather than the database.
 # For large tables this can benefit from better compressed file sizes.
 # This is optional, tables are retrieved from the database if not specified in the TOML.

core/test/io_test.jl

@@ -8,6 +8,7 @@
         database = "path/to/file",
         input_dir = ".",
         results_dir = "results",
+        ribasim_version = string(Ribasim.pkgversion(Ribasim)),
     )
     config = Ribasim.Config(toml, "model")
     @test Ribasim.input_path(config, "path/to/file") ==
@@ -20,6 +21,7 @@
         database = "path/to/file",
         input_dir = "input",
         results_dir = "results",
+        ribasim_version = string(Ribasim.pkgversion(Ribasim)),
     )
     config = Ribasim.Config(toml, "model")
     @test Ribasim.input_path(config, "path/to/file") ==
@@ -32,6 +34,7 @@
         database = "/path/to/file",
         input_dir = ".",
         results_dir = "results",
+        ribasim_version = string(Ribasim.pkgversion(Ribasim)),
     )
     config = Ribasim.Config(toml)
     @test Ribasim.input_path(config, "/path/to/file") == abspath("/path/to/file")

core/test/main_test.jl

@@ -10,9 +10,18 @@ end
 
 @testitem "toml_path" begin
     using IOCapture: capture
+    import TOML
 
     model_path = normpath(@__DIR__, "../../generated_testmodels/basic/")
     toml_path = normpath(model_path, "ribasim.toml")
+
+    # change the ribasim_version in the toml file to check warning
+    toml_dict = TOML.parsefile(toml_path)
+    toml_dict["ribasim_version"] = "a_different_version"
+    open(toml_path, "w") do io
+        TOML.print(io, toml_dict)
+    end
+
     @test ispath(toml_path)
     (; value, output, error, backtrace) = capture() do
         Ribasim.main([toml_path])
@@ -23,6 +32,7 @@ end
         @show error
         @show backtrace
     end
+    @test occursin("version in the TOML config file does not match", output)
 end
 
 @testitem "too many arguments for main" begin

docs/contribute/release.qmd

@@ -25,13 +25,8 @@ Determine the new version number like `2023.1.0`, filling in the current year, a
 This follows `YYYY.MINOR.MICRO` from [calver](https://calver.org/).
 
 Update the version numbers in the repository to the new version number.
-A single find and replace can update all 5 locations:
-
-- `pixi.toml`
-- `core/Project.toml`
-- `python/ribasim/ribasim/__init__.py`
-- `python/ribasim_api/ribasim_api/__init__.py`
-- `ribasim_qgis/metadata.txt`
+A single find and replace can update all locations.
+The Ribasim version number is not in `pixi.lock`, that file does not need updating.
 
 Now submit a pull request to update the version numbers.
 

python/ribasim/ribasim/model.py

@@ -16,6 +16,7 @@
     model_validator,
 )
 
+import ribasim
 from ribasim.config import (
     Allocation,
     Basin,
@@ -229,6 +230,7 @@ def _write_toml(self, fn: FilePath):
         content = self.model_dump(exclude_unset=True, exclude_none=True, by_alias=True)
         # Filter empty dicts (default Nodes)
         content = dict(filter(lambda x: x[1], content.items()))
+        content["ribasim_version"] = ribasim.__version__
         with open(fn, "wb") as f:
             tomli_w.dump(content, f)
         return fn

python/ribasim/tests/test_io.py

@@ -1,6 +1,7 @@
 import pandas as pd
 import pytest
 import ribasim
+import tomli
 from numpy.testing import assert_array_equal
 from pandas import DataFrame
 from pandas.testing import assert_frame_equal
@@ -36,8 +37,14 @@ def __assert_equal(a: DataFrame, b: DataFrame, is_network=False) -> None:
 
 def test_basic(basic, tmp_path):
     model_orig = basic
-    model_orig.write(tmp_path / "basic/ribasim.toml")
-    model_loaded = ribasim.Model(filepath=tmp_path / "basic/ribasim.toml")
+    toml_path = tmp_path / "basic/ribasim.toml"
+    model_orig.write(toml_path)
+    model_loaded = ribasim.Model(filepath=toml_path)
+
+    with open(toml_path, "rb") as f:
+        toml_dict = tomli.load(f)
+
+    assert toml_dict["ribasim_version"] == ribasim.__version__
 
     index_a = model_orig.network.node.df.index.to_numpy(int)
     index_b = model_loaded.network.node.df.index.to_numpy(int)