org.apache.commons.math3.analysis.integration

## Class BaseAbstractUnivariateIntegrator

- java.lang.Object
- - org.apache.commons.math3.analysis.integration.BaseAbstractUnivariateIntegrator

- All Implemented Interfaces:
    UnivariateIntegrator
  Direct Known Subclasses:
    IterativeLegendreGaussIntegrator, LegendreGaussIntegrator, RombergIntegrator, SimpsonIntegrator, TrapezoidIntegrator

      public abstract class BaseAbstractUnivariateIntegrator
      extends java.lang.Object
      implements UnivariateIntegrator

  Provide a default implementation for several generic functions.
  Since:
    1.2
  Version:
    $Id: BaseAbstractUnivariateIntegrator.java 1364387 2012-07-22 18:14:11Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `absoluteAccuracy` Maximum absolute error.
    `static double` | `DEFAULT_ABSOLUTE_ACCURACY` Default absolute accuracy.
    `static int` | `DEFAULT_MAX_ITERATIONS_COUNT` Default maximal iteration count.
    `static int` | `DEFAULT_MIN_ITERATIONS_COUNT` Default minimal iteration count.
    `static double` | `DEFAULT_RELATIVE_ACCURACY` Default relative accuracy.
    `private Incrementor` | `evaluations` The functions evaluation count.
    `private UnivariateFunction` | `function` Function to integrate.
    `protected Incrementor` | `iterations` The iteration count.
    `private double` | `max` Upper bound for the interval.
    `private double` | `min` Lower bound for the interval.
    `private int` | `minimalIterationCount` minimum number of iterations
    `private double` | `relativeAccuracy` Maximum relative error.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `BaseAbstractUnivariateIntegrator(double relativeAccuracy, double absoluteAccuracy)` Construct an integrator with given accuracies.
    `protected` | `BaseAbstractUnivariateIntegrator(double relativeAccuracy, double absoluteAccuracy, int minimalIterationCount, int maximalIterationCount)` Construct an integrator with given accuracies and iteration counts.
    `protected` | `BaseAbstractUnivariateIntegrator(int minimalIterationCount, int maximalIterationCount)` Construct an integrator with given iteration counts.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `computeObjectiveValue(double point)` Compute the objective function value.
    `protected abstract double` | `doIntegrate()` Method for implementing actual integration algorithms in derived classes.
    `double` | `getAbsoluteAccuracy()` Get the actual absolute accuracy.
    `int` | `getEvaluations()` Get the number of function evaluations of the last run of the integrator.
    `int` | `getIterations()` Get the number of iterations of the last run of the integrator.
    `protected double` | `getMax()`
    `int` | `getMaximalIterationCount()` Get the upper limit for the number of iterations.
    `protected double` | `getMin()`
    `int` | `getMinimalIterationCount()` Get the min limit for the number of iterations.
    `double` | `getRelativeAccuracy()` Get the actual relative accuracy.
    `double` | `integrate(int maxEval, UnivariateFunction f, double lower, double upper)` Integrate the function in the given interval.
    `protected void` | `setup(int maxEval, UnivariateFunction f, double lower, double upper)` Prepare for computation.

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

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

