Top Description Inners Fields Constructors Methods
org.apache.commons.math3.ode

public abstract Class MultistepFieldIntegrator<T extends RealFieldElement<T>>

extends AdaptiveStepsizeFieldIntegrator<T extends RealFieldElement<T>>
Class Inheritance
Known Direct Subclasses
org.apache.commons.math3.ode.nonstiff.AdamsFieldIntegrator
Type Parameters
<T>
the type of the field elements
Imports
org.apache.commons.math3.Field, .RealFieldElement, org.apache.commons.math3.exception.DimensionMismatchException, .MathIllegalStateException, .MaxCountExceededException, .NoBracketingException, .NumberIsTooSmallException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.linear.Array2DRowFieldMatrix, org.apache.commons.math3.ode.nonstiff.AdaptiveStepsizeFieldIntegrator, .DormandPrince853FieldIntegrator, org.apache.commons.math3.ode.sampling.FieldStepHandler, .FieldStepInterpolator, org.apache.commons.math3.util.FastMath, .MathArrays, .MathUtils
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
3.6
See Also
org.apache.commons.math3.ode.nonstiff.AdamsBashforthFieldIntegrator, org.apache.commons.math3.ode.nonstiff.AdamsMoultonFieldIntegrator

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
MultistepFieldIntegrator.FieldNordsieckInitializer

Specialized step handler storing the first step.

private static class
MultistepFieldIntegrator.InitializationCompletedMarkerException

Marker exception used ONLY to stop the starter integrator after first step.

Field Summary

Modifier and TypeField 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 Array2DRowFieldMatrix<T>
nordsieck

Nordsieck matrix of the higher scaled derivatives.

private final int
nSteps

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

private double
safety

Safety factor for stepsize control.

protected T[]
scaled

