Classes
struct	RootFind::rfTable
	Structure containing the iteration history. More...

class	RootFind
	Root finder for 1D problems. More...

Functions
	RootFind (ResidEval *resid)
	Constructor for the object. More...

	RootFind (const RootFind &r)

RootFind &	operator= (const RootFind &right)

doublereal	delXNonzero (doublereal x1) const
	Calculate a deltaX from an input value of x. More...

doublereal	delXMeaningful (doublereal x1) const
	Calculate a deltaX from an input value of x. More...

doublereal	deltaXControlled (doublereal x2, doublereal x1) const
	Calculate a controlled, nonzero delta between two numbers. More...

bool	theSame (doublereal x2, doublereal x1, doublereal factor=1.0) const
	Function to decide whether two real numbers are the same or not. More...

int	solve (doublereal xmin, doublereal xmax, int itmax, doublereal &funcTargetValue, doublereal *xbest)
	Using a line search method, find the root of a 1D function. More...

doublereal	func (doublereal x)
	Return the function value. More...

void	setTol (doublereal rtolf, doublereal atolf, doublereal rtolx=0.0, doublereal atolx=0.0)
	Set the tolerance parameters for the rootfinder. More...

void	setPrintLvl (int printLvl)
	Set the print level from the rootfinder. More...

void	setFuncIsGenerallyIncreasing (bool value)
	Set the function behavior flag. More...

void	setFuncIsGenerallyDecreasing (bool value)
	Set the function behavior flag. More...

void	setDeltaX (doublereal deltaXNorm)
	Set the minimum value of deltaX. More...

void	setDeltaXMax (doublereal deltaX)
	Set the maximum value of deltaX. More...

void	printTable ()
	Print the iteration history table. More...

Variables
ResidEval *	m_residFunc
	Pointer to the residual function evaluator. More...

doublereal	m_funcTargetValue
	Target value for the function. More...

doublereal	m_atolf
	Absolute tolerance for the value of f. More...

doublereal	m_atolx
	Absolute tolerance for the value of x. More...

doublereal	m_rtolf
	Relative tolerance for the value of f and x. More...

doublereal	m_rtolx
	Relative tolerance for the value of x. More...

doublereal	m_maxstep
	Maximum number of step sizes. More...

int	printLvl
	Print level. More...

bool	writeLogAllowed_
	Boolean to turn on the possibility of writing a log file. More...

doublereal	DeltaXnorm_
	Delta X norm. More...

int	specifiedDeltaXnorm_
	Boolean indicating whether DeltaXnorm_ has been specified by the user or not. More...

doublereal	DeltaXMax_
	Delta X Max. More...

int	specifiedDeltaXMax_
	Boolean indicating whether DeltaXMax_ has been specified by the user or not. More...

bool	FuncIsGenerallyIncreasing_
	Boolean indicating whether the function is an increasing with x. More...

bool	FuncIsGenerallyDecreasing_
	Boolean indicating whether the function is decreasing with x. More...

doublereal	deltaXConverged_
	Value of delta X that is needed for convergence. More...

doublereal	x_maxTried_
	Internal variable tracking largest x tried. More...

doublereal	fx_maxTried_
	Internal variable tracking f(x) of largest x tried. More...

doublereal	x_minTried_
	Internal variable tracking smallest x tried. More...

doublereal	fx_minTried_
	Internal variable tracking f(x) of smallest x tried. More...

std::vector< struct rfTable >	rfHistory_
	Vector of iteration histories. More...

Constant which determines the return integer from the routine
#define	ROOTFIND_SUCCESS 0
	This means that the root solver was a success. More...

#define	ROOTFIND_SUCCESS_XCONVERGENCEONLY 1
	This return value means that the root finder resolved a solution in the x coordinate, however, convergence in F was not achieved. More...

#define	ROOTFIND_FAILEDCONVERGENCE -1
	This means that the root solver failed to achieve convergence. More...

#define	ROOTFIND_BADINPUT -2
	This means that the input to the root solver was defective. More...

#define	ROOTFIND_SOLNLOWERTHANXMIN -3
	This means that the rootfinder believes the solution is lower than xmin. More...

