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

public abstract Class AdaptiveStepsizeIntegrator

extends AbstractIntegrator
Class Inheritance
Known Direct Subclasses
org.apache.commons.math3.ode.nonstiff.GraggBulirschStoerIntegrator, org.apache.commons.math3.ode.nonstiff.EmbeddedRungeKuttaIntegrator, org.apache.commons.math3.ode.MultistepIntegrator
Imports
org.apache.commons.math3.exception.DimensionMismatchException, .MaxCountExceededException, .NoBracketingException, .NumberIsTooSmallException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.ode.AbstractIntegrator, .ExpandableStatefulODE, org.apache.commons.math3.util.FastMath
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

Field Summary

Modifier and TypeField 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.

Inherited from org.apache.commons.math3.ode.AbstractIntegrator:
isLastStepresetOccurredstepHandlersstepSizestepStart

Constructor Summary

AccessConstructor and Description
public
AdaptiveStepsizeIntegrator(final String
name of the method
name, final double
minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
minStep, final double
maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
maxStep, final double
allowed absolute error
scalAbsoluteTolerance, final double
allowed relative error
scalRelativeTolerance)

Build an integrator with the given stepsize bounds.

public
AdaptiveStepsizeIntegrator(final String
name of the method
name, final double
minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
minStep, final double
maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this
maxStep, final double[]
allowed absolute error
vecAbsoluteTolerance, final double[]
allowed relative error
vecRelativeTolerance)

Build an integrator with the given stepsize bounds.

Method Summary

Modifier and TypeMethod and Description
protected double

Returns:

a bounded integration step (h if no bound is reach, or a bounded value)
filterStep(final double
signed step
h, final boolean
forward integration indicator
forward, final boolean
if true, steps smaller than the minimal value are silently increased up to this value, if false such small steps generate an exception
acceptSmall)

Filter the integration step.

public double
getCurrentStepStart()

Overrides org.apache.commons.math3.ode.AbstractIntegrator.getCurrentStepStart.

Implements org.apache.commons.math3.ode.ODEIntegrator.getCurrentStepStart.

Get the current value of the step start time ti.

public double

Returns:

maximal step
getMaxStep()

Get the maximal step.

public double

Returns:

minimal step
getMinStep()

Get the minimal step.

public double

Returns:

first integration step
initializeStep(final boolean
forward integration indicator
forward, final int
order of the method
order, final double[]
scaling vector for the state vector (can be shorter than state vector)
scale, final double
start time
t0, final double[]
state vector at t0
y0, final double[]
first time derivative of y0
yDot0, final double[]
work array for a state vector
y1, final double[]
work array for the first time derivative of y1
yDot1)

Initialize the integration step.

public abstract void
integrate(ExpandableStatefulODE
complete set of differential equations to integrate
equations, double
target time for the integration (can be set to a value smaller than t0 for backward integration)
t)

Implements abstract org.apache.commons.math3.ode.AbstractIntegrator.integrate.

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

protected void
resetInternalState()

Reset internal state to dummy values.

protected void
sanityChecks(final ExpandableStatefulODE
set of differential equations
equations, final double
target time for the integration
t)

Overrides org.apache.commons.math3.ode.AbstractIntegrator.sanityChecks.

Check the integration span.

public void
setInitialStepSize(final double
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)
initialStepSize)

Set the initial step size.

public void
setStepSizeControl(final double
minimal step (must be positive even for backward integration), the last step can be smaller than this
minimalStep, final double
maximal step (must be positive even for backward integration)
maximalStep, final double
allowed absolute error
absoluteTolerance, final double
allowed relative error
relativeTolerance)

Set the adaptive step size control parameters.

public void
setStepSizeControl(final double
minimal step (must be positive even for backward integration), the last step can be smaller than this
minimalStep, final double
maximal step (must be positive even for backward integration)
maximalStep, final double[]
allowed absolute error
absoluteTolerance, final double[]
allowed relative error
relativeTolerance)

Set the adaptive step size control parameters.

Inherited from org.apache.commons.math3.ode.AbstractIntegrator:
acceptStepaddEventHandleraddEventHandleraddStepHandlerclearEventHandlersclearStepHandlerscomputeDerivativesgetCountergetCurrentSignedStepsizegetEvaluationsgetEvaluationsCountergetEventHandlersgetExpandablegetMaxEvaluationsgetNamegetStepHandlersinitIntegrationintegratesetEquationssetMaxEvaluationssetStateInitialized

Field Detail

initialStepback to summary
private double initialStep

User supplied initial step.

mainSetDimensionback to summary
protected int mainSetDimension

Main set dimension.

maxStepback to summary
private double maxStep

Maximal step.

minStepback to summary
private double minStep

Minimal step.

scalAbsoluteToleranceback to summary
protected double scalAbsoluteTolerance

Allowed absolute scalar error.

scalRelativeToleranceback to summary
protected double scalRelativeTolerance

Allowed relative scalar error.

vecAbsoluteToleranceback to summary
protected double[] vecAbsoluteTolerance

Allowed absolute vectorial error.

vecRelativeToleranceback to summary
protected double[] vecRelativeTolerance

Allowed relative vectorial error.

Constructor Detail

AdaptiveStepsizeIntegratorback to summary
public AdaptiveStepsizeIntegrator(final String name, final double minStep, final double maxStep, final double scalAbsoluteTolerance, final double scalRelativeTolerance)

Build an integrator with the given stepsize bounds. The default step handler does nothing.

Parameters
name:String

name of the method

minStep:double

minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this

maxStep:double

maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this

scalAbsoluteTolerance:double

allowed absolute error

scalRelativeTolerance:double

allowed relative error

AdaptiveStepsizeIntegratorback to summary
public AdaptiveStepsizeIntegrator(final String name, final double minStep, final double maxStep, final double[] vecAbsoluteTolerance, final double[] vecRelativeTolerance)

Build an integrator with the given stepsize bounds. The default step handler does nothing.

Parameters
name:String

name of the method

minStep:double

minimal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this

maxStep:double

maximal step (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this

vecAbsoluteTolerance:double[]

allowed absolute error

vecRelativeTolerance:double[]

allowed relative error

Method Detail

filterStepback to summary
protected double filterStep(final double h, final boolean forward, final boolean acceptSmall) throws NumberIsTooSmallException

Filter the integration step.

Parameters
h:double

signed step

forward:boolean

forward integration indicator

acceptSmall:boolean

if true, steps smaller than the minimal value are silently increased up to this value, if false such small steps generate an exception

Returns:double

a bounded integration step (h if no bound is reach, or a bounded value)

Exceptions
NumberIsTooSmallException:
if the step is too small and acceptSmall is false
getCurrentStepStartback to summary
public double getCurrentStepStart()

Overrides org.apache.commons.math3.ode.AbstractIntegrator.getCurrentStepStart.

Implements org.apache.commons.math3.ode.ODEIntegrator.getCurrentStepStart.

Doc from org.apache.commons.math3.ode.AbstractIntegrator.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.

Returns:double

Doc from org.apache.commons.math3.ode.ODEIntegrator.getCurrentStepStart.

current value of the step start time ti

Annotations
@Override
getMaxStepback to summary
public double getMaxStep()

Get the maximal step.

Returns:double

maximal step

getMinStepback to summary
public double getMinStep()

Get the minimal step.

Returns:double

minimal step

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

Initialize the integration step.

Parameters
forward:boolean

forward integration indicator

order:int

order of the method

scale:double[]

scaling vector for the state vector (can be shorter than state vector)

t0:double

start time

y0:double[]

state vector at t0

yDot0:double[]

first time derivative of y0

y1:double[]

work array for a state vector

yDot1:double[]

work array for the first time derivative of y1

Returns:double

first integration step

Exceptions
MaxCountExceededException:
if the number of functions evaluations is exceeded
DimensionMismatchException:
if arrays dimensions do not match equations settings
integrateback to summary
public abstract void integrate(ExpandableStatefulODE equations, double t) throws NumberIsTooSmallException, DimensionMismatchException, MaxCountExceededException, NoBracketingException

Implements abstract org.apache.commons.math3.ode.AbstractIntegrator.integrate.

Doc from org.apache.commons.math3.ode.AbstractIntegrator.integrate.

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 (getCurrentSignedStepsize()), it is not thread-safe.

Parameters
equations:ExpandableStatefulODE

complete set of differential equations to integrate

t:double

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

Annotations
@Override
Exceptions
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
resetInternalStateback to summary
protected void resetInternalState()

Reset internal state to dummy values.

sanityChecksback to summary
protected void sanityChecks(final ExpandableStatefulODE equations, final double t) throws DimensionMismatchException, NumberIsTooSmallException

Overrides org.apache.commons.math3.ode.AbstractIntegrator.sanityChecks.

Doc from org.apache.commons.math3.ode.AbstractIntegrator.sanityChecks.

Check the integration span.

Parameters
equations:ExpandableStatefulODE

set of differential equations

t:double

target time for the integration

Annotations
@Override
Exceptions
DimensionMismatchException:
if adaptive step size integrators tolerance arrays dimensions are not compatible with equations settings
NumberIsTooSmallException:
if integration span is too small
setInitialStepSizeback to summary
public void setInitialStepSize(final 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:double

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)

setStepSizeControlback to summary
public void setStepSizeControl(final double minimalStep, final double maximalStep, final double absoluteTolerance, final 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:double

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

maximalStep:double

maximal step (must be positive even for backward integration)

absoluteTolerance:double

allowed absolute error

relativeTolerance:double

allowed relative error

setStepSizeControlback to summary
public void setStepSizeControl(final double minimalStep, final double maximalStep, final double[] absoluteTolerance, final 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:double

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

maximalStep:double

maximal step (must be positive even for backward integration)

absoluteTolerance:double[]

allowed absolute error

relativeTolerance:double[]

allowed relative error