org.apache.commons.math.analysis.solvers

## Class UnivariateRealSolverUtils

- java.lang.Object
- - org.apache.commons.math.analysis.solvers.UnivariateRealSolverUtils

    public class UnivariateRealSolverUtils
    extends Object

Utility routines for `UnivariateRealSolver` objects.

Version:
  $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $

### Nested Class Summary

Nested Classes
`private static class` `UnivariateRealSolverUtils.LazyHolder` Holder for the factory.

### Constructor Summary

Constructors
`private` `UnivariateRealSolverUtils()` Default constructor.

### Method Summary

Methods
`static double[]` `bracket(UnivariateRealFunction 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(UnivariateRealFunction 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` `midpoint(double a, double b)` Compute the midpoint of two values.
`private static void` `setup(UnivariateRealFunction f)` Checks to see if f is null, throwing IllegalArgumentException if so.
`static double` `solve(UnivariateRealFunction f, double x0, double x1)` Convenience method to find a zero of a univariate real function.
`static double` `solve(UnivariateRealFunction f, double x0, double x1, double absoluteAccuracy)` Convenience method to find a zero of a univariate real function.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### UnivariateRealSolverUtils

    private UnivariateRealSolverUtils()

Default constructor.

### Method Detail

#### solve

    public static double solve(UnivariateRealFunction f,
               double x0,
               double x1)
                        throws ConvergenceException,
                               FunctionEvaluationException

Convenience method to find a zero of a univariate real function. A default solver is used.

Parameters:
  `f` - the function.
  `x0` - the lower bound for the interval.
  `x1` - the upper bound for the interval.
Returns:
  a value where the function is zero.
Throws:
  `ConvergenceException` - if the iteration count was exceeded
  `FunctionEvaluationException` - if an error occurs evaluating the function
  `IllegalArgumentException` - if f is null or the endpoints do not specify a valid interval

#### solve

    public static double solve(UnivariateRealFunction f,
               double x0,
               double x1,
               double absoluteAccuracy)
                        throws ConvergenceException,
                               FunctionEvaluationException

Convenience method to find a zero of a univariate real function. A default solver is used.

Parameters:
  `f` - the function
  `x0` - the lower bound for the interval
  `x1` - the upper bound for the interval
  `absoluteAccuracy` - the accuracy to be used by the solver
Returns:
  a value where the function is zero
Throws:
  `ConvergenceException` - if the iteration count is exceeded
  `FunctionEvaluationException` - if an error occurs evaluating the function
  `IllegalArgumentException` - if f is null, the endpoints do not specify a valid interval, or the absoluteAccuracy is not valid for the default solver

#### bracket

    public static double[] bracket(UnivariateRealFunction function,
                   double initial,
                   double lowerBound,
                   double upperBound)
                            throws ConvergenceException,
                                   FunctionEvaluationException

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` -- ConvergenceException
- `Integer.MAX_VALUE` iterations elapse -- ConvergenceException

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(UnivariateRealFunction, double, double, double, int)`, explicitly specifying the maximum number of iterations.

Parameters:
  `function` - the 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, b}
Throws:
  `ConvergenceException` - if a root can not be bracketted
  `FunctionEvaluationException` - if an error occurs evaluating the function
  `IllegalArgumentException` - if function is null, maximumIterations is not positive, or initial is not between lowerBound and upperBound

#### bracket

    public static double[] bracket(UnivariateRealFunction function,
                   double initial,
                   double lowerBound,
                   double upperBound,
                   int maximumIterations)
                            throws ConvergenceException,
                                   FunctionEvaluationException

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` -- ConvergenceException
- `maximumIterations` iterations elapse -- ConvergenceException

Parameters:
  `function` - the 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, b}.
Throws:
  `ConvergenceException` - if the algorithm fails to find a and b satisfying the desired conditions
  `FunctionEvaluationException` - if an error occurs evaluating the function
  `IllegalArgumentException` - if function is null, maximumIterations is not positive, or initial is not between lowerBound and upperBound

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

#### setup

    private static void setup(UnivariateRealFunction f)

Checks to see if f is null, throwing IllegalArgumentException if so.

Parameters:
  `f` - input function
Throws:
  `IllegalArgumentException` - if f is null