Apache Commons Math 3.6.1 · org.apache.commons.math3.analysis.solvers.UnivariateSolverUtils

Access	Constructor and Description
private	UnivariateSolverUtils() Class contains only static methods.

Method Summary

Modifier and Type	Method and Description
public static double[]	Returns: a two-element array holding a and b. bracket(UnivariateFunction Function. function, double Initial midpoint of interval being expanded to bracket a root. initial, double Lower bound (a is never lower than this value) lowerBound, double Upper bound (b never is greater than this value). upperBound) This method simply calls `bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations)` with `q` and `r` set to 1.0 and `maximumIterations` set to `Integer.MAX_VALUE`.
public static double[]	Returns: a two element array holding a and b. bracket(UnivariateFunction Function. function, double Initial midpoint of interval being expanded to bracket a root. initial, double Lower bound (a is never lower than this value). lowerBound, double Upper bound (b never is greater than this value). upperBound, int Maximum number of iterations to perform maximumIterations) This method simply calls `bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations)` with `q` and `r` set to 1.0.
public static double[]	Returns: a two element array holding the bracketing values. bracket(final UnivariateFunction function to check function, final double Initial midpoint of interval being expanded to bracket a root. initial, final double Lower bound (a is never lower than this value). lowerBound, final double Upper bound (b never is greater than this value). upperBound, final double additive offset used to compute bounds sequence (must be strictly positive) q, final double multiplicative factor used to compute bounds sequence r, final int Maximum number of iterations to perform maximumIterations) This method attempts to find two values a and b satisfying `lowerBound <= a < initial < b <= upperBound` `f(a) * f(b) <= 0`
public static double	Returns: a root approximation, on the specified side of the exact root forceSide(final int maximal number of new evaluations of the function (evaluations already done for finding the root should have already been subtracted from this number) maxEval, final UnivariateFunction function to solve f, final BracketedUnivariateSolver<UnivariateFunction> bracketing solver to use for shifting the root bracketing, final double original root found by a previous non-bracketing solver baseRoot, final double minimal bound of the search interval min, final double maximal bound of the search interval max, final AllowedSolution the kind of solutions that the root-finding algorithm may accept as solutions. allowedSolution) Force a root found by a non-bracketing solver to lie on a specified side, as if the solver were a bracketing one.
public static boolean	Returns: `true` if the function values have opposite signs at the given points. isBracketing(UnivariateFunction Function. function, final double Lower endpoint. lower, final double Upper endpoint. upper) Check whether the interval bounds bracket a root.
public static boolean	Returns: `true` if the arguments form an increasing sequence. isSequence(final double First number. start, final double Second number. mid, final double Third number. end) Check whether the arguments form a (strictly) increasing sequence.
public static double	Returns: the midpoint. midpoint(double first value. a, double second value. b) Compute the midpoint of two values.
public static double	Returns: a value where the function is zero. solve(UnivariateFunction Function. function, double Lower bound for the interval. x0, double Upper bound for the interval. x1) Convenience method to find a zero of a univariate real function.
public static double	Returns: a value where the function is zero. solve(UnivariateFunction Function. function, double Lower bound for the interval. x0, double Upper bound for the interval. x1, double Accuracy to be used by the solver. absoluteAccuracy) Convenience method to find a zero of a univariate real function.
public static void	verifyBracketing(UnivariateFunction Function. function, final double Lower endpoint. lower, final double Upper endpoint. upper) Check that the endpoints specify an interval and the end points bracket a root.
public static void	verifyInterval(final double Lower endpoint. lower, final double Upper endpoint. upper) Check that the endpoints specify an interval.
public static void	verifySequence(final double Lower endpoint. lower, final double Initial value. initial, final double Upper endpoint. upper) Check that `lower < initial < upper`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

UnivariateSolverUtils	back to summary
private UnivariateSolverUtils() Class contains only static methods.

Method Detail

bracket back to summary

