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
`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
`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)