org.apache.commons.math3.ode

## Class MultistepIntegrator

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

- All Implemented Interfaces:
    FirstOrderIntegrator, ODEIntegrator
  Direct Known Subclasses:
    AdamsIntegrator

      public abstract class MultistepIntegrator
      extends AdaptiveStepsizeIntegrator

  This class is the base class for multistep integrators for Ordinary Differential Equations.

  We define scaled derivatives si(n) at step n as:

       s1(n) = h y'n for first derivative
       s2(n) = h2/2 y''n for second derivative
       s3(n) = h3/6 y'''n for third derivative
       ...
       sk(n) = hk/k! y(k)n for kth derivative

  Rather than storing several previous steps separately, this implementation uses the Nordsieck vector with higher degrees scaled derivatives all taken at the same step (yn, s1(n) and rn) where rn is defined as:

       rn = [ s2(n), s3(n) ... sk(n) ]T

  (we omit the k index in the notation for clarity)

  Multistep integrators with Nordsieck representation are highly sensitive to large step changes because when the step is multiplied by factor a, the kth component of the Nordsieck vector is multiplied by ak and the last components are the least accurate ones. The default max growth factor is therefore set to a quite low value: 21/order.

  Since:
    2.0
  Version:
    $Id: MultistepIntegrator.java 1421448 2012-12-13 19:45:57Z tn $
  See Also:
    `AdamsBashforthIntegrator`, `AdamsMoultonIntegrator`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private class` | `MultistepIntegrator.CountingDifferentialEquations` Wrapper for differential equations, ensuring start evaluations are counted.
    `private static class` | `MultistepIntegrator.InitializationCompletedMarkerException` Marker exception used ONLY to stop the starter integrator after first step.
    `private class` | `MultistepIntegrator.NordsieckInitializer` Specialized step handler storing the first step.
    `static interface` | `MultistepIntegrator.NordsieckTransformer` Transformer used to convert the first step to Nordsieck representation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `exp` Stepsize control exponent.
    `private double` | `maxGrowth` Maximal growth factor for stepsize control.
    `private double` | `minReduction` Minimal reduction factor for stepsize control.
    `protected Array2DRowRealMatrix` | `nordsieck` Nordsieck matrix of the higher scaled derivatives.
    `private int` | `nSteps` Number of steps of the multistep method (excluding the one being computed).
    `private double` | `safety` Safety factor for stepsize control.
    `protected double[]` | `scaled` First scaled derivative (h y').
    `private FirstOrderIntegrator` | `starter` Starter integrator.

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

      `mainSetDimension, scalAbsoluteTolerance, scalRelativeTolerance, vecAbsoluteTolerance, vecRelativeTolerance`

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

      `isLastStep, resetOccurred, stepHandlers, stepSize, stepStart`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `MultistepIntegrator(String name, int nSteps, int order, double minStep, double maxStep, double[] vecAbsoluteTolerance, double[] vecRelativeTolerance)` Build a multistep integrator with the given stepsize bounds.
    `protected` | `MultistepIntegrator(String name, int nSteps, int order, double minStep, double maxStep, double scalAbsoluteTolerance, double scalRelativeTolerance)` Build a multistep integrator with the given stepsize bounds.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `computeStepGrowShrinkFactor(double error)` Compute step grow/shrink factor according to normalized error.
    `double` | `getMaxGrowth()` Get the maximal growth factor for stepsize control.
    `double` | `getMinReduction()` Get the minimal reduction factor for stepsize control.
    `double` | `getSafety()` Get the safety factor for stepsize control.
    `ODEIntegrator` | `getStarterIntegrator()` Get the starter integrator.
    `protected abstract Array2DRowRealMatrix` | `initializeHighOrderDerivatives(double h, double[] t, double[][] y, double[][] yDot)` Initialize the high order scaled derivatives at step start.
    `void` | `setMaxGrowth(double maxGrowth)` Set the maximal growth factor for stepsize control.
    `void` | `setMinReduction(double minReduction)` Set the minimal reduction factor for stepsize control.
    `void` | `setSafety(double safety)` Set the safety factor for stepsize control.
    `void` | `setStarterIntegrator(FirstOrderIntegrator starterIntegrator)` Set the starter integrator.
    `protected void` | `start(double t0, double[] y0, double t)` Start the integration.

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

      `filterStep, getCurrentStepStart, getMaxStep, getMinStep, initializeStep, integrate, resetInternalState, sanityChecks, setInitialStepSize, setStepSizeControl, setStepSizeControl`

    - ### 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

    - #### scaled

          protected double[] scaled

      First scaled derivative (h y').

    - #### nordsieck

          protected Array2DRowRealMatrix nordsieck

      Nordsieck matrix of the higher scaled derivatives.

      (h2/2 y'', h3/6 y''' ..., hk/k! y(k))

    - #### starter

          private FirstOrderIntegrator starter

      Starter integrator.

    - #### nSteps

          private final int nSteps

      Number of steps of the multistep method (excluding the one being computed).

    - #### exp

          private double exp

      Stepsize control exponent.

    - #### safety

          private double safety

      Safety factor for stepsize control.

    - #### minReduction

          private double minReduction

      Minimal reduction factor for stepsize control.

    - #### maxGrowth

          private double maxGrowth

      Maximal growth factor for stepsize control.

  - ### Constructor Detail

    - #### MultistepIntegrator

          protected MultistepIntegrator(String name,
                             int nSteps,
                             int order,
                             double minStep,
                             double maxStep,
                             double scalAbsoluteTolerance,
                             double scalRelativeTolerance)
                                 throws NumberIsTooSmallException

      Build a multistep integrator with the given stepsize bounds.

      The default starter integrator is set to the `Dormand-Prince 8(5,3)` integrator with some defaults settings.

      The default max growth factor is set to a quite low value: 21/order.

      Parameters:
        `name` - name of the method
        `nSteps` - number of steps of the multistep method (excluding the one being computed)
        `order` - order of the method
        `minStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
        `maxStep` - maximal step (must be positive even for backward integration)
        `scalAbsoluteTolerance` - allowed absolute error
        `scalRelativeTolerance` - allowed relative error
      Throws:
        `NumberIsTooSmallException` - if number of steps is smaller than 2

    - #### MultistepIntegrator

          protected MultistepIntegrator(String name,
                             int nSteps,
                             int order,
                             double minStep,
                             double maxStep,
                             double[] vecAbsoluteTolerance,
                             double[] vecRelativeTolerance)

      Build a multistep integrator with the given stepsize bounds.

      The default starter integrator is set to the `Dormand-Prince 8(5,3)` integrator with some defaults settings.

      The default max growth factor is set to a quite low value: 21/order.

      Parameters:
        `name` - name of the method
        `nSteps` - number of steps of the multistep method (excluding the one being computed)
        `order` - order of the method
        `minStep` - minimal step (must be positive even for backward integration), the last step can be smaller than this
        `maxStep` - maximal step (must be positive even for backward integration)
        `vecAbsoluteTolerance` - allowed absolute error
        `vecRelativeTolerance` - allowed relative error

  - ### Method Detail

    - #### getStarterIntegrator

          public ODEIntegrator getStarterIntegrator()

      Get the starter integrator.
      Returns:
        starter integrator

    - #### setStarterIntegrator

          public void setStarterIntegrator(FirstOrderIntegrator starterIntegrator)

      Set the starter integrator.

      The various step and event handlers for this starter integrator will be managed automatically by the multi-step integrator. Any user configuration for these elements will be cleared before use.

      Parameters:
        `starterIntegrator` - starter integrator

    - #### start

          protected void start(double t0,
                   double[] y0,
                   double t)
                        throws DimensionMismatchException,
                               NumberIsTooSmallException,
                               MaxCountExceededException,
                               NoBracketingException

      Start the integration.

      This method computes one step using the underlying starter integrator, and initializes the Nordsieck vector at step start. The starter integrator purpose is only to establish initial conditions, it does not really change time by itself. The top level multistep integrator remains in charge of handling time propagation and events handling as it will starts its own computation right from the beginning. In a sense, the starter integrator can be seen as a dummy one and so it will never trigger any user event nor call any user step handler.

      Parameters:
        `t0` - initial time
        `y0` - initial value of the state vector at t0
        `t` - target time for the integration (can be set to a value smaller than `t0` for backward integration)
      Throws:
        `DimensionMismatchException` - if arrays dimension do not match equations settings
        `NumberIsTooSmallException` - if integration step is too small
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
        `NoBracketingException` - if the location of an event cannot be bracketed

    - #### initializeHighOrderDerivatives

          protected abstract Array2DRowRealMatrix initializeHighOrderDerivatives(double h,
                                                            double[] t,
                                                            double[][] y,
                                                            double[][] yDot)

      Initialize the high order scaled derivatives at step start.
      Parameters:
        `h` - step size to use for scaling
        `t` - first steps times
        `y` - first steps states
        `yDot` - first steps derivatives
      Returns:
        Nordieck vector at first step (h2/2 y''n, h3/6 y'''n ... hk/k! y(k)n)

    - #### getMinReduction

          public double getMinReduction()

      Get the minimal reduction factor for stepsize control.
      Returns:
        minimal reduction factor

    - #### setMinReduction

          public void setMinReduction(double minReduction)

      Set the minimal reduction factor for stepsize control.
      Parameters:
        `minReduction` - minimal reduction factor

    - #### getMaxGrowth

          public double getMaxGrowth()

      Get the maximal growth factor for stepsize control.
      Returns:
        maximal growth factor

    - #### setMaxGrowth

          public void setMaxGrowth(double maxGrowth)

      Set the maximal growth factor for stepsize control.
      Parameters:
        `maxGrowth` - maximal growth factor

    - #### getSafety

          public double getSafety()

      Get the safety factor for stepsize control.
      Returns:
        safety factor

    - #### setSafety

          public void setSafety(double safety)

      Set the safety factor for stepsize control.
      Parameters:
        `safety` - safety factor

    - #### computeStepGrowShrinkFactor

          protected double computeStepGrowShrinkFactor(double error)

      Compute step grow/shrink factor according to normalized error.
      Parameters:
        `error` - normalized error of the current step
      Returns:
        grow/shrink factor for next step

Copyright (c) 2003-2013 Apache Software Foundation