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    }