## 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 java.lang.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
`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
`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
`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.

Copyright (c) 2003-2013 Apache Software Foundation