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