Cantera  2.0
Classes | Functions | Variables
Solvers for Equation Systems

Classes

class  RootFind
 Root finder for 1D problems. More...
 
struct  RootFind::rfTable
 Structure containing the iteration history. More...
 
class  solveProb
 Method to solve a pseudo steady state of a nonlinear problem. More...
 

Functions

 RootFind (ResidEval *resid)
 Constructor for the object.
 
 RootFind (const RootFind &r)
 Copy constructor.
 
 ~RootFind ()
 Destructor. Deletes the integrator.
 
RootFind & operator= (const RootFind &right)
 Assignment operator.
 
doublereal delXNonzero (doublereal x1) const
 Calculate a deltaX from an input value of x.
 
doublereal delXMeaningful (doublereal x1) const
 Calculate a deltaX from an input value of x.
 
doublereal deltaXControlled (doublereal x2, doublereal x1) const
 Calculate a controlled, nonzero delta between two numbers.
 
bool theSame (doublereal x2, doublereal x1, doublereal factor=1.0) const
 Function to decide whether two real numbers are the same or not.
 
int solve (doublereal xmin, doublereal xmax, int itmax, doublereal &funcTargetValue, doublereal *xbest)
 Using a line search method, find the root of a 1D function.
 
doublereal func (doublereal x)
 Return the function value.
 
void setTol (doublereal rtolf, doublereal atolf, doublereal rtolx=0.0, doublereal atolx=0.0)
 Set the tolerance parameters for the rootfinder.
 
void setPrintLvl (int printLvl)
 Set the print level from the rootfinder.
 
void setFuncIsGenerallyIncreasing (bool value)
 Set the function behavior flag.
 
void setFuncIsGenerallyDecreasing (bool value)
 Set the function behavior flag.
 
void setDeltaX (doublereal deltaXNorm)
 Set the minimum value of deltaX.
 
void setDeltaXMax (doublereal deltaX)
 Set the maximum value of deltaX.
 
void printTable ()
 Print the iteration history table.
 

Variables

ResidEval * m_residFunc
 Pointer to the residual function evaluator.
 
doublereal m_funcTargetValue
 Target value for the function. We seek the value of f that is equal to this value.
 
doublereal m_atolf
 Absolute tolerance for the value of f.
 
doublereal m_atolx
 Absolute tolerance for the value of x.
 
doublereal m_rtolf
 Relative tolerance for the value of f and x.
 
doublereal m_rtolx
 Relative tolerance for the value of x.
 
doublereal m_maxstep
 Maximum number of step sizes.
 
int printLvl
 Print level.
 
bool writeLogAllowed_
 Boolean to turn on the possibility of writing a log file.
 
doublereal DeltaXnorm_
 Delta X norm. This is the nominal value of deltaX that will be used by the program.
 
int specifiedDeltaXnorm_
 Boolean indicating whether DeltaXnorm_ has been specified by the user or not.
 
doublereal DeltaXMax_
 Delta X Max. This is the maximum value of deltaX that will be used by the program.
 
int specifiedDeltaXMax_
 Boolean indicating whether DeltaXMax_ has been specified by the user or not.
 
bool FuncIsGenerallyIncreasing_
 Boolean indicating whether the function is an increasing with x.
 
bool FuncIsGenerallyDecreasing_
 Boolean indicating whether the function is decreasing with x.
 
doublereal deltaXConverged_
 Value of delta X that is needed for convergence.
 
doublereal x_maxTried_
 Internal variable tracking largest x tried.
 
doublereal fx_maxTried_
 Internal variable tracking f(x) of largest x tried.
 
doublereal x_minTried_
 Internal variable tracking smallest x tried.
 
doublereal fx_minTried_
 Internal variable tracking f(x) of smallest x tried.
 
std::vector< struct rfTable > rfHistory_
 Vector of iteration histories.
 

Constant which determines the return integer from the routine

#define ROOTFIND_SUCCESS   0
 This means that the root solver was a success.
 
#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.
 
#define ROOTFIND_FAILEDCONVERGENCE   -1
 This means that the root solver failed to achieve convergence.
 
#define ROOTFIND_BADINPUT   -2
 This means that the input to the root solver was defective.
 
#define ROOTFIND_SOLNLOWERTHANXMIN   -3
 This means that the rootfinder believes the solution is lower than xmin.
 
#define ROOTFIND_SOLNHIGHERTHANXMAX   -4
 This means that the rootfinder believes the solution is higher than xmax.
 
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

#define ROOTFIND_SUCCESS   0

This means that the root solver was a success.

Definition at line 30 of file RootFind.h.

Referenced by RedlichKwongMFTP::densSpinodalGas(), RedlichKwongMFTP::densSpinodalLiquid(), and RootFind::solve().

#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 38 of file RootFind.h.

Referenced by RootFind::solve().

#define ROOTFIND_FAILEDCONVERGENCE   -1

This means that the root solver failed to achieve convergence.

Definition at line 40 of file RootFind.h.

Referenced by RootFind::solve().

#define ROOTFIND_BADINPUT   -2

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

Definition at line 42 of file RootFind.h.

Referenced by RootFind::solve().

#define ROOTFIND_SOLNLOWERTHANXMIN   -3

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

Definition at line 44 of file RootFind.h.

Referenced by RootFind::solve().

#define ROOTFIND_SOLNHIGHERTHANXMAX   -4

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

Definition at line 49 of file RootFind.h.

Referenced by RootFind::solve().

Function Documentation

RootFind ( ResidEval resid)

Constructor for the object.

Parameters
residPointer to the residual function to be used to calculate f(x)

Definition at line 71 of file RootFind.cpp.

RootFind ( const RootFind r)

Copy constructor.

Parameters
robject to be copied

Definition at line 96 of file RootFind.cpp.

~RootFind ( )

Destructor. Deletes the integrator.

Definition at line 122 of file RootFind.cpp.

RootFind & operator= ( const RootFind right)
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
x1input value of x

Definition at line 162 of file RootFind.cpp.

References RootFind::DeltaXnorm_.

Referenced by RootFind::deltaXControlled(), and RootFind::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
x1input value of x

Definition at line 179 of file RootFind.cpp.

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

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

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
x2first number
x1second number

Definition at line 197 of file RootFind.cpp.

References RootFind::delXNonzero().

Referenced by RootFind::solve().

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
x1First number
x2second number
factorMultiplicative factor to multiple deltaX with
Returns
Returns a boolean indicating whether the two numbers are the same or not.

Definition at line 223 of file RootFind.cpp.

References RootFind::delXMeaningful(), and ckr::max().

Referenced by RootFind::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
xminMinimum value of x to be used.
xmaxMaximum value of x to be used
itmaxmaximum number of iterations. Usually, it can be less than 50.
funcTargetValueValue of \( f_o \) in the equation. On return, it contains the value of the function actually obtained.
xbestReturns 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 245 of file RootFind.cpp.

References AssertThrow, RootFind::deltaXControlled(), RootFind::deltaXConverged_, RootFind::DeltaXMax_, RootFind::DeltaXnorm_, RootFind::delXMeaningful(), Cantera::fp2str(), RootFind::func(), RootFind::FuncIsGenerallyDecreasing_, RootFind::FuncIsGenerallyIncreasing_, RootFind::m_atolf, RootFind::m_atolx, RootFind::m_funcTargetValue, RootFind::m_rtolf, RootFind::m_rtolx, ckr::max(), ckr::min(), Cantera::print_funcEval(), RootFind::printLvl, RootFind::printTable(), RootFind::rfHistory_, ROOTFIND_BADINPUT, ROOTFIND_FAILEDCONVERGENCE, ROOTFIND_SOLNHIGHERTHANXMAX, ROOTFIND_SOLNLOWERTHANXMIN, ROOTFIND_SUCCESS, ROOTFIND_SUCCESS_XCONVERGENCEONLY, RootFind::specifiedDeltaXMax_, RootFind::specifiedDeltaXnorm_, RootFind::theSame(), Cantera::writelog(), RootFind::writeLogAllowed_, Cantera::writelogf(), RootFind::x_maxTried_, and RootFind::x_minTried_.

Referenced by RedlichKwongMFTP::densSpinodalGas(), and RedlichKwongMFTP::densSpinodalLiquid().

doublereal func ( doublereal  x)

Return the function value.

This routine evaluates the following equation.

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

Parameters
xValue of the independent variable
Returns
The routine returns the value of \( R(x) \)

Definition at line 1182 of file RootFind.cpp.

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

Referenced by RootFind::solve().

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
rtolfRelative tolerance. The default is 10^-5
atolfabsolute tolerance. The default is 10^-11
rtolxRelative tolerance. The default is 10^-5 Default parameter is 0.0, in which case rtolx is set equal to rtolf
atolxabsolute tolerance. The default is 10^-11 Default parameter is 0.0, in which case atolx is set equal to atolf

