From 153428e5ba4f64321e5e4369867bdd7eeb56d773 Mon Sep 17 00:00:00 2001 From: Bart de Koning Date: Thu, 10 Oct 2024 15:33:12 +0200 Subject: [PATCH 1/2] Add explanation of water balance error options --- docs/concept/equations.qmd | 8 ++++---- docs/reference/usage.qmd | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/concept/equations.qmd b/docs/concept/equations.qmd index 7bc45dc57..d8c4497ba 100644 --- a/docs/concept/equations.qmd +++ b/docs/concept/equations.qmd @@ -86,12 +86,12 @@ $$ \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: +in a Basin over a time period $\Delta t$ 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. +Whether a flow is an inflow or an outflow depends on whether the flow contributes to or takes from the Basin storage, which means that this is independent of the edge direction. This is determined for each solver timestep individually. Then from this we compute the errors: @@ -103,9 +103,9 @@ $$ $$ 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. +The default tolerances are $0.001 \text{ m}^3$ for the balance error and $0.01$ for the relative 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. +In extreme cases where the 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 $ \ge 10^{15}$ times bigger than the storage rate. ### Example calculation diff --git a/docs/reference/usage.qmd b/docs/reference/usage.qmd index 50f1f63cd..cd7f991fd 100644 --- a/docs/reference/usage.qmd +++ b/docs/reference/usage.qmd @@ -35,6 +35,10 @@ The calculation and result stepsize need not be the same. If you wish to save every calculation step, set `saveat = 0`. If you wish to not save any intermediate steps, set `saveat = inf`. +The water balance error is a measure of the error in the consistency with which the core keeps track of the water resources per basin, for more details see [here](../concept/equations.qmd#the-water-balance-error). +`water_balance_abstol` and `water_balance_reltol` give upper bounds on this error, above which an error is thrown. +A too large error generally indicates an error in the code or floating point truncation errors. + The Jacobian matrix provides information about the local sensitivity of the model with respect to changes in the states. For implicit solvers it must be calculated often, which can be expensive to do. There are several methods to do this. From d8876f6961eb2409b81b02538f68a2d7b8227da1 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Thu, 10 Oct 2024 15:50:24 +0200 Subject: [PATCH 2/2] Update docs/reference/usage.qmd --- docs/reference/usage.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/usage.qmd b/docs/reference/usage.qmd index cd7f991fd..b905da172 100644 --- a/docs/reference/usage.qmd +++ b/docs/reference/usage.qmd @@ -35,7 +35,7 @@ The calculation and result stepsize need not be the same. If you wish to save every calculation step, set `saveat = 0`. If you wish to not save any intermediate steps, set `saveat = inf`. -The water balance error is a measure of the error in the consistency with which the core keeps track of the water resources per basin, for more details see [here](../concept/equations.qmd#the-water-balance-error). +The water balance error is a measure of the error in the consistency with which the core keeps track of the water resources per Basin, for more details see [here](/concept/equations.qmd#the-water-balance-error). `water_balance_abstol` and `water_balance_reltol` give upper bounds on this error, above which an error is thrown. A too large error generally indicates an error in the code or floating point truncation errors.