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
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `UnivariateRealSolverUtils.LazyHolder` Holder for the factory.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `UnivariateRealSolverUtils()` Default constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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

Copyright (c) 2003-2013 Apache Software Foundation