Cantera  2.0
Classes | Public Member Functions | Public Attributes | Protected Attributes | Private Member Functions | List of all members
RootFind Class Reference

Root finder for 1D problems. More...

#include <RootFind.h>

Collaboration diagram for RootFind:
[legend]

Classes

struct  rfTable
 Structure containing the iteration history. More...
 

Public Member Functions

 RootFind (ResidEval *resid)
 Constructor for the object.
 
 RootFind (const RootFind &r)
 Copy constructor.
 
 ~RootFind ()
 Destructor. Deletes the integrator.
 
RootFindoperator= (const RootFind &right)
 Assignment operator.
 
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.
 

Public Attributes

ResidEvalm_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.
 
bool writeLogAllowed_
 Boolean to turn on the possibility of writing a log file.
 

Protected Attributes

int printLvl
 Print level.
 
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 rfTablerfHistory_
 Vector of iteration histories.
 

Private Member Functions

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.
 

Detailed Description

Root finder for 1D problems.

The root finder solves a single nonlinear equation described below.

\[ f(x) = f_0 \]

\( f(x) \) is assumed to be single valued as a function of x. \( f(x) \) is not assumed to be continuous nor is its derivative assumed to be well formed.

Root finders are significantly different in the sense that do not have to rely solely on Newton's method to find the answer to the problem. Instead they use a method to bound the solution between high and low values and then use a method to refine that bound. The eventual solution to the problem is presented as x_best and as a bound, delta_X, on the solution component. Because of this, they are far more stable for functions and Jacobians that have discontinuities or noise associated with them.

The algorithm is a convolution of a local Secant method with an approach of finding a straddle in x. The Jacobian is never required.

There is a general breakdown of the algorithm into stages. The first stage seeks to find a straddle of the function. The second stage seeks to reduce the bounds in x and f in order to satisfy the specification of the stopping criteria. In the last stage the algorithm seeks to find the base value of x that satisfies the original equation given what it current knows about the function.

Globalization strategy

Specifying the General Changes in x

Supplying Hints with General Function Behavior Flags

Stopping Criteria

Specification of the Stopping Criteria

Additional constraints

Bounds Criteria For the Routine

Example

// Define a residual. The definition of a residual involves a lot more work than is shown here.
ResidEval * ec;
// Instantiate the root finder with the residual to be solved, ec.
RootFind rf(&ec);
// Set the relative and absolute tolerancess for f and x.
rf.setTol(1.0E-5, 1.0E-10, 1.0E-5, 1.0E-11);
// Give a hint about the function's dependence on x. This is needed, for example, if the function has
// flat regions.
rf.setFuncIsGenerallyIncreasing(true);
rf.setDeltaX(0.01);
// Supply an initial guess for the solution
double xbest = phiM;
double oldP = printLvl_;
// Set the print level for the solver. Zero produces no output. Two produces a summary table of each iteration.
rf.setPrintLvl(2);
// Define a minimum and maximum for the independent variable.
double phimin = 1.3;
double phimax = 2.2;
// Define a maximum iteration number
int itmax = 100;
// Define the f_0 value, and on return will contain the actual value of f(x) obtained
double currentObtained;
// Call the solver
status = rf.solve(phimin, phimax, 100, currentObtained, &xbest);
if (status == 0) {
if (printLvl_ > 1) {
printf("Electrode::integrateConstantCurrent(): Volts (%g amps) = %g\n", currentObtained, xbest);
}
} else {
if (printLvl_) {
printf("Electrode::integrateConstantCurrent(): bad status = %d Volts (%g amps) = %g\n",
status, currentObtained, xbest);
}
}
Todo:

Noise

General Search to be done when all else fails

Definition at line 142 of file RootFind.h.


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