#define	ROOTFIND_SOLNHIGHERTHANXMAX -4
	This means that the rootfinder believes the solution is higher than xmax. More...

int	its

int	TP_its

double	slope

double	xval

double	fval

int	foundPos

int	foundNeg

double	deltaXConverged

double	deltaFConverged

double	delX

std::string	reasoning

void	clear ()

Detailed Description

Macro Definition Documentation

◆ ROOTFIND_SUCCESS

#define ROOTFIND_SUCCESS 0

This means that the root solver was a success.

Definition at line 25 of file RootFind.h.

Referenced by RootFind::solve().

◆ ROOTFIND_SUCCESS_XCONVERGENCEONLY

#define ROOTFIND_SUCCESS_XCONVERGENCEONLY 1

This return value means that the root finder resolved a solution in the x coordinate, however, convergence in F was not achieved.

A common situation for this to happen is that f(x) is discontinuous about f(x) = f_0, where we seek the x where the function is equal to f_0. f(x) spans the f_0 while not being equal to f_0 anywhere.

Definition at line 33 of file RootFind.h.

◆ ROOTFIND_FAILEDCONVERGENCE

#define ROOTFIND_FAILEDCONVERGENCE -1

This means that the root solver failed to achieve convergence.

Definition at line 35 of file RootFind.h.

Referenced by RootFind::solve().

◆ ROOTFIND_BADINPUT

#define ROOTFIND_BADINPUT -2

This means that the input to the root solver was defective.

Definition at line 37 of file RootFind.h.

Referenced by RootFind::solve().

◆ ROOTFIND_SOLNLOWERTHANXMIN

#define ROOTFIND_SOLNLOWERTHANXMIN -3

This means that the rootfinder believes the solution is lower than xmin.

Definition at line 39 of file RootFind.h.

◆ ROOTFIND_SOLNHIGHERTHANXMAX

#define ROOTFIND_SOLNHIGHERTHANXMAX -4

This means that the rootfinder believes the solution is higher than xmax.

Definition at line 41 of file RootFind.h.

Function Documentation

◆ RootFind() [1/2]

RootFind ( ResidEval * resid )

Constructor for the object.

Parameters

resid Pointer to the residual function to be used to calculate f(x)

Definition at line 33 of file RootFind.cpp.

◆ RootFind() [2/2]

RootFind ( const RootFind & r )

Deprecated:: To be removed after Cantera 2.3.

Definition at line 59 of file RootFind.cpp.

◆ operator=()

RootFind & operator= ( const RootFind & right )

◆ delXNonzero()

doublereal delXNonzero ( doublereal x1 ) const

private

Calculate a deltaX from an input value of x.

This routine ensure that the deltaX will be greater or equal to DeltaXNorm_ or 1.0E-14 x

Parameters

x1	input value of x

Definition at line 117 of file RootFind.cpp.

References RootFind::DeltaXnorm_.

Referenced by RootFind::deltaXControlled(), and RootFind::delXMeaningful().

◆ delXMeaningful()

doublereal delXMeaningful ( doublereal x1 ) const

private

Calculate a deltaX from an input value of x.

This routine ensure that the deltaX will be greater or equal to DeltaXNorm_ or 1.0E-14 x or deltaXConverged_.

Parameters

x1	input value of x

Definition at line 127 of file RootFind.cpp.

References RootFind::deltaXConverged_, and RootFind::delXNonzero().

Referenced by RootFind::theSame().

◆ deltaXControlled()

double deltaXControlled	(	doublereal	x2,
		doublereal	x1
	)		const

private

Calculate a controlled, nonzero delta between two numbers.

The delta is designed to be greater than or equal to delXMeaningful(x) defined above with the same sign as the original delta. Therefore if you subtract it from either of the two original numbers, you get a different number.

Parameters

x2	first number
x1	second number

Definition at line 136 of file RootFind.cpp.

References RootFind::delXNonzero().

Referenced by RootFind::solve().

◆ theSame()

bool theSame	(	doublereal	x2,
		doublereal	x1,
		doublereal	factor = `1.0`
	)		const

private

Function to decide whether two real numbers are the same or not.

