Class AbstractStepInterpolator
 java.lang.Object

 org.apache.commons.math4.legacy.ode.sampling.AbstractStepInterpolator

 All Implemented Interfaces:
Externalizable
,Serializable
,StepInterpolator
 Direct Known Subclasses:
NordsieckStepInterpolator
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
 See Also:
FirstOrderIntegrator
,SecondOrderIntegrator
,StepHandler
, Serialized Form


Field Summary
Fields Modifier and Type Field Description protected double[]
currentState
current state.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.

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

Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description 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.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)



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, thereinitialize(double[], boolean, org.apache.commons.math4.legacy.ode.EquationsMapper, org.apache.commons.math4.legacy.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, theEmbeddedRungeKuttaIntegrator
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 stepforward
 integration direction indicatorprimaryMapper
 equations mapper for the primary equations setsecondaryMappers
 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 stepisForward
 integration direction indicatorprimary
 equations mapper for the primary equations setsecondary
 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 interfaceStepInterpolator
 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 tostoreTime

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 interfaceStepInterpolator
 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 interfaceStepInterpolator
 Returns:
 current soft grid point time
 See Also:
setSoftCurrentTime(double)

getInterpolatedTime
public double getInterpolatedTime()
Get the time of the interpolated point. IfStepInterpolator.setInterpolatedTime(double)
has not been called, it returns the current grid point time. Specified by:
getInterpolatedTime
in interfaceStepInterpolator
 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)
andStepInterpolator.getInterpolatedSecondaryDerivatives(int)
. So if their content must be preserved across several calls, user must copy them. Specified by:
setInterpolatedTime
in interfaceStepInterpolator
 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 interfaceStepInterpolator
 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 interfaceStepInterpolator
 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 interfaceStepInterpolator
 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 interfaceStepInterpolator
 Parameters:
index
 index of the secondary set, as returned byExpandableStatefulODE.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 interfaceStepInterpolator
 Parameters:
index
 index of the secondary set, as returned byExpandableStatefulODE.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 RungeKutta 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 thehandleStep
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 thedoFinalize
method which should perform the evaluations. This wrapping prevents from callingdoFinalize
several times and hence evaluating the differential equations too often. Therefore, subclasses are not allowed not reimplement it, they should rather reimplementdoFinalize
. 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 interfaceExternalizable
 Throws:
IOException

readExternal
public abstract void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
 Specified by:
readExternal
in interfaceExternalizable
 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 thesetInterpolatedTime(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 errorClassNotFoundException
 if an equation mapper class cannot be found

