Base class for all classes performing Newton's iteration. More...

#include <newton_base.h>

Inheritance diagram for FuelCell::ApplicationCore::newtonBase:

Collaboration diagram for FuelCell::ApplicationCore::newtonBase:

Public Member Functions
	newtonBase (ApplicationBase &app)
	Constructor, receiving the application computing the residual and solving the linear problem. More...

virtual void	declare_parameters (ParameterHandler &param)
	Declare the input parameters. More...

virtual void	initialize (ParameterHandler &param)
	Read the parameters. More...

void	_initialize (ParameterHandler &param)
	Read the parameters local to newtonBase. More...

double	threshold (double new_value)
	Set the maximal residual reduction allowed without triggering assembling in the next step. More...

void	initialize_initial_guess (BlockVector< double > &dst)
	Control object for the Newton iteration. More...

virtual void	assemble ()
	Instead of assembling, this function only sets a flag, such that the inner application will be required to assemble a new derivative matrix next time solve() is called. More...

virtual double	residual (FuelCell::ApplicationCore::FEVector &dst, const FuelCell::ApplicationCore::FEVectors &rhs)
	Returns the L2-norm of the residual and the residual vector in "dst" using the residual function in the ApplicationBase used to initialize the application. More...

virtual void	solve (FuelCell::ApplicationCore::FEVector &u, const FuelCell::ApplicationCore::FEVectors &in_vectors)=0
	The actual Newton solver. More...

Public Member Functions inherited from FuelCell::ApplicationCore::ApplicationWrapper
	ApplicationWrapper (ApplicationBase &app)
	Constructor for a derived application. More...

	~ApplicationWrapper ()
	Destructor. More...

virtual void	remesh ()
	Generate the next mesh depending on the mesh generation parameters. More...

virtual void	init_vector (FEVector &dst) const
	Initialize vector to problem size. More...

virtual double	residual (FEVector &dst, const FEVectors &src, bool apply_boundaries=true)
	Compute residual of `src` and store it into `dst`. More...

virtual void	Tsolve (FEVector &dst, const FEVectors &src)
	Solve the dual system assembled with right hand side `rhs` and return the result in `start`. More...

virtual double	estimate (const FEVectors &src)
	Estimate cell-wise errors. More...

virtual double	evaluate (const FEVectors &src)
	Evaluate a functional. More...

virtual void	grid_out (const std::string &filename) const

virtual void	data_out (const std::string &filename, const FEVectors &src)
	Write data in the format specified by the ParameterHandler. More...

virtual std::string	id () const
	Return a unique identification string for this application. More...

virtual void	notify (const Event &reason)
	Add a reason for assembling. More...

Public Member Functions inherited from FuelCell::ApplicationCore::ApplicationBase
	ApplicationBase (boost::shared_ptr< ApplicationData > data=boost::shared_ptr< ApplicationData >())
	Constructor for an application. More...

	ApplicationBase (const ApplicationBase &other)
	Copy constructor. More...

virtual	~ApplicationBase ()
	Virtual destructor. More...

void	print_parameters_to_file (ParameterHandler &param, const std::string &file_name, const ParameterHandler::OutputStyle &style)
	Print default parameters for the application to a file. More...

virtual void	start_vector (FEVector &dst, std::string) const
	Initialize vector to problem size. More...

virtual void	grid_out (const std::string &)
	Write the mesh in the format specified by the ParameterHandler. More...

boost::shared_ptr < ApplicationData >	get_data ()
	Get access to the protected variable data. More...

const boost::shared_ptr < ApplicationData >	get_data () const
	Get read-only access to the protected variable data. More...

virtual void	clear ()
	All `true` in `notifications`. More...

virtual void	clear_events ()
	All `false` in `notifications`. More...

virtual unsigned int	get_solution_index ()
	Returns solution index. More...

Public Attributes
ReductionControl	control
	Control object for the Newton iteration. More...

double	numIter
	Number of Iterations;. More...

Static Public Attributes
static const FuelCell::ApplicationCore::Event	bad_derivative
	The Event set if convergence is becoming bad and a new matrix should be assembled. More...

Protected Member Functions
void	debug_output (const FEVector &sol, const FEVector &update, const FEVector &residual) const
	Function used to output any necessary information at each Newton iteration for debugging purposes. More...

