fr.cnes.sirius.patrius.math.analysis.solver

Class UnivariateSolverUtils

java.lang.Object

fr.cnes.sirius.patrius.math.analysis.solver.UnivariateSolverUtils

public final class UnivariateSolverUtils
extends Object

Utility routines for UnivariateSolver objects.

Version:

$Id: UnivariateSolverUtils.java 18108 2017-10-04 06:45:27Z bignon $

Method Summary

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	verifyIntervalStrict(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.
static void	verifySequenceStrict(double lower, double initial, double upper) Check that lower <= initial <= upper & lower < 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)

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)

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)

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)

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)

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)

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)

Check that the endpoints specify an interval.

Parameters:

lower - Lower endpoint.

upper - Upper endpoint.

Throws:

NumberIsTooLargeException - if lower >= upper.

verifyIntervalStrict

public static void verifyIntervalStrict(double lower,
                                        double upper)

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)

Check that lower < initial < upper.

Parameters:

lower - Lower endpoint.

initial - Initial value.

upper - Upper endpoint.

Throws:

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

verifySequenceStrict

public static void verifySequenceStrict(double lower,
                                        double initial,
                                        double upper)

Check that lower <= initial <= upper & lower < upper.

Parameters:

lower - Lower endpoint.

initial - Initial value.

upper - Upper endpoint.

Throws:

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

verifyBracketing

public static void verifyBracketing(UnivariateFunction function,
                                    double lower,
                                    double upper)

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.