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

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

• 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. This includes the internal arrays returned in StepInterpolator.getInterpolatedState(), StepInterpolator.getInterpolatedDerivatives(), StepInterpolator.getInterpolatedSecondaryState(int) and StepInterpolator.getInterpolatedSecondaryDerivatives(int). So if their content must be preserved across several calls, user must copy them.

  Specified by:

  setInterpolatedTime in interface StepInterpolator

  Parameters:

  time - time of the interpolated point

  See Also:

  StepInterpolator.getInterpolatedState(), StepInterpolator.getInterpolatedDerivatives(), StepInterpolator.getInterpolatedSecondaryState(int), StepInterpolator.getInterpolatedSecondaryDerivatives(int)

• 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

• 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 to the associated StepInterpolator.setInterpolatedTime(double) method.

  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(), StepInterpolator.getInterpolatedSecondaryState(int), StepInterpolator.getInterpolatedSecondaryDerivatives(int), StepInterpolator.setInterpolatedTime(double)

• 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 to the associated StepInterpolator.setInterpolatedTime(double) method.

  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(), StepInterpolator.getInterpolatedSecondaryState(int), StepInterpolator.getInterpolatedSecondaryDerivatives(int), StepInterpolator.setInterpolatedTime(double)

• 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 to the associated StepInterpolator.setInterpolatedTime(double) method.

  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