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