org.apache.commons.math3.ode.sampling

Class StepNormalizer

java.lang.Object

org.apache.commons.math3.ode.sampling.StepNormalizer

All Implemented Interfaces:

StepHandler

public class StepNormalizer
extends java.lang.Object
implements StepHandler

This class wraps an object implementing FixedStepHandler into a StepHandler.

This wrapper allows to use fixed step handlers with general integrators which cannot guaranty their integration steps will remain constant and therefore only accept general step handlers.

The stepsize used is selected at construction time. The handleStep method of the underlying FixedStepHandler object is called at normalized times. The normalized times can be influenced by the StepNormalizerMode and StepNormalizerBounds.

There is no constraint on the integrator, it can use any time step it needs (time steps longer or shorter than the fixed time step and non-integer ratios are all allowed).

Examples (step size = 0.5)
Start time	End time	Direction	Mode	Bounds	Output
0.3	3.1	forward	INCREMENT	NEITHER	0.8, 1.3, 1.8, 2.3, 2.8
0.3	3.1	forward	INCREMENT	FIRST	0.3, 0.8, 1.3, 1.8, 2.3, 2.8
0.3	3.1	forward	INCREMENT	LAST	0.8, 1.3, 1.8, 2.3, 2.8, 3.1
0.3	3.1	forward	INCREMENT	BOTH	0.3, 0.8, 1.3, 1.8, 2.3, 2.8, 3.1
0.3	3.1	forward	MULTIPLES	NEITHER	0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.3	3.1	forward	MULTIPLES	FIRST	0.3, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.3	3.1	forward	MULTIPLES	LAST	0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.1
0.3	3.1	forward	MULTIPLES	BOTH	0.3, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.1
0.0	3.0	forward	INCREMENT	NEITHER	0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	INCREMENT	FIRST	0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	INCREMENT	LAST	0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	INCREMENT	BOTH	0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	MULTIPLES	NEITHER	0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	MULTIPLES	FIRST	0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	MULTIPLES	LAST	0.5, 1.0, 1.5, 2.0, 2.5, 3.0
0.0	3.0	forward	MULTIPLES	BOTH	0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0
3.1	0.3	backward	INCREMENT	NEITHER	2.6, 2.1, 1.6, 1.1, 0.6
3.1	0.3	backward	INCREMENT	FIRST	3.1, 2.6, 2.1, 1.6, 1.1, 0.6
3.1	0.3	backward	INCREMENT	LAST	2.6, 2.1, 1.6, 1.1, 0.6, 0.3
3.1	0.3	backward	INCREMENT	BOTH	3.1, 2.6, 2.1, 1.6, 1.1, 0.6, 0.3
3.1	0.3	backward	MULTIPLES	NEITHER	3.0, 2.5, 2.0, 1.5, 1.0, 0.5
3.1	0.3	backward	MULTIPLES	FIRST	3.1, 3.0, 2.5, 2.0, 1.5, 1.0, 0.5
3.1	0.3	backward	MULTIPLES	LAST	3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.3
3.1	0.3	backward	MULTIPLES	BOTH	3.1, 3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.3
3.0	0.0	backward	INCREMENT	NEITHER	2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	INCREMENT	FIRST	3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	INCREMENT	LAST	2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	INCREMENT	BOTH	3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	MULTIPLES	NEITHER	2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	MULTIPLES	FIRST	3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	MULTIPLES	LAST	2.5, 2.0, 1.5, 1.0, 0.5, 0.0
3.0	0.0	backward	MULTIPLES	BOTH	3.0, 2.5, 2.0, 1.5, 1.0, 0.5, 0.0

Since:

1.2

See Also:

StepHandler, FixedStepHandler, StepNormalizerMode, StepNormalizerBounds

Field Summary

Fields

Modifier and Type	Field and Description
private StepNormalizerBounds	bounds The step normalizer bounds settings to use.
private double	firstTime First step time.
private boolean	forward Integration direction indicator.
private double	h Fixed time step.
private FixedStepHandler	handler Underlying step handler.
private double[]	lastDerivatives Last derivatives vector.
private double[]	lastState Last state vector.
private double	lastTime Last step time.
private StepNormalizerMode	mode The step normalizer mode to use.

Constructor Summary

Constructors

Constructor and Description
StepNormalizer(double h, FixedStepHandler handler) Simple constructor.
StepNormalizer(double h, FixedStepHandler handler, StepNormalizerBounds bounds) Simple constructor.
StepNormalizer(double h, FixedStepHandler handler, StepNormalizerMode mode) Simple constructor.
StepNormalizer(double h, FixedStepHandler handler, StepNormalizerMode mode, StepNormalizerBounds bounds) Simple constructor.

