## org.apache.commons.math.analysis.solvers
Class UnivariateRealSolverUtils

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

    public class UnivariateRealSolverUtils

extends java.lang.Object

Utility routines for `UnivariateRealSolver` objects.

Version:
  $Revision: 885278 $ $Date: 2009-11-29 16:47:51 -0500 (Sun, 29 Nov 2009) $

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

Field Summary
`private static java.lang.String` `NULL_FUNCTION_MESSAGE` Message for null function.

Constructor Summary
`private` `UnivariateRealSolverUtils()` Default constructor.

Method Summary
`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`

Field Detail

### NULL_FUNCTION_MESSAGE

    private static final java.lang.String NULL_FUNCTION_MESSAGE

  Message for null function.

  See Also:
    Constant Field Values

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
    `java.lang.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
    `java.lang.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
    `java.lang.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
    `java.lang.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:
    `java.lang.IllegalArgumentException` - if f is null

Copyright (c) 2003-2011 Apache Software Foundation