1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22
23 package org.hipparchus.migration.ode.sampling;
24
25 import org.hipparchus.exception.MathIllegalStateException;
26 import org.hipparchus.ode.sampling.ODEStateInterpolator;
27
28 /** This interface represents an interpolator over the last step
29 * during an ODE integration.
30 *
31 * <p>The various ODE integrators provide objects implementing this
32 * interface to the step handlers. These objects are often custom
33 * objects tightly bound to the integrator internal algorithms. The
34 * handlers can use these objects to retrieve the state vector at
35 * intermediate times between the previous and the current grid points
36 * (this feature is often called dense output).</p>
37 * <p>One important thing to note is that the step handlers may be so
38 * tightly bound to the integrators that they often share some internal
39 * state arrays. This imply that one should <em>never</em> use a direct
40 * reference to a step interpolator outside of the step handler, either
41 * for future use or for use in another thread. If such a need arise, the
42 * step interpolator <em>must</em> be copied using the dedicated
43 * {@link #copy()} method.
44 * </p>
45 *
46 * @see org.hipparchus.ode.ODEIntegrator
47 * @see StepHandler
48 * @deprecated as of 1.0, replaced with {@link ODEStateInterpolator}
49 */
50 @Deprecated
51 public interface StepInterpolator extends ODEStateInterpolator {
52
53 /**
54 * Get the previous grid point time.
55 * @return previous grid point time
56 * @deprecated as of 1.0, replaced with {@link #getPreviousState()}/{@link org.hipparchus.ode.ODEState#getTime()}
57 */
58 @Deprecated
59 double getPreviousTime();
60
61 /**
62 * Get the current grid point time.
63 * @return current grid point time
64 * @deprecated as of 1.0, replaced with {@link #getCurrentState()}/{@link org.hipparchus.ode.ODEState#getTime()}
65 */
66 @Deprecated
67 double getCurrentTime();
68
69 /**
70 * Get the time of the interpolated point.
71 * If {@link #setInterpolatedTime} has not been called, it returns
72 * the current grid point time.
73 * @return interpolation point time
74 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}/{@link org.hipparchus.ode.ODEState#getTime()}
75 */
76 @Deprecated
77 double getInterpolatedTime();
78
79 /**
80 * Set the time of the interpolated point.
81 * <p>Setting the time outside of the current step is now allowed, but
82 * should be used with care since the accuracy of the interpolator will
83 * probably be very poor far from this step. This allowance has been
84 * added to simplify implementation of search algorithms near the
85 * step endpoints.</p>
86 * <p>Setting the time changes the instance internal state. This includes
87 * the internal arrays returned in {@link #getInterpolatedState()},
88 * {@link #getInterpolatedDerivatives()}, {@link
89 * #getInterpolatedSecondaryState(int)} and {@link
90 * #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved
91 * across several calls, user must copy them.</p>
92 * @param time time of the interpolated point
93 * @see #getInterpolatedState()
94 * @see #getInterpolatedDerivatives()
95 * @see #getInterpolatedSecondaryState(int)
96 * @see #getInterpolatedSecondaryDerivatives(int)
97 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}
98 */
99 @Deprecated
100 void setInterpolatedTime(double time);
101
102 /**
103 * Get the state vector of the interpolated point.
104 * <p>The returned vector is a reference to a reused array, so
105 * it should not be modified and it should be copied if it needs
106 * to be preserved across several calls to the associated
107 * {@link #setInterpolatedTime(double)} method.</p>
108 * @return state vector at time {@link #getInterpolatedTime}
109 * @see #getInterpolatedDerivatives()
110 * @see #getInterpolatedSecondaryState(int)
111 * @see #getInterpolatedSecondaryDerivatives(int)
112 * @see #setInterpolatedTime(double)
113 * @exception MathIllegalStateException if the number of functions evaluations is exceeded
114 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}.{@link org.hipparchus.ode.ODEState#getPrimaryState()}
115 */
116 @Deprecated
117 double[] getInterpolatedState() throws MathIllegalStateException;
118
119 /**
120 * Get the derivatives of the state vector of the interpolated point.
121 * <p>The returned vector is a reference to a reused array, so
122 * it should not be modified and it should be copied if it needs
123 * to be preserved across several calls to the associated
124 * {@link #setInterpolatedTime(double)} method.</p>
125 * @return derivatives of the state vector at time {@link #getInterpolatedTime}
126 * @see #getInterpolatedState()
127 * @see #getInterpolatedSecondaryState(int)
128 * @see #getInterpolatedSecondaryDerivatives(int)
129 * @see #setInterpolatedTime(double)
130 * @exception MathIllegalStateException if the number of functions evaluations is exceeded
131 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}.{@link org.hipparchus.ode.ODEStateAndDerivative#getPrimaryDerivative()}
132 */
133 @Deprecated
134 double[] getInterpolatedDerivatives() throws MathIllegalStateException;
135
136 /** Get the interpolated secondary state corresponding to the secondary equations.
137 * <p>The returned vector is a reference to a reused array, so
138 * it should not be modified and it should be copied if it needs
139 * to be preserved across several calls to the associated
140 * {@link #setInterpolatedTime(double)} method.</p>
141 * @param index index of the secondary set, as returned by {@link
142 * org.hipparchus.ode.ExpandableODE#addSecondaryEquations(org.hipparchus.ode.SecondaryODE)
143 * ExpandableODE.addSecondaryEquations(secondary)}
144 * @return interpolated secondary state at the current interpolation date
145 * @see #getInterpolatedState()
146 * @see #getInterpolatedDerivatives()
147 * @see #getInterpolatedSecondaryDerivatives(int)
148 * @see #setInterpolatedTime(double)
149 * @exception MathIllegalStateException if the number of functions evaluations is exceeded
150 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}.{@link org.hipparchus.ode.ODEState#getSecondaryState(int)}
151 */
152 @Deprecated
153 double[] getInterpolatedSecondaryState(int index) throws MathIllegalStateException;
154
155 /** Get the interpolated secondary derivatives corresponding to the secondary equations.
156 * <p>The returned vector is a reference to a reused array, so
157 * it should not be modified and it should be copied if it needs
158 * to be preserved across several calls.</p>
159 * @param index index of the secondary set, as returned by {@link
160 * org.hipparchus.ode.ExpandableODE#addSecondaryEquations(org.hipparchus.ode.SecondaryODE)
161 * ExpandableODE.addSecondaryEquations(secondary)}
162 * @return interpolated secondary derivatives at the current interpolation date
163 * @see #getInterpolatedState()
164 * @see #getInterpolatedDerivatives()
165 * @see #getInterpolatedSecondaryState(int)
166 * @see #setInterpolatedTime(double)
167 * @exception MathIllegalStateException if the number of functions evaluations is exceeded
168 * @deprecated as of 1.0, replaced with {@link #getInterpolatedState(double)}.{@link org.hipparchus.ode.ODEStateAndDerivative#getSecondaryDerivative(int)}
169 */
170 @Deprecated
171 double[] getInterpolatedSecondaryDerivatives(int index) throws MathIllegalStateException;
172
173 /** Check if the natural integration direction is forward.
174 * <p>This method provides the integration direction as specified by
175 * the integrator itself, it avoid some nasty problems in
176 * degenerated cases like null steps due to cancellation at step
177 * initialization, step control or discrete events
178 * triggering.</p>
179 * @return true if the integration variable (time) increases during
180 * integration
181 */
182 @Override
183 boolean isForward();
184
185 /** Copy the instance.
186 * <p>The copied instance is guaranteed to be independent from the
187 * original one. Both can be used with different settings for
188 * interpolated time without any side effect.</p>
189 * @return a deep copy of the instance, which can be used independently.
190 * @see #setInterpolatedTime(double)
191 * @exception MathIllegalStateException if the number of functions evaluations is exceeded
192 * during step finalization
193 */
194 StepInterpolator copy() throws MathIllegalStateException;
195
196 }