org.apache.commons.math.analysis.solvers

## Class MullerSolver

- java.lang.Object
- - org.apache.commons.math.ConvergingAlgorithmImpl
  - - org.apache.commons.math.analysis.solvers.UnivariateRealSolverImpl
    - - org.apache.commons.math.analysis.solvers.MullerSolver

- All Implemented Interfaces:
    UnivariateRealSolver, ConvergingAlgorithm

      public class MullerSolver
      extends UnivariateRealSolverImpl

  Implements the Muller's Method for root finding of real univariate functions. For reference, see Elementary Numerical Analysis, ISBN 0070124477, chapter 3.

  Muller's method applies to both real and complex functions, but here we restrict ourselves to real functions. Methods solve() and solve2() find real zeros, using different ways to bypass complex arithmetics.

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

- - ### Field Summary

    - ### Fields inherited from class org.apache.commons.math.analysis.solvers.UnivariateRealSolverImpl

      `defaultFunctionValueAccuracy, f, functionValue, functionValueAccuracy, result, resultComputed`

    - ### Fields inherited from class org.apache.commons.math.ConvergingAlgorithmImpl

      `absoluteAccuracy, defaultAbsoluteAccuracy, defaultMaximalIterationCount, defaultRelativeAccuracy, iterationCount, maximalIterationCount, relativeAccuracy`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MullerSolver()` Deprecated. in 2.2 (to be removed in 3.0).
    `MullerSolver(UnivariateRealFunction f)` Deprecated. as of 2.0 the function to solve is passed as an argument to the `solve(UnivariateRealFunction, double, double)` or `UnivariateRealSolver.solve(UnivariateRealFunction, double, double, double)` method.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `solve(double min, double max)` Deprecated.
    `double` | `solve(double min, double max, double initial)` Deprecated.
    `double` | `solve(int maxEval, UnivariateRealFunction f, double min, double max)` Find a real root in the given interval.
    `double` | `solve(int maxEval, UnivariateRealFunction f, double min, double max, double initial)` Find a real root in the given interval with initial value.
    `double` | `solve(UnivariateRealFunction f, double min, double max)` Deprecated. in 2.2 (to be removed in 3.0).
    `double` | `solve(UnivariateRealFunction f, double min, double max, double initial)` Deprecated. in 2.2 (to be removed in 3.0).
    `double` | `solve2(double min, double max)` Deprecated. replaced by `solve2(UnivariateRealFunction, double, double)` since 2.0
    `double` | `solve2(UnivariateRealFunction f, double min, double max)` Deprecated. in 2.2 (to be removed in 3.0).

    - ### Methods inherited from class org.apache.commons.math.analysis.solvers.UnivariateRealSolverImpl

      `checkResultComputed, clearResult, getFunctionValue, getFunctionValueAccuracy, getResult, isBracketing, isSequence, resetFunctionValueAccuracy, setFunctionValueAccuracy, setResult, setResult, verifyBracketing, verifyInterval, verifySequence`

    - ### Methods inherited from class org.apache.commons.math.ConvergingAlgorithmImpl

      `getAbsoluteAccuracy, getIterationCount, getMaximalIterationCount, getRelativeAccuracy, incrementIterationsCounter, resetAbsoluteAccuracy, resetIterationsCounter, resetMaximalIterationCount, resetRelativeAccuracy, setAbsoluteAccuracy, setMaximalIterationCount, setRelativeAccuracy`

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

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

    - ### Methods inherited from interface org.apache.commons.math.ConvergingAlgorithm

      `getAbsoluteAccuracy, getIterationCount, getMaximalIterationCount, getRelativeAccuracy, resetAbsoluteAccuracy, resetMaximalIterationCount, resetRelativeAccuracy, setAbsoluteAccuracy, setMaximalIterationCount, setRelativeAccuracy`

- - ### Constructor Detail

    - #### MullerSolver

          @Deprecated
          public MullerSolver(UnivariateRealFunction f)

      Deprecated. as of 2.0 the function to solve is passed as an argument to the `solve(UnivariateRealFunction, double, double)` or `UnivariateRealSolver.solve(UnivariateRealFunction, double, double, double)` method.
      Construct a solver for the given function.
      Parameters:
        `f` - function to solve

    - #### MullerSolver

          @Deprecated
          public MullerSolver()

      Deprecated. in 2.2 (to be removed in 3.0).
      Construct a solver.

  - ### Method Detail

    - #### solve

          @Deprecated
          public double solve(double min,
                                double max)
                       throws ConvergenceException,
                              FunctionEvaluationException

      Deprecated.
      Solve for a zero root in the given interval.

      A solver may require that the interval brackets a single zero root. Solvers that do require bracketing should be able to handle the case where one of the endpoints is itself a root.

      Parameters:
        `min` - the lower bound for the interval.
        `max` - the upper bound for the interval.
      Returns:
        a value where the function is zero
      Throws:
        `ConvergenceException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise.
        `FunctionEvaluationException` - if an error occurs evaluating the function

    - #### solve

          @Deprecated
          public double solve(double min,
                                double max,
                                double initial)
                       throws ConvergenceException,
                              FunctionEvaluationException

      Deprecated.
      Solve for a zero in the given interval, start at startValue.

      A solver may require that the interval brackets a single zero root. Solvers that do require bracketing should be able to handle the case where one of the endpoints is itself a root.

      Parameters:
        `min` - the lower bound for the interval.
        `max` - the upper bound for the interval.
        `initial` - the start value to use
      Returns:
        a value where the function is zero
      Throws:
        `ConvergenceException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise.
        `FunctionEvaluationException` - if an error occurs evaluating the function

    - #### solve

          public double solve(int maxEval,
                     UnivariateRealFunction f,
                     double min,
                     double max,
                     double initial)
                       throws MaxIterationsExceededException,
                              FunctionEvaluationException

      Find a real root in the given interval with initial value.

      Requires bracketing condition.

      Overrides:
        `solve` in class `UnivariateRealSolverImpl`
      Parameters:
        `f` - the function to solve
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
        `initial` - the start value to use
        `maxEval` - Maximum number of evaluations.
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

    - #### solve

          @Deprecated
          public double solve(UnivariateRealFunction f,
                                double min,
                                double max,
                                double initial)
                       throws MaxIterationsExceededException,
                              FunctionEvaluationException

      Deprecated. in 2.2 (to be removed in 3.0).
      Find a real root in the given interval with initial value.

      Requires bracketing condition.

      Parameters:
        `f` - the function to solve
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
        `initial` - the start value to use
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

    - #### solve

          public double solve(int maxEval,
                     UnivariateRealFunction f,
                     double min,
                     double max)
                       throws MaxIterationsExceededException,
                              FunctionEvaluationException

      Find a real root in the given interval.

      Original Muller's method would have function evaluation at complex point. Since our f(x) is real, we have to find ways to avoid that. Bracketing condition is one way to go: by requiring bracketing in every iteration, the newly computed approximation is guaranteed to be real.

      Normally Muller's method converges quadratically in the vicinity of a zero, however it may be very slow in regions far away from zeros. For example, f(x) = exp(x) - 1, min = -50, max = 100. In such case we use bisection as a safety backup if it performs very poorly.

      The formulas here use divided differences directly.

      Overrides:
        `solve` in class `UnivariateRealSolverImpl`
      Parameters:
        `f` - the function to solve
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
        `maxEval` - Maximum number of evaluations.
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

    - #### solve

          @Deprecated
          public double solve(UnivariateRealFunction f,
                                double min,
                                double max)
                       throws MaxIterationsExceededException,
                              FunctionEvaluationException

      Deprecated. in 2.2 (to be removed in 3.0).
      Find a real root in the given interval.

      Original Muller's method would have function evaluation at complex point. Since our f(x) is real, we have to find ways to avoid that. Bracketing condition is one way to go: by requiring bracketing in every iteration, the newly computed approximation is guaranteed to be real.

      Normally Muller's method converges quadratically in the vicinity of a zero, however it may be very slow in regions far away from zeros. For example, f(x) = exp(x) - 1, min = -50, max = 100. In such case we use bisection as a safety backup if it performs very poorly.

      The formulas here use divided differences directly.

      Parameters:
        `f` - the function to solve
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

    - #### solve2

          @Deprecated
          public double solve2(double min,
                                 double max)
                        throws MaxIterationsExceededException,
                               FunctionEvaluationException

      Deprecated. replaced by `solve2(UnivariateRealFunction, double, double)` since 2.0
      Find a real root in the given interval.

      solve2() differs from solve() in the way it avoids complex operations. Except for the initial [min, max], solve2() does not require bracketing condition, e.g. f(x0), f(x1), f(x2) can have the same sign. If complex number arises in the computation, we simply use its modulus as real approximation.

      Because the interval may not be bracketing, bisection alternative is not applicable here. However in practice our treatment usually works well, especially near real zeros where the imaginary part of complex approximation is often negligible.

      The formulas here do not use divided differences directly.

      Parameters:
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

    - #### solve2

          @Deprecated
          public double solve2(UnivariateRealFunction f,
                                 double min,
                                 double max)
                        throws MaxIterationsExceededException,
                               FunctionEvaluationException

      Deprecated. in 2.2 (to be removed in 3.0).
      Find a real root in the given interval.

      solve2() differs from solve() in the way it avoids complex operations. Except for the initial [min, max], solve2() does not require bracketing condition, e.g. f(x0), f(x1), f(x2) can have the same sign. If complex number arises in the computation, we simply use its modulus as real approximation.

      Because the interval may not be bracketing, bisection alternative is not applicable here. However in practice our treatment usually works well, especially near real zeros where the imaginary part of complex approximation is often negligible.

      The formulas here do not use divided differences directly.

      Parameters:
        `f` - the function to solve
        `min` - the lower bound for the interval
        `max` - the upper bound for the interval
      Returns:
        the point at which the function value is zero
      Throws:
        `MaxIterationsExceededException` - if the maximum iteration count is exceeded or the solver detects convergence problems otherwise
        `FunctionEvaluationException` - if an error occurs evaluating the function
        `IllegalArgumentException` - if any parameters are invalid

Copyright (c) 2003-2013 Apache Software Foundation