org.apache.commons.math3.dfp

## Class BracketingNthOrderBrentSolverDFP

- java.lang.Object
- - org.apache.commons.math3.dfp.BracketingNthOrderBrentSolverDFP

-     public class BracketingNthOrderBrentSolverDFP
      extends java.lang.Object

  This class implements a modification of the Brent algorithm.

  The changes with respect to the original Brent algorithm are:

  - the returned value is chosen in the current interval according to user specified `AllowedSolution`,
  - the maximal order for the invert polynomial root search is user-specified instead of being invert quadratic only
  The given interval must bracket the root.
  Version:
    $Id: BracketingNthOrderBrentSolverDFP.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private Dfp` | `absoluteAccuracy` Absolute accuracy.
    `private Incrementor` | `evaluations` Evaluations counter.
    `private Dfp` | `functionValueAccuracy` Function value accuracy.
    `private static int` | `MAXIMAL_AGING` Maximal aging triggering an attempt to balance the bracketing interval.
    `private int` | `maximalOrder` Maximal order.
    `private Dfp` | `relativeAccuracy` Relative accuracy.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BracketingNthOrderBrentSolverDFP(Dfp relativeAccuracy, Dfp absoluteAccuracy, Dfp functionValueAccuracy, int maximalOrder)` Construct a solver.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Dfp` | `getAbsoluteAccuracy()` Get the absolute accuracy.
    `int` | `getEvaluations()` Get the number of evaluations of the objective function.
    `Dfp` | `getFunctionValueAccuracy()` Get the function accuracy.
    `int` | `getMaxEvaluations()` Get the maximal number of function evaluations.
    `int` | `getMaximalOrder()` Get the maximal order.
    `Dfp` | `getRelativeAccuracy()` Get the relative accuracy.
    `private Dfp` | `guessX(Dfp targetY, Dfp[] x, Dfp[] y, int start, int end)` Guess an x value by nth order inverse polynomial interpolation.
    `Dfp` | `solve(int maxEval, UnivariateDfpFunction f, Dfp min, Dfp max, AllowedSolution allowedSolution)` Solve for a zero in the given interval.
    `Dfp` | `solve(int maxEval, UnivariateDfpFunction f, Dfp min, Dfp max, Dfp startValue, AllowedSolution allowedSolution)` Solve for a zero in the given interval, start at `startValue`.

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

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

- - ### Field Detail

    - #### MAXIMAL_AGING

          private static final int MAXIMAL_AGING

      Maximal aging triggering an attempt to balance the bracketing interval.
      See Also:
        Constant Field Values

    - #### maximalOrder

          private final int maximalOrder

      Maximal order.

    - #### functionValueAccuracy

          private final Dfp functionValueAccuracy

      Function value accuracy.

    - #### absoluteAccuracy

          private final Dfp absoluteAccuracy

      Absolute accuracy.

    - #### relativeAccuracy

          private final Dfp relativeAccuracy

      Relative accuracy.

    - #### evaluations

          private final Incrementor evaluations

      Evaluations counter.

  - ### Constructor Detail

    - #### BracketingNthOrderBrentSolverDFP

          public BracketingNthOrderBrentSolverDFP(Dfp relativeAccuracy,
                                          Dfp absoluteAccuracy,
                                          Dfp functionValueAccuracy,
                                          int maximalOrder)
                                           throws NumberIsTooSmallException

      Construct a solver.
      Parameters:
        `relativeAccuracy` - Relative accuracy.
        `absoluteAccuracy` - Absolute accuracy.
        `functionValueAccuracy` - Function value accuracy.
        `maximalOrder` - maximal order.
      Throws:
        `NumberIsTooSmallException` - if maximal order is lower than 2

  - ### Method Detail

    - #### getMaximalOrder

          public int getMaximalOrder()

      Get the maximal order.
      Returns:
        maximal order

    - #### getMaxEvaluations

          public int getMaxEvaluations()

      Get the maximal number of function evaluations.
      Returns:
        the maximal number of function evaluations.

    - #### getEvaluations

          public int getEvaluations()

      Get the number of evaluations of the objective function. The number of evaluations corresponds to the last call to the `optimize` method. It is 0 if the method has not been called yet.
      Returns:
        the number of evaluations of the objective function.

    - #### getAbsoluteAccuracy

          public Dfp getAbsoluteAccuracy()

      Get the absolute accuracy.
      Returns:
        absolute accuracy

    - #### getRelativeAccuracy

          public Dfp getRelativeAccuracy()

      Get the relative accuracy.
      Returns:
        relative accuracy

    - #### getFunctionValueAccuracy

          public Dfp getFunctionValueAccuracy()

      Get the function accuracy.
      Returns:
        function accuracy

    - #### solve

          public Dfp solve(int maxEval,
                  UnivariateDfpFunction f,
                  Dfp min,
                  Dfp max,
                  AllowedSolution allowedSolution)
                    throws NullArgumentException,
                           NoBracketingException

      Solve for a zero 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:
        `maxEval` - Maximum number of evaluations.
        `f` - Function to solve.
        `min` - Lower bound for the interval.
        `max` - Upper bound for the interval.
        `allowedSolution` - The kind of solutions that the root-finding algorithm may accept as solutions.
      Returns:
        a value where the function is zero.
      Throws:
        `NullArgumentException` - if f is null.
        `NoBracketingException` - if root cannot be bracketed

    - #### solve

          public Dfp solve(int maxEval,
                  UnivariateDfpFunction f,
                  Dfp min,
                  Dfp max,
                  Dfp startValue,
                  AllowedSolution allowedSolution)
                    throws NullArgumentException,
                           NoBracketingException

      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:
        `maxEval` - Maximum number of evaluations.
        `f` - Function to solve.
        `min` - Lower bound for the interval.
        `max` - Upper bound for the interval.
        `startValue` - Start value to use.
        `allowedSolution` - The kind of solutions that the root-finding algorithm may accept as solutions.
      Returns:
        a value where the function is zero.
      Throws:
        `NullArgumentException` - if f is null.
        `NoBracketingException` - if root cannot be bracketed

    - #### guessX

          private Dfp guessX(Dfp targetY,
                   Dfp[] x,
                   Dfp[] y,
                   int start,
                   int end)

      Guess an x value by nth order inverse polynomial interpolation.

      The x value is guessed by evaluating polynomial Q(y) at y = targetY, where Q is built such that for all considered points (xi, yi), Q(yi) = xi.

      Parameters:
        `targetY` - target value for y
        `x` - reference points abscissas for interpolation, note that this array is modified during computation
        `y` - reference points ordinates for interpolation
        `start` - start index of the points to consider (inclusive)
        `end` - end index of the points to consider (exclusive)
      Returns:
        guessed root (will be a NaN if two points share the same y)

Copyright (c) 2003-2013 Apache Software Foundation