Commit 1abd1a4f authored by Santiago Ospina De Los Ríos's avatar Santiago Ospina De Los Ríos

Merge branch...

Merge branch '174-document-model-solver-loop-and-time-step-adaptation-schemes-in-user-manual' into 'master'

Resolve "Document model solver loop and time step adaptation schemes in user manual"

Closes #174

See merge request !190
parents 53ed029d b61f2b48
......@@ -38,6 +38,7 @@
* DG solver for solute transport model !112
* Cookbook tutorial on using the random field generator !184
* Outflow boundary condition for Richards model !191
* Documentation about model solver loop and time step adaptation schemes !190
### Changed
* Data structures for storing and accessing parameter information !55
......
......@@ -69,6 +69,7 @@ assignment and increment are based on the :doc:`public-api`.
manual/parameter-file
manual/bcfile
manual/initial
manual/time-steps
manual/fluxes
manual/interpolators
public-api
......
=============
Time Stepping
=============
An overview of the time step algorithms used in the dedicated solvers
implemented in DORiE.
.. contents::
Model Run Algorithm
-------------------
All solvers in DORiE are derived from the ``Model`` base class which implements
the way a model "runs" a simulation. The ``run()`` method works as a simple loop
over the ``step()`` method described below for each model separately.
All model ``run()`` algorithms proceed as follows:
#. Write the output if enabled via the model's ``output.policy``.
#. Check if the model has reached the simulation end time. If yes, return.
Otherwise, continue.
#. Perform a :ref:`model time step <man-time_step>`.
#. Adapt the grid if enabled via the ``adaptivity.policy``.
#. Repeat from 2.
.. _man-time_step:
Model Step Methods
------------------
Every model implements its own time step algorithm variant.
Richards Solver
^^^^^^^^^^^^^^^
Because the Richards equation is non-linear, a Newton solver is used
to compute a time step. Since the equation is also very stiff, we only use
an implicit time step scheme. The Newton solver needs to iteratively linearise
the equation system in order to solve it. Depending on the "local"
non-linearity of the problem, this operation might fail. However, for implicit
time step schemes there is no a-priori estimate on a maximum time step.
We tackle these issues with a heuristic approach: If the equation system is
highly non-linear, the linearisation in the Newton solver is ineffective and it
requires more iteration steps. High non-linearities also hint at strongly
varying soil water dynamics during that time step. In this case, we want the
time steps to be small. If the dynamics are nearly constant, we want the time
steps to be large and expect very few Newton solver iterations because the
problem becomes nearly linear.
Our time step size heurisic is therefore as follows: Depending on the current
time step size, we compute a maximum number of Newton iterations allowed. If
the solver does not converge within this range, it is aborted and the time step
is reduced. Whenever computing a solution succeeds, the time step is increased.
The number of Newton solver iterations allowed is given by
.. math::
N_\text{Newton} = \left\lfloor (N_\text{min} - N_\text{max})
\frac{\lg (T - T_\text{min} + 1)}
{\lg (T_\text{max} - T_\text{min} + 1)}
+ N_\text{max} \right\rceil ,
where :math:`N_\text{min}` and :math:`N_\text{max}` are the allowed iterations
at the minimum and maximum time step, respectively, :math:`T_\text{min}` and
:math:`T_\text{max}` are the minimum and maximum time steps, respectively,
and :math:`T` is the current time step. These values may be adjusted in the
:ref:`Configuration File <inifile-cheatsheet>`. Note that the result
:math:`N_\text{Newton}` is rounded.
.. _man-richards-time_step:
The Richards solver ``step()`` algorithm proceeds as follows:
#. Limit the current time step according to any boundary condition change.
#. Compute the number of allowed Newton solver iterations with the equation
above.
#. Apply the non-linear solver.
If this fails, reduce the time step by the user-supplied factor and repeat
from 2.
#. Increment the simulation time and increase the time step by the
user-supplied factor.
#. Write the current data depending on the output policy.
Transport Solver
^^^^^^^^^^^^^^^^
The Transport solver usually does not work on its own because it requires
information on soil water content and water flux which need to be computed by
the Richards solver. However, it is implemented as an independent solver with
its own time step algorithm.
The main difference to the Richards solver is that the equation is linear,
which means that applying the solver only fails due to numerical errors.
Therefore, we have devised an a-posteriori solution check which can be
controlled by the user. This check may reject solutions and force a reduction
of the time step. Additionally, the solver supports explicit time steps. In
this case, the maximum time step is given by the CFL condition which can be
computed based on local velocities before applying the solver.
.. _man-transport-time_step:
The Transport solver ``step()`` algorithm proceeds as follows:
#. If the time step scheme is explicit, compute the maximum time step with the
CFL criterion and the user-supplied Courant number.
#. Limit the time step according to any boundary condition change.
#. Apply the linear solver.
If this fails, reduce the time step by the user-supplied factor and repeat.
#. Perform a check of the computed solution.
Depending on the user settings, this may reject the solution, in which case
the time step is reduced and step 3 is repeated.
#. Increment the simulation time and increase the time step by the
user-supplied factor.
#. Depending on the output policy, write the current data.
.. _man-coupled-solver:
Coupled Solver
^^^^^^^^^^^^^^
If the Transport solver is enabled, the software actually runs a coupled solver
which combines both Richards and Transport solver and manages their
interaction. Whenever it calls one its subordinate solvers, they perform their
respective time step algorithm as depicted above.
The coupled solver ``step()`` algorithm proceeds as follows:
#. Retrieve water content and water flux states from the Richards solver at the
start of the time step.
#. Compute a time step with the Richards solver, calling
:ref:`its algorithm <man-richards-time_step>`.
#. Retrieve water content and water flux states from the Richards solver at the
end of the time step.
#. Pass water content and water flux states to the Transport solver.
#. Suggest the difference between the current Transport solver time and the
Richards solver time as maxiumum time step in the Transport solver.
#. Compute a time step with the Transport solver, calling
:ref:`its algorithm <man-transport-time_step>`.
Repeat from 5 until both solvers are synchronized.
.. note:: Depending on the grid adaptivity policy, the task of marking and
adapting the grid may be forwarded to one of the integrated models
while both model solutions are projected onto the new grid.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment