Cantera  2.0
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


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: