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 org.hipparchus.CalculusFieldElement;
21 import org.hipparchus.ode.FieldODEStateAndDerivative;
22
23 /** This interface represents an interpolator over the last step
24 * during an ODE integration.
25 *
26 * <p>The various ODE integrators provide objects implementing this
27 * interface to the step handlers. These objects are often custom
28 * objects tightly bound to the integrator internal algorithms. The
29 * handlers can use these objects to retrieve the state vector at
30 * intermediate times between the previous and the current grid points
31 * (this feature is often called dense output).</p>
32 *
33 * @param <T> the type of the field elements
34 * @see org.hipparchus.ode.FieldODEIntegrator
35 * @see FieldODEStepHandler
36 */
37
38 public interface FieldODEStateInterpolator<T extends CalculusFieldElement<T>> {
39
40 /**
41 * Get the state at previous grid point time.
42 * @return state at previous grid point time
43 */
44 FieldODEStateAndDerivative<T> getPreviousState();
45
46 /**
47 * Determines if the {@link #getPreviousState() previous state} is computed directly
48 * by the integrator, or if it is calculated using {@link #getInterpolatedState(CalculusFieldElement)
49 * interpolation}.
50 *
51 * <p> Typically the previous state is directly computed by the integrator, but when
52 * events are detected the steps are shortened so that events occur on step boundaries
53 * which means the previous state may be computed by the interpolator.
54 *
55 * @return {@code true} if the previous state was calculated by the interpolator and
56 * false if it was computed directly by the integrator.
57 */
58 boolean isPreviousStateInterpolated();
59
60 /**
61 * Get the state at current grid point time.
62 * @return state at current grid point time
63 */
64 FieldODEStateAndDerivative<T> getCurrentState();
65
66 /**
67 * Determines if the {@link #getCurrentState() current state} is computed directly by
68 * the integrator, or if it is calculated using {@link #getInterpolatedState(CalculusFieldElement)
69 * interpolation}.
70 *
71 * <p> Typically the current state is directly computed by the integrator, but when
72 * events are detected the steps are shortened so that events occur on step boundaries
73 * which means the current state may be computed by the interpolator.
74 *
75 * @return {@code true} if the current state was calculated by the interpolator and
76 * false if it was computed directly by the integrator.
77 */
78 boolean isCurrentStateInterpolated();
79
80 /**
81 * Get the state at interpolated time.
82 * <p>Setting the time outside of the current step is allowed, but
83 * should be used with care since the accuracy of the interpolator will
84 * probably be very poor far from this step. This allowance has been
85 * added to simplify implementation of search algorithms near the
86 * step endpoints.</p>
87 * @param time time of the interpolated point
88 * @return state at interpolated time
89 */
90 FieldODEStateAndDerivative<T> getInterpolatedState(T time);
91
92 /** Check if the natural integration direction is forward.
93 * <p>This method provides the integration direction as specified by
94 * the integrator itself, it avoid some nasty problems in
95 * degenerated cases like null steps due to cancellation at step
96 * initialization, step control or discrete events
97 * triggering.</p>
98 * @return true if the integration variable (time) increases during
99 * integration
100 */
101 boolean isForward();
102
103 /** Create a new restricted version of the instance.
104 * <p>
105 * The instance is not changed at all.
106 * </p>
107 * @param previousState start of the restricted step
108 * @param currentState end of the restricted step
109 * @return restricted version of the instance
110 * @see #getPreviousState()
111 * @see #getCurrentState()
112 */
113 FieldODEStateInterpolator<T> restrictStep(FieldODEStateAndDerivative<T> previousState,
114 FieldODEStateAndDerivative<T> currentState);
115 }