org.opensourcephysics.numerics
Interface ODESolverInterpolator

All Known Implementing Classes:

AbstractAdaptiveRKSolverInterpolator, AbstractDiscreteTimeAdaptiveSolverInterpolator, AbstractDiscreteTimeSolverInterpolator, AbstractExplicitRKSolverInterpolator, BogackiShampine23, BogackiShampine23, CashKarp45, CashKarp45, Dopri5, Dopri5, Dopri853, Dopri853, Euler, Euler, EulerRichardson, EulerRichardson, Fehlberg78, Fehlberg78, Fehlberg8, Fehlberg8, Qss, Qss2, Qss3, Radau5, Radau5, RK4, RK4, VelocityVerlet, VelocityVerlet

public interface ODESolverInterpolator

ODESolverInterpolator is an interface for objects which use an ODESolver to keep a set of internal states that are used to interpolate values of the ODE solution to create a so-called dense output. Typically, this scheme is used with adaptive solvers that can step much further than the prescribed step size set by the user without loosing precision. But also for fixed-step methods whose state can be read more frequently than it is computed. An ODESolverInterpolator can keep a memory of the states in past values of time. This memory can be used to retrieve those past values when needed. For instance, when solvinf Delay Differential Equations, or when plotting values already computed.

Version:

1.0 November 2007, 2.0 February 2011

Author:

Francisco Esquembre

See Also:

ODEInterpolatorEventSolver

Method Summary

double[]	bestInterpolate(double time, double[] state) Similar to interpolate(), but using the best estimate the algorith can provide and only between the current time and getMaximumTime().
long	getCounter() Returns the number of function evaluations required by the method to reach the tolerance
double[]	getCurrentRate() Returns the rate of the current state
double	getInternalStepSize() Returns the actual internal step size
double	getMaximumTime() Returns the maximum time forward in time (or minimum, if the step is negative) for which the solver can interpolate without doing any internal step.
ODE	getODE() Returns the ODE with which it was created.
StateMemory	getStateMemory() Provides access to the internal StateMemory responsible for interpolations.
double	getStepSize() Returns the current step size
void	initialize(double stepSize) Initializes the interpolator and clears the memory.
double	internalStep() Steps the internal step as much as possible (respecting the step size and the tolerance, if any).
double[]	interpolate(double time, boolean useLeftApproximation, double[] state) Returns the value of the ODE's state[] at the given time in the provided state[] array.
void	reinitialize(double[] state) Does the minimum (soft) initialization of the solver to a given state.
void	setEstimateFirstStep(boolean _estimate) Makes adaptive steps estimate the best initial step after reinitialize().
void	setMaximumStepSize(double stepSize) Sets a maximum step size for variable step solvers.
void	setMemoryLength(double length) Sets the length of the memory requested to the solver.
void	setStepSize(double stepSize) Changes the internal step size.
void	setTolerances(double absTol, double relTol) The preferred absolute and relative tolerance desired for the solution if the underlying solver supports it.

Method Detail

getODE

ODE getODE()

Returns the ODE with which it was created.

Returns:

initialize

void initialize(double stepSize)

Initializes the interpolator and clears the memory. Implementing classes typically use this method to declare arrays, initialize the underlying ODESolver, set its step size, and call reinitialize().

reinitialize

void reinitialize(double[] state)

Does the minimum (soft) initialization of the solver to a given state. The memory is preserved. Users of an ODESolverInterpolator MUST call reinitialize (or the harder initialize) whenever they change the state. Typically, solvers synchronize their internal states and auxiliary variables using the provided state.

Parameters:

state - double[]

getCurrentRate

double[] getCurrentRate()

Returns the rate of the current state

Returns:

setStepSize

void setStepSize(double stepSize)

Changes the internal step size. This is the step at which internal steps are computed for fixed step methods, and the initial step size (after reinitialize()) for variable step methods.

Parameters:

stepSize -

setMaximumStepSize

void setMaximumStepSize(double stepSize)

Sets a maximum step size for variable step solvers. Has no effect on fixed-step solvers.

Parameters:

stepSize -

getStepSize

double getStepSize()

Returns the current step size

Returns:

getInternalStepSize

double getInternalStepSize()

Returns the actual internal step size

Returns:

setEstimateFirstStep

void setEstimateFirstStep(boolean _estimate)

Makes adaptive steps estimate the best initial step after reinitialize(). If false, the given initial step (as set by setStepSize()) is used.

Parameters:

_estimate -

setTolerances

void setTolerances(double absTol,
                   double relTol)

The preferred absolute and relative tolerance desired for the solution if the underlying solver supports it. If the solver does not support this feature, the method is ignored. Changing the tolerances typically involves a re-computation of the current step.

Parameters:

tol -

getMaximumTime

double getMaximumTime()

Returns the maximum time forward in time (or minimum, if the step is negative) for which the solver can interpolate without doing any internal step.

Returns:

double The maximum advance time or NaN if there was any error.

internalStep

double internalStep()

Steps the internal step as much as possible (respecting the step size and the tolerance, if any).

Returns:

double Same as getMaximumTime()

getCounter

long getCounter()

Returns the number of function evaluations required by the method to reach the tolerance

Returns:

setMemoryLength

void setMemoryLength(double length)

Sets the length of the memory requested to the solver. Must be a positive value. The user will then be able to ask for values of the state as far as the current time minus this length. 0 is the default for plain ODE, getMaximumDelay() is the minimum used by DDEs. Setting a value of Infinity makes the solver to remmeber for ever (i.e. as much as computer memory permits)

Parameters:

length -

getStateMemory

StateMemory getStateMemory()

Provides access to the internal StateMemory responsible for interpolations.

Returns:

interpolate

double[] interpolate(double time,
                     boolean useLeftApproximation,
                     double[] state)

Returns the value of the ODE's state[] at the given time in the provided state[] array. The time must be in the range of the memory or between the current time and getMaximumTime() for correct operation.

Parameters:

time - the time for the interpolation desired

useLeftApproximation - In case of doubt, approximate the value from the left (this is important if the state has a discontinuity at that instant of time, such as for DDEs)

state - placeholder for the returned state

Returns:

The state provided as argument or null if there is no interpolation available at this time.

bestInterpolate

double[] bestInterpolate(double time,
                         double[] state)

Similar to interpolate(), but using the best estimate the algorith can provide and only between the current time and getMaximumTime(). In some RK schemes, this results in computing the RK algorithm from the initial point. Therefore, this method typically involves a bigger computational load.

Returns:

The state provided as argument or null if there was any previous error.