A comparison is made between the two numbers to decide whether they are close to one another. This is defined as being within factor * delXMeaningful() of each other.

The basic premise here is that if the two numbers are too close, the noise will prevent an accurate calculation of the function and its slope.

Parameters

x1	First number
x2	second number
factor	Multiplicative factor to multiple deltaX with

Returns: a boolean indicating whether the two numbers are the same or not.

Definition at line 151 of file RootFind.cpp.

References RootFind::delXMeaningful().

◆ solve()

int solve	(	doublereal	xmin,
		doublereal	xmax,
		int	itmax,
		doublereal &	funcTargetValue,
		doublereal *	xbest
	)

Using a line search method, find the root of a 1D function.

This routine solves the following equation.

\[ R(x) = f(x) - f_o = 0 \]

Parameters

xmin	Minimum value of x to be used.
xmax	Maximum value of x to be used
itmax	maximum number of iterations. Usually, it can be less than 50.
funcTargetValue	Value of \( f_o \) in the equation. On return, it contains the value of the function actually obtained.
xbest	Returns the x that satisfies the function On input, xbest should contain the best estimate of the solution. An attempt to find the solution near xbest is made.

Returns: : 0 = ROOTFIND_SUCCESS Found function -1 = ROOTFIND_FAILEDCONVERGENCE Failed to find the answer -2 = ROOTFIND_BADINPUT Bad input was detected

Definition at line 163 of file RootFind.cpp.

References RootFind::deltaXControlled(), RootFind::deltaXConverged_, RootFind::DeltaXMax_, RootFind::DeltaXnorm_, RootFind::func(), RootFind::m_atolf, RootFind::m_atolx, RootFind::m_funcTargetValue, RootFind::m_rtolf, RootFind::m_rtolx, Cantera::print_funcEval(), RootFind::printLvl, RootFind::rfHistory_, ROOTFIND_BADINPUT, ROOTFIND_FAILEDCONVERGENCE, ROOTFIND_SUCCESS, RootFind::specifiedDeltaXMax_, RootFind::specifiedDeltaXnorm_, Cantera::writelog(), RootFind::writeLogAllowed_, Cantera::writelogf(), RootFind::x_maxTried_, and RootFind::x_minTried_.

◆ func()

doublereal func ( doublereal x )

Return the function value.

This routine evaluates the following equation.

\[ R(x) = f(x) - f_o = 0 \]

Parameters

x	Value of the independent variable

Returns: The routine returns the value of \( R(x) \)

Definition at line 990 of file RootFind.cpp.

References Cantera::checkFinite(), RootFind::fx_maxTried_, RootFind::fx_minTried_, RootFind::m_funcTargetValue, RootFind::m_residFunc, RootFind::x_maxTried_, and RootFind::x_minTried_.

Referenced by RootFind::solve().

◆ setTol()

void setTol	(	doublereal	rtolf,
		doublereal	atolf,
		doublereal	rtolx = `0.0`,
		doublereal	atolx = `0.0`
	)

Set the tolerance parameters for the rootfinder.

These tolerance parameters are used on the function value and the independent value to determine convergence

Parameters

rtolf	Relative tolerance. The default is 10^-5
atolf	absolute tolerance. The default is 10^-11
rtolx	Relative tolerance. The default is 10^-5. Default parameter is 0.0, in which case rtolx is set equal to rtolf
atolx	absolute tolerance. The default is 10^-11. Default parameter is 0.0, in which case atolx is set equal to atolf

Definition at line 1008 of file RootFind.cpp.

References RootFind::m_atolf, RootFind::m_atolx, RootFind::m_rtolf, and RootFind::m_rtolx.

◆ setPrintLvl()

void setPrintLvl ( int printLvl )

Set the print level from the rootfinder.

0: No printing of any kind
1: Single print line indicating success or failure of the routine.
2: Summary table printed at the end of the routine, with a convergence history
3: Printouts during the iteration are added. Summary table is printed out at the end. if writeLogAllowed_ is turned on, a file is written out with the convergence history.

Parameters

printLvl integer value

Definition at line 1024 of file RootFind.cpp.

References RootFind::printLvl.

◆ setFuncIsGenerallyIncreasing()

