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 org.apache.commons.math4.legacy.core.RealFieldElement;
21 import org.apache.commons.math4.legacy.exception.MaxCountExceededException;
22 import org.apache.commons.math4.legacy.ode.FieldEquationsMapper;
23 import org.apache.commons.math4.legacy.ode.FieldODEStateAndDerivative;
24
25 /** This abstract class represents an interpolator over the last step
26 * during an ODE integration.
27 *
28 * <p>The various ODE integrators provide objects extending this class
29 * to the step handlers. The handlers can use these objects to
30 * retrieve the state vector at intermediate times between the
31 * previous and the current grid points (dense output).</p>
32 *
33 * @see org.apache.commons.math4.legacy.ode.FirstOrderFieldIntegrator
34 * @see StepHandler
35 *
36 * @param <T> the type of the field elements
37 * @since 3.6
38 */
39
40 public abstract class AbstractFieldStepInterpolator<T extends RealFieldElement<T>>
41 implements FieldStepInterpolator<T> {
42
43 /** Global previous state. */
44 private final FieldODEStateAndDerivative<T> globalPreviousState;
45
46 /** Global current state. */
47 private final FieldODEStateAndDerivative<T> globalCurrentState;
48
49 /** Soft previous state. */
50 private final FieldODEStateAndDerivative<T> softPreviousState;
51
52 /** Soft current state. */
53 private final FieldODEStateAndDerivative<T> softCurrentState;
54
55 /** integration direction. */
56 private final boolean forward;
57
58 /** Mapper for ODE equations primary and secondary components. */
59 private FieldEquationsMapper<T> mapper;
60
61 /** Simple constructor.
62 * @param isForward integration direction indicator
63 * @param globalPreviousState start of the global step
64 * @param globalCurrentState end of the global step
65 * @param softPreviousState start of the restricted step
66 * @param softCurrentState end of the restricted step
67 * @param equationsMapper mapper for ODE equations primary and secondary components
68 */
69 protected AbstractFieldStepInterpolator(final boolean isForward,
70 final FieldODEStateAndDerivative<T> globalPreviousState,
71 final FieldODEStateAndDerivative<T> globalCurrentState,
72 final FieldODEStateAndDerivative<T> softPreviousState,
73 final FieldODEStateAndDerivative<T> softCurrentState,
74 final FieldEquationsMapper<T> equationsMapper) {
75 this.forward = isForward;
76 this.globalPreviousState = globalPreviousState;
77 this.globalCurrentState = globalCurrentState;
78 this.softPreviousState = softPreviousState;
79 this.softCurrentState = softCurrentState;
80 this.mapper = equationsMapper;
81 }
82
83 /** Create a new restricted version of the instance.
84 * <p>
85 * The instance is not changed at all.
86 * </p>
87 * @param previousState start of the restricted step
88 * @param currentState end of the restricted step
89 * @return restricted version of the instance
90 * @see #getPreviousState()
91 * @see #getCurrentState()
92 */
93 public AbstractFieldStepInterpolator<T> restrictStep(final FieldODEStateAndDerivative<T> previousState,
94 final FieldODEStateAndDerivative<T> currentState) {
95 return create(forward, globalPreviousState, globalCurrentState, previousState, currentState, mapper);
96 }
97
98 /** Create a new instance.
99 * @param newForward integration direction indicator
100 * @param newGlobalPreviousState start of the global step
101 * @param newGlobalCurrentState end of the global step
102 * @param newSoftPreviousState start of the restricted step
103 * @param newSoftCurrentState end of the restricted step
104 * @param newMapper equations mapper for the all equations
105 * @return a new instance
106 */
107 protected abstract AbstractFieldStepInterpolator<T> create(boolean newForward,
108 FieldODEStateAndDerivative<T> newGlobalPreviousState,
109 FieldODEStateAndDerivative<T> newGlobalCurrentState,
110 FieldODEStateAndDerivative<T> newSoftPreviousState,
111 FieldODEStateAndDerivative<T> newSoftCurrentState,
112 FieldEquationsMapper<T> newMapper);
113
114 /**
115 * Get the previous global grid point state.
116 * @return previous global grid point state
117 */
118 public FieldODEStateAndDerivative<T> getGlobalPreviousState() {
119 return globalPreviousState;
120 }
121
122 /**
123 * Get the current global grid point state.
124 * @return current global grid point state
125 */
126 public FieldODEStateAndDerivative<T> getGlobalCurrentState() {
127 return globalCurrentState;
128 }
129
130 /** {@inheritDoc} */
131 @Override
132 public FieldODEStateAndDerivative<T> getPreviousState() {
133 return softPreviousState;
134 }
135
136 /** {@inheritDoc} */
137 @Override
138 public FieldODEStateAndDerivative<T> getCurrentState() {
139 return softCurrentState;
140 }
141
142 /** {@inheritDoc} */
143 @Override
144 public FieldODEStateAndDerivative<T> getInterpolatedState(final T time) {
145 final T thetaH = time.subtract(globalPreviousState.getTime());
146 final T oneMinusThetaH = globalCurrentState.getTime().subtract(time);
147 final T theta = thetaH.divide(globalCurrentState.getTime().subtract(globalPreviousState.getTime()));
148 return computeInterpolatedStateAndDerivatives(mapper, time, theta, thetaH, oneMinusThetaH);
149 }
150
151 /** {@inheritDoc} */
152 @Override
153 public boolean isForward() {
154 return forward;
155 }
156
157 /** Compute the state and derivatives at the interpolated time.
158 * This is the main processing method that should be implemented by
159 * the derived classes to perform the interpolation.
160 * @param equationsMapper mapper for ODE equations primary and secondary components
161 * @param time interpolation time
162 * @param theta normalized interpolation abscissa within the step
163 * (theta is zero at the previous time step and one at the current time step)
164 * @param thetaH time gap between the previous time and the interpolated time
165 * @param oneMinusThetaH time gap between the interpolated time and
166 * the current time
167 * @return interpolated state and derivatives
168 * @exception MaxCountExceededException if the number of functions evaluations is exceeded
169 */
170 protected abstract FieldODEStateAndDerivative<T> computeInterpolatedStateAndDerivatives(FieldEquationsMapper<T> equationsMapper,
171 T time, T theta,
172 T thetaH, T oneMinusThetaH)
173 throws MaxCountExceededException;
174 }