    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.math.ode.sampling;
    019
    020    import java.io.Externalizable;
    021
    022    import org.apache.commons.math.ode.DerivativeException;
    023
    024    /** This interface represents an interpolator over the last step
    025     * during an ODE integration.
    026     *
    027     * <p>The various ODE integrators provide objects implementing this
    028     * interface to the step handlers. These objects are often custom
    029     * objects tightly bound to the integrator internal algorithms. The
    030     * handlers can use these objects to retrieve the state vector at
    031     * intermediate times between the previous and the current grid points
    032     * (this feature is often called dense output).</p>
    033     * <p>One important thing to note is that the step handlers may be so
    034     * tightly bound to the integrators that they often share some internal
    035     * state arrays. This imply that one should <em>never</em> use a direct
    036     * reference to a step interpolator outside of the step handler, either
    037     * for future use or for use in another thread. If such a need arise, the
    038     * step interpolator <em>must</em> be copied using the dedicated
    039     * {@link #copy()} method.
    040     * </p>
    041     *
    042     * @see org.apache.commons.math.ode.FirstOrderIntegrator
    043     * @see org.apache.commons.math.ode.SecondOrderIntegrator
    044     * @see StepHandler
    045     * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
    046     * @since 1.2
    047     */
    048
    049    public interface StepInterpolator extends Externalizable {
    050
    051      /**
    052       * Get the previous grid point time.
    053       * @return previous grid point time
    054       */
    055      double getPreviousTime();
    056
    057      /**
    058       * Get the current grid point time.
    059       * @return current grid point time
    060       */
    061      double getCurrentTime();
    062
    063      /**
    064       * Get the time of the interpolated point.
    065       * If {@link #setInterpolatedTime} has not been called, it returns
    066       * the current grid point time.
    067       * @return interpolation point time
    068       */
    069      double getInterpolatedTime();
    070
    071      /**
    072       * Set the time of the interpolated point.
    073       * <p>Setting the time outside of the current step is now allowed, but
    074       * should be used with care since the accuracy of the interpolator will
    075       * probably be very poor far from this step. This allowance has been
    076       * added to simplify implementation of search algorithms near the
    077       * step endpoints.</p>
    078       * <p>Setting the time changes the instance internal state. If a
    079       * specific state must be preserved, a copy of the instance must be
    080       * created using {@link #copy()}.</p>
    081       * @param time time of the interpolated point
    082       */
    083      void setInterpolatedTime(double time);
    084
    085      /**
    086       * Get the state vector of the interpolated point.
    087       * <p>The returned vector is a reference to a reused array, so
    088       * it should not be modified and it should be copied if it needs
    089       * to be preserved across several calls.</p>
    090       * @return state vector at time {@link #getInterpolatedTime}
    091       * @see #getInterpolatedDerivatives()
    092       * @exception DerivativeException if user code called from step interpolator
    093       * finalization triggers one
    094       */
    095      double[] getInterpolatedState() throws DerivativeException;
    096
    097      /**
    098       * Get the derivatives of the state vector of the interpolated point.
    099       * <p>The returned vector is a reference to a reused array, so
    100       * it should not be modified and it should be copied if it needs
    101       * to be preserved across several calls.</p>
    102       * @return derivatives of the state vector at time {@link #getInterpolatedTime}
    103       * @see #getInterpolatedState()
    104       * @exception DerivativeException if user code called from step interpolator
    105       * finalization triggers one
    106       * @since 2.0
    107       */
    108      double[] getInterpolatedDerivatives() throws DerivativeException;
    109
    110      /** Check if the natural integration direction is forward.
    111       * <p>This method provides the integration direction as specified by
    112       * the integrator itself, it avoid some nasty problems in
    113       * degenerated cases like null steps due to cancellation at step
    114       * initialization, step control or discrete events
    115       * triggering.</p>
    116       * @return true if the integration variable (time) increases during
    117       * integration
    118       */
    119      boolean isForward();
    120
    121      /** Copy the instance.
    122       * <p>The copied instance is guaranteed to be independent from the
    123       * original one. Both can be used with different settings for
    124       * interpolated time without any side effect.</p>
    125       * @return a deep copy of the instance, which can be used independently.
    126       * @exception DerivativeException if user code called from step interpolator
    127       * finalization triggers one
    128       * @see #setInterpolatedTime(double)
    129       */
    130       StepInterpolator copy() throws DerivativeException;
    131
    132    }