Protected Member Functions inherited from FuelCell::ApplicationCore::ApplicationWrapper
SmartPointer< ApplicationBase >	get_wrapped_application ()
	Gain access to the inner application. More...

Protected Member Functions inherited from FuelCell::ApplicationCore::ApplicationBase
void	print_caller_name (const std::string &caller_name) const
	Print caller name. More...

Protected Attributes
bool	assemble_now
	This flag is set by the function assemble(), indicating that the matrix must be assembled anew upon start. More...

double	assemble_threshold
	Threshold for re-assembling matrix. More...

bool	debug_solution
	Print updated solution after each step into file `Newton_uNNN`? More...

bool	debug_update
	Print Newton update after each step into file `Newton_dNNN`? More...

bool	debug_residual
	Print Newton residual after each step into file `Newton_rNNN`? More...

unsigned int	debug
	Write debug output to FcstUtilities::log; the higher the number, the more output. More...

unsigned int	step
	The number of a basic Newton iteration. More...

std::vector< unsigned int >	blocks
	This vector specifies the blocks of the global solution which are supposed to be treated specially. More...

unsigned int	n_blocks
	The total number of `blocks`. More...

Protected Attributes inherited from FuelCell::ApplicationCore::ApplicationWrapper
SmartPointer< ApplicationBase >	app
	Pointer to the application this one depends upon. More...

Protected Attributes inherited from FuelCell::ApplicationCore::ApplicationBase
boost::shared_ptr < ApplicationData >	data
	Object for auxiliary data. More...

Event	notifications
	Accumulate reasons for assembling here. More...

Detailed Description

Base class for all classes performing Newton's iteration.

Children of this class mainly differ due to the global search method implemented as discussed below.

Theory

Newton's method approximates a value for $\mathbf{x}^* \in R^n$ such that

$\mathbf{F}(\mathbf{x}^*) = 0$

where $\mathbf{F}$ is a system of $ n $ nonlinear equations.

Solution $\mathbf{x}^*$ is iteratively determined by evaluating

$\mathbf{x}_i = \mathbf{x}_{i-1} + \delta \mathbf{x}$

where $\mathbf{x}_i$ is ith Newton iterate starting from an initial guess $\mathbf{x}_0$ and

$\delta \mathbf{x} = - \left( \frac{\partial \mathbf{F}(\mathbf{x}_{i-1})}{\partial \mathbf{x}} \right)^{-1} \mathbf{F}(\mathbf{x}_{i-1})$

Matrix

$\frac{\partial \mathbf{F}(\mathbf{x}_{i-1})}{\partial \mathbf{x}}$

is Jacobian matrix evaluated at $\mathbf{x}_{i-1}$ . Most steady-state openFCST linear applications compute the Jacobian and solve the linear system above in order to provide the Newton solver with iteration update, $\delta \mathbf{x}$ , based on the system of PDEs that user wants to solve.

Newton iterations are performed until the error between the iterate and the final solution is sufficiently small:

$\| \mathbf{e}_i \| = \| \mathbf{x}^* - \mathbf{x}_i \|$

The error $\mathbf{e}_i$ is not known in practice. However, the norm of the residual $\| \mathbf{F(\mathbf{x}_i)} \|$ proves to be an effective indicator of the rate of decay of the error. In the case of openFCST, the L2 norm of the residual is used as a termination criteria.

openFCST checks if

$\| \mathbf{F(\mathbf{x}_i)} \| \leq \tau_a$

where $\tau_a$ is user-supplied absolute tolerance. If the absolute tolerance is satisfied, the Newton iterations are terminated. This user-supplied parameter is an input parameter specified in "set Tolerance = 1e-5" as discussed below.

Further, user can specify a maximum number of iteration in the Newton subsection of the input file using "set Max steps = 10". In this case, the solver would terminate when the max. number of iterations is reached regardless of the value of the residual, i.e. the nonlinear problem is not solved.

A third option for stopping convergence, not used in openFCST, is to terminate when

$\| \mathbf{F(\mathbf{x}_i)} \| \leq \tau_r \| \mathbf{F(\mathbf{x}_0)} \|$

where $\tau_r$ is user-supplied relative tolerance.

