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 s_i(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 (y_n, s₁(n) and r_n) where r_n 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 k^th component of the Nordsieck vector is multiplied by a^k and the last components are the least accurate ones. The default max growth factor is therefore set to a quite low value: 2^1/order.

Since:

2.0

See Also:

AdamsBashforthIntegrator, AdamsMoultonIntegrator

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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(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.
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.

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, getEvaluationsCounter, getEventHandlers, getExpandable, 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.

(h²/2 y'', h³/6 y''' ..., h^k/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(java.lang.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: 2^1/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(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: 2^1/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 (h²/2 y''_n, h³/6 y'''_n ... h^k/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