org.apache.commons.math.ode.sampling
Class AbstractStepInterpolator

java.lang.Object
  org.apache.commons.math.ode.sampling.AbstractStepInterpolator

All Implemented Interfaces:

Externalizable, Serializable, StepInterpolator

Direct Known Subclasses:

DummyStepInterpolator, 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

Version:

$Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $

See Also:

FirstOrderIntegrator, SecondOrderIntegrator, StepHandler, Serialized Form

Field Summary

protected double[]	currentState current state
protected double	currentTime current time
protected double	h current time step
protected double[]	interpolatedDerivatives interpolated derivatives
protected double[]	interpolatedState interpolated state
protected double	interpolatedTime interpolated time
protected double	previousTime previous time

Constructor Summary

protected	AbstractStepInterpolator() Simple constructor.
protected	AbstractStepInterpolator(AbstractStepInterpolator interpolator) Copy constructor.
protected	AbstractStepInterpolator(double[] y, boolean forward) Simple constructor.

Method Summary

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 grid point time.
double[]	getInterpolatedDerivatives() Get the derivatives of the state vector of the interpolated point.
double[]	getInterpolatedState() Get the state vector of the interpolated point.
double	getInterpolatedTime() Get the time of the interpolated point.
double	getPreviousTime() Get the previous 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) Reinitialize the instance
void	setInterpolatedTime(double time) Set the time of the interpolated point.
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

previousTime

protected double previousTime

previous time

currentTime

protected double currentTime

current time

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

Constructor Detail

AbstractStepInterpolator

protected AbstractStepInterpolator()

Simple constructor. This constructor builds an instance that is not usable yet, the reinitialize(double[], boolean) 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)

Simple constructor.

Parameters:

y - reference to the integrator array holding the state at the end of the step

forward - integration direction indicator

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)

Reinitialize the instance

Parameters:

y - reference to the integrator array holding the state at the end of the step

isForward - integration direction indicator

copy

public StepInterpolator copy()
                      throws DerivativeException

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:

DerivativeException - if this call induces an automatic step finalization that throws one

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

getPreviousTime

public double getPreviousTime()

Get the previous grid point time.

Specified by:

getPreviousTime in interface StepInterpolator

Returns:

previous grid point time

getCurrentTime

public double getCurrentTime()

Get the current grid point time.

Specified by:

getCurrentTime in interface StepInterpolator

Returns:

current grid point time

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 DerivativeException

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:

DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

getInterpolatedState

public double[] getInterpolatedState()
                              throws DerivativeException

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:

DerivativeException - if this call induces an automatic step finalization that throws one

See Also:

StepInterpolator.getInterpolatedDerivatives()

getInterpolatedDerivatives

public double[] getInterpolatedDerivatives()
                                    throws DerivativeException

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:

DerivativeException - if this call induces an automatic step finalization that throws one

See Also:

StepInterpolator.getInterpolatedState()

finalizeStep

public final void finalizeStep()
                        throws DerivativeException

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:

DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

doFinalize

protected void doFinalize()
                   throws DerivativeException

Really finalize the step. The default implementation of this method does nothing.

Throws:

DerivativeException - this exception is propagated to the caller if the underlying user function triggers one

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

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 be set later by the caller

Throws:

IOException - in case of read error