void setFuncIsGenerallyIncreasing ( bool value )

Set the function behavior flag.

If this is true, the function is generally an increasing function of x. In particular, if the algorithm is seeking a higher value of f, it will look in the positive x direction.

This type of function is needed because this algorithm must deal with regions of f(x) where f is not changing with x.

Parameters

value boolean value

Definition at line 1029 of file RootFind.cpp.

References RootFind::FuncIsGenerallyDecreasing_, and RootFind::FuncIsGenerallyIncreasing_.

◆ setFuncIsGenerallyDecreasing()

void setFuncIsGenerallyDecreasing ( bool value )

Set the function behavior flag.

If this is true, the function is generally a decreasing function of x. In particular, if the algorithm is seeking a higher value of f, it will look in the negative x direction.

This type of function is needed because this algorithm must deal with regions of f(x) where f is not changing with x.

Parameters

value boolean value

Definition at line 1037 of file RootFind.cpp.

References RootFind::FuncIsGenerallyDecreasing_, and RootFind::FuncIsGenerallyIncreasing_.

◆ setDeltaX()

void setDeltaX ( doublereal deltaXNorm )

Set the minimum value of deltaX.

Parameters

deltaXNorm

Definition at line 1045 of file RootFind.cpp.

References RootFind::DeltaXnorm_, and RootFind::specifiedDeltaXnorm_.

◆ setDeltaXMax()

void setDeltaXMax ( doublereal deltaX )

Set the maximum value of deltaX.

Parameters

deltaX

Definition at line 1051 of file RootFind.cpp.

References RootFind::DeltaXMax_, and RootFind::specifiedDeltaXMax_.

◆ printTable()

void printTable ( )

Print the iteration history table.

Definition at line 1057 of file RootFind.cpp.

References RootFind::m_funcTargetValue, RootFind::rfHistory_, and Cantera::writelogf().

Variable Documentation

◆ m_residFunc

ResidEval* m_residFunc

Pointer to the residual function evaluator.

Definition at line 305 of file RootFind.h.

Referenced by RootFind::func(), and RootFind::operator=().

◆ m_funcTargetValue

doublereal m_funcTargetValue

Target value for the function.

We seek the value of f that is equal to this value

Definition at line 309 of file RootFind.h.

Referenced by RootFind::func(), RootFind::operator=(), RootFind::printTable(), and RootFind::solve().

◆ m_atolf

doublereal m_atolf

Absolute tolerance for the value of f.

Definition at line 312 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setTol(), and RootFind::solve().

◆ m_atolx

doublereal m_atolx

Absolute tolerance for the value of x.

Definition at line 315 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setTol(), and RootFind::solve().

◆ m_rtolf

doublereal m_rtolf

Relative tolerance for the value of f and x.

Definition at line 318 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setTol(), and RootFind::solve().

◆ m_rtolx

doublereal m_rtolx

Relative tolerance for the value of x.

Definition at line 321 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setTol(), and RootFind::solve().

◆ m_maxstep

doublereal m_maxstep

Maximum number of step sizes.

Definition at line 324 of file RootFind.h.

Referenced by RootFind::operator=().

◆ printLvl

int printLvl

protected

Print level.

See also: setPrintLvl

Definition at line 328 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setPrintLvl(), and RootFind::solve().

◆ writeLogAllowed_

bool writeLogAllowed_

Boolean to turn on the possibility of writing a log file.

Definition at line 332 of file RootFind.h.

Referenced by RootFind::operator=(), and RootFind::solve().

◆ DeltaXnorm_

doublereal DeltaXnorm_

protected

Delta X norm.

This is the nominal value of deltaX that will be used by the program

Definition at line 337 of file RootFind.h.

Referenced by RootFind::delXNonzero(), RootFind::operator=(), RootFind::setDeltaX(), and RootFind::solve().

◆ specifiedDeltaXnorm_

int specifiedDeltaXnorm_

protected

Boolean indicating whether DeltaXnorm_ has been specified by the user or not.

Definition at line 341 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setDeltaX(), and RootFind::solve().

◆ DeltaXMax_

doublereal DeltaXMax_

protected

