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 * http://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 package org.apache.commons.math4.legacy.ode.sampling;
19
20 import java.io.Externalizable;
21
22 import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
23
24 /** This interface represents an interpolator over the last step
25 * during an ODE integration.
26 *
27 * <p>The various ODE integrators provide objects implementing this
28 * interface to the step handlers. These objects are often custom
29 * objects tightly bound to the integrator internal algorithms. The
30 * handlers can use these objects to retrieve the state vector at
31 * intermediate times between the previous and the current grid points
32 * (this feature is often called dense output).</p>
33 * <p>One important thing to note is that the step handlers may be so
34 * tightly bound to the integrators that they often share some internal
35 * state arrays. This imply that one should <em>never</em> use a direct
36 * reference to a step interpolator outside of the step handler, either
37 * for future use or for use in another thread. If such a need arise, the
38 * step interpolator <em>must</em> be copied using the dedicated
39 * {@link #copy()} method.
40 * </p>
41 *
42 * @see org.apache.commons.math4.legacy.ode.FirstOrderIntegrator
43 * @see org.apache.commons.math4.legacy.ode.SecondOrderIntegrator
44 * @see StepHandler
45 * @since 1.2
46 */
47
48 public interface StepInterpolator extends Externalizable {
49
50 /**
51 * Get the previous grid point time.
52 * @return previous grid point time
53 */
54 double getPreviousTime();
55
56 /**
57 * Get the current grid point time.
58 * @return current grid point time
59 */
60 double getCurrentTime();
61
62 /**
63 * Get the time of the interpolated point.
64 * If {@link #setInterpolatedTime} has not been called, it returns
65 * the current grid point time.
66 * @return interpolation point time
67 */
68 double getInterpolatedTime();
69
70 /**
71 * Set the time of the interpolated point.
72 * <p>Setting the time outside of the current step is now allowed, but
73 * should be used with care since the accuracy of the interpolator will
74 * probably be very poor far from this step. This allowance has been
75 * added to simplify implementation of search algorithms near the
76 * step endpoints.</p>
77 * <p>Setting the time changes the instance internal state. This includes
78 * the internal arrays returned in {@link #getInterpolatedState()},
79 * {@link #getInterpolatedDerivatives()}, {@link
80 * #getInterpolatedSecondaryState(int)} and {@link
81 * #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved
82 * across several calls, user must copy them.</p>
83 * @param time time of the interpolated point
84 * @see #getInterpolatedState()
85 * @see #getInterpolatedDerivatives()
86 * @see #getInterpolatedSecondaryState(int)
87 * @see #getInterpolatedSecondaryDerivatives(int)
88 */
89 void setInterpolatedTime(double time);
90
91 /**
92 * Get the state vector of the interpolated point.
93 * <p>The returned vector is a reference to a reused array, so
94 * it should not be modified and it should be copied if it needs
95 * to be preserved across several calls to the associated
96 * {@link #setInterpolatedTime(double)} method.</p>
97 * @return state vector at time {@link #getInterpolatedTime}
98 * @see #getInterpolatedDerivatives()
99 * @see #getInterpolatedSecondaryState(int)
100 * @see #getInterpolatedSecondaryDerivatives(int)
101 * @see #setInterpolatedTime(double)
102 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
103 */
104 double[] getInterpolatedState() throws MaxCountExceededException;
105
106 /**
107 * Get the derivatives of the state vector of the interpolated point.
108 * <p>The returned vector is a reference to a reused array, so
109 * it should not be modified and it should be copied if it needs
110 * to be preserved across several calls to the associated
111 * {@link #setInterpolatedTime(double)} method.</p>
112 * @return derivatives of the state vector at time {@link #getInterpolatedTime}
113 * @see #getInterpolatedState()
114 * @see #getInterpolatedSecondaryState(int)
115 * @see #getInterpolatedSecondaryDerivatives(int)
116 * @see #setInterpolatedTime(double)
117 * @since 2.0
118 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
119 */
120 double[] getInterpolatedDerivatives() throws MaxCountExceededException;
121
122 /** Get the interpolated secondary state corresponding to the secondary equations.
123 * <p>The returned vector is a reference to a reused array, so
124 * it should not be modified and it should be copied if it needs
125 * to be preserved across several calls to the associated
126 * {@link #setInterpolatedTime(double)} method.</p>
127 * @param index index of the secondary set, as returned by {@link
128 * org.apache.commons.math4.legacy.ode.ExpandableStatefulODE#addSecondaryEquations(
129 * org.apache.commons.math4.legacy.ode.SecondaryEquations)
130 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
131 * @return interpolated secondary state at the current interpolation date
132 * @see #getInterpolatedState()
133 * @see #getInterpolatedDerivatives()
134 * @see #getInterpolatedSecondaryDerivatives(int)
135 * @see #setInterpolatedTime(double)
136 * @since 3.0
137 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
138 */
139 double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
140
141 /** Get the interpolated secondary derivatives corresponding to the secondary equations.
142 * <p>The returned vector is a reference to a reused array, so
143 * it should not be modified and it should be copied if it needs
144 * to be preserved across several calls.</p>
145 * @param index index of the secondary set, as returned by {@link
146 * org.apache.commons.math4.legacy.ode.ExpandableStatefulODE#addSecondaryEquations(
147 * org.apache.commons.math4.legacy.ode.SecondaryEquations)
148 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
149 * @return interpolated secondary derivatives at the current interpolation date
150 * @see #getInterpolatedState()
151 * @see #getInterpolatedDerivatives()
152 * @see #getInterpolatedSecondaryState(int)
153 * @see #setInterpolatedTime(double)
154 * @since 3.0
155 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
156 */
157 double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
158
159 /** Check if the natural integration direction is forward.
160 * <p>This method provides the integration direction as specified by
161 * the integrator itself, it avoid some nasty problems in
162 * degenerated cases like null steps due to cancellation at step
163 * initialization, step control or discrete events
164 * triggering.</p>
165 * @return true if the integration variable (time) increases during
166 * integration
167 */
168 boolean isForward();
169
170 /** Copy the instance.
171 * <p>The copied instance is guaranteed to be independent from the
172 * original one. Both can be used with different settings for
173 * interpolated time without any side effect.</p>
174 * @return a deep copy of the instance, which can be used independently.
175 * @see #setInterpolatedTime(double)
176 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
177 * during step finalization
178 */
179 StepInterpolator copy() throws MaxCountExceededException;
180 }