First scaled derivative (h y').

private FirstOrderFieldIntegrator<T>
starter

Starter integrator.

Inherited from org.apache.commons.math3.ode.nonstiff.AdaptiveStepsizeFieldIntegrator:
mainSetDimensionscalAbsoluteTolerancescalRelativeTolerancevecAbsoluteTolerancevecRelativeTolerance

Constructor Summary

AccessConstructor and Description
protected
MultistepFieldIntegrator(final Field<T>
field to which the time and state vector elements belong
field, final String
name of the method
name, final int
number of steps of the multistep method (excluding the one being computed)
nSteps, final int
order of the method
order, final double
minimal step (must be positive even for backward integration), the last step can be smaller than this
minStep, final double
maximal step (must be positive even for backward integration)
maxStep, final double
allowed absolute error
scalAbsoluteTolerance, final double
allowed relative error
scalRelativeTolerance)

Build a multistep integrator with the given stepsize bounds.

protected
MultistepFieldIntegrator(final Field<T>
field to which the time and state vector elements belong
field, final String
name of the method
name, final int
number of steps of the multistep method (excluding the one being computed)
nSteps, final int
order of the method
order, final double
minimal step (must be positive even for backward integration), the last step can be smaller than this
minStep, final double
maximal step (must be positive even for backward integration)
maxStep, final double[]
allowed absolute error
vecAbsoluteTolerance, final double[]
allowed relative error
vecRelativeTolerance)

Build a multistep integrator with the given stepsize bounds.

Method Summary

Modifier and TypeMethod and Description
protected T

Returns:

grow/shrink factor for next step
computeStepGrowShrinkFactor(final T
normalized error of the current step
error)

Compute step grow/shrink factor according to normalized error.

public double

Returns:

maximal growth factor
getMaxGrowth()

Get the maximal growth factor for stepsize control.

public double

Returns:

minimal reduction factor
getMinReduction()

Get the minimal reduction factor for stepsize control.

public int

Returns:

number of steps of the multistep method (excluding the one being computed)
getNSteps()

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

public double

Returns:

safety factor
getSafety()

Get the safety factor for stepsize control.

public FirstOrderFieldIntegrator<T>

Returns:

starter integrator
getStarterIntegrator()

Get the starter integrator.

protected abstract Array2DRowFieldMatrix<T>

Returns:

Nordieck vector at first step (h2/2 y''n, h3/6 y'''n ... hk/k! y(k)n)
initializeHighOrderDerivatives(final T
step size to use for scaling
h, final T[]
first steps times
t, final T[][]
first steps states
y, final T[][]
first steps derivatives
yDot)

Initialize the high order scaled derivatives at step start.

protected void
rescale(final T
new step size to use in the scaled and Nordsieck arrays
newStepSize)

Rescale the instance.

public void
setMaxGrowth(final double
maximal growth factor
maxGrowth)

Set the maximal growth factor for stepsize control.

public void
setMinReduction(final double
minimal reduction factor
minReduction)

Set the minimal reduction factor for stepsize control.

public void
setSafety(final double
safety factor
safety)

Set the safety factor for stepsize control.

public void
setStarterIntegrator(FirstOrderFieldIntegrator<T>
starter integrator
starterIntegrator)

Set the starter integrator.

protected void
start(final FieldExpandableODE<T>
complete set of differential equations to integrate
equations, final FieldODEState<T>
initial state (time, primary and secondary state vectors)
initialState, final T
target time for the integration (can be set to a value smaller than t0 for backward integration)
t)

Start the integration.

Inherited from org.apache.commons.math3.ode.nonstiff.AdaptiveStepsizeFieldIntegrator:
filterStepgetMaxStepgetMinStepinitializeStepresetInternalStatesanityCheckssetInitialStepSizesetStepSizeControlsetStepSizeControl

Field Detail

expback to summary
private double exp

Stepsize control exponent.

maxGrowthback to summary
private double maxGrowth

Maximal growth factor for stepsize control.

minReductionback to summary
private double minReduction

Minimal reduction factor for stepsize control.

nordsieckback to summary
protected Array2DRowFieldMatrix<T> nordsieck

Nordsieck matrix of the higher scaled derivatives.

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

nStepsback to summary
private final int nSteps

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

safetyback to summary
private double safety

Safety factor for stepsize control.

scaledback to summary
protected T[] scaled

First scaled derivative (h y').

starterback to summary
private FirstOrderFieldIntegrator<T> starter

Starter integrator.

Constructor Detail

MultistepFieldIntegratorback to summary
protected MultistepFieldIntegrator(final Field<T> field, final String name, final int nSteps, final int order, final double minStep, final double maxStep, final double scalAbsoluteTolerance, final 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
field:Field<T>

field to which the time and state vector elements belong

name:String

name of the method

nSteps:int

number of steps of the multistep method (excluding the one being computed)

order:int

order of the method

minStep:double

minimal step (must be positive even for backward integration), the last step can be smaller than this

maxStep:double

maximal step (must be positive even for backward integration)

scalAbsoluteTolerance:double

allowed absolute error

scalRelativeTolerance:double

allowed relative error

Exceptions
NumberIsTooSmallException:
if number of steps is smaller than 2
MultistepFieldIntegratorback to summary
protected MultistepFieldIntegrator(final Field<T> field, final String name, final int nSteps, final int order, final double minStep, final double maxStep, final double[] vecAbsoluteTolerance, final 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
field:Field<T>

field to which the time and state vector elements belong

name:String

name of the method

nSteps:int

number of steps of the multistep method (excluding the one being computed)

order:int

order of the method

minStep:double

minimal step (must be positive even for backward integration), the last step can be smaller than this

maxStep:double

maximal step (must be positive even for backward integration)

vecAbsoluteTolerance:double[]

allowed absolute error

vecRelativeTolerance:double[]

allowed relative error

Method Detail

computeStepGrowShrinkFactorback to summary
protected T computeStepGrowShrinkFactor(final T error)

Compute step grow/shrink factor according to normalized error.

Parameters
error:T

normalized error of the current step

Returns:T

grow/shrink factor for next step

getMaxGrowthback to summary
public double getMaxGrowth()

Get the maximal growth factor for stepsize control.

Returns:double

maximal growth factor

getMinReductionback to summary
public double getMinReduction()

Get the minimal reduction factor for stepsize control.

Returns:double

minimal reduction factor

getNStepsback to summary
public int getNSteps()

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

Returns:int

number of steps of the multistep method (excluding the one being computed)

getSafetyback to summary
public double getSafety()

Get the safety factor for stepsize control.

Returns:double

safety factor

getStarterIntegratorback to summary
public FirstOrderFieldIntegrator<T> getStarterIntegrator()

Get the starter integrator.

Returns:FirstOrderFieldIntegrator<T>

starter integrator

initializeHighOrderDerivativesback to summary
protected abstract Array2DRowFieldMatrix<T> initializeHighOrderDerivatives(final T h, final T[] t, final T[][] y, final T[][] yDot)

Initialize the high order scaled derivatives at step start.

Parameters
h:T

step size to use for scaling

t:T[]

first steps times

y:T[][]

first steps states

yDot:T[][]

first steps derivatives

Returns:Array2DRowFieldMatrix<T>

Nordieck vector at first step (h2/2 y''n, h3/6 y'''n ... hk/k! y(k)n)

rescaleback to summary
protected void rescale(final T newStepSize)

Rescale the instance.

Since the scaled and Nordsieck arrays are shared with the caller, this method has the side effect of rescaling this arrays in the caller too.

Parameters
newStepSize:T

new step size to use in the scaled and Nordsieck arrays

setMaxGrowthback to summary
public void setMaxGrowth(final double maxGrowth)

Set the maximal growth factor for stepsize control.

Parameters
maxGrowth:double

maximal growth factor

setMinReductionback to summary
public void setMinReduction(final double minReduction)

Set the minimal reduction factor for stepsize control.

Parameters
minReduction:double

minimal reduction factor

setSafetyback to summary
public void setSafety(final double safety)

Set the safety factor for stepsize control.

Parameters
safety:double

safety factor

setStarterIntegratorback to summary
public void setStarterIntegrator(FirstOrderFieldIntegrator<T> 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:FirstOrderFieldIntegrator<T>

starter integrator

startback to summary
protected void start(final FieldExpandableODE<T> equations, final FieldODEState<T> initialState, final T 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
equations:FieldExpandableODE<T>

complete set of differential equations to integrate

initialState:FieldODEState<T>

initial state (time, primary and secondary state vectors)

t:T

target time for the integration (can be set to a value smaller than t0 for backward integration)

Exceptions
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
org.apache.commons.math3.ode back to summary

private Class MultistepFieldIntegrator.FieldNordsieckInitializer

extends Object
implements FieldStepHandler<T extends RealFieldElement<T>>
Class Inheritance
  • java.lang.Object
  • org.apache.commons.math3.ode.MultistepFieldIntegrator.FieldNordsieckInitializer
All Implemented Interfaces
org.apache.commons.math3.ode.sampling.FieldStepHandler
Specialized step handler storing the first step.

Field Summary

Modifier and TypeField and Description
private int
count

Steps counter.

private final FieldEquationsMapper<T>
mapper

Equation mapper.

private FieldODEStateAndDerivative<T>
savedStart

Saved start.

private final T[]
t

First steps times.

private final T[][]
y

First steps states.

private final T[][]
yDot

First steps derivatives.

Constructor Summary

AccessConstructor and Description
pack-priv
FieldNordsieckInitializer(final FieldEquationsMapper<T>
equation mapper
mapper, final int
number of start points (including the initial point)
nbStartPoints)

Simple constructor.

Method Summary

Modifier and TypeMethod and Description
public void
handleStep(FieldStepInterpolator<T>
interpolator for the last accepted step. For efficiency purposes, the various integrators reuse the same object on each call, so if the instance wants to keep it across all calls (for example to provide at the end of the integration a continuous model valid throughout the integration range, as the ContinuousOutputModel class does), it should build a local copy using the clone method of the interpolator and store this copy. Keeping only a reference to the interpolator and reusing it will result in unpredictable behavior (potentially crashing the application).
interpolator, boolean
true if the step is the last one
isLast)

Implements org.apache.commons.math3.ode.sampling.FieldStepHandler.handleStep.

Handle the last accepted step

public void
init(final FieldODEStateAndDerivative<T>
initial time, state vector and derivative
initialState, T
target time for the integration
finalTime)

Implements org.apache.commons.math3.ode.sampling.FieldStepHandler.init.

Initialize step handler at the start of an ODE integration.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

countback to summary
private int count

Steps counter.

mapperback to summary
private final FieldEquationsMapper<T> mapper

Equation mapper.

savedStartback to summary
private FieldODEStateAndDerivative<T> savedStart

Saved start.

tback to summary
private final T[] t

First steps times.

yback to summary
private final T[][] y

First steps states.

yDotback to summary
private final T[][] yDot

First steps derivatives.

Constructor Detail

FieldNordsieckInitializerback to summary
pack-priv FieldNordsieckInitializer(final FieldEquationsMapper<T> mapper, final int nbStartPoints)

Simple constructor.

Parameters
mapper:FieldEquationsMapper<T>

equation mapper

nbStartPoints:int

number of start points (including the initial point)

Method Detail

handleStepback to summary
public void handleStep(FieldStepInterpolator<T> interpolator, boolean isLast) throws MaxCountExceededException

Implements org.apache.commons.math3.ode.sampling.FieldStepHandler.handleStep.

Doc from org.apache.commons.math3.ode.sampling.FieldStepHandler.handleStep.

Handle the last accepted step

Parameters
interpolator:FieldStepInterpolator<T>

interpolator for the last accepted step. For efficiency purposes, the various integrators reuse the same object on each call, so if the instance wants to keep it across all calls (for example to provide at the end of the integration a continuous model valid throughout the integration range, as the ContinuousOutputModel class does), it should build a local copy using the clone method of the interpolator and store this copy. Keeping only a reference to the interpolator and reusing it will result in unpredictable behavior (potentially crashing the application).

isLast:boolean

true if the step is the last one

Exceptions
MaxCountExceededException:
if the interpolator throws one because the number of functions evaluations is exceeded
initback to summary
public void init(final FieldODEStateAndDerivative<T> initialState, T finalTime)

Implements org.apache.commons.math3.ode.sampling.FieldStepHandler.init.

Doc from org.apache.commons.math3.ode.sampling.FieldStepHandler.init.

Initialize step handler at the start of an ODE integration.

This method is called once at the start of the integration. It may be used by the step handler to initialize some internal data if needed.

Parameters
initialState:FieldODEStateAndDerivative<T>

initial time, state vector and derivative

finalTime:T

target time for the integration

org.apache.commons.math3.ode back to summary

private Class MultistepFieldIntegrator.InitializationCompletedMarkerException

extends RuntimeException
Class Inheritance
Marker exception used ONLY to stop the starter integrator after first step.

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Hides java.lang.RuntimeException.serialVersionUID.

Serializable version identifier.

Constructor Summary

AccessConstructor and Description
pack-priv
InitializationCompletedMarkerException()

Simple constructor.

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.lang.RuntimeException.serialVersionUID.

Serializable version identifier.

Constructor Detail

InitializationCompletedMarkerExceptionback to summary
pack-priv InitializationCompletedMarkerException()

Simple constructor.