Delta X Max.

This is the maximum value of deltaX that will be used by the program. Sometimes a large change in x causes problems.

Definition at line 348 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setDeltaXMax(), and RootFind::solve().

◆ specifiedDeltaXMax_

int specifiedDeltaXMax_

protected

Boolean indicating whether DeltaXMax_ has been specified by the user or not.

Definition at line 352 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setDeltaXMax(), and RootFind::solve().

◆ FuncIsGenerallyIncreasing_

bool FuncIsGenerallyIncreasing_

protected

Boolean indicating whether the function is an increasing with x.

Definition at line 355 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setFuncIsGenerallyDecreasing(), and RootFind::setFuncIsGenerallyIncreasing().

◆ FuncIsGenerallyDecreasing_

bool FuncIsGenerallyDecreasing_

protected

Boolean indicating whether the function is decreasing with x.

Definition at line 358 of file RootFind.h.

Referenced by RootFind::operator=(), RootFind::setFuncIsGenerallyDecreasing(), and RootFind::setFuncIsGenerallyIncreasing().

◆ deltaXConverged_

doublereal deltaXConverged_

protected

Value of delta X that is needed for convergence.

X will be considered as converged if we are within deltaXConverged_ of the solution The default is zero.

Definition at line 365 of file RootFind.h.

Referenced by RootFind::delXMeaningful(), RootFind::operator=(), and RootFind::solve().

◆ x_maxTried_

doublereal x_maxTried_

protected

Internal variable tracking largest x tried.

Definition at line 368 of file RootFind.h.

Referenced by RootFind::func(), RootFind::operator=(), and RootFind::solve().

◆ fx_maxTried_

doublereal fx_maxTried_

protected

Internal variable tracking f(x) of largest x tried.

Definition at line 371 of file RootFind.h.

Referenced by RootFind::func(), and RootFind::operator=().

◆ x_minTried_

doublereal x_minTried_

protected

Internal variable tracking smallest x tried.

Definition at line 374 of file RootFind.h.

Referenced by RootFind::func(), RootFind::operator=(), and RootFind::solve().

◆ fx_minTried_

doublereal fx_minTried_

protected

Internal variable tracking f(x) of smallest x tried.

Definition at line 377 of file RootFind.h.

Referenced by RootFind::func(), and RootFind::operator=().

◆ rfHistory_

std::vector<struct rfTable> rfHistory_

protected

Vector of iteration histories.

Definition at line 420 of file RootFind.h.

Referenced by RootFind::printTable(), and RootFind::solve().

Classes

Functions

Variables

Constant which determines the return integer from the routine

Detailed Description

Macro Definition Documentation

◆ ROOTFIND_SUCCESS

◆ ROOTFIND_SUCCESS_XCONVERGENCEONLY

◆ ROOTFIND_FAILEDCONVERGENCE

◆ ROOTFIND_BADINPUT

◆ ROOTFIND_SOLNLOWERTHANXMIN

◆ ROOTFIND_SOLNHIGHERTHANXMAX

Function Documentation

◆ RootFind() [1/2]

◆ RootFind() [2/2]

◆ operator=()

◆ delXNonzero()

◆ delXMeaningful()

◆ deltaXControlled()

◆ theSame()

◆ solve()

◆ func()

◆ setTol()

◆ setPrintLvl()

◆ setFuncIsGenerallyIncreasing()

◆ setFuncIsGenerallyDecreasing()

◆ setDeltaX()

◆ setDeltaXMax()

◆ printTable()

Variable Documentation

◆ m_residFunc

◆ m_funcTargetValue

◆ m_atolf

◆ m_atolx

◆ m_rtolf

◆ m_rtolx

◆ m_maxstep

◆ printLvl

◆ writeLogAllowed_

◆ DeltaXnorm_

◆ specifiedDeltaXnorm_

◆ DeltaXMax_

◆ specifiedDeltaXMax_

◆ FuncIsGenerallyIncreasing_

◆ FuncIsGenerallyDecreasing_

◆ deltaXConverged_

◆ x_maxTried_

◆ fx_maxTried_

◆ x_minTried_

◆ fx_minTried_

◆ rfHistory_