NonlinearSystem Class Reference

Definition of a nonlinear system of equations. More...

Detailed Description

Definition of a nonlinear system of equations.

#include <NonlinearSystem.h>

Inheritance diagram for NonlinearSystem:

Classes
struct	Jac
struct	Res
struct	Sol

Public Member Functions
	NonlinearSystem (const NonlinearSystem &)=default
	NonlinearSystem (NonlinearSystem &&) noexcept=default
NonlinearSystem &	operator= (const NonlinearSystem &)=delete
NonlinearSystem &	operator= (NonlinearSystem &&)=delete
virtual	~NonlinearSystem ()=default
	NonlinearSystem (const OptionSet &options)
virtual void	init_scaling (const Sol< false > &x, const bool verbose=false)
	Compute algebraic Jacobian-based automatic scaling following https://cs.stanford.edu/people/paulliu/files/cs517-project.pdf.
Res< true >	scale (const Res< false > &r) const
	Apply scaling to the residual.
Res< false >	unscale (const Res< true > &r) const
	Remove scaling to the residual.
Jac< true >	scale (const Jac< false > &J) const
	Apply scaling to the Jacobian.
Jac< false >	unscale (const Jac< true > &J) const
	Remove scaling to the Jacobian.
Sol< true >	scale (const Sol< false > &u) const
	Apply scaling to the solution.
Sol< false >	unscale (const Sol< true > &u) const
	Remove scaling to the solution.
void	set_guess (const Sol< true > &x)
	Set the current guess.
virtual void	set_guess (const Sol< false > &x)=0
	Set the unscaled current guess.
template<bool scaled>
Res< scaled >	residual ()
	Assemble and return the residual.