Newton’s method should converge to the solution as the number of Newton iterations becomes large. If the initial guess $\mathbf{x}_0$ is poor, however, convergence may fail to occur. Often the failure of convergence is a consequence of the Newton step, $\delta \mathbf{x}$ , overshooting the correct value of $\mathbf{x}^*$ .

The problem of overshooting can usually be solved by using only a fraction of the Newton direction for each Newton iteration; see section 1.6 of [2] for additional details. In other words, a new Newton step, $\delta \mathbf{x}^*$ , is applied to each Newton iteration such that

$\delta \mathbf{x}^* = h \delta \mathbf{x}$

where $ h $ is known as the step size.

The method used to determine $ h $ is referred to as the global-convergence strategy. The strategy can greatly affect both the efficiency and versatility of Newton’s method.

Several Newton solvers have been implemented that use a different global-convergence strategy. In particular, user has three options:

NewtonBasic: No global-convergence strategy is implemented;
NewtonLineSearch: A line search is implemented as a global strategy;
Newton3pp: A three-point parabolic method is implemented as a global-strategy; two options are possible, with or without prediction of step size.

Usage Details:

FuelCell::Application::AppCathode<dim> app_linear;     // Create a linear application (computes the step size by solving linear problem)
FuelCell::ApplicationCore::NewtonBasic(*app_linear);                    // Associate linear problem to nonlinear solver
app_linear->init_solution(solution);                   // Initialize solution
FuelCell::ApplicationCore::FEVector solution;                           // Create a vector where solution will be stored
FuelCell::ApplicationCore::FEVectors vectors;                           // Pass any other constant data to Newton solver
vectors.add_vector(solution,"Solution");
FcstUtilities::log << "Solving..." << std::endl;
app->solve(solution, vectors);                         // Solve
app->data_out(sol_filename,vectors);                   // Output solution

For a more detailed example, please see AdaptiveRefinement.

Parameters

The parameters that control all Newton solvers are defined in the subsection Newton in the data input file. The parameters are the following:

subsection Newton
 set Max steps          = 100           # Maximum number of iterations
 set Tolerance          = 1.e-8         # Absolute tolerance
 set Reduction          = 1.e-20        # Maximum allowed reduction during line search. If the residual is not reduced by at least this number the iteration is discarded.
 set Assemble threshold = 0.0           # Used as a threshold to state if the Jacobian needs to be re-evaluated
 set Debug level        = 0
 set Debug residual     = false         # Would you like the code to output the residual at every Newton iteration?
 set Debug solution     = false         # Would you like the code to output the solution at every Newton iteration?
 set Debug update       = false
end

References

[1] C. T. Kelley. Iterative methods for linear and nonlinear equations, volume 16 of Frontiers in Applied Mathematics. Society for Industrial and Applied Mathematics (SIAM), Philadelphia, PA, 1995. With separately available software.

[2] C. T. Kelley. Solving nonlinear equations with Newton’s method. Fundamentals of Algorithms. Society for Industrial and Applied Mathematics (SIAM), Philadelphia, PA, 2003.

Author: Marc Secanell and Jason Boisvert, 2009-13

Constructor & Destructor Documentation

FuelCell::ApplicationCore::newtonBase::newtonBase ( ApplicationBase & app )

Constructor, receiving the application computing the residual and solving the linear problem.

Member Function Documentation

void FuelCell::ApplicationCore::newtonBase::_initialize ( ParameterHandler & param )

Read the parameters local to newtonBase.

virtual void FuelCell::ApplicationCore::newtonBase::assemble ( )

virtual

Instead of assembling, this function only sets a flag, such that the inner application will be required to assemble a new derivative matrix next time solve() is called.

void FuelCell::ApplicationCore::newtonBase::debug_output	(	const FEVector &	sol,
		const FEVector &	update,
		const FEVector &	residual
	)		const

protected

Function used to output any necessary information at each Newton iteration for debugging purposes.

virtual void FuelCell::ApplicationCore::newtonBase::declare_parameters ( ParameterHandler & param )

virtual

Declare the input parameters.

The following are the parameters used and their default values: In section: "Newton"

"Tolerance",
"Max steps",
"Assemble threshold", Default: "0."
"Debug level", Default: "0",
"Debug solution", Default: "false", Patterns::Bool()
"Debug update", Default: "false", Patterns::Bool()
"Debug residual", "false", Patterns::Bool()

