Class container for the multi-dimensional root finder. More...

#include <RootFinder.hh>

Inherits Optimist::SolverBase< Real, N, N, DerivedSolver, false >.

Public Types
using	Vector = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::InputType
using	Matrix = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FirstDerivativeType
using	Tensor = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::SecondDerivativeType
using	FunctionWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FunctionWrapper
using	JacobianWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FirstDerivativeWrapper
using	HessianWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::SecondDerivativeWrapper

Public Member Functions
	RootFinder ()
std::string	name () const
Integer	jacobian_evaluations () const
Integer	max_jacobian_evaluations () const
void	max_jacobian_evaluations (Integer t_jacobian_evaluations)
Integer	hessian_evaluations () const
Integer	max_hessian_evaluations () const
void	max_hessian_evaluations (Integer t_hessian_evaluations)
bool	solve (FunctionWrapper function, Vector const &x_ini, Vector &x_sol)
bool	solve (FunctionWrapper function, JacobianWrapper jacobian, Vector const &x_ini, Vector &x_sol)
bool	solve (FunctionWrapper function, JacobianWrapper jacobian, HessianWrapper hessian, Vector const &x_ini, Vector &x_sol)
Public Member Functions inherited from Optimist::SolverBase< Real, N, N, DerivedSolver, false >
	SolverBase ()
const InputType &	lower_bound () const
const InputType &	upper_bound () const
void	bounds (const InputType &t_lower_bound, const InputType &t_upper_bound)
constexpr Integer	input_dimension () const
constexpr Integer	output_dimension () const
Integer	function_evaluations () const
void	max_function_evaluations (Integer t_max_function_evaluations)
Integer	iterations () const
Integer	max_iterations () const
Real	alpha () const
Integer	relaxations () const
Integer	max_relaxations () const
Real	tolerance () const
void	verbose_mode (bool t_verbose)
void	enable_verbose_mode ()
void	disable_verbose_mode ()
void	damped_mode (bool t_damped)
void	enable_damped_mode ()
void	disable_damped_mode ()
std::string	task () const
bool	converged () const
const TraceType &	trace () const
std::ostream &	ostream () const
bool	solve (FunctionWrapper function, const InputType &x_ini, InputType &x_sol)
bool	rootfind (FunctionBase< Real, FunInDim, FunOutDim, DerivedFunction, ForceEigen &&FunOutDim==1 > const &function, const InputType &x_ini, InputType &x_sol)
bool	optimize (FunctionBase< Real, FunInDim, FunOutDim, DerivedFunction, ForceEigen &&FunOutDim==1 > const &function, const InputType &x_ini, InputType &x_sol)
std::string	name () const

Static Public Attributes
static constexpr bool	is_rootfinder {true}
static constexpr bool	is_optimizer {false}
static constexpr bool	requires_function {DerivedSolver::requires_function}
static constexpr bool	requires_first_derivative {DerivedSolver::requires_first_derivative}
static constexpr bool	requires_second_derivative {DerivedSolver::requires_second_derivative}

Protected Member Functions
void	evaluate_jacobian (JacobianWrapper jacobian, const Vector &x, Matrix &out)
void	evaluate_hessian (HessianWrapper hessian, const Vector &x, Matrix &out)
Protected Member Functions inherited from Optimist::SolverBase< Real, N, N, DerivedSolver, false >
Integer	first_derivative_evaluations () const
Integer	max_first_derivative_evaluations () const
Integer	second_derivative_evaluations () const
Integer	max_second_derivative_evaluations () const
void	reset ()
void	evaluate_function (FunctionWrapper function, const InputType &x, OutputType &out)
void	evaluate_first_derivative (FirstDerivativeWrapper function, const InputType &x, FirstDerivativeType &out)
void	evaluate_second_derivative (SecondDerivativeWrapper function, const InputType &x, SecondDerivativeType &out)
void	store_trace (const InputType &x)
bool	damp (FunctionWrapper function, InputType const &x_old, InputType const &function_old, InputType const &step_old, InputType &x_new, InputType &function_new, InputType &step_new)
void	header ()
void	bottom ()
void	info (Real residuals, std::string const &notes="-")

Friends
class	SolverBase< Real, N, N, RootFinder< Real, N, DerivedSolver, ForceEigen > >