bracket	back to summary
public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException This method simply calls `bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations)` with `q` and `r` set to 1.0 and `maximumIterations` set to `Integer.MAX_VALUE`. 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(function, initial, lowerBound, upperBound, q, r, maximumIterations)`, explicitly specifying the maximum number of iterations. Parameters function:UnivariateFunction Function. initial:double Initial midpoint of interval being expanded to bracket a root. lowerBound:double Lower bound (a is never lower than this value) upperBound:double Upper bound (b never is greater than this value). Returns:double[] a two-element array holding a and b. Exceptions NullArgumentException: if `function` is `null`. NotStrictlyPositiveException: if `maximumIterations <= 0`. NoBracketingException: if a root cannot be bracketted.

public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException

This method simply calls bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations) with q and r set to 1.0 and maximumIterations set to Integer.MAX_VALUE.

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(function, initial, lowerBound, upperBound, q, r, maximumIterations), explicitly specifying the maximum number of iterations.

Parameters

function:UnivariateFunction: Function.
initial:double: Initial midpoint of interval being expanded to bracket a root.
lowerBound:double: Lower bound (a is never lower than this value)
upperBound:double: Upper bound (b never is greater than this value).

Returns:double[]

a two-element array holding a and b.

Exceptions

NullArgumentException:: if function is null.
NotStrictlyPositiveException:: if maximumIterations <= 0.
NoBracketingException:: if a root cannot be bracketted.

bracket back to summary

bracket	back to summary
public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound, int maximumIterations) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException This method simply calls `bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations)` with `q` and `r` set to 1.0. Parameters function:UnivariateFunction Function. initial:double Initial midpoint of interval being expanded to bracket a root. lowerBound:double Lower bound (a is never lower than this value). upperBound:double Upper bound (b never is greater than this value). maximumIterations:int Maximum number of iterations to perform Returns:double[] a two element array holding a and b. Exceptions NullArgumentException: if `function` is `null`. NotStrictlyPositiveException: if `maximumIterations <= 0`. NoBracketingException: if the algorithm fails to find a and b satisfying the desired conditions.

public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound, int maximumIterations) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException

This method simply calls bracket(function, initial, lowerBound, upperBound, q, r, maximumIterations) with q and r set to 1.0.

Parameters

function:UnivariateFunction: Function.
initial:double: Initial midpoint of interval being expanded to bracket a root.
lowerBound:double: Lower bound (a is never lower than this value).
upperBound:double: Upper bound (b never is greater than this value).
maximumIterations:int: Maximum number of iterations to perform

Returns:double[]

a two element array holding a and b.

Exceptions

NullArgumentException:: if function is null.
NotStrictlyPositiveException:: if maximumIterations <= 0.
NoBracketingException:: if the algorithm fails to find a and b satisfying the desired conditions.

bracket back to summary

bracket	back to summary
public static double[] bracket(final UnivariateFunction function, final double initial, final double lowerBound, final double upperBound, final double q, final double r, final int maximumIterations) throws 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 checks the sign of \( f(l_k) \) and \( f(u_k) \) for increasing values of k, where \( l_k = max(lower, initial - \delta_k) \), \( u_k = min(upper, initial + \delta_k) \), using recurrence \( \delta_{k+1} = r \delta_k + q, \delta_0 = 0\) and starting search with \( k=1 \). The algorithm stops when one of the following happens: at least one positive and one negative value have been found -- success! both endpoints have reached their respective limits -- NoBracketingException `maximumIterations` iterations elapse -- NoBracketingException If different signs are found at first iteration (`k=1`), then the returned interval will be \( [a, b] = [l_1, u_1] \). If different signs are found at a later iteration `k>1`, then the returned interval will be either \( [a, b] = [l_{k+1}, l_{k}] \) or \( [a, b] = [u_{k}, u_{k+1}] \). A root solver called with these parameters will therefore start with the smallest bracketing interval known at this step. Interval expansion rate is tuned by changing the recurrence parameters `r` and `q`. When the multiplicative factor `r` is set to 1, the sequence is a simple arithmetic sequence with linear increase. When the multiplicative factor `r` is larger than 1, the sequence has an asymptotically exponential rate. Note than the additive parameter `q` should never be set to zero, otherwise the interval would degenerate to the single initial point for all values of `k`. As a rule of thumb, when the location of the root is expected to be approximately known within some error margin, `r` should be set to 1 and `q` should be set to the order of magnitude of the error margin. When the location of the root is really a wild guess, then `r` should be set to a value larger than 1 (typically 2 to double the interval length at each iteration) and `q` should be set according to half the initial search interval length. As an example, if we consider the trivial function `f(x) = 1 - x` and use `initial = 4`, `r = 1`, `q = 2`, the algorithm will compute `f(4-2) = f(2) = -1` and `f(4+2) = f(6) = -5` for `k = 1`, then `f(4-4) = f(0) = +1` and `f(4+4) = f(8) = -7` for `k = 2`. Then it will return the interval `[0, 2]` as the smallest one known to be bracketing the root. As shown by this example, the initial value (here `4`) may lie outside of the returned bracketing interval. Parameters function:UnivariateFunction function to check initial:double Initial midpoint of interval being expanded to bracket a root. lowerBound:double Lower bound (a is never lower than this value). upperBound:double Upper bound (b never is greater than this value). q:double additive offset used to compute bounds sequence (must be strictly positive) r:double multiplicative factor used to compute bounds sequence maximumIterations:int Maximum number of iterations to perform Returns:double[] a two element array holding the bracketing values. Exceptions NoBracketingException: if function cannot be bracketed in the search interval

public static double[] bracket(final UnivariateFunction function, final double initial, final double lowerBound, final double upperBound, final double q, final double r, final int maximumIterations) throws 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 checks the sign of \( f(l_k) \) and \( f(u_k) \) for increasing values of k, where \( l_k = max(lower, initial - \delta_k) \), \( u_k = min(upper, initial + \delta_k) \), using recurrence \( \delta_{k+1} = r \delta_k + q, \delta_0 = 0\) and starting search with \( k=1 \). The algorithm stops when one of the following happens:

at least one positive and one negative value have been found -- success!
both endpoints have reached their respective limits -- NoBracketingException
maximumIterations iterations elapse -- NoBracketingException

If different signs are found at first iteration (k=1), then the returned interval will be \( [a, b] = [l_1, u_1] \). If different signs are found at a later iteration k>1, then the returned interval will be either \( [a, b] = [l_{k+1}, l_{k}] \) or \( [a, b] = [u_{k}, u_{k+1}] \). A root solver called with these parameters will therefore start with the smallest bracketing interval known at this step.

Interval expansion rate is tuned by changing the recurrence parameters r and q. When the multiplicative factor r is set to 1, the sequence is a simple arithmetic sequence with linear increase. When the multiplicative factor r is larger than 1, the sequence has an asymptotically exponential rate. Note than the additive parameter q should never be set to zero, otherwise the interval would degenerate to the single initial point for all values of k.

As a rule of thumb, when the location of the root is expected to be approximately known within some error margin, r should be set to 1 and q should be set to the order of magnitude of the error margin. When the location of the root is really a wild guess, then r should be set to a value larger than 1 (typically 2 to double the interval length at each iteration) and q should be set according to half the initial search interval length.

As an example, if we consider the trivial function f(x) = 1 - x and use initial = 4, r = 1, q = 2, the algorithm will compute f(4-2) = f(2) = -1 and f(4+2) = f(6) = -5 for k = 1, then f(4-4) = f(0) = +1 and f(4+4) = f(8) = -7 for k = 2. Then it will return the interval [0, 2] as the smallest one known to be bracketing the root. As shown by this example, the initial value (here 4) may lie outside of the returned bracketing interval.

Parameters

function:UnivariateFunction: function to check
initial:double: Initial midpoint of interval being expanded to bracket a root.
lowerBound:double: Lower bound (a is never lower than this value).
upperBound:double: Upper bound (b never is greater than this value).
q:double: additive offset used to compute bounds sequence (must be strictly positive)
r:double: multiplicative factor used to compute bounds sequence
maximumIterations:int: Maximum number of iterations to perform

Returns:double[]

a two element array holding the bracketing values.

Exceptions

NoBracketingException:: if function cannot be bracketed in the search interval

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

forceSide

back to summary

public static double forceSide(final int maxEval, final UnivariateFunction f, final BracketedUnivariateSolver<UnivariateFunction> bracketing, final double baseRoot, final double min, final double max, final AllowedSolution allowedSolution) throws NoBracketingException

Force a root found by a non-bracketing solver to lie on a specified side, as if the solver were a bracketing one.

Parameters

maxEval:int: maximal number of new evaluations of the function (evaluations already done for finding the root should have already been subtracted from this number)
f:UnivariateFunction: function to solve
bracketing:BracketedUnivariateSolver<UnivariateFunction>: bracketing solver to use for shifting the root
baseRoot:double: original root found by a previous non-bracketing solver
min:double: minimal bound of the search interval
max:double: maximal bound of the search interval
allowedSolution:AllowedSolution: the kind of solutions that the root-finding algorithm may accept as solutions.

Returns:double

a root approximation, on the specified side of the exact root

Exceptions

NoBracketingException:: if the function has the same sign at the endpoints.

isBracketing back to summary

isBracketing	back to summary
public static boolean isBracketing(UnivariateFunction function, final double lower, final 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:UnivariateFunction Function. lower:double Lower endpoint. upper:double Upper endpoint. Returns:boolean `true` if the function values have opposite signs at the given points. Exceptions NullArgumentException: if `function` is `null`.

public static boolean isBracketing(UnivariateFunction function, final double lower, final 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:UnivariateFunction: Function.
lower:double: Lower endpoint.
upper:double: Upper endpoint.

Returns:boolean

true if the function values have opposite signs at the given points.

Exceptions

NullArgumentException:: if function is null.

isSequence back to summary

isSequence	back to summary
public static boolean isSequence(final double start, final double mid, final double end) Check whether the arguments form a (strictly) increasing sequence. Parameters start:double First number. mid:double Second number. end:double Third number. Returns:boolean `true` if the arguments form an increasing sequence.

public static boolean isSequence(final double start, final double mid, final double end)

Check whether the arguments form a (strictly) increasing sequence.

Parameters

start:double: First number.
mid:double: Second number.
end:double: Third number.

Returns:boolean

true if the arguments form an increasing sequence.

midpoint	back to summary
public static double midpoint(double a, double b) Compute the midpoint of two values. Parameters a:double first value. b:double second value. Returns:double the midpoint.

midpoint

back to summary

public static double midpoint(double a, double b)

Compute the midpoint of two values.

Parameters

a:double: first value.
b:double: second value.

Returns:double

the midpoint.

solve back to summary

solve	back to summary
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:UnivariateFunction Function. x0:double Lower bound for the interval. x1:double Upper bound for the interval. Returns:double a value where the function is zero. Exceptions NullArgumentException: if `function` is `null`. NoBracketingException: if the function has the same sign at the endpoints.

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:UnivariateFunction: Function.
x0:double: Lower bound for the interval.
x1:double: Upper bound for the interval.

Returns:double

a value where the function is zero.

Exceptions

NullArgumentException:: if function is null.
NoBracketingException:: if the function has the same sign at the endpoints.

solve back to summary

solve	back to summary
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:UnivariateFunction Function. x0:double Lower bound for the interval. x1:double Upper bound for the interval. absoluteAccuracy:double Accuracy to be used by the solver. Returns:double a value where the function is zero. Exceptions NullArgumentException: if `function` is `null`. NoBracketingException: if the function has the same sign at the endpoints.

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:UnivariateFunction: Function.
x0:double: Lower bound for the interval.
x1:double: Upper bound for the interval.
absoluteAccuracy:double: Accuracy to be used by the solver.

Returns:double

a value where the function is zero.

Exceptions

NullArgumentException:: if function is null.
NoBracketingException:: if the function has the same sign at the endpoints.

verifyBracketing back to summary

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

public static void verifyBracketing(UnivariateFunction function, final double lower, final double upper) throws NullArgumentException, NoBracketingException

Check that the endpoints specify an interval and the end points bracket a root.

Parameters

function:UnivariateFunction: Function.
lower:double: Lower endpoint.
upper:double: Upper endpoint.

Exceptions

NullArgumentException:: if function is null.
NoBracketingException:: if the function has the same sign at the endpoints.

verifyInterval back to summary

verifyInterval	back to summary
public static void verifyInterval(final double lower, final double upper) throws NumberIsTooLargeException Check that the endpoints specify an interval. Parameters lower:double Lower endpoint. upper:double Upper endpoint. Exceptions NumberIsTooLargeException: if `lower >= upper`.

public static void verifyInterval(final double lower, final double upper) throws NumberIsTooLargeException

Check that the endpoints specify an interval.

Parameters

lower:double: Lower endpoint.
upper:double: Upper endpoint.

Exceptions

NumberIsTooLargeException:: if lower >= upper.

verifySequence back to summary

verifySequence	back to summary
public static void verifySequence(final double lower, final double initial, final double upper) throws NumberIsTooLargeException Check that `lower < initial < upper`. Parameters lower:double Lower endpoint. initial:double Initial value. upper:double Upper endpoint. Exceptions NumberIsTooLargeException: if `lower >= initial` or `initial >= upper`.

public static void verifySequence(final double lower, final double initial, final double upper) throws NumberIsTooLargeException

Check that lower < initial < upper.

Parameters

lower:double: Lower endpoint.
initial:double: Initial value.
upper:double: Upper endpoint.

Exceptions

NumberIsTooLargeException:: if lower >= initial or initial >= upper.

public Class UnivariateSolverUtils

Constructor Summary

Method Summary

Constructor Detail

Method Detail