Add explanation of water balance error (#1828)

Fixes #1820.

---------

Co-authored-by: Martijn Visser <[email protected]>

docs/concept/equations.qmd

@@ -79,6 +79,63 @@ $$
 $$
 i.e. $J_{i,j}$ quantifies how $f_j$. the time derivative of state $j$, changes with respect to changes in state $i$. Most of these entries are $0$, because flows in distant parts of the model do not depend on each other.
 
+## The water balance error
+
+The water balance error quantifies how well the water volume in the model is conserved for each Basin over an output save period, i.e. whether no water erroneously appears or disappears. It looks at the storage rate
+$$
+	\text{storage rate} = \frac{\Delta S_b}{\Delta t}
+$$
+
+in a Basin over a time period $\Delta t = t_1 - t_0$ and compares that to the total inflows and outflows of that Basin over that period. More precisely, we first compute the total inflow and outflow, where:
+
+- $\text{total inflow}$: the precipitation, drainage and horizontal flows into the Basin;
+- $\text{total outflow}$: the evaporation, infiltration and horizontal flows out of the Basin.
+
+Whether a flow is an inflow or an outflow depends on whether the flow contributes to or takes from the Basin storage, and thus this is independent of the edge direction. This is determined for each solver timestep individually.
+
+Then from this we compute the errors:
+
+$$
+	\begin{align}
+	\text{balance error} =&& \text{storage rate} - (\text{total inflow} - \text{total outflow}) \\
+	\text{relative error}=&& \frac{\text{absolute error}}{0.5(\text{total inflow} + \text{total outflow})}
+	\end{align}
+$$
+Hence the reference used for computing the relative error is the average of the total inflow and total outflow of the Basin (which are both non-negative).
+
+The default tolerances are $0.001 \text{ m}^3$ for the balance error and $0.01$ for the absolute error, which should not be exceeded for realistic models.
+
+In extreme cases where storage rate is many orders of magnitude smaller than the storage itself, these computations can have floating point truncation errors which can lead to large relative errors.  This is however only when the storage is roughly $10^{15}$ or more times bigger than the storage rate.
+
+### Example calculation
+
+Say we have the following model:
+
+![](https://s3.deltares.nl/ribasim/doc-image/concept/equations/subnetwork.png){fig-align="left"}
+
+and we want to calculate the water balance error for Basin 6. We have the following data:
+
+- Time period length: $10.0 \text{ s}$
+- Basin storage start: $100.0 \text{ m}^3$
+- Basin storage end: $50.0 \text{ m}^3$
+- UserDemand #11 inflow average: $10.0 \text{ m}^3/\text{s}$
+- UserDemand #11 outflow average: $5.0 \text{ m}^3/\text{s}$
+- Outlet #7 flow average: $- 3.5 \text{ m}^3/\text{s}$
+- Outlet #11 flow average: $4.0 \text{ m}^3/\text{s}$
+
+And so we get
+
+$$
+\begin{align}
+	\text{storage rate} = && \frac{50.0 - 100.0}{10.0} &= & -6.0 \text{ m}^3/\text{s} \\
+	\text{total inflow} = && 5.0 + 3.5 &= & 8.5 \text{ m}^3/\text{s}\\
+	\text{total outflow} = && 10.0 + 4.0 &= & 14.0 \text{ m}^3/\text{s}\\
+	\text{balance error} = && -6.0 - (8.5 - 14.0) &= & -0.5 \text{ m}^3/\text{s}\\
+	\text{relative error} = && \frac{-0.5}{8.5 + 14.0} &\approx & -0.022
+\end{align}
+$$
+Note that the balance error and relative error are negative, but we use their absolute value to compare to the respective tolerances.
+
 ## Why this formulation
 
 You might wonder why in the above explanation the states are given by the cumulative flows and not by the Basin storages, which is arguably conceptually simpler.

docs/reference/usage.qmd

@@ -201,6 +201,8 @@ The Basin table contains:
   It can be used to check if the numerical error when solving the water balance is sufficiently small.
 - The `relative_error` is the fraction of the `balance_error` over the mean of the `total_inflow` and `total_outflow`.
 
+For a more in-depth explanation of the water balance error see [here](/concept/equations.qmd#the-water-balance-error).
+
 column         | type     | unit
 -------------- | ---------| ----
 time           | DateTime | -