org.jscience.mathematics.analysis.ode
Class AdaptiveStepsizeIntegrator

java.lang.Object
  org.jscience.mathematics.analysis.ode.AdaptiveStepsizeIntegrator

All Implemented Interfaces:

FirstOrderIntegrator

Direct Known Subclasses:

GraggBulirschStoerIntegrator, RungeKuttaFehlbergIntegrator

public abstract class AdaptiveStepsizeIntegrator
extends java.lang.Object
implements FirstOrderIntegrator

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 estimated error for ym+1 is such that

 sqrt((sum (errEst_i / threshold_i)^2 ) / n) < 1
 

(where n is the state vector dimension) then the step is accepted, otherwise the step is rejected and a new attempt is made with a new stepsize.

Field Summary

protected StepHandler	handler Step handler.
protected double	scalAbsoluteTolerance Allowed absolute scalar error.
protected double	scalRelativeTolerance Allowed relative scalar error.
protected SwitchingFunctionsHandler	switchesHandler Switching functions handler.
protected double[]	vecAbsoluteTolerance Allowed absolute vectorial error.
protected double[]	vecRelativeTolerance Allowed relative vectorial error.

Constructor Summary

AdaptiveStepsizeIntegrator(double minStep, double maxStep, double[] vecAbsoluteTolerance, double[] vecRelativeTolerance)
Build an integrator with the given stepsize bounds.

AdaptiveStepsizeIntegrator(double minStep, double maxStep, double scalAbsoluteTolerance, double scalRelativeTolerance)
Build an integrator with the given stepsize bounds.

Method Summary

void	addSwitchingFunction(SwitchingFunction function, double maxCheckInterval, double convergence) Add a switching function to the integrator.
protected double	filterStep(double h, boolean acceptSmall) Filter the integration step.
double	getMaxStep() Get the maximal step.
double	getMinStep() Get the minimal step.
StepHandler	getStepHandler() Get the step handler for this integrator.
double	initializeStep(FirstOrderDifferentialEquations equations, boolean forward, int order, double[] scale, double t0, double[] y0, double[] yDot0, double[] y1, double[] yDot1) Initialize the integration step.
abstract void	integrate(FirstOrderDifferentialEquations equations, double t0, double[] y0, double t, double[] y) Integrate the differential equations up to the given time
void	setInitialStepSize(double initialStepSize) Set the initial step size.
void	setStepHandler(StepHandler handler) Set the step handler for this integrator.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jscience.mathematics.analysis.ode.FirstOrderIntegrator

getName

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.

handler

protected StepHandler handler

Step handler.

switchesHandler

protected SwitchingFunctionsHandler switchesHandler

Switching functions handler.

Constructor Detail

AdaptiveStepsizeIntegrator

public AdaptiveStepsizeIntegrator(double minStep,
                                  double maxStep,
                                  double scalAbsoluteTolerance,
                                  double scalRelativeTolerance)

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

Parameters:

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

AdaptiveStepsizeIntegrator

public AdaptiveStepsizeIntegrator(double minStep,
                                  double maxStep,
                                  double[] vecAbsoluteTolerance,
                                  double[] vecRelativeTolerance)

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

Parameters:

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

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)

setStepHandler

public void setStepHandler(StepHandler handler)

Set the step handler for this integrator. The handler will be called by the integrator for each accepted step.

Specified by:

setStepHandler in interface FirstOrderIntegrator

Parameters:

handler - handler for the accepted steps

getStepHandler

public StepHandler getStepHandler()

Get the step handler for this integrator.

Specified by:

getStepHandler in interface FirstOrderIntegrator

Returns:

the step handler for this integrator

addSwitchingFunction

public void addSwitchingFunction(SwitchingFunction function,
                                 double maxCheckInterval,
                                 double convergence)

Add a switching function to the integrator.

Specified by:

addSwitchingFunction in interface FirstOrderIntegrator

Parameters:

function - switching function

maxCheckInterval - maximal time interval between switching function checks (this interval prevents missing sign changes in case the integration steps becomes very large)

convergence - convergence threshold in the event time search

initializeStep

public double initializeStep(FirstOrderDifferentialEquations equations,
                             boolean forward,
                             int order,
                             double[] scale,
                             double t0,
                             double[] y0,
                             double[] yDot0,
                             double[] y1,
                             double[] yDot1)
                      throws DerivativeException

Initialize the integration step.

Parameters:

equations - differential equations set

forward - forward integration indicator

order - order of the method

scale - scaling vector for the 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

Returns:

first integration step

Throws:

DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

filterStep

protected double filterStep(double h,
                            boolean acceptSmall)
                     throws IntegrationException

Filter the integration step.

Parameters:

h - signed step

acceptSmall - 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:

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

integrate

public abstract void integrate(FirstOrderDifferentialEquations equations,
                               double t0,
                               double[] y0,
                               double t,
                               double[] y)
                        throws DerivativeException,
                               IntegrationException

Description copied from interface: FirstOrderIntegrator

Integrate the differential equations up to the given time

Specified by:

integrate in interface FirstOrderIntegrator

Parameters:

equations - differential equations to integrate

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 thant t0 for backward integration)

y - placeholder where to put the state vector at each successful step (and hence at the end of integration), can be the same object as y0

Throws:

DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

IntegrationException - if the integrator cannot perform integration

getMinStep

public double getMinStep()

Get the minimal step.

Returns:

minimal step

getMaxStep

public double getMaxStep()

Get the maximal step.

Returns:

maximal step