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 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
  Version:
    $Id: StepNormalizer.java 1416643 2012-12-03 19:37:14Z tn $
  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

Copyright (c) 2003-2013 Apache Software Foundation