## org.apache.commons.math3.analysis.solvers
Class UnivariateSolverUtils

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

    public class UnivariateSolverUtils

extends java.lang.Object

Utility routines for `UnivariateSolver` objects.

Version:
  $Id: UnivariateSolverUtils.java 1400850 2012-10-22 11:57:17Z erans $

Constructor Summary
`private` `UnivariateSolverUtils()` Class contains only static methods.

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`

Constructor Detail

### UnivariateSolverUtils

    private UnivariateSolverUtils()

  Class contains only static methods.

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

Copyright (c) 2003-2013 Apache Software Foundation