OGS 6.1.0-1402-g949b995be  949b995b
Source code documentation
ODE Solver Library

Detailed Description

This ODE solver library has been designed with an implicit first-order quasilinear ODE in mind.

However, it is in principle not restricted to such a kind of equation, but can be extended to also solve other equation types. In particular it is possible to introduce equation types that are no ODEs, but are nonlinear equations without time derivative terms.

The aim of the library's design is being able to formulate FEM processes without having to care which time discretization scheme and which nonlinear iteration method will be used to solve it.

The library offers different time discretization schemes, cf. the conceputal remarks on them, namely the forward and backward Euler and Crank-Nicolson methods and Backward Differentiation Formulas. The design follows Gear's method, which also underlies the DASSL algorithm of Petzold et al., cf. Differential-algebraic equations article, section Numerical methods/Direct discretization [2].

A rough overview over the interplay between the various parts of this library is given in the image below. Therein red symbols indicate which classes own which matrices or vectors (for the meaning of the different symbols refer to the documentation of the respective classes). The word own should not be taken too strict in the sense of C++ member ownership, although currently it is implemented as such; but in the future this implementation detail might change. Rather own means that the class is in charge of the respective matrix or vector, i.e., it can read from and write to it or pass it on to functions; or in other words: The class knows about the meaning of that matrix/vector. Note that only matrices and vectors that describe some proper state of the respective classes are shown; those storing only intermediate computations have been omitted from the image.

ode-solver-concept.png
Interplay of the different parts of the ODE solver library at the example of a first-order implicit quasilinear ODE.
In the ODE solver library the instances of some classes can work together with several instances of other classes throughout there lifetime, whereas they have a strict one-to-one correspondence to objects of some different type. Those relations are given in the following table.

Class 1 Class 2 Relation Remarks
TimeDiscretizedODESystem ODESystem 1:1 the ODESystem represents part of the state of the TimeDiscretizedODESystem
TimeDiscretizedODESystem TimeDiscretization 1:1 analogous for the TimeDiscretization
TimeDiscretizedODESystem MatrixTranslator 1:1 analogous for the MatrixTranslator
NonlinearSolver NonlinearSystem 1:n a nonlinear solver can solve various equations, one after the other
LinearSolver NonlinearSolver 1:n various NonlinearSolver's can share the same LinearSolver

Classes

class  NumLib::EquationSystem
 Collection of basic methods every equation system must provide. More...
 
class  NumLib::MatrixTranslator< ODETag >
 Translates matrices and vectors assembled by a provided ODE (or other equation) to the stiffness matrix and right-hand side vector of a linear equation system that can be solved by a linear equation system solver. More...
 
class  NumLib::MatrixTranslator< ODESystemTag::FirstOrderImplicitQuasilinear >
 Translates matrices assembled by a provided first order implicit quasi-linear ODE to some other matrices suitable to be passed on to nonlinear solvers. More...
 
class  NumLib::MatrixTranslatorGeneral< ODETag >
 General GlobalMatrix translator used with time discretization schemes that have no special needs. More...
 
class  NumLib::MatrixTranslatorGeneral< ODESystemTag::FirstOrderImplicitQuasilinear >
 General matrix translator for first order implicit quasi-linear ODEs, used with time discretization schemes that have no special needs. More...
 
class  NumLib::MatrixTranslatorForwardEuler< ODETag >
 GlobalMatrix translator used with the ForwardEuler scheme. More...
 
class  NumLib::MatrixTranslatorForwardEuler< ODESystemTag::FirstOrderImplicitQuasilinear >
 GlobalMatrix translator for first order implicit quasi-linear ODEs, used with the ForwardEuler scheme. More...
 
class  NumLib::MatrixTranslatorCrankNicolson< ODETag >
 GlobalMatrix translator used with the CrankNicolson scheme. More...
 
class  NumLib::MatrixTranslatorCrankNicolson< ODESystemTag::FirstOrderImplicitQuasilinear >
 GlobalMatrix translator for first order implicit quasi-linear ODEs, used with the CrankNicolson scheme. More...
 
class  NumLib::NonlinearSolver< NLTag >
 Find a solution to a nonlinear equation. More...
 