- - ### Field Detail

    - #### DEFAULT_ABSOLUTE_ACCURACY

          public static final double DEFAULT_ABSOLUTE_ACCURACY

      Default absolute accuracy.
      See Also:
        Constant Field Values

    - #### DEFAULT_RELATIVE_ACCURACY

          public static final double DEFAULT_RELATIVE_ACCURACY

      Default relative accuracy.
      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_ITERATIONS_COUNT

          public static final int DEFAULT_MIN_ITERATIONS_COUNT

      Default minimal iteration count.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_ITERATIONS_COUNT

          public static final int DEFAULT_MAX_ITERATIONS_COUNT

      Default maximal iteration count.
      See Also:
        Constant Field Values

    - #### iterations

          protected final Incrementor iterations

      The iteration count.

    - #### absoluteAccuracy

          private final double absoluteAccuracy

      Maximum absolute error.

    - #### relativeAccuracy

          private final double relativeAccuracy

      Maximum relative error.

    - #### minimalIterationCount

          private final int minimalIterationCount

      minimum number of iterations

    - #### evaluations

          private final Incrementor evaluations

      The functions evaluation count.

    - #### function

          private UnivariateFunction function

      Function to integrate.

    - #### min

          private double min

      Lower bound for the interval.

    - #### max

          private double max

      Upper bound for the interval.

  - ### Constructor Detail

    - #### BaseAbstractUnivariateIntegrator

          protected BaseAbstractUnivariateIntegrator(double relativeAccuracy,
                                          double absoluteAccuracy,
                                          int minimalIterationCount,
                                          int maximalIterationCount)
                                              throws NotStrictlyPositiveException,
                                                     NumberIsTooSmallException

      Construct an integrator with given accuracies and iteration counts.

      The meanings of the various parameters are:

      - relative accuracy: this is used to stop iterations if the absolute accuracy can't be achieved due to large values or short mantissa length. If this should be the primary criterion for convergence rather then a safety measure, set the absolute accuracy to a ridiculously small value, like `Precision.SAFE_MIN`.
      - absolute accuracy: The default is usually chosen so that results in the interval -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the expected absolute value of your results is of much smaller magnitude, set this to a smaller value.
      - minimum number of iterations: minimal iteration is needed to avoid false early convergence, e.g. the sample points happen to be zeroes of the function. Users can use the default value or choose one that they see as appropriate.
      - maximum number of iterations: usually a high iteration count indicates convergence problems. However, the "reasonable value" varies widely for different algorithms. Users are advised to use the default value supplied by the algorithm.
      Parameters:
        `relativeAccuracy` - relative accuracy of the result
        `absoluteAccuracy` - absolute accuracy of the result
        `minimalIterationCount` - minimum number of iterations
        `maximalIterationCount` - maximum number of iterations
      Throws:
        `NotStrictlyPositiveException` - if minimal number of iterations is not strictly positive
        `NumberIsTooSmallException` - if maximal number of iterations is lesser than or equal to the minimal number of iterations

    - #### BaseAbstractUnivariateIntegrator

          protected BaseAbstractUnivariateIntegrator(double relativeAccuracy,
                                          double absoluteAccuracy)

      Construct an integrator with given accuracies.
      Parameters:
        `relativeAccuracy` - relative accuracy of the result
        `absoluteAccuracy` - absolute accuracy of the result

    - #### BaseAbstractUnivariateIntegrator

          protected BaseAbstractUnivariateIntegrator(int minimalIterationCount,
                                          int maximalIterationCount)
                                              throws NotStrictlyPositiveException,
                                                     NumberIsTooSmallException

      Construct an integrator with given iteration counts.
      Parameters:
        `minimalIterationCount` - minimum number of iterations
        `maximalIterationCount` - maximum number of iterations
      Throws:
        `NotStrictlyPositiveException` - if minimal number of iterations is not strictly positive
        `NumberIsTooSmallException` - if maximal number of iterations is lesser than or equal to the minimal number of iterations

  - ### Method Detail

    - #### getRelativeAccuracy

          public double getRelativeAccuracy()

      Get the actual relative accuracy.
      Specified by:
        `getRelativeAccuracy` in interface `UnivariateIntegrator`
      Returns:
        the accuracy

    - #### getAbsoluteAccuracy

          public double getAbsoluteAccuracy()

      Get the actual absolute accuracy.
      Specified by:
        `getAbsoluteAccuracy` in interface `UnivariateIntegrator`
      Returns:
        the accuracy

    - #### getMinimalIterationCount

          public int getMinimalIterationCount()

      Get the min limit for the number of iterations.
      Specified by:
        `getMinimalIterationCount` in interface `UnivariateIntegrator`
      Returns:
        the actual min limit

    - #### getMaximalIterationCount

          public int getMaximalIterationCount()

      Get the upper limit for the number of iterations.
      Specified by:
        `getMaximalIterationCount` in interface `UnivariateIntegrator`
      Returns:
        the actual upper limit

    - #### getEvaluations

          public int getEvaluations()

      Get the number of function evaluations of the last run of the integrator.
      Specified by:
        `getEvaluations` in interface `UnivariateIntegrator`
      Returns:
        number of function evaluations

    - #### getIterations

          public int getIterations()

      Get the number of iterations of the last run of the integrator.
      Specified by:
        `getIterations` in interface `UnivariateIntegrator`
      Returns:
        number of iterations

    - #### getMin

          protected double getMin()

      Returns:
        the lower bound.

    - #### getMax

          protected double getMax()

      Returns:
        the upper bound.

    - #### 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 function evaluations is exceeded.

    - #### setup

          protected void setup(int maxEval,
                   UnivariateFunction f,
                   double lower,
                   double upper)
                        throws NullArgumentException,
                               MathIllegalArgumentException

      Prepare for computation. Subclasses must call this method if they override any of the `solve` methods.
      Parameters:
        `maxEval` - Maximum number of evaluations.
        `f` - the integrand function
        `lower` - the min bound for the interval
        `upper` - the upper bound for the interval
      Throws:
        `NullArgumentException` - if `f` is `null`.
        `MathIllegalArgumentException` - if `min >= max`.

    - #### integrate

          public double integrate(int maxEval,
                         UnivariateFunction f,
                         double lower,
                         double upper)
                           throws TooManyEvaluationsException,
                                  MaxCountExceededException,
                                  MathIllegalArgumentException,
                                  NullArgumentException

      Integrate the function in the given interval.
      Specified by:
        `integrate` in interface `UnivariateIntegrator`
      Parameters:
        `maxEval` - Maximum number of evaluations.
        `f` - the integrand function
        `lower` - the min bound for the interval
        `upper` - the upper bound for the interval
      Returns:
        the value of integral
      Throws:
        `TooManyEvaluationsException` - if the maximum number of function evaluations is exceeded.
        `MaxCountExceededException` - if the maximum iteration count is exceeded or the integrator detects convergence problems otherwise
        `MathIllegalArgumentException` - if min > max or the endpoints do not satisfy the requirements specified by the integrator
        `NullArgumentException` - if `f` is `null`.

    - #### doIntegrate

          protected abstract double doIntegrate()
                                         throws TooManyEvaluationsException,
                                                MaxCountExceededException

      Method for implementing actual integration algorithms in derived classes.
      Returns:
        the root.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
        `MaxCountExceededException` - if the maximum iteration count is exceeded or the integrator detects convergence problems otherwise

Copyright (c) 2003-2013 Apache Software Foundation