BaseAbstractUnivariateSolver (Apache Commons Math 3.6.1 API)

org.apache.commons.math3.analysis.solvers

## Class BaseAbstractUnivariateSolver<FUNC extends UnivariateFunction>

- java.lang.Object
- - org.apache.commons.math3.analysis.solvers.BaseAbstractUnivariateSolver<FUNC>

- Type Parameters:
    `FUNC` - Type of function to solve.
  All Implemented Interfaces:
    BaseUnivariateSolver<FUNC>
  Direct Known Subclasses:
    AbstractDifferentiableUnivariateSolver, AbstractPolynomialSolver, AbstractUnivariateDifferentiableSolver, AbstractUnivariateSolver

      public abstract class BaseAbstractUnivariateSolver<FUNC extends UnivariateFunction>
      extends Object
      implements BaseUnivariateSolver<FUNC>

  Provide a default implementation for several functions useful to generic solvers. The default values for relative and function tolerances are 1e-14 and 1e-15, respectively. It is however highly recommended to not rely on the default, but rather carefully consider values that match user's expectations, as well as the specifics of each implementation.
  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BaseAbstractUnivariateSolver(double absoluteAccuracy)` Construct a solver with given absolute accuracy.
    `protected` | `BaseAbstractUnivariateSolver(double relativeAccuracy, double absoluteAccuracy)` Construct a solver with given accuracies.
    `protected` | `BaseAbstractUnivariateSolver(double relativeAccuracy, double absoluteAccuracy, double functionValueAccuracy)` Construct a solver with given accuracies.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `computeObjectiveValue(double point)` Compute the objective function value.
    `protected abstract double` | `doSolve()` Method for implementing actual optimization algorithms in derived classes.
    `double` | `getAbsoluteAccuracy()` Get the absolute accuracy of the solver.
    `int` | `getEvaluations()` Get the number of evaluations of the objective function.
    `double` | `getFunctionValueAccuracy()` Get the function value accuracy of the solver.
    `double` | `getMax()`
    `int` | `getMaxEvaluations()` Get the maximum number of function evaluations.
    `double` | `getMin()`
    `double` | `getRelativeAccuracy()` Get the relative accuracy of the solver.
    `double` | `getStartValue()`
    `protected void` | `incrementEvaluationCount()` Increment the evaluation count by one.
    `protected boolean` | `isBracketing(double lower, double upper)` Check whether the function takes opposite signs at the endpoints.
    `protected boolean` | `isSequence(double start, double mid, double end)` Check whether the arguments form a (strictly) increasing sequence.
    `protected void` | `setup(int maxEval, FUNC f, double min, double max, double startValue)` Prepare for computation.
    `double` | `solve(int maxEval, FUNC f, double startValue)` Solve for a zero in the vicinity of `startValue`.
    `double` | `solve(int maxEval, FUNC f, double min, double max)` Solve for a zero root in the given interval.
    `double` | `solve(int maxEval, FUNC f, double min, double max, double startValue)` Solve for a zero in the given interval, start at `startValue`.
    `protected void` | `verifyBracketing(double lower, double upper)` Check that the endpoints specify an interval and the function takes opposite signs at the endpoints.
    `protected void` | `verifyInterval(double lower, double upper)` Check that the endpoints specify an interval.
    `protected void` | `verifySequence(double lower, double initial, double upper)` Check that `lower < initial < upper`.

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

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

- - ### Constructor Detail

    - #### BaseAbstractUnivariateSolver

          protected BaseAbstractUnivariateSolver(double absoluteAccuracy)

      Construct a solver with given absolute accuracy.
      Parameters:
        `absoluteAccuracy` - Maximum absolute error.

    - #### BaseAbstractUnivariateSolver

          protected BaseAbstractUnivariateSolver(double relativeAccuracy,
                                      double absoluteAccuracy)

      Construct a solver with given accuracies.
      Parameters:
        `relativeAccuracy` - Maximum relative error.
        `absoluteAccuracy` - Maximum absolute error.

    - #### BaseAbstractUnivariateSolver

          protected BaseAbstractUnivariateSolver(double relativeAccuracy,
                                      double absoluteAccuracy,
                                      double functionValueAccuracy)

      Construct a solver with given accuracies.
      Parameters:
        `relativeAccuracy` - Maximum relative error.
        `absoluteAccuracy` - Maximum absolute error.
        `functionValueAccuracy` - Maximum function value error.

  - ### Method Detail

    - #### getMaxEvaluations

          public int getMaxEvaluations()

      Get the maximum number of function evaluations.
      Specified by:
        `getMaxEvaluations` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Returns:
        the maximum 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.
      Specified by:
        `getEvaluations` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Returns:
        the number of evaluations of the objective function.

    - #### getMin

          public double getMin()

      Returns:
        the lower end of the search interval.

    - #### getMax

          public double getMax()

      Returns:
        the higher end of the search interval.

    - #### getStartValue

          public double getStartValue()

      Returns:
        the initial guess.

    - #### getAbsoluteAccuracy

          public double getAbsoluteAccuracy()

      Get the absolute accuracy of the solver. Solutions returned by the solver should be accurate to this tolerance, i.e., if ε is the absolute accuracy of the solver and `v` is a value returned by one of the `solve` methods, then a root of the function should exist somewhere in the interval (`v` - ε, `v` + ε).
      Specified by:
        `getAbsoluteAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Returns:
        the absolute accuracy.

    - #### getRelativeAccuracy

          public double getRelativeAccuracy()

      Get the relative accuracy of the solver. The contract for relative accuracy is the same as `BaseUnivariateSolver.getAbsoluteAccuracy()`, but using relative, rather than absolute error. If ρ is the relative accuracy configured for a solver and `v` is a value returned, then a root of the function should exist somewhere in the interval (`v` - ρ `v`, `v` + ρ `v`).
      Specified by:
        `getRelativeAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Returns:
        the relative accuracy.

    - #### getFunctionValueAccuracy

          public double getFunctionValueAccuracy()

      Get the function value accuracy of the solver. If `v` is a value returned by the solver for a function `f`, then by contract, `|f(v)|` should be less than or equal to the function value accuracy configured for the solver.
      Specified by:
        `getFunctionValueAccuracy` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Returns:
        the function value accuracy.

    - #### computeObjectiveValue

          protected double computeObjectiveValue(double point)
                                          throws TooManyEvaluationsException

      Compute the objective function value.
      Parameters:
        `point` - Point at which the objective function must be evaluated.
      Returns:
        the objective function value at specified point.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.

    - #### setup

          protected void setup(int maxEval,
                   FUNC f,
                   double min,
                   double max,
                   double startValue)
                        throws NullArgumentException

      Prepare for computation. Subclasses must call this method if they override any of the `solve` methods.
      Parameters:
        `f` - Function to solve.
        `min` - Lower bound for the interval.
        `max` - Upper bound for the interval.
        `startValue` - Start value to use.
        `maxEval` - Maximum number of evaluations.
      Throws:
        `NullArgumentException` - if f is null

    - #### solve

          public double solve(int maxEval,
                     FUNC f,
                     double min,
                     double max,
                     double startValue)
                       throws TooManyEvaluationsException,
                              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.
      Specified by:
        `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      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.
      Returns:
        a value where the function is zero.
      Throws:
        `TooManyEvaluationsException` - if the allowed number of evaluations is exceeded.
        `NoBracketingException`

    - #### solve

          public double solve(int maxEval,
                     FUNC f,
                     double min,
                     double max)

      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.
      Specified by:
        `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Parameters:
        `maxEval` - Maximum number of evaluations.
        `f` - Function to solve.
        `min` - Lower bound for the interval.
        `max` - Upper bound for the interval.
      Returns:
        a value where the function is zero.

    - #### solve

          public double solve(int maxEval,
                     FUNC f,
                     double startValue)
                       throws TooManyEvaluationsException,
                              NoBracketingException

      Solve for a zero in the vicinity of `startValue`.
      Specified by:
        `solve` in interface `BaseUnivariateSolver<FUNC extends UnivariateFunction>`
      Parameters:
        `maxEval` - Maximum number of evaluations.
        `f` - Function to solve.
        `startValue` - Start value to use.
      Returns:
        a value where the function is zero.
      Throws:
        `TooManyEvaluationsException` - if the allowed number of evaluations is exceeded.
        `NoBracketingException`

    - #### doSolve

          protected abstract double doSolve()
                                     throws TooManyEvaluationsException,
                                            NoBracketingException

      Method for implementing actual optimization algorithms in derived classes.
      Returns:
        the root.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
        `NoBracketingException` - if the initial search interval does not bracket a root and the solver requires it.

    - #### isBracketing

          protected boolean isBracketing(double lower,
                             double upper)

      Check whether the function takes opposite signs at the endpoints.
      Parameters:
        `lower` - Lower endpoint.
        `upper` - Upper endpoint.
      Returns:
        `true` if the function values have opposite signs at the given points.

    - #### isSequence

          protected boolean isSequence(double start,
                           double mid,
                           double end)

      Check whether the arguments form a (strictly) increasing sequence.
      Parameters:
        `start` - First number.
        `mid` - Second number.
        `end` - Third number.
      Returns:
        `true` if the arguments form an increasing sequence.

    - #### verifyInterval

          protected void verifyInterval(double lower,
                            double upper)
                                 throws NumberIsTooLargeException

      Check that the endpoints specify an interval.
      Parameters:
        `lower` - Lower endpoint.
        `upper` - Upper endpoint.
      Throws:
        `NumberIsTooLargeException` - if `lower >= upper`.

    - #### verifySequence

          protected void verifySequence(double lower,
                            double initial,
                            double upper)
                                 throws NumberIsTooLargeException

      Check that `lower < initial < upper`.
      Parameters:
        `lower` - Lower endpoint.
        `initial` - Initial value.
        `upper` - Upper endpoint.
      Throws:
        `NumberIsTooLargeException` - if `lower >= initial` or `initial >= upper`.

    - #### verifyBracketing

          protected void verifyBracketing(double lower,
                              double upper)
                                   throws NullArgumentException,
                                          NoBracketingException

      Check that the endpoints specify an interval and the function takes opposite signs at the endpoints.
      Parameters:
        `lower` - Lower endpoint.
        `upper` - Upper endpoint.
      Throws:
        `NullArgumentException` - if the function has not been set.
        `NoBracketingException` - if the function has the same sign at the endpoints.

    - #### incrementEvaluationCount

          protected void incrementEvaluationCount()
                                           throws TooManyEvaluationsException

      Increment the evaluation count by one. Method `computeObjectiveValue(double)` calls this method internally. It is provided for subclasses that do not exclusively use `computeObjectiveValue` to solve the function. See e.g. `AbstractUnivariateDifferentiableSolver`.
      Throws:
        `TooManyEvaluationsException` - when the allowed number of function evaluations has been exhausted.

Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.