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.math.ode;
19
20 import java.io.Externalizable;
21
22 /** This interface represents an interpolator over the last step
23 * during an ODE integration.
24 *
25 * <p>The various ODE integrators provide objects implementing this
26 * interface to the step handlers. These objects are often custom
27 * objects tightly bound to the integrator internal algorithms. The
28 * handlers can use these objects to retrieve the state vector at
29 * intermediate times between the previous and the current grid points
30 * (this feature is often called dense output).</p>
31 *
32 * @see FirstOrderIntegrator
33 * @see SecondOrderIntegrator
34 * @see StepHandler
35 * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
36 * @since 1.2
37 */
38
39 public interface StepInterpolator
40 extends Externalizable {
41
42 /**
43 * Get the previous grid point time.
44 * @return previous grid point time
45 */
46 public double getPreviousTime();
47
48 /**
49 * Get the current grid point time.
50 * @return current grid point time
51 */
52 public double getCurrentTime();
53
54 /**
55 * Get the time of the interpolated point.
56 * If {@link #setInterpolatedTime} has not been called, it returns
57 * the current grid point time.
58 * @return interpolation point time
59 */
60 public double getInterpolatedTime();
61
62 /**
63 * Set the time of the interpolated point.
64 * <p>Setting the time outside of the current step is now allowed, but
65 * should be used with care since the accuracy of the interpolator will
66 * probably be very poor far from this step. This allowance has been
67 * added to simplify implementation of search algorithms near the
68 * step endpoints.</p>
69 * <p>Setting the time changes the instance internal state. If a
70 * specific state must be preserved, a copy of the instance must be
71 * created using {@link #copy()}.</p>
72 * @param time time of the interpolated point
73 * @throws DerivativeException if this call induces an automatic
74 * step finalization that throws one
75 */
76 public void setInterpolatedTime(double time)
77 throws DerivativeException;
78
79 /**
80 * Get the state vector of the interpolated point.
81 * @return state vector at time {@link #getInterpolatedTime}
82 */
83 public double[] getInterpolatedState();
84
85 /** Check if the natural integration direction is forward.
86 * <p>This method provides the integration direction as specified by
87 * the integrator itself, it avoid some nasty problems in
88 * degenerated cases like null steps due to cancellation at step
89 * initialization, step control or switching function
90 * triggering.</p>
91 * @return true if the integration variable (time) increases during
92 * integration
93 */
94 public boolean isForward();
95
96 /** Copy the instance.
97 * <p>The copied instance is guaranteed to be independent from the
98 * original one. Both can be used with different settings for
99 * interpolated time without any side effect.</p>
100 * @return a deep copy of the instance, which can be used independently.
101 * @throws DerivativeException if this call induces an automatic
102 * step finalization that throws one
103 * @see #setInterpolatedTime(double)
104 */
105 public StepInterpolator copy() throws DerivativeException;
106
107 }