Definition at line 1212 of file RootFind.cpp.

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

Referenced by RedlichKwongMFTP::densSpinodalGas(), and RedlichKwongMFTP::densSpinodalLiquid().

void setPrintLvl ( int  printLvl)

Set the print level from the rootfinder.

0 -> absolutely nothing is printed for a single time step. 1 -> One line summary per solve_nonlinear call 2 -> short description, points of interest: Table of nonlinear solve - one line per iteration 3 -> Table is included -> More printing per nonlinear iteration (default) that occurs during the table 4 -> Summaries of the nonlinear solve iteration as they are occurring -> table no longer printed 5 -> Algorithm information on the nonlinear iterates are printed out 6 -> Additional info on the nonlinear iterates are printed out 7 -> Additional info on the linear solve is printed out. 8 -> Info on a per iterate of the linear solve is printed out.

Parameters
printLvlinteger value

Definition at line 1243 of file RootFind.cpp.

References RootFind::printLvl.

Referenced by RedlichKwongMFTP::densSpinodalGas(), and RedlichKwongMFTP::densSpinodalLiquid().

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
valueboolean value

Definition at line 1259 of file RootFind.cpp.

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

Referenced by RedlichKwongMFTP::densSpinodalGas().

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
valueboolean value

Definition at line 1278 of file RootFind.cpp.

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

Referenced by RedlichKwongMFTP::densSpinodalLiquid().

void setDeltaX ( doublereal  deltaXNorm)

Set the minimum value of deltaX.

This sets the value of deltaXNorm_

Parameters
deltaXNorm

Definition at line 1292 of file RootFind.cpp.

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

void setDeltaXMax ( doublereal  deltaX)

Set the maximum value of deltaX.

This sets the value of deltaXMax_

Parameters
deltaX

Definition at line 1304 of file RootFind.cpp.

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

void printTable ( )

Print the iteration history table.

Definition at line 1312 of file RootFind.cpp.

References RootFind::m_funcTargetValue, and RootFind::rfHistory_.

Referenced by RootFind::solve().

Variable Documentation

ResidEval* m_residFunc

Pointer to the residual function evaluator.

Definition at line 338 of file RootFind.h.

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

doublereal m_funcTargetValue

Target value for the function. We seek the value of f that is equal to this value.

Definition at line 341 of file RootFind.h.

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

doublereal m_atolf

Absolute tolerance for the value of f.

Definition at line 344 of file RootFind.h.

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

doublereal m_atolx

Absolute tolerance for the value of x.

Definition at line 347 of file RootFind.h.

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

doublereal m_rtolf

Relative tolerance for the value of f and x.

Definition at line 350 of file RootFind.h.

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

doublereal m_rtolx

Relative tolerance for the value of x.

Definition at line 353 of file RootFind.h.

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

doublereal m_maxstep

Maximum number of step sizes.

Definition at line 356 of file RootFind.h.

Referenced by RootFind::operator=().

int printLvl
protected

Print level.

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.

Definition at line 368 of file RootFind.h.

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

bool writeLogAllowed_

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

Definition at line 373 of file RootFind.h.

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

doublereal DeltaXnorm_
protected

Delta X norm. This is the nominal value of deltaX that will be used by the program.

Definition at line 377 of file RootFind.h.

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

int specifiedDeltaXnorm_
protected

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

Definition at line 380 of file RootFind.h.

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

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 386 of file RootFind.h.

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

int specifiedDeltaXMax_
protected

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

Definition at line 389 of file RootFind.h.

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

bool FuncIsGenerallyIncreasing_
protected

Boolean indicating whether the function is an increasing with x.

Definition at line 392 of file RootFind.h.

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

bool FuncIsGenerallyDecreasing_
protected

Boolean indicating whether the function is decreasing with x.

Definition at line 395 of file RootFind.h.

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

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 402 of file RootFind.h.

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

doublereal x_maxTried_
protected

Internal variable tracking largest x tried.

Definition at line 405 of file RootFind.h.

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

doublereal fx_maxTried_
protected

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

Definition at line 408 of file RootFind.h.

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

doublereal x_minTried_
protected

Internal variable tracking smallest x tried.

Definition at line 411 of file RootFind.h.

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

doublereal fx_minTried_
protected

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

Definition at line 414 of file RootFind.h.

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

std::vector<struct rfTable> rfHistory_
protected

Vector of iteration histories.

Definition at line 462 of file RootFind.h.

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