Reimplemented from FuelCell::ApplicationCore::ApplicationWrapper.

Reimplemented in FuelCell::ApplicationCore::Newton3pp, FuelCell::ApplicationCore::NewtonLineSearch, and FuelCell::ApplicationCore::NewtonBasic.

virtual void FuelCell::ApplicationCore::newtonBase::initialize ( ParameterHandler & param )

virtual

Read the parameters.

Reimplemented from FuelCell::ApplicationCore::ApplicationWrapper.

Reimplemented in FuelCell::ApplicationCore::Newton3pp, FuelCell::ApplicationCore::NewtonLineSearch, and FuelCell::ApplicationCore::NewtonBasic.

void FuelCell::ApplicationCore::newtonBase::initialize_initial_guess ( BlockVector< double > & dst )

inline

Control object for the Newton iteration.

virtual double FuelCell::ApplicationCore::newtonBase::residual	(	FuelCell::ApplicationCore::FEVector &	dst,
		const FuelCell::ApplicationCore::FEVectors &	rhs
	)

virtual

Returns the L2-norm of the residual and the residual vector in "dst" using the residual function in the ApplicationBase used to initialize the application.

The FEVectors rhs should contain at least the following vectors:

Note
Finish this section

virtual void FuelCell::ApplicationCore::newtonBase::solve	(	FuelCell::ApplicationCore::FEVector &	u,
		const FuelCell::ApplicationCore::FEVectors &	in_vectors
	)

pure virtual

The actual Newton solver.

In this section, the Newton solver performs the iterations necessary to solve the nonlinear system. During the process it will call assemble() and residual() as needed. Once it is done, it will return the solution as parameter {u}.

Reimplemented from FuelCell::ApplicationCore::ApplicationWrapper.

Implemented in FuelCell::ApplicationCore::Newton3pp, FuelCell::ApplicationCore::NewtonLineSearch, and FuelCell::ApplicationCore::NewtonBasic.

double FuelCell::ApplicationCore::newtonBase::threshold ( double new_value )

Set the maximal residual reduction allowed without triggering assembling in the next step.

Return the previous value.

Member Data Documentation

bool FuelCell::ApplicationCore::newtonBase::assemble_now

protected

This flag is set by the function assemble(), indicating that the matrix must be assembled anew upon start.

double FuelCell::ApplicationCore::newtonBase::assemble_threshold

protected

Threshold for re-assembling matrix.

If the quotient of two consecutive residuals is smaller than this threshold, the system matrix is not assembled in this step.

Note: This parameter should be adjusted to the residual gain of the inner solver.

const FuelCell::ApplicationCore::Event FuelCell::ApplicationCore::newtonBase::bad_derivative

static

The Event set if convergence is becoming bad and a new matrix should be assembled.

std::vector<unsigned int> FuelCell::ApplicationCore::newtonBase::blocks

protected

This vector specifies the blocks of the global solution which are supposed to be treated specially.

Such blocks usually include the density or molar fraction of oxygen (burns as a result of chemical reactions) and the density or molar fraction of hydrogen (burns as well as a result of chemical reactions).

These blocks are defined in the parameter files manually. Therefore, you need to know them beforehand.

Knowing these blocks, the non-linear solver checks against the negative values in those blocks and reduces the solution update if needed to keep the values positive.

ReductionControl FuelCell::ApplicationCore::newtonBase::control

Control object for the Newton iteration.

unsigned int FuelCell::ApplicationCore::newtonBase::debug

protected

Write debug output to FcstUtilities::log; the higher the number, the more output.

bool FuelCell::ApplicationCore::newtonBase::debug_residual

protected

Print Newton residual after each step into file Newton_rNNN?

bool FuelCell::ApplicationCore::newtonBase::debug_solution

protected

Print updated solution after each step into file Newton_uNNN?

bool FuelCell::ApplicationCore::newtonBase::debug_update

protected

Print Newton update after each step into file Newton_dNNN?

unsigned int FuelCell::ApplicationCore::newtonBase::n_blocks

protected

The total number of blocks.

double FuelCell::ApplicationCore::newtonBase::numIter

Number of Iterations;.

unsigned int FuelCell::ApplicationCore::newtonBase::step

protected

The number of a basic Newton iteration.

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

newton_base.h

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Usage Details:

Parameters

References

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation