org.apache.commons.math3.ode.nonstiff

## Class AdaptiveStepsizeIntegrator

- java.lang.Object
- - org.apache.commons.math3.ode.AbstractIntegrator
  - - org.apache.commons.math3.ode.nonstiff.AdaptiveStepsizeIntegrator

- All Implemented Interfaces:
    FirstOrderIntegrator, ODEIntegrator
  Direct Known Subclasses:
    EmbeddedRungeKuttaIntegrator, GraggBulirschStoerIntegrator, MultistepIntegrator

      public abstract class AdaptiveStepsizeIntegrator
      extends AbstractIntegrator

  This abstract class holds the common part of all adaptive stepsize integrators for Ordinary Differential Equations.

  These algorithms perform integration with stepsize control, which means the user does not specify the integration step but rather a tolerance on error. The error threshold is computed as

       threshold_i = absTol_i + relTol_i * max (abs (ym), abs (ym+1))

  where absTol_i is the absolute tolerance for component i of the state vector and relTol_i is the relative tolerance for the same component. The user can also use only two scalar values absTol and relTol which will be used for all components.

  If the Ordinary Differential Equations is an `extended ODE` rather than a `basic ODE`, then only the `primary part` of the state vector is used for stepsize control, not the complete state vector.

  If the estimated error for ym+1 is such that

       sqrt((sum (errEst_i / threshold_i)^2 ) / n) < 1

  (where n is the main set dimension) then the step is accepted, otherwise the step is rejected and a new attempt is made with a new stepsize.
  Since:
    1.2
  Version:
    $Id: AdaptiveStepsizeIntegrator.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `initialStep` User supplied initial step.
    `protected int` | `mainSetDimension` Main set dimension.
    `private double` | `maxStep` Maximal step.
    `private double` | `minStep` Minimal step.
    `protected double` | `scalAbsoluteTolerance` Allowed absolute scalar error.
    `protected double` | `scalRelativeTolerance` Allowed relative scalar error.
    `protected double[]` | `vecAbsoluteTolerance` Allowed absolute vectorial error.
    `protected double[]` | `vecRelativeTolerance` Allowed relative vectorial error.

    - ### Fields inherited from class org.apache.commons.math3.ode.AbstractIntegrator

      `isLastStep, resetOccurred, stepHandlers, stepSize, stepStart`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AdaptiveStepsizeIntegrator(String name, double minStep, double maxStep, double[] vecAbsoluteTolerance, double[] vecRelativeTolerance)` Build an integrator with the given stepsize bounds.
    `AdaptiveStepsizeIntegrator(String name, double minStep, double maxStep, double scalAbsoluteTolerance, double scalRelativeTolerance)` Build an integrator with the given stepsize bounds.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `filterStep(double h, boolean forward, boolean acceptSmall)` Filter the integration step.
    `double` | `getCurrentStepStart()` Get the current value of the step start time ti.
    `double` | `getMaxStep()` Get the maximal step.
    `double` | `getMinStep()` Get the minimal step.
    `double` | `initializeStep(boolean forward, int order, double[] scale, double t0, double[] y0, double[] yDot0, double[] y1, double[] yDot1)` Initialize the integration step.
    `abstract void` | `integrate(ExpandableStatefulODE equations, double t)` Integrate a set of differential equations up to the given time.
    `protected void` | `resetInternalState()` Reset internal state to dummy values.
    `protected void` | `sanityChecks(ExpandableStatefulODE equations, double t)` Check the integration span.
    `void` | `setInitialStepSize(double initialStepSize)` Set the initial step size.
    `void` | `setStepSizeControl(double minimalStep, double maximalStep, double[] absoluteTolerance, double[] relativeTolerance)` Set the adaptive step size control parameters.
    `void` | `setStepSizeControl(double minimalStep, double maximalStep, double absoluteTolerance, double relativeTolerance)` Set the adaptive step size control parameters.

    - ### Methods inherited from class org.apache.commons.math3.ode.AbstractIntegrator

      `acceptStep, addEventHandler, addEventHandler, addStepHandler, clearEventHandlers, clearStepHandlers, computeDerivatives, getCurrentSignedStepsize, getEvaluations, getEventHandlers, getMaxEvaluations, getName, getStepHandlers, initIntegration, integrate, setEquations, setMaxEvaluations, setStateInitialized`

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

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

- - ### Field Detail

    - #### scalAbsoluteTolerance

          protected double scalAbsoluteTolerance

      Allowed absolute scalar error.

    - #### scalRelativeTolerance

          protected double scalRelativeTolerance

      Allowed relative scalar error.

    - #### vecAbsoluteTolerance

          protected double[] vecAbsoluteTolerance

      Allowed absolute vectorial error.

    - #### vecRelativeTolerance

          protected double[] vecRelativeTolerance

      Allowed relative vectorial error.

    - #### mainSetDimension

          protected int mainSetDimension

      Main set dimension.

    - #### initialStep

          private double initialStep

      User supplied initial step.

    - #### minStep

          private double minStep

      Minimal step.

    - #### maxStep

          private double maxStep

      Maximal step.

  - ### Constructor Detail

    - #### AdaptiveStepsizeIntegrator

          public AdaptiveStepsizeIntegrator(String name,
                                    double minStep,
                                    double maxStep,
                                    double scalAbsoluteTolerance,
                                    double scalRelativeTolerance)

      Build an integrator with the given stepsize bounds. The default step handler does nothing.
      Parameters:
        `name` - name of the method
        `minStep` - minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
        `maxStep` - maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
        `scalAbsoluteTolerance` - allowed absolute error
        `scalRelativeTolerance` - allowed relative error

    - #### AdaptiveStepsizeIntegrator

          public AdaptiveStepsizeIntegrator(String name,
                                    double minStep,
                                    double maxStep,
                                    double[] vecAbsoluteTolerance,
                                    double[] vecRelativeTolerance)

      Build an integrator with the given stepsize bounds. The default step handler does nothing.
      Parameters:
        `name` - name of the method
        `minStep` - minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
        `maxStep` - maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
        `vecAbsoluteTolerance` - allowed absolute error
        `vecRelativeTolerance` - allowed relative error

  - ### Method Detail

    - #### setStepSizeControl

          public void setStepSizeControl(double minimalStep,
                                double maximalStep,
                                double absoluteTolerance,
                                double relativeTolerance)

      Set the adaptive step size control parameters.

      A side effect of this method is to also reset the initial step so it will be automatically computed by the integrator if `setInitialStepSize` is not called by the user.

      Parameters:
        `minimalStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
        `maximalStep` - maximal step (must be positive even for backward integration)
        `absoluteTolerance` - allowed absolute error
        `relativeTolerance` - allowed relative error

    - #### setStepSizeControl

          public void setStepSizeControl(double minimalStep,
                                double maximalStep,
                                double[] absoluteTolerance,
                                double[] relativeTolerance)

      Set the adaptive step size control parameters.

      A side effect of this method is to also reset the initial step so it will be automatically computed by the integrator if `setInitialStepSize` is not called by the user.

      Parameters:
        `minimalStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
        `maximalStep` - maximal step (must be positive even for backward integration)
        `absoluteTolerance` - allowed absolute error
        `relativeTolerance` - allowed relative error

    - #### setInitialStepSize

          public void setInitialStepSize(double initialStepSize)

      Set the initial step size.

      This method allows the user to specify an initial positive step size instead of letting the integrator guess it by itself. If this method is not called before integration is started, the initial step size will be estimated by the integrator.

      Parameters:
        `initialStepSize` - initial step size to use (must be positive even for backward integration ; providing a negative value or a value outside of the min/max step interval will lead the integrator to ignore the value and compute the initial step size by itself)

    - #### sanityChecks

          protected void sanityChecks(ExpandableStatefulODE equations,
                          double t)
                               throws DimensionMismatchException,
                                      NumberIsTooSmallException

      Check the integration span.
      Overrides:
        `sanityChecks` in class `AbstractIntegrator`
      Parameters:
        `equations` - set of differential equations
        `t` - target time for the integration
      Throws:
        `DimensionMismatchException` - if adaptive step size integrators tolerance arrays dimensions are not compatible with equations settings
        `NumberIsTooSmallException` - if integration span is too small

    - #### initializeStep

          public double initializeStep(boolean forward,
                              int order,
                              double[] scale,
                              double t0,
                              double[] y0,
                              double[] yDot0,
                              double[] y1,
                              double[] yDot1)
                                throws MaxCountExceededException,
                                       DimensionMismatchException

      Initialize the integration step.
      Parameters:
        `forward` - forward integration indicator
        `order` - order of the method
        `scale` - scaling vector for the state vector (can be shorter than state vector)
        `t0` - start time
        `y0` - state vector at t0
        `yDot0` - first time derivative of y0
        `y1` - work array for a state vector
        `yDot1` - work array for the first time derivative of y1
      Returns:
        first integration step
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
        `DimensionMismatchException` - if arrays dimensions do not match equations settings

    - #### filterStep

          protected double filterStep(double h,
                          boolean forward,
                          boolean acceptSmall)
                               throws NumberIsTooSmallException

      Filter the integration step.
      Parameters:
        `h` - signed step
        `forward` - forward integration indicator
        `acceptSmall` - if true, steps smaller than the minimal value are silently increased up to this value, if false such small steps generate an exception
      Returns:
        a bounded integration step (h if no bound is reach, or a bounded value)
      Throws:
        `NumberIsTooSmallException` - if the step is too small and acceptSmall is false

    - #### integrate

          public abstract void integrate(ExpandableStatefulODE equations,
                       double t)
                                  throws NumberIsTooSmallException,
                                         DimensionMismatchException,
                                         MaxCountExceededException,
                                         NoBracketingException

      Integrate a set of differential equations up to the given time.

      This method solves an Initial Value Problem (IVP).

      The set of differential equations is composed of a main set, which can be extended by some sets of secondary equations. The set of equations must be already set up with initial time and partial states. At integration completion, the final time and partial states will be available in the same object.

      Since this method stores some internal state variables made available in its public interface during integration (`AbstractIntegrator.getCurrentSignedStepsize()`), it is not thread-safe.

      Specified by:
        `integrate` in class `AbstractIntegrator`
      Parameters:
        `equations` - complete set of differential equations to integrate
        `t` - target time for the integration (can be set to a value smaller than `t0` for backward integration)
      Throws:
        `NumberIsTooSmallException` - if integration step is too small
        `DimensionMismatchException` - if the dimension of the complete state does not match the complete equations sets dimension
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
        `NoBracketingException` - if the location of an event cannot be bracketed

    - #### getCurrentStepStart

          public double getCurrentStepStart()

      Get the current value of the step start time ti.

      This method can be called during integration (typically by the object implementing the `differential equations` problem) if the value of the current step that is attempted is needed.

      The result is undefined if the method is called outside of calls to `integrate`.

      Specified by:
        `getCurrentStepStart` in interface `ODEIntegrator`
      Overrides:
        `getCurrentStepStart` in class `AbstractIntegrator`
      Returns:
        current value of the step start time ti

    - #### resetInternalState

          protected void resetInternalState()

      Reset internal state to dummy values.

    - #### getMinStep

          public double getMinStep()

      Get the minimal step.
      Returns:
        minimal step

    - #### getMaxStep

          public double getMaxStep()

      Get the maximal step.
      Returns:
        maximal step

Copyright (c) 2003-2013 Apache Software Foundation