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] (https://web.archive.org/web/20240423230323/http://www.scholarpedia.org/article/Differential-algebraic_equations#Numerical_methods.2FDirect_discretization) [8].

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.

Interplay of the different parts of the ODE

solver library at the example of a first-order implicit quasilinear ODE."@image latex ode-solver-concept.pdf "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. <table class="markdownTable"> <tr class="markdownTableHead"> <th class="markdownTableHeadRight"> 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
class	NumLib::MatrixTranslator< ODETag >
class	NumLib::MatrixTranslator< ODESystemTag::FirstOrderImplicitQuasilinear >
class	NumLib::MatrixTranslatorGeneral< ODETag >
class	NumLib::MatrixTranslatorGeneral< ODESystemTag::FirstOrderImplicitQuasilinear >
class	NumLib::NonlinearSolver< NLTag >
class	NumLib::NonlinearSolver< NonlinearSolverTag::Newton >
class	NumLib::NonlinearSolver< NonlinearSolverTag::Picard >
class	NumLib::NonlinearSystem< NLTag >
class	NumLib::NonlinearSystem< NonlinearSolverTag::Newton >
class	NumLib::NonlinearSystem< NonlinearSolverTag::Picard >
class	NumLib::ODESystem< ODETag, NLTag >
class	NumLib::ODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Picard >
class	NumLib::ODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Newton >
class	NumLib::PETScNonlinearSolver
class	NumLib::TimeDiscretization
class	NumLib::BackwardEuler
	Backward Euler scheme. More...
class	NumLib::TimeDiscretizedODESystemBase< NLTag >
class	NumLib::TimeDiscretizedODESystem< ODETag, NLTag >
class	NumLib::TimeDiscretizedODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Newton >
class	NumLib::TimeDiscretizedODESystem< ODESystemTag::FirstOrderImplicitQuasilinear, NonlinearSolverTag::Picard >

Enumerations
enum class	NumLib::IterationResult : char { NumLib::IterationResult::SUCCESS , NumLib::IterationResult::FAILURE , NumLib::IterationResult::REPEAT_ITERATION }
	Status flags telling the NonlinearSolver if an iteration succeeded. More...
enum class	NumLib::NonlinearSolverTag : bool { NumLib::NonlinearSolverTag::Picard , NumLib::NonlinearSolverTag::Newton }
	Tag used to specify which nonlinear solver will be used. More...
enum class	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)
std::pair< std::unique_ptr< NonlinearSolverBase >, NonlinearSolverTag >	NumLib::createNonlinearSolver (GlobalLinearSolver &linear_solver, BaseLib::ConfigTree const &config)

Enumeration Type Documentation

IterationResult

enum class NumLib::IterationResult : char

strong

Status flags telling the NonlinearSolver if an iteration succeeded.

Enumerator
SUCCESS
FAILURE
REPEAT_ITERATION

Definition at line 21 of file EquationSystem.h.

{
    SUCCESS,
    FAILURE,
    REPEAT_ITERATION
};

NonlinearSolverTag

enum class 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.

{
    Picard ,
    Newton 
};

ODESystemTag

enum class 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 26 of file Types.h.

{
    FirstOrderImplicitQuasilinear,
    NeumannBC  // Sure, that's misuse of this enum, so sue me!
};

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 137 of file MatrixTranslator.h.

{
    return std::unique_ptr<MatrixTranslator<ODETag>>(
        new MatrixTranslatorGeneral<ODETag>(timeDisc));
}

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_solver	the linear solver that will be used by the nonlinear solver
config	configuration 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

Input File Parameter

prj__nonlinear_solvers__nonlinear_solver__prefix

Definition at line 515 of file NonlinearSolver.cpp.

{
    auto const type = config.getConfigParameter<std::string>("type");
    auto const max_iter = config.getConfigParameter<int>("max_iter");
 
    if (type == "Picard")
    {
        auto const tag = NonlinearSolverTag::Picard;
        using ConcreteNLS = NonlinearSolver<tag>;
        return std::make_pair(
            std::make_unique<ConcreteNLS>(linear_solver, max_iter), tag);
    }
    if (type == "Newton")
    {
        auto const damping = config.getConfigParameter<double>("damping", 1.0);
        if (damping <= 0)
        {
            OGS_FATAL(
                "The damping factor for the Newon method must be positive, got "
                "{:g}.",
                damping);
        }
        auto const tag = NonlinearSolverTag::Newton;
        using ConcreteNLS = NonlinearSolver<tag>;
        return std::make_pair(
            std::make_unique<ConcreteNLS>(linear_solver, max_iter, damping),
            tag);
    }
#ifdef USE_PETSC
    if (boost::iequals(type, "PETScSNES"))
    {
        auto prefix =
            config.getConfigParameter<std::string>("prefix", "");
        auto const tag = NonlinearSolverTag::Newton;
        using ConcreteNLS = PETScNonlinearSolver;
        return std::make_pair(std::make_unique<ConcreteNLS>(
                                  linear_solver, max_iter, std::move(prefix)),
                              tag);
    }
 
#endif
    OGS_FATAL("Unsupported nonlinear solver type '{:s}'.", type.c_str());
}

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

Referenced by ProjectData::parseNonlinearSolvers().