    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.jacobians;
    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 FirstOrderIntegratorWithJacobians
    043     * @see StepHandlerWithJacobians
    044     * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
    045     * @since 2.1
    046     * @deprecated as of 2.2 the complete package is deprecated, it will be replaced
    047     * in 3.0 by a completely rewritten implementation
    048     */
    049    @Deprecated
    050    public interface StepInterpolatorWithJacobians extends Externalizable {
    051
    052      /**
    053       * Get the previous grid point time.
    054       * @return previous grid point time
    055       */
    056      double getPreviousTime();
    057
    058      /**
    059       * Get the current grid point time.
    060       * @return current grid point time
    061       */
    062      double getCurrentTime();
    063
    064      /**
    065       * Get the time of the interpolated point.
    066       * If {@link #setInterpolatedTime} has not been called, it returns
    067       * the current grid point time.
    068       * @return interpolation point time
    069       */
    070      double getInterpolatedTime();
    071
    072      /**
    073       * Set the time of the interpolated point.
    074       * <p>Setting the time outside of the current step is now allowed, but
    075       * should be used with care since the accuracy of the interpolator will
    076       * probably be very poor far from this step. This allowance has been
    077       * added to simplify implementation of search algorithms near the
    078       * step endpoints.</p>
    079       * <p>Setting the time changes the instance internal state. If a
    080       * specific state must be preserved, a copy of the instance must be
    081       * created using {@link #copy()}.</p>
    082       * @param time time of the interpolated point
    083       */
    084      void setInterpolatedTime(double time);
    085
    086      /**
    087       * Get the state vector of the interpolated point.
    088       * <p>The returned vector is a reference to a reused array, so
    089       * it should not be modified and it should be copied if it needs
    090       * to be preserved across several calls.</p>
    091       * @return state vector at time {@link #getInterpolatedTime}
    092       * @see #getInterpolatedYDot()
    093       * @throws DerivativeException if this call induces an automatic
    094       * step finalization that throws one
    095       */
    096      double[] getInterpolatedY() throws DerivativeException;
    097
    098      /**
    099       * Get the partial derivatives of the state vector with respect to
    100       * the initial state of the interpolated point.
    101       * <p>The returned vector is a reference to a reused array, so
    102       * it should not be modified and it should be copied if it needs
    103       * to be preserved across several calls.</p>
    104       * @return partial derivatives of the state vector with respect to
    105       * the initial state at time {@link #getInterpolatedTime}
    106       * @see #getInterpolatedY()
    107       * @throws DerivativeException if this call induces an automatic
    108       * step finalization that throws one
    109       */
    110      double[][] getInterpolatedDyDy0() throws DerivativeException;
    111
    112      /**
    113       * Get the partial derivatives of the state vector with respect to
    114       * the ODE parameters of the interpolated point.
    115       * <p>The returned vector is a reference to a reused array, so
    116       * it should not be modified and it should be copied if it needs
    117       * to be preserved across several calls.</p>
    118       * @return partial derivatives of the state vector with respect to
    119       * the ODE parameters at time {@link #getInterpolatedTime}
    120       * @see #getInterpolatedY()
    121       * @throws DerivativeException if this call induces an automatic
    122       * step finalization that throws one
    123       */
    124      double[][] getInterpolatedDyDp() throws DerivativeException;
    125
    126      /**
    127       * Get the time derivatives of the state vector of the interpolated point.
    128       * <p>The returned vector is a reference to a reused array, so
    129       * it should not be modified and it should be copied if it needs
    130       * to be preserved across several calls.</p>
    131       * @return derivatives of the state vector at time {@link #getInterpolatedTime}
    132       * @see #getInterpolatedY()
    133       * @throws DerivativeException if this call induces an automatic
    134       * step finalization that throws one
    135       */
    136      double[] getInterpolatedYDot() throws DerivativeException;
    137
    138      /**
    139       * Get the time derivatives of the jacobian of the state vector
    140       * with respect to the initial state of the interpolated point.
    141       * <p>The returned vector is a reference to a reused array, so
    142       * it should not be modified and it should be copied if it needs
    143       * to be preserved across several calls.</p>
    144       * @return time derivatives of the jacobian of the state vector
    145       * with respect to the initial state at time {@link #getInterpolatedTime}
    146       * @see #getInterpolatedY()
    147       * @throws DerivativeException if this call induces an automatic
    148       * step finalization that throws one
    149       */
    150      double[][] getInterpolatedDyDy0Dot() throws DerivativeException;
    151
    152      /**
    153       * Get the time derivatives of the jacobian of the state vector
    154       * with respect to the ODE parameters of the interpolated point.
    155       * <p>The returned vector is a reference to a reused array, so
    156       * it should not be modified and it should be copied if it needs
    157       * to be preserved across several calls.</p>
    158       * @return time derivatives of the jacobian of the state vector
    159       * with respect to the ODE parameters at time {@link #getInterpolatedTime}
    160       * @see #getInterpolatedY()
    161       * @throws DerivativeException if this call induces an automatic
    162       * step finalization that throws one
    163       */
    164      double[][] getInterpolatedDyDpDot() throws DerivativeException;
    165
    166      /** Check if the natural integration direction is forward.
    167       * <p>This method provides the integration direction as specified by
    168       * the integrator itself, it avoid some nasty problems in
    169       * degenerated cases like null steps due to cancellation at step
    170       * initialization, step control or discrete events
    171       * triggering.</p>
    172       * @return true if the integration variable (time) increases during
    173       * integration
    174       */
    175      boolean isForward();
    176
    177      /** Copy the instance.
    178       * <p>The copied instance is guaranteed to be independent from the
    179       * original one. Both can be used with different settings for
    180       * interpolated time without any side effect.</p>
    181       * @return a deep copy of the instance, which can be used independently.
    182       * @throws DerivativeException if this call induces an automatic
    183       * step finalization that throws one
    184       * @see #setInterpolatedTime(double)
    185       */
    186       StepInterpolatorWithJacobians copy() throws DerivativeException;
    187
    188    }