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.math3.ode.sampling;
19
20 import java.io.Externalizable;
21
22 import org.apache.commons.math3.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.math3.ode.FirstOrderIntegrator
43 * @see org.apache.commons.math3.ode.SecondOrderIntegrator
44 * @see StepHandler
45 * @version $Id: StepInterpolator.java 1416643 2012-12-03 19:37:14Z tn $
46 * @since 1.2
47 */
48
49 public interface StepInterpolator extends Externalizable {
50
51 /**
52 * Get the previous grid point time.
53 * @return previous grid point time
54 */
55 double getPreviousTime();
56
57 /**
58 * Get the current grid point time.
59 * @return current grid point time
60 */
61 double getCurrentTime();
62
63 /**
64 * Get the time of the interpolated point.
65 * If {@link #setInterpolatedTime} has not been called, it returns
66 * the current grid point time.
67 * @return interpolation point time
68 */
69 double getInterpolatedTime();
70
71 /**
72 * Set the time of the interpolated point.
73 * <p>Setting the time outside of the current step is now allowed, but
74 * should be used with care since the accuracy of the interpolator will
75 * probably be very poor far from this step. This allowance has been
76 * added to simplify implementation of search algorithms near the
77 * step endpoints.</p>
78 * <p>Setting the time changes the instance internal state. If a
79 * specific state must be preserved, a copy of the instance must be
80 * created using {@link #copy()}.</p>
81 * @param time time of the interpolated point
82 */
83 void setInterpolatedTime(double time);
84
85 /**
86 * Get the state vector of the interpolated point.
87 * <p>The returned vector is a reference to a reused array, so
88 * it should not be modified and it should be copied if it needs
89 * to be preserved across several calls.</p>
90 * @return state vector at time {@link #getInterpolatedTime}
91 * @see #getInterpolatedDerivatives()
92 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
93 */
94 double[] getInterpolatedState() throws MaxCountExceededException;
95
96 /**
97 * Get the derivatives of the state vector of the interpolated point.
98 * <p>The returned vector is a reference to a reused array, so
99 * it should not be modified and it should be copied if it needs
100 * to be preserved across several calls.</p>
101 * @return derivatives of the state vector at time {@link #getInterpolatedTime}
102 * @see #getInterpolatedState()
103 * @since 2.0
104 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
105 */
106 double[] getInterpolatedDerivatives() throws MaxCountExceededException;
107
108 /** Get the interpolated secondary state corresponding to the secondary equations.
109 * <p>The returned vector is a reference to a reused array, so
110 * it should not be modified and it should be copied if it needs
111 * to be preserved across several calls.</p>
112 * @param index index of the secondary set, as returned by {@link
113 * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
114 * org.apache.commons.math3.ode.SecondaryEquations)
115 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
116 * @return interpolated secondary state at the current interpolation date
117 * @see #getInterpolatedState()
118 * @see #getInterpolatedDerivatives()
119 * @see #getInterpolatedSecondaryDerivatives(int)
120 * @see #setInterpolatedTime(double)
121 * @since 3.0
122 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
123 */
124 double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
125
126 /** Get the interpolated secondary derivatives corresponding to the secondary equations.
127 * <p>The returned vector is a reference to a reused array, so
128 * it should not be modified and it should be copied if it needs
129 * to be preserved across several calls.</p>
130 * @param index index of the secondary set, as returned by {@link
131 * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
132 * org.apache.commons.math3.ode.SecondaryEquations)
133 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
134 * @return interpolated secondary derivatives at the current interpolation date
135 * @see #getInterpolatedState()
136 * @see #getInterpolatedDerivatives()
137 * @see #getInterpolatedSecondaryState(int)
138 * @see #setInterpolatedTime(double)
139 * @since 3.0
140 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
141 */
142 double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
143
144 /** Check if the natural integration direction is forward.
145 * <p>This method provides the integration direction as specified by
146 * the integrator itself, it avoid some nasty problems in
147 * degenerated cases like null steps due to cancellation at step
148 * initialization, step control or discrete events
149 * triggering.</p>
150 * @return true if the integration variable (time) increases during
151 * integration
152 */
153 boolean isForward();
154
155 /** Copy the instance.
156 * <p>The copied instance is guaranteed to be independent from the
157 * original one. Both can be used with different settings for
158 * interpolated time without any side effect.</p>
159 * @return a deep copy of the instance, which can be used independently.
160 * @see #setInterpolatedTime(double)
161 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
162 * during step finalization
163 */
164 StepInterpolator copy() throws MaxCountExceededException;
165
166 }