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:

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

Method Summary

Modifier and Type	Method and Description
StepInterpolator	copy() Copy the instance.
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.
abstract void	readExternal(ObjectInput in)
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.
abstract void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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)

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

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

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