Debugging models

1 Unexpected flow rates

When a connector node (e.g., TabulatedRatingCurve, Pump, Outlet, ManningResistance) produces unexpected flow rates, it’s important to understand how Ribasim calculates flows and which reduction factors may apply.

1.1 Review the equations

Each connector node type has specific equations that govern its behavior. Review the equations for your node type in the reference documentation. For example, see the TabulatedRatingCurve equations.

1.2 Check reduction factors

Ribasim applies several reduction factors that can limit flows. To verify that none of them unexpectedly applies, check the following examples:

  1. Upstream Basin level and storage: If the upstream Basin is nearly empty, a reduction factor prevents extracting more water than available.

  2. Downstream Basin level: If the downstream Basin level is higher, only Pumps can flow against gravity.

  3. Connector node parameters: Review the node’s parameters in your model input to ensure they match your expectations. Parameters like max_flow_rate or min_upstream_level directly affect the computed flow.

1.3 Check control and allocation

If the node is subject to control or allocation:

  • Discrete Control: Check the control results to see which control state is active and when it changes. The active state determines which parameter set is used.

  • Allocation: Check the allocation results to see the allocated flow for the node.

In all these cases the reduction factors still apply, and may be the reason allocated flows cannot be realized.

2 Slow models

When your model is slow, it’s often only a handful of nodes that are hard to solve. If the model finishes or is interrupted, convergence bottlenecks are shown like so:

┌ Info: Convergence bottlenecks in descending order of severity:
│   ManningResistance #251242 = 0.09023997405863035
│   ManningResistance #70523 = 0.006218636603583534
│   ManningResistance #251181 = 0.004716432403226626
│   ManningResistance #251182 = 0.0035319514660666165
└   ManningResistance #591558 = 0.003284110004804508

It’s best to inspect these nodes, and try to adjust the parametrization, or merge smaller nodes. You can find the convergence measure per node over time in the flow.arrow and basin.arrow output files.

To gain further insight into model performance, one can inspect the solver_stats.arrow output file, which gives the number of computations, number of rejected and accepted solutions, and the size of each calculation timestep.

3 Unstable models

When your model exits with a message like so:

┌ Error: The model exited at model time 2024-01-27T14:46:17.791 with return code Unstable. See https://docs.sciml.ai/DiffEqDocs/stable/basics/solution/#retcodes

it’s best to rerun the model with saveat = 0 in the solver settings. The model might then instead exit with

┌ Error: Too large water balance error
│   id = Basin #2
│   balance_error = 0.0017985748886167501
│   relative_error = 1.3503344464431657

which helps you pin down the problematic node(s). The normal output for every calculation timestep is written until the moment of error, so one can use this information to understand the problem.