org.hipparchus.analysis.solvers

Interface BracketedUnivariateSolver<FUNC extends UnivariateFunction>

Type Parameters:

FUNC - Type of function to solve.

All Superinterfaces:

BaseUnivariateSolver<FUNC>

All Known Implementing Classes:

BaseSecantSolver, BracketingNthOrderBrentSolver, IllinoisSolver, PegasusSolver, RegulaFalsiSolver

public interface BracketedUnivariateSolver<FUNC extends UnivariateFunction>
extends BaseUnivariateSolver<FUNC>

Interface for (univariate real) root-finding algorithms that maintain a bracketed solution. There are several advantages to having such root-finding algorithms:

• The bracketed solution guarantees that the root is kept within the interval. As such, these algorithms generally also guarantee convergence.
• The bracketed solution means that we have the opportunity to only return roots that are greater than or equal to the actual root, or are less than or equal to the actual root. That is, we can control whether under-approximations and over-approximations are allowed solutions. Other root-finding algorithms can usually only guarantee that the solution (the root that was found) is around the actual root.

For backwards compatibility, all root-finding algorithms must have ANY_SIDE as default for the allowed solutions.

See Also:

AllowedSolution

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	BracketedUnivariateSolver.Interval An interval of a function that brackets a root.

Method Summary

Modifier and Type	Method and Description
double	solve(int maxEval, FUNC f, double min, double max, AllowedSolution allowedSolution) Solve for a zero in the given interval.
double	solve(int maxEval, FUNC f, double min, double max, double startValue, AllowedSolution allowedSolution) Solve for a zero in the given interval, start at startValue.
default BracketedUnivariateSolver.Interval	solveInterval(int maxEval, FUNC f, double min, double max) Solve for a zero in the given interval and return a tolerance interval surrounding the root.
BracketedUnivariateSolver.Interval	solveInterval(int maxEval, FUNC f, double min, double max, double startValue) Solve for a zero in the given interval and return a tolerance interval surrounding the root.

Methods inherited from interface org.hipparchus.analysis.solvers.BaseUnivariateSolver

getAbsoluteAccuracy, getEvaluations, getFunctionValueAccuracy, getMaxEvaluations, getRelativeAccuracy, solve, solve, solve

Method Detail

solve

double solve(int maxEval,
             FUNC f,
             double min,
             double max,
             AllowedSolution allowedSolution)

Solve for a zero 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.

Parameters:

maxEval - Maximum number of evaluations.

f - Function to solve.

min - Lower bound for the interval.

max - Upper bound for the interval.

allowedSolution - The kind of solutions that the root-finding algorithm may accept as solutions.

Returns:

A value where the function is zero.

Throws:

MathIllegalArgumentException - if the arguments do not satisfy the requirements specified by the solver.

MathIllegalStateException - if the allowed number of evaluations is exceeded.

solve

double solve(int maxEval,
             FUNC f,
             double min,
             double max,
             double startValue,
             AllowedSolution allowedSolution)

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.

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.

allowedSolution - The kind of solutions that the root-finding algorithm may accept as solutions.

Returns:

A value where the function is zero.

Throws:

MathIllegalArgumentException - if the arguments do not satisfy the requirements specified by the solver.

MathIllegalStateException - if the allowed number of evaluations is exceeded.

solveInterval

default BracketedUnivariateSolver.Interval solveInterval(int maxEval,
                                                         FUNC f,
                                                         double min,
                                                         double max)
                                                  throws MathIllegalArgumentException,
                                                         MathIllegalStateException

Solve for a zero in the given interval and return a tolerance interval surrounding the root.

It is required that the starting interval brackets a root or that the function value at either end point is 0.0.

Parameters:

maxEval - Maximum number of evaluations.

f - Function to solve.

min - Lower bound for the interval.

max - Upper bound for the interval. Must be greater than min.

Returns:

an interval [ta, tb] such that for some t in [ta, tb] f(t) == 0.0 or has a step wise discontinuity that crosses zero. Both end points also satisfy the convergence criteria so either one could be used as the root. That is the interval satisfies the condition (| tb - ta | <= absolute accuracy + max(ta, tb) * relative accuracy) or ( max(|f(ta)|, |f(tb)|) <= BaseUnivariateSolver.getFunctionValueAccuracy()) or there are no floating point numbers between ta and tb. The width of the interval (tb - ta) may be zero.

Throws:

MathIllegalArgumentException - if the arguments do not satisfy the requirements specified by the solver.

MathIllegalStateException - if the allowed number of evaluations is exceeded.

solveInterval

BracketedUnivariateSolver.Interval solveInterval(int maxEval,
                                                 FUNC f,
                                                 double min,
                                                 double max,
                                                 double startValue)
                                          throws MathIllegalArgumentException,
                                                 MathIllegalStateException

Solve for a zero in the given interval and return a tolerance interval surrounding the root.

It is required that the starting interval brackets a root or that the function value at either end point is 0.0.

Parameters:

maxEval - Maximum number of evaluations.

startValue - start value to use. Must be in the interval [min, max].

f - Function to solve.

min - Lower bound for the interval.

max - Upper bound for the interval. Must be greater than min.

Returns:

an interval [ta, tb] such that for some t in [ta, tb] f(t) == 0.0 or has a step wise discontinuity that crosses zero. Both end points also satisfy the convergence criteria so either one could be used as the root. That is the interval satisfies the condition (| tb - ta | <= absolute accuracy + max(ta, tb) * relative accuracy) or ( max(|f(ta)|, |f(tb)|) <= BaseUnivariateSolver.getFunctionValueAccuracy()) or there are no floating point numbers between ta and tb. The width of the interval (tb - ta) may be zero.

Throws:

MathIllegalArgumentException - if the arguments do not satisfy the requirements specified by the solver.

MathIllegalStateException - if the allowed number of evaluations is exceeded.