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 }