org.apache.commons.math3.analysis.solvers

## Class UnivariateSolverUtils

• java.lang.Object
• org.apache.commons.math3.analysis.solvers.UnivariateSolverUtils

• public class UnivariateSolverUtils
extends Object
Utility routines for UnivariateSolver objects.
Version:
$Id: UnivariateSolverUtils.java 1400850 2012-10-22 11:57:17Z erans$
• ### Method Summary

Methods
Modifier and Type Method and Description
static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound)
This method attempts to find two values a and b satisfying  lowerBound <= a < initial < b <= upperBound  f(a) * f(b) < 0  If f is continuous on [a,b], this means that a and b bracket a root of f.
static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound, int maximumIterations)
This method attempts to find two values a and b satisfying  lowerBound <= a < initial < b <= upperBound  f(a) * f(b) <= 0  If f is continuous on [a,b], this means that a and b bracket a root of f.
static double forceSide(int maxEval, UnivariateFunction f, BracketedUnivariateSolver<UnivariateFunction> bracketing, double baseRoot, double min, double max, AllowedSolution allowedSolution)
Force a root found by a non-bracketing solver to lie on a specified side, as if the solver was a bracketing one.
static boolean isBracketing(UnivariateFunction function, double lower, double upper)
Check whether the interval bounds bracket a root.
static boolean isSequence(double start, double mid, double end)
Check whether the arguments form a (strictly) increasing sequence.
static double midpoint(double a, double b)
Compute the midpoint of two values.
static double solve(UnivariateFunction function, double x0, double x1)
Convenience method to find a zero of a univariate real function.
static double solve(UnivariateFunction function, double x0, double x1, double absoluteAccuracy)
Convenience method to find a zero of a univariate real function.
static void verifyBracketing(UnivariateFunction function, double lower, double upper)
Check that the endpoints specify an interval and the end points bracket a root.
static void verifyInterval(double lower, double upper)
Check that the endpoints specify an interval.
static 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
• ### Method Detail

• #### solve

public static double solve(UnivariateFunction function,
double x0,
double x1)
throws NullArgumentException,
NoBracketingException
Convenience method to find a zero of a univariate real function. A default solver is used.
Parameters:
function - Function.
x0 - Lower bound for the interval.
x1 - Upper bound for the interval.
Returns:
a value where the function is zero.
Throws:
NoBracketingException - if the function has the same sign at the endpoints.
NullArgumentException - if function is null.
• #### solve

public static double solve(UnivariateFunction function,
double x0,
double x1,
double absoluteAccuracy)
throws NullArgumentException,
NoBracketingException
Convenience method to find a zero of a univariate real function. A default solver is used.
Parameters:
function - Function.
x0 - Lower bound for the interval.
x1 - Upper bound for the interval.
absoluteAccuracy - Accuracy to be used by the solver.
Returns:
a value where the function is zero.
Throws:
NoBracketingException - if the function has the same sign at the endpoints.
NullArgumentException - if function is null.
• #### forceSide

public static double forceSide(int maxEval,
UnivariateFunction f,
BracketedUnivariateSolver<UnivariateFunction> bracketing,
double baseRoot,
double min,
double max,
AllowedSolution allowedSolution)
throws NoBracketingException
Force a root found by a non-bracketing solver to lie on a specified side, as if the solver was a bracketing one.
Parameters:
maxEval - maximal number of new evaluations of the function (evaluations already done for finding the root should have already been subtracted from this number)
f - function to solve
bracketing - bracketing solver to use for shifting the root
baseRoot - original root found by a previous non-bracketing solver
min - minimal bound of the search interval
max - maximal bound of the search interval
allowedSolution - the kind of solutions that the root-finding algorithm may accept as solutions.
Returns:
a root approximation, on the specified side of the exact root
Throws:
NoBracketingException - if the function has the same sign at the endpoints.
• #### bracket

public static double[] bracket(UnivariateFunction function,
double initial,
double lowerBound,
double upperBound)
throws NullArgumentException,
NotStrictlyPositiveException,
NoBracketingException
This method attempts to find two values a and b satisfying
•  lowerBound <= a < initial < b <= upperBound
•  f(a) * f(b) < 0
If f is continuous on [a,b], this means that a and b bracket a root of f.

The algorithm starts by setting a := initial -1; b := initial +1, examines the value of the function at a and b and keeps moving the endpoints out by one unit each time through a loop that terminates when one of the following happens:

•  f(a) * f(b) < 0  -- success!
•  a = lower  and  b = upper -- NoBracketingException
•  Integer.MAX_VALUE iterations elapse -- NoBracketingException

Note: this method can take Integer.MAX_VALUE iterations to throw a ConvergenceException. Unless you are confident that there is a root between lowerBound and upperBound near initial, it is better to use bracket(UnivariateFunction, double, double, double, int), explicitly specifying the maximum number of iterations.

Parameters:
function - Function.
initial - Initial midpoint of interval being expanded to bracket a root.
lowerBound - Lower bound (a is never lower than this value)
upperBound - Upper bound (b never is greater than this value).
Returns:
a two-element array holding a and b.
Throws:
NoBracketingException - if a root cannot be bracketted.
NotStrictlyPositiveException - if maximumIterations <= 0.
NullArgumentException - if function is null.
• #### bracket

public static double[] bracket(UnivariateFunction function,
double initial,
double lowerBound,
double upperBound,
int maximumIterations)
throws NullArgumentException,
NotStrictlyPositiveException,
NoBracketingException
This method attempts to find two values a and b satisfying
•  lowerBound <= a < initial < b <= upperBound
•  f(a) * f(b) <= 0
If f is continuous on [a,b], this means that a and b bracket a root of f.

The algorithm starts by setting a := initial -1; b := initial +1, examines the value of the function at a and b and keeps moving the endpoints out by one unit each time through a loop that terminates when one of the following happens:

•  f(a) * f(b) <= 0  -- success!
•  a = lower  and  b = upper -- NoBracketingException
•  maximumIterations iterations elapse -- NoBracketingException

Parameters:
function - Function.
initial - Initial midpoint of interval being expanded to bracket a root.
lowerBound - Lower bound (a is never lower than this value).
upperBound - Upper bound (b never is greater than this value).
maximumIterations - Maximum number of iterations to perform
Returns:
a two element array holding a and b.
Throws:
NoBracketingException - if the algorithm fails to find a and b satisfying the desired conditions.
NotStrictlyPositiveException - if maximumIterations <= 0.
NullArgumentException - if function is null.
• #### midpoint

public static double midpoint(double a,
double b)
Compute the midpoint of two values.
Parameters:
a - first value.
b - second value.
Returns:
the midpoint.
• #### isBracketing

public static boolean isBracketing(UnivariateFunction function,
double lower,
double upper)
throws NullArgumentException
Check whether the interval bounds bracket a root. That is, if the values at the endpoints are not equal to zero, then the function takes opposite signs at the endpoints.
Parameters:
function - Function.
lower - Lower endpoint.
upper - Upper endpoint.
Returns:
true if the function values have opposite signs at the given points.
Throws:
NullArgumentException - if function is null.
• #### isSequence

public static 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

public static 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

public static 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

public static void verifyBracketing(UnivariateFunction function,
double lower,
double upper)
throws NullArgumentException,
NoBracketingException
Check that the endpoints specify an interval and the end points bracket a root.
Parameters:
function - Function.
lower - Lower endpoint.
upper - Upper endpoint.
Throws:
NoBracketingException - if the function has the same sign at the endpoints.
NullArgumentException - if function is null.