fr.cnes.sirius.patrius.math.ode.nonstiff

Class AdaptiveStepsizeIntegrator

java.lang.Object

java.util.Observable

fr.cnes.sirius.patrius.math.ode.AbstractIntegrator

fr.cnes.sirius.patrius.math.ode.nonstiff.AdaptiveStepsizeIntegrator

All Implemented Interfaces:

FirstOrderIntegrator, ODEIntegrator

Direct Known Subclasses:

EmbeddedRungeKuttaIntegrator, GraggBulirschStoerIntegrator, MultistepIntegrator

public abstract class AdaptiveStepsizeIntegrator
extends AbstractIntegrator

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

Version:

$Id: AdaptiveStepsizeIntegrator.java 18108 2017-10-04 06:45:27Z bignon $

Field Summary

Fields

Modifier and Type	Field and Description
protected int	mainSetDimension Main set dimension.
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.

Fields inherited from class fr.cnes.sirius.patrius.math.ode.AbstractIntegrator

isLastStep, lastStepHandle, resetOccurred, stepHandlers, stepSize, stepStart

Constructor Summary

Constructors

Constructor and Description
AdaptiveStepsizeIntegrator(String name, double minStepIn, double maxStepIn, double[] vecAbsoluteToleranceIn, double[] vecRelativeToleranceIn, boolean acceptSmall) Build an integrator with the given stepsize bounds.
AdaptiveStepsizeIntegrator(String name, double minStepIn, double maxStepIn, double scalAbsoluteToleranceIn, double scalRelativeToleranceIn, boolean acceptSmall) Build an integrator with the given stepsize bounds.

Method Summary

Modifier and Type	Method and Description
protected double	filterStep(double h, boolean forward, boolean acceptSmallIn) Filter the integration step.
double	getCurrentStepStart() Get the current value of the step start time ti.
double	getMaxStep() Get the maximal step.
double	getMinStep() Get the minimal step.
double	initializeStep(boolean forward, int order, double[] scale, double t0, double[] y0, double[] yDot0, double[] y1, double[] yDot1, double t) Initialize the integration step.
abstract void	integrate(ExpandableStatefulODE equations, double t) Integrate a set of differential equations up to the given time.
protected void	resetInternalState() Reset internal state to dummy values.
protected void	sanityChecks(ExpandableStatefulODE equations, double t) Check the integration span.
void	setInitialStepSize(double initialStepSize) Set the initial step size.
void	setStepSizeControl(double minimalStep, double maximalStep, double[] absoluteTolerance, double[] relativeTolerance, boolean acceptSmallIn) Set the adaptive step size control parameters.
void	setStepSizeControl(double minimalStep, double maximalStep, double absoluteTolerance, double relativeTolerance, boolean acceptSmallIn) Set the adaptive step size control parameters.

Methods inherited from class fr.cnes.sirius.patrius.math.ode.AbstractIntegrator

acceptStep, addEventHandler, addEventHandler, addStepHandler, clearEventHandlers, clearStepHandlers, computeDerivatives, getCurrentSignedStepsize, getEvaluations, getEventHandlers, getMaxEvaluations, getName, getStepHandlers, handleLastStep, initIntegration, integrate, removeEventState, setEquations, setMaxEvaluations, setStateInitialized

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

scalAbsoluteTolerance

protected double scalAbsoluteTolerance

Allowed absolute scalar error.

scalRelativeTolerance

protected double scalRelativeTolerance

Allowed relative scalar error.

vecAbsoluteTolerance

protected double[] vecAbsoluteTolerance

Allowed absolute vectorial error.

vecRelativeTolerance

protected double[] vecRelativeTolerance

Allowed relative vectorial error.

mainSetDimension

protected int mainSetDimension

Main set dimension.

Constructor Detail

AdaptiveStepsizeIntegrator

public AdaptiveStepsizeIntegrator(String name,
                                  double minStepIn,
                                  double maxStepIn,
                                  double scalAbsoluteToleranceIn,
                                  double scalRelativeToleranceIn,
                                  boolean acceptSmall)

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

Parameters:

name - name of the method

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

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

scalAbsoluteToleranceIn - allowed absolute error

scalRelativeToleranceIn - allowed relative error

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

AdaptiveStepsizeIntegrator

public AdaptiveStepsizeIntegrator(String name,
                                  double minStepIn,
                                  double maxStepIn,
                                  double[] vecAbsoluteToleranceIn,
                                  double[] vecRelativeToleranceIn,
                                  boolean acceptSmall)

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

Parameters:

name - name of the method

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

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

vecAbsoluteToleranceIn - allowed absolute error

vecRelativeToleranceIn - allowed relative error

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

Method Detail

setStepSizeControl

public void setStepSizeControl(double minimalStep,
                               double maximalStep,
                               double absoluteTolerance,
                               double relativeTolerance,
                               boolean acceptSmallIn)

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 - minimal step (must be positive even for backward integration), the last step can be smaller than this

maximalStep - maximal step (must be positive even for backward integration)

absoluteTolerance - allowed absolute error

relativeTolerance - allowed relative error

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

setStepSizeControl

public void setStepSizeControl(double minimalStep,
                               double maximalStep,
                               double[] absoluteTolerance,
                               double[] relativeTolerance,
                               boolean acceptSmallIn)

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 - minimal step (must be positive even for backward integration), the last step can be smaller than this

maximalStep - maximal step (must be positive even for backward integration)

absoluteTolerance - allowed absolute error

relativeTolerance - allowed relative error

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

setInitialStepSize

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

sanityChecks

protected void sanityChecks(ExpandableStatefulODE equations,
                            double t)

Check the integration span.

Overrides:

sanityChecks in class AbstractIntegrator

Parameters:

equations - set of differential equations

t - target time for the integration

initializeStep

public double initializeStep(boolean forward,
                             int order,
                             double[] scale,
                             double t0,
                             double[] y0,
                             double[] yDot0,
                             double[] y1,
                             double[] yDot1,
                             double t)

Initialize the integration step.

Parameters:

forward - forward integration indicator

order - order of the method

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

t0 - start time

y0 - state vector at t0

yDot0 - first time derivative of y0

y1 - work array for a state vector

yDot1 - work array for the first time derivative of y1

t - final integration time

Returns:

first integration step

Throws:

MaxCountExceededException - if the number of functions evaluations is exceeded

DimensionMismatchException - if arrays dimensions do not match equations settings

NumberIsTooSmallException - if the step is too small and acceptSmall is false

filterStep

protected double filterStep(double h,
                            boolean forward,
                            boolean acceptSmallIn)

Filter the integration step.

Parameters:

h - signed step

forward - forward integration indicator

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

Returns:

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

Throws:

NumberIsTooSmallException - if the step is too small and acceptSmall is false

integrate

public abstract void integrate(ExpandableStatefulODE equations,
                               double t)

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

Specified by:

integrate in class AbstractIntegrator

Parameters:

equations - complete set of differential equations to integrate

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

getCurrentStepStart

public double getCurrentStepStart()

Get the current value of the step start time t_i.

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.

Specified by:

getCurrentStepStart in interface ODEIntegrator

Overrides:

getCurrentStepStart in class AbstractIntegrator

Returns:

current value of the step start time t_i

resetInternalState

protected void resetInternalState()

Reset internal state to dummy values.

getMinStep

public double getMinStep()

Get the minimal step.

Returns:

minimal step

getMaxStep

public double getMaxStep()

Get the maximal step.

Returns:

maximal step