Additional Inherited Members
Protected Types inherited from Optimist::SolverBase< Real, N, N, DerivedSolver, false >
using	InputType
using	OutputType
using	TraceType
using	FirstDerivativeType
using	SecondDerivativeType
using	FunctionWrapper
using	FirstDerivativeWrapper
using	SecondDerivativeWrapper
Protected Attributes inherited from Optimist::SolverBase< Real, N, N, DerivedSolver, false >
InputType	m_lower_bound
InputType	m_upper_bound
Integer	m_function_evaluations
Integer	m_first_derivative_evaluations
Integer	m_second_derivative_evaluations
Integer	m_max_function_evaluations
Integer	m_max_first_derivative_evaluations
Integer	m_max_second_derivative_evaluations
Integer	m_iterations
Integer	m_max_iterations
Real	m_alpha
Integer	m_relaxations
Integer	m_max_relaxations
Real	m_tolerance
bool	m_verbose
bool	m_damped
std::ostream *	m_ostream
std::string	m_task
bool	m_converged
TraceType	m_trace

Detailed Description

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>
class Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >

Root finder

This section describes the multi-dimensional root-finders implemented in Optimist. The available root-finding solvers are Newton (derivative) and quasi-Newton (non-derivative) methods. Derivative methods employ the function's derivative to find the root with high accuracy, while non-derivative methods approximate the derivative for improved efficiency in certain scenarios.

Here, the solvers are implemented for solving problems of the form

\[ \mathbf{f}(\mathbf{x}) = \mathbf{0} \text{,} \quad \text{with} \quad \mathbf{f}: \mathbb{R}^{n} \rightarrow \mathbb{R}^{n} \text{,} \]

which consist in finding the root of the function \(\mathbf{f}\) by iteratively updating the current iterate \(\mathbf{x}_k\) until convergence is achieved. The solvers require the function \(\mathbf{f}\) and its Jacobian matrix \(\mathbf{Jf}_{\mathbf{x}}\) to be provided by the user. The Jacobian matrix can be computed analytically or numerically, depending on the problem's complexity and the user's preference. Alternatively, the Jacobian can be approximated numerically using finite differences, depending on the problem's complexity and the user's preference.

Affine-invariant step

By default, the multi-dimensional root-finders in Optimist use optionally an affine-invariant advancing step to ensure convergence. The generic advancing step \(\mathbf{h}_k\) is computed as

\[ \mathbf{x}_{k+1} = \mathbf{x}_k + \alpha_k \mathbf{h}_k \text{,} \]

where \(\alpha_k\) is a damping coefficient that ensures convergence by satisfying

\[ \left\|\mathbf{Jf}_{\mathbf{x}}(\mathbf{x}_k)^{-1} \mathbf{f}(\mathbf{x}_{k+1})\right\| \leq \left(1 - \displaystyle\frac{\alpha_k}{2}\right) \left\|\mathbf{Jf}_{\mathbf{x}}(\mathbf{x}_k)^{-1} \mathbf{f}(\mathbf{x}_k)\right\| = \left(1 - \displaystyle\frac{\alpha_k}{2} \right) \left\|\mathbf{h}_k\right\| \text{.} \]

For detailed information on the affine-invariant Newton's method, refer to this link, or the works by P. Deuflhard.

Template Parameters

Real	Scalar number type.
N	The dimension of the root-finding problem.
DerivedSolver	Derived solver class.
ForceEigen	Force the use of Eigen types for input and output.

Member Typedef Documentation

◆ FunctionWrapper

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::FunctionWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FunctionWrapper

◆ HessianWrapper

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::HessianWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::SecondDerivativeWrapper

◆ JacobianWrapper

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::JacobianWrapper = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FirstDerivativeWrapper

◆ Matrix

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::Matrix = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::FirstDerivativeType

Jacobian matrix type.

◆ Tensor

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::Tensor = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::SecondDerivativeType

Hessian tensor type.

◆ Vector

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

using Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::Vector = typename SolverBase<Real, N, N, DerivedSolver, ForceEigen>::InputType

Vector type.

Constructor & Destructor Documentation

◆ RootFinder()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::RootFinder ( )

inline

Class constructor for the multi-dimensional root finder.

Member Function Documentation

◆ evaluate_hessian()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

void Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::evaluate_hessian	(	HessianWrapper	hessian,
		const Vector &	x,
		Matrix &	out )

inlineprotected

Evaluate the Hessian function.

Parameters

[in]	hessian	Hessian function wrapper.
[in]	x	Input point.
[out]	out	Hessian value.

◆ evaluate_jacobian()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

void Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::evaluate_jacobian	(	JacobianWrapper	jacobian,
		const Vector &	x,
		Matrix &	out )

inlineprotected

Evaluate the Jacobian function.

Parameters

[in]	jacobian	Jacobian function wrapper.
[in]	x	Input point.
[out]	out	Jacobian value.

◆ hessian_evaluations()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

Integer Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::hessian_evaluations ( ) const

inline

Get the number of Hessian evaluations.

Returns: The number of Hessian evaluations.

◆ jacobian_evaluations()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

Integer Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::jacobian_evaluations ( ) const

