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 Ordinary Differential Equations is an extended ODE rather than a basic ODE, then only the main set 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) invalid input: '<' 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:
$Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 févr. 2011) $
  • Field Details

    • 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.
    • mainSetDimension

      protected int mainSetDimension
      Main set dimension.
  • Constructor Details

    • AdaptiveStepsizeIntegrator

      public AdaptiveStepsizeIntegrator(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(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 Details

    • 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 (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
      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