org.apache.commons.math3.analysis.solvers

## Class BaseAbstractUnivariateSolver<FUNC extends UnivariateFunction>

- java.lang.Object
- - org.apache.commons.math3.analysis.solvers.BaseAbstractUnivariateSolver<FUNC>

Type Parameters:
  `FUNC` - Type of function to solve.

All Implemented Interfaces:
  BaseUnivariateSolver<FUNC>

Direct Known Subclasses:
  AbstractDifferentiableUnivariateSolver, AbstractPolynomialSolver, AbstractUnivariateDifferentiableSolver, AbstractUnivariateSolver

    public abstract class BaseAbstractUnivariateSolver<FUNC extends UnivariateFunction>
    extends Object
    implements BaseUnivariateSolver<FUNC>

Provide a default implementation for several functions useful to generic solvers.

Since:
  2.0
Version:
  $Id: BaseAbstractUnivariateSolver.java 1391927 2012-09-30 00:03:30Z erans $

### Field Summary

Fields
`private double` `absoluteAccuracy` Absolute accuracy.
`private static double` `DEFAULT_FUNCTION_VALUE_ACCURACY` Default function value accuracy.
`private static double` `DEFAULT_RELATIVE_ACCURACY` Default relative accuracy.
`private Incrementor` `evaluations` Evaluations counter.
`private FUNC` `function` Function to solve.
`private double` `functionValueAccuracy` Function value accuracy.
`private double` `relativeAccuracy` Relative accuracy.
`private double` `searchMax` Higher end of search interval.
`private double` `searchMin` Lower end of search interval.
`private double` `searchStart` Initial guess.

### Constructor Summary

Constructors
`protected` `BaseAbstractUnivariateSolver(double absoluteAccuracy)` Construct a solver with given absolute accuracy.
`protected` `BaseAbstractUnivariateSolver(double relativeAccuracy, double absoluteAccuracy)` Construct a solver with given accuracies.
`protected` `BaseAbstractUnivariateSolver(double relativeAccuracy, double absoluteAccuracy, double functionValueAccuracy)` Construct a solver with given accuracies.

### Method Summary

Methods
`protected double` `computeObjectiveValue(double point)` Compute the objective function value.
`protected abstract double` `doSolve()` Method for implementing actual optimization algorithms in derived classes.
`double` `getAbsoluteAccuracy()` Get the absolute accuracy of the solver.
`int` `getEvaluations()` Get the number of evaluations of the objective function.
`double` `getFunctionValueAccuracy()` Get the function value accuracy of the solver.
`double` `getMax()`
`int` `getMaxEvaluations()` Get the maximum number of function evaluations.
`double` `getMin()`
`double` `getRelativeAccuracy()` Get the relative accuracy of the solver.
`double` `getStartValue()`
`protected void` `incrementEvaluationCount()` Increment the evaluation count by one.
`protected boolean` `isBracketing(double lower, double upper)` Check whether the function takes opposite signs at the endpoints.
`protected boolean` `isSequence(double start, double mid, double end)` Check whether the arguments form a (strictly) increasing sequence.
`protected void` `setup(int maxEval, FUNC f, double min, double max, double startValue)` Prepare for computation.
`double` `solve(int maxEval, FUNC f, double startValue)` Solve for a zero in the vicinity of `startValue`.
`double` `solve(int maxEval, FUNC f, double min, double max)` Solve for a zero root in the given interval.
`double` `solve(int maxEval, FUNC f, double min, double max, double startValue)` Solve for a zero in the given interval, start at `startValue`.
`protected void` `verifyBracketing(double lower, double upper)` Check that the endpoints specify an interval and the function takes opposite signs at the endpoints.
`protected void` `verifyInterval(double lower, double upper)` Check that the endpoints specify an interval.
`protected void` `verifySequence(double lower, double initial, double upper)` Check that `lower < initial < upper`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### DEFAULT_RELATIVE_ACCURACY

    private static final double DEFAULT_RELATIVE_ACCURACY

Default relative accuracy.

See Also:
  Constant Field Values

#### DEFAULT_FUNCTION_VALUE_ACCURACY

    private static final double DEFAULT_FUNCTION_VALUE_ACCURACY

Default function value accuracy.

See Also:
  Constant Field Values