inline

Get the number of Jacobian evaluations.

Returns: The number of Jacobian evaluations.

◆ max_hessian_evaluations() [1/2]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

Integer Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::max_hessian_evaluations ( ) const

inline

Get the number of maximum allowed Hessian evaluations.

Returns: The number of maximum allowed Hessian evaluations.

◆ max_hessian_evaluations() [2/2]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

void Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::max_hessian_evaluations ( Integer t_hessian_evaluations )

inline

Set the number of maximum allowed Hessian evaluations.

Parameters

[in] t_hessian_evaluations The number of maximum allowed Hessian evaluations.

◆ max_jacobian_evaluations() [1/2]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

Integer Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::max_jacobian_evaluations ( ) const

inline

Get the number of maximum allowed Jacobian evaluations.

Returns: The number of maximum allowed Jacobian evaluations.

◆ max_jacobian_evaluations() [2/2]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

void Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::max_jacobian_evaluations ( Integer t_jacobian_evaluations )

inline

Set the number of maximum allowed Jacobian evaluations.

Parameters

[in] t_jacobian_evaluations The number of maximum allowed Jacobian evaluations.

◆ name()

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

std::string Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::name ( ) const

inline

Get the solver name.

Returns: The solver name.

◆ solve() [1/3]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::solve	(	FunctionWrapper	function,
		JacobianWrapper	jacobian,
		HessianWrapper	hessian,
		Vector const &	x_ini,
		Vector &	x_sol )

inline

Solve the root-finding problem given the function, and its Jacobian and Hessian.

Parameters

[in]	function	Function wrapper.
[in]	jacobian	The Jacobian function wrapper.
[in]	hessian	The Hessian function wrapper.
[in]	x_ini	Initialization point.
[out]	x_sol	Solution point.

Returns: The convergence boolean flag.

◆ solve() [2/3]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::solve	(	FunctionWrapper	function,
		JacobianWrapper	jacobian,
		Vector const &	x_ini,
		Vector &	x_sol )

inline

Solve the root-finding problem given the function, and its Jacobian.

Parameters

[in]	function	Function wrapper.
[in]	jacobian	The Jacobian function wrapper.
[in]	x_ini	Initialization point.
[out]	x_sol	Solution point.

Returns: The convergence boolean flag.

◆ solve() [3/3]

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::solve	(	FunctionWrapper	function,
		Vector const &	x_ini,
		Vector &	x_sol )

inline

Solve the root-finding problem given the function, and without derivatives.

Parameters

[in]	function	Function wrapper.
[in]	x_ini	Initialization point.
[out]	x_sol	Solution point.

Returns: The convergence boolean flag.

◆ SolverBase< Real, N, N, RootFinder< Real, N, DerivedSolver, ForceEigen > >

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

friend class SolverBase< Real, N, N, RootFinder< Real, N, DerivedSolver, ForceEigen > >

friend

Member Data Documentation

◆ is_optimizer

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::is_optimizer {false}

staticconstexpr

◆ is_rootfinder

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::is_rootfinder {true}

staticconstexpr

◆ requires_first_derivative

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::requires_first_derivative {DerivedSolver::requires_first_derivative}

staticconstexpr

◆ requires_function

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::requires_function {DerivedSolver::requires_function}

staticconstexpr

◆ requires_second_derivative

template<typename Real, Integer N, typename DerivedSolver, bool ForceEigen = false>

bool Optimist::RootFinder::RootFinder< Real, N, DerivedSolver, ForceEigen >::requires_second_derivative {DerivedSolver::requires_second_derivative}

staticconstexpr

Basic constants.

The documentation for this class was generated from the following file:

include/Optimist/RootFinder.hh

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Root finder

Affine-invariant step

Member Typedef Documentation

◆ FunctionWrapper

◆ HessianWrapper

◆ JacobianWrapper

◆ Matrix

◆ Tensor

◆ Vector

Constructor & Destructor Documentation

◆ RootFinder()

Member Function Documentation

◆ evaluate_hessian()

◆ evaluate_jacobian()

◆ hessian_evaluations()

◆ jacobian_evaluations()

◆ max_hessian_evaluations() [1/2]

◆ max_hessian_evaluations() [2/2]

◆ max_jacobian_evaluations() [1/2]

◆ max_jacobian_evaluations() [2/2]

◆ name()

◆ solve() [1/3]

◆ solve() [2/3]

◆ solve() [3/3]

Friends And Related Symbol Documentation

◆ SolverBase< Real, N, N, RootFinder< Real, N, DerivedSolver, ForceEigen > >

Member Data Documentation

◆ is_optimizer

◆ is_rootfinder

◆ requires_first_derivative

◆ requires_function

◆ requires_second_derivative