org.apache.commons.math.analysis
Class UnivariateRealSolverUtils

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

public class UnivariateRealSolverUtils

extends Object

Utility routines for UnivariateRealSolver objects.

Version:

$Revision: 1.10 $ $Date: 2004/07/17 21:19:39 $

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

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.