#### functionValueAccuracy

    private final double functionValueAccuracy

Function value accuracy.

#### absoluteAccuracy

    private final double absoluteAccuracy

Absolute accuracy.

#### relativeAccuracy

    private final double relativeAccuracy

Relative accuracy.

#### evaluations

    private final Incrementor evaluations

Evaluations counter.

#### searchMin

    private double searchMin

Lower end of search interval.

#### searchMax

    private double searchMax

Higher end of search interval.

#### searchStart

    private double searchStart

Initial guess.

#### function

    private FUNC extends UnivariateFunction function

Function to solve.

### Constructor Detail

#### BaseAbstractUnivariateSolver

    protected BaseAbstractUnivariateSolver(double absoluteAccuracy)

Construct a solver with given absolute accuracy.

Parameters:
  `absoluteAccuracy` - Maximum absolute error.

#### BaseAbstractUnivariateSolver

    protected BaseAbstractUnivariateSolver(double relativeAccuracy,
                                double absoluteAccuracy)

Construct a solver with given accuracies.

Parameters:
  `relativeAccuracy` - Maximum relative error.
  `absoluteAccuracy` - Maximum absolute error.

#### BaseAbstractUnivariateSolver

    protected BaseAbstractUnivariateSolver(double relativeAccuracy,
                                double absoluteAccuracy,
                                double functionValueAccuracy)

Construct a solver with given accuracies.

Parameters:
  `relativeAccuracy` - Maximum relative error.
  `absoluteAccuracy` - Maximum absolute error.
  `functionValueAccuracy` - Maximum function value error.

### Method Detail

#### getMaxEvaluations

    public int getMaxEvaluations()

Get the maximum number of function evaluations.

Specified by:
  `getMaxEvaluations` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Returns:
  the maximum number of function evaluations.

#### getEvaluations

    public int getEvaluations()

Get the number of evaluations of the objective function. The number of evaluations corresponds to the last call to the `optimize` method. It is 0 if the method has not been called yet.

Specified by:
  `getEvaluations` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Returns:
  the number of evaluations of the objective function.

#### getMin

    public double getMin()

Returns:
  the lower end of the search interval.

#### getMax

    public double getMax()

Returns:
  the higher end of the search interval.

#### getStartValue

    public double getStartValue()

Returns:
  the initial guess.

#### getAbsoluteAccuracy

    public double getAbsoluteAccuracy()

Get the absolute accuracy of the solver. Solutions returned by the solver should be accurate to this tolerance, i.e., if ε is the absolute accuracy of the solver and `v` is a value returned by one of the `solve` methods, then a root of the function should exist somewhere in the interval (`v` - ε, `v` + ε).

Specified by:
  `getAbsoluteAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Returns:
  the absolute accuracy.

#### getRelativeAccuracy

    public double getRelativeAccuracy()

Get the relative accuracy of the solver. The contract for relative accuracy is the same as `BaseUnivariateSolver.getAbsoluteAccuracy()`, but using relative, rather than absolute error. If ρ is the relative accuracy configured for a solver and `v` is a value returned, then a root of the function should exist somewhere in the interval (`v` - ρ `v`, `v` + ρ `v`).

Specified by:
  `getRelativeAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Returns:
  the relative accuracy.

#### getFunctionValueAccuracy

    public double getFunctionValueAccuracy()

Get the function value accuracy of the solver. If `v` is a value returned by the solver for a function `f`, then by contract, `|f(v)|` should be less than or equal to the function value accuracy configured for the solver.

Specified by:
  `getFunctionValueAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Returns:
  the function value accuracy.

#### computeObjectiveValue

    protected double computeObjectiveValue(double point)
                                    throws TooManyEvaluationsException

Compute the objective function value.

Parameters:
  `point` - Point at which the objective function must be evaluated.
Returns:
  the objective function value at specified point.
Throws:
  `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.

#### setup

    protected void setup(int maxEval,
             FUNC f,
             double min,
             double max,
             double startValue)

Prepare for computation. Subclasses must call this method if they override any of the `solve` methods.

Parameters:
  `f` - Function to solve.
  `min` - Lower bound for the interval.
  `max` - Upper bound for the interval.
  `startValue` - Start value to use.
  `maxEval` - Maximum number of evaluations.

