Package org.apache.commons.math.ode

Class 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 a 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:
    $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 févr. 2011) $
    See Also:
    AdamsBashforthIntegrator, AdamsMoultonIntegrator

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

    • Constructor Detail

      • MultistepIntegrator

        protected MultistepIntegrator​(java.lang.String name,
                              int nSteps,
                              int order,
                              double minStep,
                              double maxStep,
                              double scalAbsoluteTolerance,
                              double scalRelativeTolerance)
        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

      • MultistepIntegrator

        protected MultistepIntegrator​(java.lang.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 DerivativeException,
                     IntegratorException
        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:
        IntegratorException - if the integrator cannot perform integration
        DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

      • initializeHighOrderDerivatives

        protected abstract Array2DRowRealMatrix initializeHighOrderDerivatives​(double[] first,
                                                                       double[][] multistep)
        Initialize the high order scaled derivatives at step start.
        Parameters:
        first - first scaled derivative at step start
        multistep - scaled derivatives after step start (hy'1, ..., hy'k-1) will be modified
        Returns:
        high order scaled derivatives at step start

      • 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