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

java.lang.Object
  extended by 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 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:

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

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