org.apache.commons.math.ode
Class AdaptiveStepsizeIntegrator

java.lang.Object
  extended by org.apache.commons.math.ode.AdaptiveStepsizeIntegrator
All Implemented Interfaces:
FirstOrderIntegrator
Direct Known Subclasses:
EmbeddedRungeKuttaIntegrator, GraggBulirschStoerIntegrator

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.

Since:
1.2
Version:
$Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $

Field Summary
protected  StepHandler handler
          Step handler.
private  double initialStep
          User supplied initial step.
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 stepSize
          Current stepsize.
protected  double stepStart
          Current step start time.
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, int maxIterationCount)
          Add a switching function to the integrator.
protected  double filterStep(double h, boolean acceptSmall)
          Filter the integration step.
 double getCurrentSignedStepsize()
          Get the current signed value of the integration stepsize.
 double getCurrentStepStart()
          Get the current value of the step start time ti.
 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.
protected  void resetInternalState()
          Reset internal state to dummy values.
protected  void sanityChecks(FirstOrderDifferentialEquations equations, double t0, double[] y0, double t, double[] y)
          Perform some sanity checks on the integration parameters.
 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.apache.commons.math.ode.FirstOrderIntegrator
getName
 

Field Detail

minStep

private double minStep
Minimal step.


maxStep

private double maxStep
Maximal step.


initialStep

private double initialStep
User supplied initial step.


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.


stepStart

protected double stepStart
Current step start time.


stepSize

protected double stepSize
Current stepsize.

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,
                                 int maxIterationCount)
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
maxIterationCount - upper limit of the iteration count in the event time search

sanityChecks

protected void sanityChecks(FirstOrderDifferentialEquations equations,
                            double t0,
                            double[] y0,
                            double t,
                            double[] y)
                     throws IntegratorException
Perform some sanity checks on the integration parameters.

Parameters:
equations - differential equations set
t0 - start time
y0 - state vector at t0
t - target time for the integration
y - placeholder where to put the state vector
Throws:
IntegratorException - if some inconsistency is detected

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 IntegratorException
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:
IntegratorException - 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,
                               IntegratorException
Integrate the differential equations up to the given time.

This method solves an Initial Value Problem (IVP).

Since this method stores some internal state variables made available in its public interface during integration (getCurrentSignedStepsize()), it is not thread-safe.

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 than 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:
IntegratorException - if the integrator cannot perform integration
DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

getCurrentStepStart

public double 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(org.apache.commons.math.ode.FirstOrderDifferentialEquations, double, double[], double, double[])

Specified by:
getCurrentStepStart in interface FirstOrderIntegrator
Returns:
current value of the step start time ti

getCurrentSignedStepsize

public double getCurrentSignedStepsize()
Get the current signed value of the integration stepsize.

This method can be called during integration (typically by the object implementing the differential equations problem) if the signed value of the current stepsize that is tried is needed.

The result is undefined if the method is called outside of calls to integrate(org.apache.commons.math.ode.FirstOrderDifferentialEquations, double, double[], double, double[])

Specified by:
getCurrentSignedStepsize in interface FirstOrderIntegrator
Returns:
current signed value of the stepsize

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