package org.spaceroots.mantissa.ode;

/**
 * This class wraps an object implementing {@link FixedStepHandler}
 * into a {@link 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 {@link
 * FixedStepHandler#handleStep handleStep} method of the underlying
 * {@link FixedStepHandler} object is called at the beginning time of
 * the integration t0 and also at times t0+h, t0+2h, ... If the
 * integration range is an integer multiple of the stepsize, then the
 * last point handled will be the endpoint of the integration tend, if
 * not, the last point will belong to the interval [tend - h ;
 * tend].

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

 * @see StepHandler
 * @see FixedStepHandler

 * @version $Id: StepNormalizer.java 1709 2006-12-03 21:16:50Z luc $
 * @author L. Maisonobe

 */

public class StepNormalizer
  implements StepHandler {

  /** Simple constructor.
   * @param h fixed time step (sign is not used)
   * @param handler fixed time step handler to wrap
   */
  public StepNormalizer(double h, FixedStepHandler handler) {
    this.h       = Math.abs(h);
    this.handler = handler;
    reset();
  }

  /** Determines whether this handler needs dense output.
   * This handler needs dense output in order to provide data at
   * regularly spaced steps regardless of the steps the integrator
   * uses, so this method always returns true.
   * @return always true
   */
  public boolean requiresDenseOutput() {
    return true;
  }

  /** Reset the step handler.
   * Initialize the internal data as required before the first step is
   * handled.
   */
  public void reset() {
    lastTime  = Double.NaN;
    lastState = null;
    forward   = true;
  }

  /**
   * Handle the last accepted step
   * @param 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.
   * @param isLast true if the step is the last one
   * @throws DerivativeException this exception is propagated to the
   * caller if the underlying user function triggers one
   */
  public void handleStep(StepInterpolator interpolator, boolean isLast)
    throws DerivativeException {

    double nextTime;

    if (lastState == null) {

      lastTime = interpolator.getPreviousTime();
      interpolator.setInterpolatedTime(lastTime);

      double[] state = interpolator.getInterpolatedState();
      lastState = (double[]) state.clone();

      // take the integration direction into account
      forward = (interpolator.getCurrentTime() >= lastTime);
      if (! forward) {
        h = -h;
      }

    }

    nextTime = lastTime + h;
    boolean nextInStep = forward ^ (nextTime > interpolator.getCurrentTime());
    while (nextInStep) {

      // output the stored previous step
      handler.handleStep(lastTime, lastState, false);

      // store the next step
      lastTime = nextTime;
      interpolator.setInterpolatedTime(lastTime);
      System.arraycopy(interpolator.getInterpolatedState(), 0,
                       lastState, 0, lastState.length);

      nextTime  += h;
      nextInStep = forward ^ (nextTime > interpolator.getCurrentTime());

    }

    if (isLast) {
      // there will be no more steps,
      // the stored one should be flagged as being the last
      handler.handleStep(lastTime, lastState, true);
    }

  }

  /** Fixed time step. */
  private double h;

  /** Underlying step handler. */
  private FixedStepHandler handler;

  /** Last step time. */
  private double lastTime;

  /** Last State vector. */
  private double[] lastState;

  /** Integration direction indicator. */
  private boolean forward;

}