template<class LinearSolver>
Rodin::Solver::NewtonSolver class final

Newton solver for state-dependent tangential problems.

Template parameters
LinearSolver Type of the linear solver used at each Newton step. It must have a FormLanguage::Traits specialization exposing LinearSystemType.

This class implements a damped Newton method for nonlinear problems whose current linearization is represented by a tangential Variational::ProblemBase owned or referenced by the associated linear solver.

At Newton iteration $ k $ , the solver reassembles the current tangential problem and solves the linear system

\[ J(x^k)\,\delta x^k = -F(x^k), \]

then updates the nonlinear state according to

\[ x^{k+1} = x^k + \alpha\,\delta x^k, \]

where $ \alpha > 0 $ is a constant damping factor.

The nonlinear state vector passed to solve() is updated in place and is used both as the initial guess and as the storage for the final iterate.

In typical Rodin usage, state-dependent integrators store a reference to the nonlinear state object, so that reassembly automatically reflects the updated iterate after each Newton step.

An optional step criterion may also be enabled. When the step tolerance is positive, convergence is additionally declared if

\[ \alpha\,\|\delta x^k\| \le \mathrm{stol}. \]

Base classes

template<class LinearSolver>
class NewtonSolverBase<LinearSolver>
Abstract base class for Newton-type nonlinear solvers.

Public types

struct Report
Summary of the most recent call to solve().
enum class ConvergenceReason { AbsoluteTolerance, RelativeTolerance, StepTolerance, MaxIterations }
Reason why the most recent solve terminated.
using Monitor = std::function<void(const Report&)>
Type of the optional iteration monitor.

Constructors, destructors, conversion operators

NewtonSolver(LinearSolver& solver) explicit
Constructs a Newton solver from a linear solver reference.

Public functions

auto copy() const -> NewtonSolver* override noexcept
Creates a polymorphic copy of this object.
auto setAbsoluteTolerance(Real atol) -> NewtonSolver&
Sets the absolute residual tolerance.
auto getAbsoluteTolerance() const -> Real noexcept
Gets the absolute residual tolerance.
auto setRelativeTolerance(Real rtol) -> NewtonSolver&
Sets the relative residual tolerance.
auto getRelativeTolerance() const -> Real noexcept
Gets the relative residual tolerance.
auto setStepTolerance(Real stol) -> NewtonSolver&
Sets the step tolerance.
auto getStepTolerance() const -> Real noexcept
Gets the step tolerance.
auto setDampingFactor(Real alpha) -> NewtonSolver&
Sets the constant damping factor.
auto getDampingFactor() const -> Real noexcept
Gets the damping factor.
auto setMaxIterations(size_t maxIt) -> NewtonSolver&
Sets the maximum number of Newton iterations.
auto getMaxIterations() const -> size_t noexcept
Gets the maximum number of Newton iterations.
auto setMonitor(Optional<Monitor> monitor) -> NewtonSolver&
Sets the optional iteration monitor.
auto getMonitor() const -> const Optional<Monitor>& noexcept
Gets the optional iteration monitor.
auto getReport() const -> const Report& noexcept
Gets the report of the most recent solve.
auto converged() const -> bool noexcept
Returns whether the most recent solve converged.
void solve(SolutionType& x) override
Solves the nonlinear problem starting from x.
void solve(SolutionType& x) pure virtual
Solve a nonlinear system starting from the initial guess stored in x.
template<class GridFunctionType, class = std::enable_if_t< std::is_same_v< typename FormLanguage::Traits<std::decay_t<GridFunctionType>>::DataType, SolutionType>>>
void solve(GridFunctionType& gf)
Solve a nonlinear system using a GridFunction as the solution container.

Enum documentation

template<class LinearSolver>
enum class Rodin::Solver::NewtonSolver<LinearSolver>::ConvergenceReason

Reason why the most recent solve terminated.

Enumerators
AbsoluteTolerance

The absolute residual tolerance was satisfied.
RelativeTolerance

The relative residual tolerance was satisfied.
StepTolerance

The step tolerance was satisfied.
MaxIterations

The maximum number of Newton iterations was reached.

Typedef documentation

template<class LinearSolver>
using Rodin::Solver::NewtonSolver<LinearSolver>::Monitor = std::function<void(const Report&)>

Type of the optional iteration monitor.

The monitor is called with the current Report after the residual has been evaluated and, when applicable, after the step norm has been computed.

Function documentation

template<class LinearSolver>
Rodin::Solver::NewtonSolver<LinearSolver>::NewtonSolver(LinearSolver& solver) explicit

Constructs a Newton solver from a linear solver reference.

Parameters
solver Linear solver used for each tangential solve.

The associated tangential problem is obtained from the linear solver and reused throughout the Newton iterations.

Default values:

  • maximum iterations: 100
  • absolute tolerance: 1e-12
  • relative tolerance: 1e-8
  • step tolerance: 0.0
  • damping factor: 1.0
  • monitor: none

template<class LinearSolver>
NewtonSolver* Rodin::Solver::NewtonSolver<LinearSolver>::copy() const override noexcept

Creates a polymorphic copy of this object.

Returns Pointer to a new instance that is a copy of this object. The caller is responsible for memory management.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setAbsoluteTolerance(Real atol)

Sets the absolute residual tolerance.

Parameters
atol Absolute residual tolerance.
Returns Reference to this solver.

The absolute tolerance must be finite and non-negative.

template<class LinearSolver>
Real Rodin::Solver::NewtonSolver<LinearSolver>::getAbsoluteTolerance() const noexcept

Gets the absolute residual tolerance.

Returns Current absolute tolerance.

Default value: 1e-12.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setRelativeTolerance(Real rtol)

Sets the relative residual tolerance.

Parameters
rtol Relative residual tolerance.
Returns Reference to this solver.

The relative tolerance must be finite and non-negative.

template<class LinearSolver>
Real Rodin::Solver::NewtonSolver<LinearSolver>::getRelativeTolerance() const noexcept

Gets the relative residual tolerance.

Returns Current relative tolerance.

Default value: 1e-8.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setStepTolerance(Real stol)

Sets the step tolerance.

Parameters
stol Step tolerance.
Returns Reference to this solver.

The step tolerance must be finite and non-negative. A value of zero disables the step-based convergence test.

template<class LinearSolver>
Real Rodin::Solver::NewtonSolver<LinearSolver>::getStepTolerance() const noexcept

Gets the step tolerance.

Returns Current step tolerance.

Default value: 0.0, which disables the step criterion.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setDampingFactor(Real alpha)

Sets the constant damping factor.

Parameters
alpha Damping factor.
Returns Reference to this solver.

The damping factor must be finite and strictly positive. A value of 1.0 corresponds to the standard undamped Newton update.

template<class LinearSolver>
Real Rodin::Solver::NewtonSolver<LinearSolver>::getDampingFactor() const noexcept

Gets the damping factor.

Returns Current damping factor.

Default value: 1.0.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setMaxIterations(size_t maxIt)

Sets the maximum number of Newton iterations.

Parameters
maxIt Maximum number of Newton iterations.
Returns Reference to this solver.

The iteration count must be strictly positive.

template<class LinearSolver>
size_t Rodin::Solver::NewtonSolver<LinearSolver>::getMaxIterations() const noexcept

Gets the maximum number of Newton iterations.

Returns Maximum number of iterations.

Default value: 100.

template<class LinearSolver>
NewtonSolver& Rodin::Solver::NewtonSolver<LinearSolver>::setMonitor(Optional<Monitor> monitor)

Sets the optional iteration monitor.

Parameters
monitor Optional monitor callback.
Returns Reference to this solver.

Passing a callable installs a monitor invoked once per Newton iteration. Passing std::nullopt disables monitoring.

Default value: none.

template<class LinearSolver>
const Optional<Monitor>& Rodin::Solver::NewtonSolver<LinearSolver>::getMonitor() const noexcept

Gets the optional iteration monitor.

Returns The currently installed monitor, if any.

template<class LinearSolver>
const Report& Rodin::Solver::NewtonSolver<LinearSolver>::getReport() const noexcept

Gets the report of the most recent solve.

Returns Diagnostic report for the last call to solve().

template<class LinearSolver>
bool Rodin::Solver::NewtonSolver<LinearSolver>::converged() const noexcept

Returns whether the most recent solve converged.

Returns true if the last solve terminated by a convergence criterion, false otherwise.

template<class LinearSolver>
void Rodin::Solver::NewtonSolver<LinearSolver>::solve(SolutionType& x) override

Solves the nonlinear problem starting from x.

Parameters
x in/out Nonlinear state vector updated in place.
Exceptions
Alert::MemberFunctionException If the residual norm or the step norm is not finite.

The vector x is used both as the initial guess and as the storage for the final nonlinear iterate. The associated tangential problem is reassembled at each Newton iteration.

The solve proceeds as follows:

  • assemble the tangential problem,
  • compute the residual norm from the assembled right-hand side,
  • test convergence,
  • solve the tangential linear system,
  • compute the damped step norm,
  • test the optional step criterion,
  • update x with the damped Newton correction.

The internal report is reset at the beginning of the solve.

template<class LinearSolver>
void Rodin::Solver::NewtonSolver<LinearSolver>::solve(SolutionType& x) pure virtual

Solve a nonlinear system starting from the initial guess stored in x.

Parameters
x in/out On entry: initial guess. On exit: final Newton iterate.

template<class LinearSolver> template<class GridFunctionType, class = std::enable_if_t< std::is_same_v< typename FormLanguage::Traits<std::decay_t<GridFunctionType>>::DataType, SolutionType>>>
void Rodin::Solver::NewtonSolver<LinearSolver>::solve(GridFunctionType& gf)

Solve a nonlinear system using a GridFunction as the solution container.

Template parameters
GridFunctionType GridFunction type whose Traits must expose DataType.
Parameters
gf in/out GridFunction holding the initial guess / final solution.

The GridFunction's internal data vector is used both as the initial guess and as the storage for the converged solution. The backend data type is inferred from FormLanguage::Traits<GridFunctionType>::DataType and must match the solver's SolutionType.

This is equivalent to calling solve(gf.getData()).