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 }