org.apache.commons.math3.ode.sampling

## Class AbstractStepInterpolator

- java.lang.Object
- - org.apache.commons.math3.ode.sampling.AbstractStepInterpolator

- All Implemented Interfaces:
    Externalizable, Serializable, StepInterpolator
  Direct Known Subclasses:
    GraggBulirschStoerStepInterpolator, NordsieckStepInterpolator, RungeKuttaStepInterpolator

      public abstract class AbstractStepInterpolator
      extends Object
      implements StepInterpolator

  This abstract class represents an interpolator over the last step during an ODE integration.

  The various ODE integrators provide objects extending this class to the step handlers. The handlers can use these objects to retrieve the state vector at intermediate times between the previous and the current grid points (dense output).

  Since:
    1.2
  Version:
    $Id: AbstractStepInterpolator.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    `FirstOrderIntegrator`, `SecondOrderIntegrator`, `StepHandler`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected double[]` | `currentState` current state
    `private boolean` | `dirtyState` indicator for dirty state.
    `private boolean` | `finalized` indicate if the step has been finalized or not.
    `private boolean` | `forward` integration direction.
    `private double` | `globalCurrentTime` global current time
    `private double` | `globalPreviousTime` global previous time
    `protected double` | `h` current time step
    `protected double[]` | `interpolatedDerivatives` interpolated derivatives
    `protected double[]` | `interpolatedPrimaryDerivatives` interpolated primary derivatives
    `protected double[]` | `interpolatedPrimaryState` interpolated primary state
    `protected double[][]` | `interpolatedSecondaryDerivatives` interpolated secondary derivatives
    `protected double[][]` | `interpolatedSecondaryState` interpolated secondary state
    `protected double[]` | `interpolatedState` interpolated state
    `protected double` | `interpolatedTime` interpolated time
    `private EquationsMapper` | `primaryMapper` Equations mapper for the primary equations set.
    `private EquationsMapper[]` | `secondaryMappers` Equations mappers for the secondary equations sets.
    `private double` | `softCurrentTime` soft current time
    `private double` | `softPreviousTime` soft previous time

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractStepInterpolator()` Simple constructor.
    `protected` | `AbstractStepInterpolator(AbstractStepInterpolator interpolator)` Copy constructor.
    `protected` | `AbstractStepInterpolator(double[] y, boolean forward, EquationsMapper primaryMapper, EquationsMapper[] secondaryMappers)` Simple constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `allocateInterpolatedArrays(int dimension)` Allocate the various interpolated states arrays.
    `protected abstract void` | `computeInterpolatedStateAndDerivatives(double theta, double oneMinusThetaH)` Compute the state and derivatives at the interpolated time.
    `StepInterpolator` | `copy()` Copy the instance.
    `protected abstract StepInterpolator` | `doCopy()` Really copy the finalized instance.
    `protected void` | `doFinalize()` Really finalize the step.
    `private void` | `evaluateCompleteInterpolatedState()` Lazy evaluation of complete interpolated state.
    `void` | `finalizeStep()` Finalize the step.
    `double` | `getCurrentTime()` Get the current soft grid point time.
    `double` | `getGlobalCurrentTime()` Get the current global grid point time.
    `double` | `getGlobalPreviousTime()` Get the previous global grid point time.
    `double[]` | `getInterpolatedDerivatives()` Get the derivatives of the state vector of the interpolated point.
    `double[]` | `getInterpolatedSecondaryDerivatives(int index)` Get the interpolated secondary derivatives corresponding to the secondary equations.
    `double[]` | `getInterpolatedSecondaryState(int index)` Get the interpolated secondary state corresponding to the secondary equations.
    `double[]` | `getInterpolatedState()` Get the state vector of the interpolated point.
    `double` | `getInterpolatedTime()` Get the time of the interpolated point.
    `double` | `getPreviousTime()` Get the previous soft grid point time.
    `boolean` | `isForward()` Check if the natural integration direction is forward.
    `protected double` | `readBaseExternal(ObjectInput in)` Read the base state of the instance.
    `abstract void` | `readExternal(ObjectInput in)`
    `protected void` | `reinitialize(double[] y, boolean isForward, EquationsMapper primary, EquationsMapper[] secondary)` Reinitialize the instance
    `void` | `setInterpolatedTime(double time)` Set the time of the interpolated point.
    `void` | `setSoftCurrentTime(double softCurrentTime)` Restrict step range to a limited part of the global step.
    `void` | `setSoftPreviousTime(double softPreviousTime)` Restrict step range to a limited part of the global step.
    `void` | `shift()` Shift one step forward.
    `void` | `storeTime(double t)` Store the current step time.
    `protected void` | `writeBaseExternal(ObjectOutput out)` Save the base state of the instance.
    `abstract void` | `writeExternal(ObjectOutput out)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### h

          protected double h

      current time step

    - #### currentState

          protected double[] currentState

      current state

    - #### interpolatedTime

          protected double interpolatedTime

      interpolated time

    - #### interpolatedState

          protected double[] interpolatedState

      interpolated state

    - #### interpolatedDerivatives

          protected double[] interpolatedDerivatives

      interpolated derivatives

    - #### interpolatedPrimaryState

          protected double[] interpolatedPrimaryState

      interpolated primary state

    - #### interpolatedPrimaryDerivatives

          protected double[] interpolatedPrimaryDerivatives

      interpolated primary derivatives

    - #### interpolatedSecondaryState

          protected double[][] interpolatedSecondaryState

      interpolated secondary state

    - #### interpolatedSecondaryDerivatives

          protected double[][] interpolatedSecondaryDerivatives

      interpolated secondary derivatives

    - #### globalPreviousTime

          private double globalPreviousTime

      global previous time

    - #### globalCurrentTime

          private double globalCurrentTime

      global current time

    - #### softPreviousTime

          private double softPreviousTime

      soft previous time

    - #### softCurrentTime

          private double softCurrentTime

      soft current time

    - #### finalized

          private boolean finalized

      indicate if the step has been finalized or not.

    - #### forward

          private boolean forward

      integration direction.

    - #### dirtyState

          private boolean dirtyState

      indicator for dirty state.

    - #### primaryMapper

          private EquationsMapper primaryMapper

      Equations mapper for the primary equations set.

    - #### secondaryMappers

          private EquationsMapper[] secondaryMappers

      Equations mappers for the secondary equations sets.

  - ### Constructor Detail

    - #### AbstractStepInterpolator

          protected AbstractStepInterpolator()

      Simple constructor. This constructor builds an instance that is not usable yet, the `reinitialize(double[], boolean, org.apache.commons.math3.ode.EquationsMapper, org.apache.commons.math3.ode.EquationsMapper[])` method should be called before using the instance in order to initialize the internal arrays. This constructor is used only in order to delay the initialization in some cases. As an example, the `EmbeddedRungeKuttaIntegrator` class uses the prototyping design pattern to create the step interpolators by cloning an uninitialized model and latter initializing the copy.

    - #### AbstractStepInterpolator

          protected AbstractStepInterpolator(double[] y,
                                  boolean forward,
                                  EquationsMapper primaryMapper,
                                  EquationsMapper[] secondaryMappers)

      Simple constructor.
      Parameters:
        `y` - reference to the integrator array holding the state at the end of the step
        `forward` - integration direction indicator
        `primaryMapper` - equations mapper for the primary equations set
        `secondaryMappers` - equations mappers for the secondary equations sets

    - #### AbstractStepInterpolator

          protected AbstractStepInterpolator(AbstractStepInterpolator interpolator)

      Copy constructor.

      The copied interpolator should have been finalized before the copy, otherwise the copy will not be able to perform correctly any derivative computation and will throw a `NullPointerException` later. Since we don't want this constructor to throw the exceptions finalization may involve and since we don't want this method to modify the state of the copied interpolator, finalization is not done automatically, it remains under user control.

      The copy is a deep copy: its arrays are separated from the original arrays of the instance.

      Parameters:
        `interpolator` - interpolator to copy from.

  - ### Method Detail

    - #### allocateInterpolatedArrays

          private void allocateInterpolatedArrays(int dimension)

      Allocate the various interpolated states arrays.
      Parameters:
        `dimension` - total dimension (negative if arrays should be set to null)

    - #### reinitialize

          protected void reinitialize(double[] y,
                          boolean isForward,
                          EquationsMapper primary,
                          EquationsMapper[] secondary)

      Reinitialize the instance
      Parameters:
        `y` - reference to the integrator array holding the state at the end of the step
        `isForward` - integration direction indicator
        `primary` - equations mapper for the primary equations set
        `secondary` - equations mappers for the secondary equations sets

    - #### copy

          public StepInterpolator copy()
                                throws MaxCountExceededException

      Copy the instance.

      The copied instance is guaranteed to be independent from the original one. Both can be used with different settings for interpolated time without any side effect.

      Specified by:
        `copy` in interface `StepInterpolator`
      Returns:
        a deep copy of the instance, which can be used independently.
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded during step finalization
      See Also:
        `StepInterpolator.setInterpolatedTime(double)`

    - #### doCopy

          protected abstract StepInterpolator doCopy()

      Really copy the finalized instance.

      This method is called by `copy()` after the step has been finalized. It must perform a deep copy to have an new instance completely independent for the original instance.

      Returns:
        a copy of the finalized instance

    - #### shift

          public void shift()

      Shift one step forward. Copy the current time into the previous time, hence preparing the interpolator for future calls to `storeTime`

    - #### storeTime

          public void storeTime(double t)

      Store the current step time.
      Parameters:
        `t` - current time

    - #### setSoftPreviousTime

          public void setSoftPreviousTime(double softPreviousTime)

      Restrict step range to a limited part of the global step.

      This method can be used to restrict a step and make it appear as if the original step was smaller. Calling this method only changes the value returned by `getPreviousTime()`, it does not change any other property

      Parameters:
        `softPreviousTime` - start of the restricted step
      Since:
        2.2

    - #### setSoftCurrentTime

          public void setSoftCurrentTime(double softCurrentTime)

      Restrict step range to a limited part of the global step.

      This method can be used to restrict a step and make it appear as if the original step was smaller. Calling this method only changes the value returned by `getCurrentTime()`, it does not change any other property

      Parameters:
        `softCurrentTime` - end of the restricted step
      Since:
        2.2

    - #### getGlobalPreviousTime

          public double getGlobalPreviousTime()

      Get the previous global grid point time.
      Returns:
        previous global grid point time

    - #### getGlobalCurrentTime

          public double getGlobalCurrentTime()

      Get the current global grid point time.
      Returns:
        current global grid point time

    - #### getPreviousTime

          public double getPreviousTime()

      Get the previous soft grid point time.
      Specified by:
        `getPreviousTime` in interface `StepInterpolator`
      Returns:
        previous soft grid point time
      See Also:
        `setSoftPreviousTime(double)`

    - #### getCurrentTime

          public double getCurrentTime()

      Get the current soft grid point time.
      Specified by:
        `getCurrentTime` in interface `StepInterpolator`
      Returns:
        current soft grid point time
      See Also:
        `setSoftCurrentTime(double)`

    - #### getInterpolatedTime

          public double getInterpolatedTime()

      Get the time of the interpolated point. If `StepInterpolator.setInterpolatedTime(double)` has not been called, it returns the current grid point time.
      Specified by:
        `getInterpolatedTime` in interface `StepInterpolator`
      Returns:
        interpolation point time

    - #### setInterpolatedTime

          public void setInterpolatedTime(double time)

      Set the time of the interpolated point.

      Setting the time outside of the current step is now allowed, but should be used with care since the accuracy of the interpolator will probably be very poor far from this step. This allowance has been added to simplify implementation of search algorithms near the step endpoints.

      Setting the time changes the instance internal state. If a specific state must be preserved, a copy of the instance must be created using `StepInterpolator.copy()`.

      Specified by:
        `setInterpolatedTime` in interface `StepInterpolator`
      Parameters:
        `time` - time of the interpolated point

    - #### isForward

          public boolean isForward()

      Check if the natural integration direction is forward.

      This method provides the integration direction as specified by the integrator itself, it avoid some nasty problems in degenerated cases like null steps due to cancellation at step initialization, step control or discrete events triggering.

      Specified by:
        `isForward` in interface `StepInterpolator`
      Returns:
        true if the integration variable (time) increases during integration

    - #### computeInterpolatedStateAndDerivatives

          protected abstract void computeInterpolatedStateAndDerivatives(double theta,
                                                    double oneMinusThetaH)
                                                                  throws MaxCountExceededException

      Compute the state and derivatives at the interpolated time. This is the main processing method that should be implemented by the derived classes to perform the interpolation.
      Parameters:
        `theta` - normalized interpolation abscissa within the step (theta is zero at the previous time step and one at the current time step)
        `oneMinusThetaH` - time gap between the interpolated time and the current time
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded

    - #### evaluateCompleteInterpolatedState

          private void evaluateCompleteInterpolatedState()
                                                  throws MaxCountExceededException

      Lazy evaluation of complete interpolated state.
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded

    - #### getInterpolatedState

          public double[] getInterpolatedState()
                                        throws MaxCountExceededException

      Get the state vector of the interpolated point.

      The returned vector is a reference to a reused array, so it should not be modified and it should be copied if it needs to be preserved across several calls.

      Specified by:
        `getInterpolatedState` in interface `StepInterpolator`
      Returns:
        state vector at time `StepInterpolator.getInterpolatedTime()`
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
      See Also:
        `StepInterpolator.getInterpolatedDerivatives()`

    - #### getInterpolatedDerivatives

          public double[] getInterpolatedDerivatives()
                                              throws MaxCountExceededException

      Get the derivatives of the state vector of the interpolated point.

      The returned vector is a reference to a reused array, so it should not be modified and it should be copied if it needs to be preserved across several calls.

      Specified by:
        `getInterpolatedDerivatives` in interface `StepInterpolator`
      Returns:
        derivatives of the state vector at time `StepInterpolator.getInterpolatedTime()`
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
      See Also:
        `StepInterpolator.getInterpolatedState()`

    - #### getInterpolatedSecondaryState

          public double[] getInterpolatedSecondaryState(int index)
                                                 throws MaxCountExceededException

      Get the interpolated secondary state corresponding to the secondary equations.

      The returned vector is a reference to a reused array, so it should not be modified and it should be copied if it needs to be preserved across several calls.

      Specified by:
        `getInterpolatedSecondaryState` in interface `StepInterpolator`
      Parameters:
        `index` - index of the secondary set, as returned by `ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)`
      Returns:
        interpolated secondary state at the current interpolation date
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
      See Also:
        `StepInterpolator.getInterpolatedState()`, `StepInterpolator.getInterpolatedDerivatives()`, `StepInterpolator.getInterpolatedSecondaryDerivatives(int)`, `StepInterpolator.setInterpolatedTime(double)`

    - #### getInterpolatedSecondaryDerivatives

          public double[] getInterpolatedSecondaryDerivatives(int index)
                                                       throws MaxCountExceededException

      Get the interpolated secondary derivatives corresponding to the secondary equations.

      The returned vector is a reference to a reused array, so it should not be modified and it should be copied if it needs to be preserved across several calls.

      Specified by:
        `getInterpolatedSecondaryDerivatives` in interface `StepInterpolator`
      Parameters:
        `index` - index of the secondary set, as returned by `ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)`
      Returns:
        interpolated secondary derivatives at the current interpolation date
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded
      See Also:
        `StepInterpolator.getInterpolatedState()`, `StepInterpolator.getInterpolatedDerivatives()`, `StepInterpolator.getInterpolatedSecondaryState(int)`, `StepInterpolator.setInterpolatedTime(double)`

    - #### finalizeStep

          public final void finalizeStep()
                                  throws MaxCountExceededException

      Finalize the step.

      Some embedded Runge-Kutta integrators need fewer functions evaluations than their counterpart step interpolators. These interpolators should perform the last evaluations they need by themselves only if they need them. This method triggers these extra evaluations. It can be called directly by the user step handler and it is called automatically if `setInterpolatedTime(double)` is called.

      Once this method has been called, no other evaluation will be performed on this step. If there is a need to have some side effects between the step handler and the differential equations (for example update some data in the equations once the step has been done), it is advised to call this method explicitly from the step handler before these side effects are set up. If the step handler induces no side effect, then this method can safely be ignored, it will be called transparently as needed.

      Warning: since the step interpolator provided to the step handler as a parameter of the `handleStep` is valid only for the duration of the `handleStep` call, one cannot simply store a reference and reuse it later. One should first finalize the instance, then copy this finalized instance into a new object that can be kept.

      This method calls the protected `doFinalize` method if it has never been called during this step and set a flag indicating that it has been called once. It is the `doFinalize` method which should perform the evaluations. This wrapping prevents from calling `doFinalize` several times and hence evaluating the differential equations too often. Therefore, subclasses are not allowed not reimplement it, they should rather reimplement `doFinalize`.

      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded

    - #### doFinalize

          protected void doFinalize()
                             throws MaxCountExceededException

      Really finalize the step. The default implementation of this method does nothing.
      Throws:
        `MaxCountExceededException` - if the number of functions evaluations is exceeded

    - #### writeExternal

          public abstract void writeExternal(ObjectOutput out)
                                      throws IOException

      Specified by:
        `writeExternal` in interface `Externalizable`
      Throws:
        `IOException`

    - #### readExternal

          public abstract void readExternal(ObjectInput in)
                                     throws IOException,
                                            ClassNotFoundException

      Specified by:
        `readExternal` in interface `Externalizable`
      Throws:
        `IOException`
        `ClassNotFoundException`

    - #### writeBaseExternal

          protected void writeBaseExternal(ObjectOutput out)
                                    throws IOException

      Save the base state of the instance. This method performs step finalization if it has not been done before.
      Parameters:
        `out` - stream where to save the state
      Throws:
        `IOException` - in case of write error

    - #### readBaseExternal

          protected double readBaseExternal(ObjectInput in)
                                     throws IOException,
                                            ClassNotFoundException

      Read the base state of the instance. This method does neither set the interpolated time nor state. It is up to the derived class to reset it properly calling the `setInterpolatedTime(double)` method later, once all rest of the object state has been set up properly.
      Parameters:
        `in` - stream where to read the state from
      Returns:
        interpolated time to be set later by the caller
      Throws:
        `IOException` - in case of read error
        `ClassNotFoundException` - if an equation mapper class cannot be found

Copyright (c) 2003-2013 Apache Software Foundation