#### solve

    public double solve(int maxEval,
               FUNC f,
               double min,
               double max,
               double startValue)
                 throws TooManyEvaluationsException,
                        NoBracketingException

Solve for a zero in the given interval, start at `startValue`. A solver may require that the interval brackets a single zero root. Solvers that do require bracketing should be able to handle the case where one of the endpoints is itself a root.

Specified by:
  `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Parameters:
  `maxEval` - Maximum number of evaluations.
  `f` - Function to solve.
  `min` - Lower bound for the interval.
  `max` - Upper bound for the interval.
  `startValue` - Start value to use.
Returns:
  a value where the function is zero.
Throws:
  `TooManyEvaluationsException` - if the allowed number of evaluations is exceeded.
  `NoBracketingException`

#### solve

    public double solve(int maxEval,
               FUNC f,
               double min,
               double max)

Solve for a zero root in the given interval. A solver may require that the interval brackets a single zero root. Solvers that do require bracketing should be able to handle the case where one of the endpoints is itself a root.

Specified by:
  `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Parameters:
  `maxEval` - Maximum number of evaluations.
  `f` - Function to solve.
  `min` - Lower bound for the interval.
  `max` - Upper bound for the interval.
Returns:
  a value where the function is zero.

#### solve

    public double solve(int maxEval,
               FUNC f,
               double startValue)
                 throws TooManyEvaluationsException,
                        NoBracketingException

Solve for a zero in the vicinity of `startValue`.

Specified by:
  `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
Parameters:
  `maxEval` - Maximum number of evaluations.
  `f` - Function to solve.
  `startValue` - Start value to use.
Returns:
  a value where the function is zero.
Throws:
  `TooManyEvaluationsException` - if the allowed number of evaluations is exceeded.
  `NoBracketingException`

#### doSolve

    protected abstract double doSolve()
                               throws TooManyEvaluationsException,
                                      NoBracketingException

Method for implementing actual optimization algorithms in derived classes.

Returns:
  the root.
Throws:
  `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
  `NoBracketingException` - if the initial search interval does not bracket a root and the solver requires it.

#### isBracketing

    protected boolean isBracketing(double lower,
                       double upper)

Check whether the function takes opposite signs at the endpoints.

Parameters:
  `lower` - Lower endpoint.
  `upper` - Upper endpoint.
Returns:
  `true` if the function values have opposite signs at the given points.

#### isSequence

    protected boolean isSequence(double start,
                     double mid,
                     double end)

Check whether the arguments form a (strictly) increasing sequence.

Parameters:
  `start` - First number.
  `mid` - Second number.
  `end` - Third number.
Returns:
  `true` if the arguments form an increasing sequence.

#### verifyInterval

    protected void verifyInterval(double lower,
                      double upper)
                           throws NumberIsTooLargeException

Check that the endpoints specify an interval.

Parameters:
  `lower` - Lower endpoint.
  `upper` - Upper endpoint.
Throws:
  `NumberIsTooLargeException` - if `lower >= upper`.

#### verifySequence

    protected void verifySequence(double lower,
                      double initial,
                      double upper)
                           throws NumberIsTooLargeException

Check that `lower < initial < upper`.

Parameters:
  `lower` - Lower endpoint.
  `initial` - Initial value.
  `upper` - Upper endpoint.
Throws:
  `NumberIsTooLargeException` - if `lower >= initial` or `initial >= upper`.

#### verifyBracketing

    protected void verifyBracketing(double lower,
                        double upper)
                             throws NullArgumentException,
                                    NoBracketingException

Check that the endpoints specify an interval and the function takes opposite signs at the endpoints.

Parameters:
  `lower` - Lower endpoint.
  `upper` - Upper endpoint.
Throws:
  `NullArgumentException` - if the function has not been set.
  `NoBracketingException` - if the function has the same sign at the endpoints.

#### incrementEvaluationCount

    protected void incrementEvaluationCount()
                                     throws TooManyEvaluationsException

Increment the evaluation count by one. Method `computeObjectiveValue(double)` calls this method internally. It is provided for subclasses that do not exclusively use `computeObjectiveValue` to solve the function. See e.g. `AbstractUnivariateDifferentiableSolver`.

Throws:
  `TooManyEvaluationsException` - when the allowed number of function evaluations has been exhausted.