class  NumLib::NonlinearSolver< NonlinearSolverTag::Newton >
 Find a solution to a nonlinear equation using the Newton-Raphson method. More...
 
class  NumLib::NonlinearSolver< NonlinearSolverTag::Picard >
 Find a solution to a nonlinear equation using the Picard fixpoint iteration method. More...
 
class  NumLib::NonlinearSystem< NLTag >
 A System of nonlinear equations. More...
 
class  NumLib::NonlinearSystem< NonlinearSolverTag::Newton >
 A System of nonlinear equations to be solved with the Newton-Raphson method. More...
 
class  NumLib::NonlinearSystem< NonlinearSolverTag::Picard >
 A System of nonlinear equations to be solved with the Picard fixpoint iteration method. More...
 
class  NumLib::ODESystem< ODETag, NLTag >
 ODE system interface. More...
 
class  NumLib::ODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Picard >
 Interface for a first-order implicit quasi-linear ODE. More...
 
class  NumLib::ODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Newton >
 Interface for a first-order implicit quasi-linear ODE. More...
 
class  NumLib::InternalMatrixStorage
 Interface that allows managing an additional internal state as required by certain time discretization schemes. More...
 
class  NumLib::TimeDiscretization
 Interface of time discretization schemes for first-order ODEs. More...
 
class  NumLib::BackwardEuler
 Backward Euler scheme. More...
 
class  NumLib::ForwardEuler
 Forward Euler scheme. More...
 
class  NumLib::CrankNicolson
 Generalized Crank-Nicolson scheme. More...
 
class  NumLib::BackwardDifferentiationFormula
 Backward differentiation formula. More...
 
class  NumLib::TimeDiscretizedODESystemBase< NLTag >
 A NonlinearSystem together with some TimeDiscretization scheme. More...
 
class  NumLib::TimeDiscretizedODESystem< ODETag, NLTag >
 A NonlinearSystem together with some TimeDiscretization scheme. More...
 
class  NumLib::TimeDiscretizedODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Newton >
 Time discretized first order implicit quasi-linear ODE; to be solved using the Newton-Raphson method for resolving nonlinearities. More...
 
class  NumLib::TimeDiscretizedODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Picard >
 Time discretized first order implicit quasi-linear ODE; to be solved using the Picard fixpoint iteration method for resolving nonlinearities. More...
 

Enumerations

enum  NumLib::IterationResult : char { NumLib::IterationResult::SUCCESS, NumLib::IterationResult::FAILURE, NumLib::IterationResult::REPEAT_ITERATION }
 Status flags telling the NonlinearSolver if an iteration succeeded. More...
 
enum  NumLib::NonlinearSolverTag : bool { NumLib::NonlinearSolverTag::Picard, NumLib::NonlinearSolverTag::Newton }
 Tag used to specify which nonlinear solver will be used. More...
 
enum  NumLib::ODESystemTag : char { NumLib::ODESystemTag::FirstOrderImplicitQuasilinear, NumLib::ODESystemTag::NeumannBC }
 Tag used to specify the type of ODE. More...
 

Functions

template<ODESystemTag ODETag>
std::unique_ptr< MatrixTranslator< ODETag > > NumLib::createMatrixTranslator (TimeDiscretization const &timeDisc)
 Creates a GlobalMatrix translator suitable to work together with the given time discretization scheme. More...
 
std::pair< std::unique_ptr< NonlinearSolverBase >, NonlinearSolverTagNumLib::createNonlinearSolver (GlobalLinearSolver &linear_solver, BaseLib::ConfigTree const &config)
 Creates a new nonlinear solver from the given configuration. More...
 

Enumeration Type Documentation

◆ IterationResult

enum NumLib::IterationResult : char
strong

Status flags telling the NonlinearSolver if an iteration succeeded.

Enumerator
SUCCESS 
FAILURE 
REPEAT_ITERATION 

Definition at line 20 of file EquationSystem.h.

◆ NonlinearSolverTag

enum NumLib::NonlinearSolverTag : bool
strong

Tag used to specify which nonlinear solver will be used.

Enumerator
Picard 

Picard fixpoint iteration scheme.

Newton 

Newton-Raphson iteration scheme.

Definition at line 19 of file Types.h.

19  : bool {
20  Picard ,
21  Newton
22 };
Picard fixpoint iteration scheme.
Newton-Raphson iteration scheme.

◆ ODESystemTag

enum NumLib::ODESystemTag : char
strong

Tag used to specify the type of ODE.

Enumerator
FirstOrderImplicitQuasilinear 

First order implicit quasi-linear ODE.

This is an ODE of the form \( M(x,t)\cdot \dot x + K(x,t) \cdot x - b(x,t) =: r(\dot x, x, t) \stackrel{!}{=} 0 \)

NeumannBC 

Definition at line 25 of file Types.h.

25  : char
26 {
34  NeumannBC // Sure, that's misuse of this enum, so sue me!
35 };
First order implicit quasi-linear ODE.

Function Documentation

◆ createMatrixTranslator()

template<ODESystemTag ODETag>
std::unique_ptr<MatrixTranslator<ODETag> > NumLib::createMatrixTranslator ( TimeDiscretization const &  timeDisc)

Creates a GlobalMatrix translator suitable to work together with the given time discretization scheme.

Definition at line 292 of file MatrixTranslator.h.

294 {
295  if (auto* fwd_euler = dynamic_cast<ForwardEuler const*>(&timeDisc))
296  {
297  return std::unique_ptr<MatrixTranslator<ODETag>>(
298  new MatrixTranslatorForwardEuler<ODETag>(*fwd_euler));
299  }
300  if (auto* crank = dynamic_cast<CrankNicolson const*>(&timeDisc))
301  {
302  return std::unique_ptr<MatrixTranslator<ODETag>>(
303  new MatrixTranslatorCrankNicolson<ODETag>(*crank));
304  }
305 
306  return std::unique_ptr<MatrixTranslator<ODETag>>(
307  new MatrixTranslatorGeneral<ODETag>(timeDisc));
308 }

◆ createNonlinearSolver()

std::pair< std::unique_ptr< NonlinearSolverBase >, NonlinearSolverTag > NumLib::createNonlinearSolver ( GlobalLinearSolver &  linear_solver,
BaseLib::ConfigTree const &  config 
)

Creates a new nonlinear solver from the given configuration.

Parameters
linear_solverthe linear solver that will be used by the nonlinear solver
configconfiguration settings
Returns
a pair (nl_slv, tag) where nl_slv is the generated nonlinear solver instance and the tag indicates if it uses the Picard or Newton-Raphson method
Input File Parameter:
prj__nonlinear_solvers__nonlinear_solver__type
Input File Parameter:
prj__nonlinear_solvers__nonlinear_solver__max_iter
Input File Parameter:
prj__nonlinear_solvers__nonlinear_solver__damping

Definition at line 317 of file NonlinearSolver.cpp.

References BaseLib::ConfigTree::getConfigParameter(), NumLib::Newton, OGS_FATAL, and NumLib::Picard.

Referenced by ProjectData::parseNonlinearSolvers().

319 {
321  auto const type = config.getConfigParameter<std::string>("type");
323  auto const max_iter = config.getConfigParameter<unsigned>("max_iter");
324 
325  if (type == "Picard") {
326  auto const tag = NonlinearSolverTag::Picard;
327  using ConcreteNLS = NonlinearSolver<tag>;
328  return std::make_pair(
329  std::make_unique<ConcreteNLS>(linear_solver, max_iter), tag);
330  }
331  if (type == "Newton")
332  {
334  auto const damping = config.getConfigParameter<double>("damping", 1.0);
335  if (damping <= 0)
336  {
337  OGS_FATAL(
338  "The damping factor for the Newon method must be positive, got "
339  "%g.",
340  damping);
341  }
342  auto const tag = NonlinearSolverTag::Newton;
343  using ConcreteNLS = NonlinearSolver<tag>;
344  return std::make_pair(
345  std::make_unique<ConcreteNLS>(linear_solver, max_iter, damping),
346  tag);
347  }
348  OGS_FATAL("Unsupported nonlinear solver type");
349 }
#define OGS_FATAL(fmt,...)
Definition: Error.h:71
Here is the call graph for this function:
Here is the caller graph for this function: