## org.apache.commons.math.ode.nonstiff
Class AdaptiveStepsizeIntegrator

    java.lang.Object
      org.apache.commons.math.ode.AbstractIntegrator
          org.apache.commons.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 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: 811827 $ $Date: 2009-09-06 11:32:50 -0400 (Sun, 06 Sep 2009) $

Field Summary
`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[]` `vecAbsoluteTolerance` Allowed absolute vectorial error.
`protected double[]` `vecRelativeTolerance` Allowed relative vectorial error.

Fields inherited from class org.apache.commons.math.ode.AbstractIntegrator
`eventsHandlersManager, stepHandlers, stepSize, stepStart`

Constructor Summary
`AdaptiveStepsizeIntegrator(java.lang.String name, double minStep, double maxStep, double[] vecAbsoluteTolerance, double[] vecRelativeTolerance)` Build an integrator with the given stepsize bounds.
`AdaptiveStepsizeIntegrator(java.lang.String name, double minStep, double maxStep, double scalAbsoluteTolerance, double scalRelativeTolerance)` Build an integrator with the given stepsize bounds.

Method Summary
`protected double` `filterStep(double h, boolean forward, boolean acceptSmall)` 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(FirstOrderDifferentialEquations equations, boolean forward, int order, double[] scale, double t0, double[] y0, double[] yDot0, double[] y1, double[] yDot1)` Initialize the integration step.
`abstract double` `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.

Methods inherited from class org.apache.commons.math.ode.AbstractIntegrator
`addEndTimeChecker, addEventHandler, addStepHandler, clearEventHandlers, clearStepHandlers, computeDerivatives, getCurrentSignedStepsize, getEvaluations, getEventHandlers, getMaxEvaluations, getName, getStepHandlers, requiresDenseOutput, resetEvaluations, setEquations, setMaxEvaluations`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### scalAbsoluteTolerance

    protected final double scalAbsoluteTolerance

  Allowed absolute scalar error.

### scalRelativeTolerance

    protected final double scalRelativeTolerance

  Allowed relative scalar error.

### vecAbsoluteTolerance

    protected final double[] vecAbsoluteTolerance

  Allowed absolute vectorial error.

### vecRelativeTolerance

    protected final double[] vecRelativeTolerance

  Allowed relative vectorial error.

### initialStep

    private double initialStep

  User supplied initial step.

### minStep

    private final double minStep

  Minimal step.

### maxStep

    private final double maxStep

  Maximal step.

Constructor Detail

### AdaptiveStepsizeIntegrator

    public AdaptiveStepsizeIntegrator(java.lang.String name,
                                      double minStep,
                                      double maxStep,
                                      double scalAbsoluteTolerance,
                                      double scalRelativeTolerance)

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

  Parameters:
    `name` - name of the method
    `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(java.lang.String name,
                                      double minStep,
                                      double maxStep,
                                      double[] vecAbsoluteTolerance,
                                      double[] vecRelativeTolerance)

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

  Parameters:
    `name` - name of the method
    `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)

### sanityChecks

    protected void sanityChecks(FirstOrderDifferentialEquations equations,
                                double t0,
                                double[] y0,
                                double t,
                                double[] y)
                         throws IntegratorException

  Perform some sanity checks on the integration parameters.

  Overrides:
    `sanityChecks` in class `AbstractIntegrator`
  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 forward,
                                boolean acceptSmall)
                         throws IntegratorException

  Filter the integration step.

  Parameters:
    `h` - signed step
    `forward` - forward integration indicator
    `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 double 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 (`ODEIntegrator.getCurrentSignedStepsize()`), it is not thread-safe.

  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
  Returns:
    stop time, will be the same as target time if integration reached its target, but may be different if some `EventHandler` stops it at some point.
  Throws:
    `DerivativeException` - this exception is propagated to the caller if the underlying user function triggers one
    `IntegratorException` - if the integrator cannot perform integration

### 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`.

  Specified by:
    `getCurrentStepStart` in interface `ODEIntegrator`
  Overrides:
    `getCurrentStepStart` in class `AbstractIntegrator`
  Returns:
    current value of the step start time ti

### 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

Copyright (c) 2003-2010 Apache Software Foundation