template<bool scaled>
Res< scaled >	residual (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the residual.
template<bool scaled>
Jac< scaled >	Jacobian ()
	Assemble and return the Jacobian.
template<bool scaled>
Jac< scaled >	Jacobian (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the Jacobian.
template<bool scaled>
std::tuple< Res< scaled >, Jac< scaled > >	residual_and_Jacobian ()
	Assemble and return the residual and Jacobian.
template<bool scaled>
std::tuple< Res< scaled >, Jac< scaled > >	residual_and_Jacobian (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the residual and Jacobian.

Static Public Member Functions
static OptionSet	expected_options ()
static void	disable_automatic_scaling (OptionSet &options)
static void	enable_automatic_scaling (OptionSet &options)

Protected Member Functions
virtual void	assemble (Res< false > *r, Jac< false > *J)=0
	Compute the unscaled residual and Jacobian.

Protected Attributes
const bool	_autoscale
	If true, do automatic scaling.
const Real	_autoscale_tol
	Tolerance for convergence check of the iterative automatic scaling algorithm.
const unsigned int	_autoscale_miter
	Maximum number of iterations allowed for the iterative automatic scaling algorithm.
bool	_scaling_matrices_initialized = false
	Flag to indicate whether scaling matrices have been computed.
Tensor	_row_scaling
	Row scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.
Tensor	_col_scaling
	Column scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.

Constructor & Destructor Documentation

NonlinearSystem() [1/3]

NonlinearSystem ( const NonlinearSystem & )

default

NonlinearSystem() [2/3]

NonlinearSystem ( NonlinearSystem && )

defaultnoexcept

~NonlinearSystem()

virtual ~NonlinearSystem ( )

virtualdefault

NonlinearSystem() [3/3]

NonlinearSystem

(

const OptionSet &

options

)

Member Function Documentation

assemble()

virtual void assemble ( Res< false > * r, Jac< false > * J )

protectedpure virtual

Compute the unscaled residual and Jacobian.

Parameters

r	Pointer to the residual vector – nullptr if not requested
J	Pointer to the Jacobian matrix – nullptr if not requested

Implemented in Model, and TrustRegionSubProblem.

disable_automatic_scaling()

void disable_automatic_scaling ( OptionSet & options )

static

enable_automatic_scaling()

void enable_automatic_scaling ( OptionSet & options )

static

expected_options()

OptionSet expected_options ( )

static

init_scaling()

void init_scaling ( const Sol< false > & x, const bool verbose = false )

virtual

Compute algebraic Jacobian-based automatic scaling following https://cs.stanford.edu/people/paulliu/files/cs517-project.pdf.

In a nutshell, given the original linearized system

$\mathrm{J}\mathrm{\Delta }\mathrm{x}=-\mathrm{r}$

Instead of solving for $\mathrm{\Delta }\mathrm{x}$ directly, we solve for a scaled version of it:

$\mathrm{J}\mathrm{C}\mathrm{\Delta }{\mathrm{x}}^{\prime }=-\mathrm{r}$

where $\mathrm{C}$ is a diagonal matrix, and apparently $\mathrm{\Delta }\mathrm{x}=\mathrm{C}\mathrm{\Delta }{\mathrm{x}}^{\prime }$. Then, left-multiply both sides by another diagonal matrix $\mathrm{R}$, we get

$\mathrm{R}\mathrm{J}\mathrm{C}\mathrm{\Delta }{\mathrm{x}}^{\prime }=-\mathrm{R}\mathrm{r}$

which is equivalent to

${\mathrm{J}}^{\prime }\mathrm{\Delta }{\mathrm{x}}^{\prime }=-{\mathrm{r}}^{\prime }$

where ${\mathrm{J}}^{\prime }=\mathrm{R}\mathrm{J}\mathrm{C}$ is the scaled Jacobian, and ${\mathrm{r}}^{\prime }=\mathrm{R}\mathrm{r}$ is the scaled residual. The goal of automatic scaling is to find the scaling matrices so that max-norm of the rows and columns of the scaled Jacobian is as close to 1 as possible.

Parameters

x	Unscaled initial guess used to compute the initial unscaled residual and Jacobian
verbose	Print automatic scaling convergence information

Jacobian() [1/2]

template<bool scaled>

NonlinearSystem::Jac< scaled > Jacobian

(

)

Assemble and return the Jacobian.

Jacobian() [2/2]

template<bool scaled>

NonlinearSystem::Jac< scaled > Jacobian

(

const Sol< scaled > &

x

)

Convenient shortcut to set the current guess, assemble and return the Jacobian.

operator=() [1/2]

NonlinearSystem & operator= ( const NonlinearSystem & )

delete

operator=() [2/2]

NonlinearSystem & operator= ( NonlinearSystem && )

delete

residual() [1/2]

template<bool scaled>

NonlinearSystem::Res< scaled > residual

(

)

Assemble and return the residual.

residual() [2/2]

template<bool scaled>

NonlinearSystem::Res< scaled > residual

(

const Sol< scaled > &

x

)

Convenient shortcut to set the current guess, assemble and return the residual.

residual_and_Jacobian() [1/2]

template<bool scaled>

std::tuple< NonlinearSystem::Res< scaled >, NonlinearSystem::Jac< scaled > > residual_and_Jacobian

(

)

Assemble and return the residual and Jacobian.

residual_and_Jacobian() [2/2]

template<bool scaled>

std::tuple< NonlinearSystem::Res< scaled >, NonlinearSystem::Jac< scaled > > residual_and_Jacobian

(

const Sol< scaled > &

x

)

Convenient shortcut to set the current guess, assemble and return the residual and Jacobian.

scale() [1/3]

NonlinearSystem::Jac< true > scale

(

const Jac< false > &

J

)

const

Apply scaling to the Jacobian.

scale() [2/3]

NonlinearSystem::Res< true > scale

(

const Res< false > &

r

)

const

Apply scaling to the residual.

scale() [3/3]

NonlinearSystem::Sol< true > scale

(

const Sol< false > &

u

)

const

Apply scaling to the solution.

set_guess() [1/2]

virtual void set_guess ( const Sol< false > & x )

pure virtual

Set the unscaled current guess.

Implemented in Model, and TrustRegionSubProblem.

set_guess() [2/2]

void set_guess

(

const Sol< true > &

x

)

Set the current guess.

unscale() [1/3]

NonlinearSystem::Jac< false > unscale

(

const Jac< true > &

J

)

const

Remove scaling to the Jacobian.

unscale() [2/3]

NonlinearSystem::Res< false > unscale

(

const Res< true > &

r

)

const

Remove scaling to the residual.

unscale() [3/3]

NonlinearSystem::Sol< false > unscale

(

const Sol< true > &

u

)

const

Remove scaling to the solution.

Member Data Documentation

_autoscale

const bool _autoscale

protected

If true, do automatic scaling.

_autoscale_miter

const unsigned int _autoscale_miter

protected

Maximum number of iterations allowed for the iterative automatic scaling algorithm.

_autoscale_tol

const Real _autoscale_tol

protected

Tolerance for convergence check of the iterative automatic scaling algorithm.

_col_scaling

Tensor _col_scaling

protected

Column scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.

_row_scaling

Tensor _row_scaling

protected

Row scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.

_scaling_matrices_initialized

bool _scaling_matrices_initialized = false

protected

Flag to indicate whether scaling matrices have been computed.