    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.math3.ode.sampling;
    019
    020    import java.io.Externalizable;
    021
    022    import org.apache.commons.math3.exception.MaxCountExceededException;
    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.math3.ode.FirstOrderIntegrator
    043     * @see org.apache.commons.math3.ode.SecondOrderIntegrator
    044     * @see StepHandler
    045     * @version $Id: StepInterpolator.java 1416643 2012-12-03 19:37:14Z tn $
    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 MaxCountExceededException if the number of functions evaluations is exceeded
    093       */
    094      double[] getInterpolatedState() throws MaxCountExceededException;
    095
    096      /**
    097       * Get the derivatives of the state vector of the interpolated point.
    098       * <p>The returned vector is a reference to a reused array, so
    099       * it should not be modified and it should be copied if it needs
    100       * to be preserved across several calls.</p>
    101       * @return derivatives of the state vector at time {@link #getInterpolatedTime}
    102       * @see #getInterpolatedState()
    103       * @since 2.0
    104       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
    105       */
    106      double[] getInterpolatedDerivatives() throws MaxCountExceededException;
    107
    108      /** Get the interpolated secondary state corresponding to the secondary equations.
    109       * <p>The returned vector is a reference to a reused array, so
    110       * it should not be modified and it should be copied if it needs
    111       * to be preserved across several calls.</p>
    112       * @param index index of the secondary set, as returned by {@link
    113       * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
    114       * org.apache.commons.math3.ode.SecondaryEquations)
    115       * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
    116       * @return interpolated secondary state at the current interpolation date
    117       * @see #getInterpolatedState()
    118       * @see #getInterpolatedDerivatives()
    119       * @see #getInterpolatedSecondaryDerivatives(int)
    120       * @see #setInterpolatedTime(double)
    121       * @since 3.0
    122       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
    123       */
    124      double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
    125
    126      /** Get the interpolated secondary derivatives corresponding to the secondary equations.
    127       * <p>The returned vector is a reference to a reused array, so
    128       * it should not be modified and it should be copied if it needs
    129       * to be preserved across several calls.</p>
    130       * @param index index of the secondary set, as returned by {@link
    131       * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
    132       * org.apache.commons.math3.ode.SecondaryEquations)
    133       * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
    134       * @return interpolated secondary derivatives at the current interpolation date
    135       * @see #getInterpolatedState()
    136       * @see #getInterpolatedDerivatives()
    137       * @see #getInterpolatedSecondaryState(int)
    138       * @see #setInterpolatedTime(double)
    139       * @since 3.0
    140       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
    141       */
    142      double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
    143
    144      /** Check if the natural integration direction is forward.
    145       * <p>This method provides the integration direction as specified by
    146       * the integrator itself, it avoid some nasty problems in
    147       * degenerated cases like null steps due to cancellation at step
    148       * initialization, step control or discrete events
    149       * triggering.</p>
    150       * @return true if the integration variable (time) increases during
    151       * integration
    152       */
    153      boolean isForward();
    154
    155      /** Copy the instance.
    156       * <p>The copied instance is guaranteed to be independent from the
    157       * original one. Both can be used with different settings for
    158       * interpolated time without any side effect.</p>
    159       * @return a deep copy of the instance, which can be used independently.
    160       * @see #setInterpolatedTime(double)
    161       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
    162       * during step finalization
    163       */
    164       StepInterpolator copy() throws MaxCountExceededException;
    165
    166    }