1 /*
2 * Licensed to the Hipparchus project 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 Hipparchus project 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 package org.hipparchus.ode.sampling;
19
20 import java.io.Serializable;
21
22 import org.hipparchus.ode.ODEStateAndDerivative;
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 *
34 * @see org.hipparchus.ode.ODEIntegrator
35 * @see ODEStepHandler
36 */
37
38 public interface ODEStateInterpolator extends Serializable {
39 /**
40 * Get the state at previous grid point time.
41 * @return state at previous grid point time
42 */
43 ODEStateAndDerivative getPreviousState();
44
45 /**
46 * Determines if the {@link #getPreviousState() previous state} is computed directly
47 * by the integrator, or if it is calculated using {@link #getInterpolatedState(double)
48 * interpolation}.
49 *
50 * <p> Typically the previous state is directly computed by the integrator, but when
51 * events are detected the steps are shortened so that events occur on step boundaries
52 * which means the previous state may be computed by the interpolator.
53 *
54 * @return {@code true} if the previous state was calculated by the interpolator and
55 * false if it was computed directly by the integrator.
56 */
57 boolean isPreviousStateInterpolated();
58
59 /**
60 * Get the state at current grid point time.
61 * @return state at current grid point time
62 */
63 ODEStateAndDerivative getCurrentState();
64
65 /**
66 * Determines if the {@link #getCurrentState() current state} is computed directly by
67 * the integrator, or if it is calculated using {@link #getInterpolatedState(double)
68 * interpolation}.
69 *
70 * <p> Typically the current state is directly computed by the integrator, but when
71 * events are detected the steps are shortened so that events occur on step boundaries
72 * which means the current state may be computed by the interpolator.
73 *
74 * @return {@code true} if the current state was calculated by the interpolator and
75 * false if it was computed directly by the integrator.
76 */
77 boolean isCurrentStateInterpolated();
78
79 /**
80 * Get the state at interpolated time.
81 * <p>Setting the time outside of the current step is 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 * @param time time of the interpolated point
87 * @return state at interpolated time
88 */
89 ODEStateAndDerivative getInterpolatedState(double time);
90
91 /** Check if the natural integration direction is forward.
92 * <p>This method provides the integration direction as specified by
93 * the integrator itself, it avoid some nasty problems in
94 * degenerated cases like null steps due to cancellation at step
95 * initialization, step control or discrete events
96 * triggering.</p>
97 * @return true if the integration variable (time) increases during
98 * integration
99 */
100 boolean isForward();
101
102 /** Create a new restricted version of the instance.
103 * <p>
104 * The instance is not changed at all.
105 * </p>
106 * @param previousState start of the restricted step
107 * @param currentState end of the restricted step
108 * @return restricted version of the instance
109 * @see #getPreviousState()
110 * @see #getCurrentState()
111 */
112 ODEStateInterpolator restrictStep(ODEStateAndDerivative previousState,
113 ODEStateAndDerivative currentState);
114 }