Package 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. The default values for relative and function tolerances are 1e-14 and 1e-15, respectively. It is however highly recommended to not rely on the default, but rather carefully consider values that match user's expectations, as well as the specifics of each implementation.

Since:
  2.0

## Constructor Summary

Constructors
Modifier
Constructor
Description
`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

Modifier and Type
Method
Description
`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`

## Constructor Details

### 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 Details

### 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) throws NullArgumentException
Prepare for computation. Subclasses must call this method if they override any of the `solve` methods.

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.
Throws:
  `NullArgumentException` - if f is null

### 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.