Method Summary

Methods

Modifier and Type	Method and Description
private void	doNormalizedStep(boolean isLast) Invokes the underlying step handler for the current normalized step.
void	handleStep(StepInterpolator interpolator, boolean isLast) Handle the last accepted step
void	init(double t0, double[] y0, double t) Initialize step handler at the start of an ODE integration.
private boolean	isNextInStep(double nextTime, StepInterpolator interpolator) Returns a value indicating whether the next normalized time is in the current step.
private void	storeStep(StepInterpolator interpolator, double t) Stores the interpolated information for the given time in the current state.

Methods inherited from class java.lang.Object

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

Field Detail

h

private double h

Fixed time step.

handler

private final FixedStepHandler handler

Underlying step handler.

firstTime

private double firstTime

First step time.

lastTime

private double lastTime

Last step time.

lastState

private double[] lastState

Last state vector.

lastDerivatives

private double[] lastDerivatives

Last derivatives vector.

forward

private boolean forward

Integration direction indicator.

bounds

private final StepNormalizerBounds bounds

The step normalizer bounds settings to use.

mode

private final StepNormalizerMode mode

The step normalizer mode to use.

Constructor Detail

StepNormalizer

public StepNormalizer(double h,
              FixedStepHandler handler)

Simple constructor. Uses INCREMENT mode, and FIRST bounds setting, for backwards compatibility.

Parameters:

h - fixed time step (sign is not used)

handler - fixed time step handler to wrap

StepNormalizer

public StepNormalizer(double h,
              FixedStepHandler handler,
              StepNormalizerMode mode)

Simple constructor. Uses FIRST bounds setting.

Parameters:

h - fixed time step (sign is not used)

handler - fixed time step handler to wrap

mode - step normalizer mode to use

Since:

3.0

StepNormalizer

public StepNormalizer(double h,
              FixedStepHandler handler,
              StepNormalizerBounds bounds)

Simple constructor. Uses INCREMENT mode.

Parameters:

h - fixed time step (sign is not used)

handler - fixed time step handler to wrap

bounds - step normalizer bounds setting to use

Since:

3.0

StepNormalizer

public StepNormalizer(double h,
              FixedStepHandler handler,
              StepNormalizerMode mode,
              StepNormalizerBounds bounds)

Simple constructor.

Parameters:

h - fixed time step (sign is not used)

handler - fixed time step handler to wrap

mode - step normalizer mode to use

bounds - step normalizer bounds setting to use

Since:

3.0

Method Detail

init

public void init(double t0,
        double[] y0,
        double t)

Initialize step handler at the start of an ODE integration.

This method is called once at the start of the integration. It may be used by the step handler to initialize some internal data if needed.

Specified by:

init in interface StepHandler

Parameters:

t0 - start value of the independent time variable

y0 - array containing the start value of the state vector

t - target time for the integration

handleStep

public void handleStep(StepInterpolator interpolator,
              boolean isLast)
                throws MaxCountExceededException

Handle the last accepted step

Specified by:

handleStep in interface StepHandler

Parameters:

interpolator - interpolator for the last accepted step. For efficiency purposes, the various integrators reuse the same object on each call, so if the instance wants to keep it across all calls (for example to provide at the end of the integration a continuous model valid throughout the integration range), it should build a local copy using the clone method and store this copy.

isLast - true if the step is the last one

Throws:

MaxCountExceededException - if the interpolator throws one because the number of functions evaluations is exceeded

isNextInStep

private boolean isNextInStep(double nextTime,
                   StepInterpolator interpolator)

Returns a value indicating whether the next normalized time is in the current step.

Parameters:

nextTime - the next normalized time

interpolator - interpolator for the last accepted step, to use to get the end time of the current step

Returns:

value indicating whether the next normalized time is in the current step

doNormalizedStep

private void doNormalizedStep(boolean isLast)

Invokes the underlying step handler for the current normalized step.

Parameters:

isLast - true if the step is the last one

storeStep

private void storeStep(StepInterpolator interpolator,
             double t)
                throws MaxCountExceededException

Stores the interpolated information for the given time in the current state.

Parameters:

interpolator - interpolator for the last accepted step, to use to get the interpolated information

t - the time for which to store the interpolated information

Throws:

MaxCountExceededException - if the interpolator throws one because the number of functions evaluations is exceeded