1 /* Copyright 2002-2026 CS GROUP
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS 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 package org.orekit.time;
18
19 import org.hipparchus.CalculusFieldElement;
20 import org.hipparchus.Field;
21 import org.hipparchus.util.FastMath;
22 import org.orekit.errors.OrekitIllegalArgumentException;
23 import org.orekit.errors.OrekitInternalError;
24 import org.orekit.errors.OrekitMessages;
25 import org.orekit.utils.FieldSortedListTrimmer;
26 import org.orekit.utils.ImmutableFieldTimeStampedCache;
27
28 import java.util.ArrayList;
29 import java.util.Collection;
30 import java.util.Collections;
31 import java.util.List;
32 import java.util.Optional;
33 import java.util.stream.Collectors;
34 import java.util.stream.Stream;
35
36 /**
37 * Abstract class for time interpolator.
38 *
39 * @param <T> interpolated time stamped type
40 * @param <KK> type of the field element
41 *
42 * @author Vincent Cucchietti
43 */
44 public abstract class AbstractFieldTimeInterpolator<T extends FieldTimeStamped<KK>, KK extends CalculusFieldElement<KK>>
45 implements FieldTimeInterpolator<T, KK> {
46
47 /** Default extrapolation time threshold: 1ms. */
48 public static final double DEFAULT_EXTRAPOLATION_THRESHOLD_SEC = 1e-3;
49
50 /** Default number of interpolation points. */
51 public static final int DEFAULT_INTERPOLATION_POINTS = 2;
52
53 /** The extrapolation threshold beyond which the propagation will fail. */
54 private final double extrapolationThreshold;
55
56 /** Neighbor size. */
57 private final int interpolationPoints;
58
59 /**
60 * Constructor.
61 *
62 * @param interpolationPoints number of interpolation points
63 * @param extrapolationThreshold extrapolation threshold beyond which the propagation will fail
64 */
65 protected AbstractFieldTimeInterpolator(final int interpolationPoints, final double extrapolationThreshold) {
66 this.interpolationPoints = interpolationPoints;
67 this.extrapolationThreshold = extrapolationThreshold;
68 }
69
70 /**
71 * Method checking if given interpolator is compatible with given sample size.
72 *
73 * @param interpolator interpolator
74 * @param sampleSize sample size
75 * @param <T> type of the field elements
76 */
77 public static <T extends CalculusFieldElement<T>> void checkInterpolatorCompatibilityWithSampleSize(
78 final FieldTimeInterpolator<? extends FieldTimeStamped<T>, T> interpolator,
79 final int sampleSize) {
80
81 // Retrieve all sub-interpolators (or a singleton list with given interpolator if there are no sub-interpolators)
82 final List<FieldTimeInterpolator<? extends FieldTimeStamped<T>, T>> subInterpolators =
83 interpolator.getSubInterpolators();
84 for (final FieldTimeInterpolator<? extends FieldTimeStamped<T>, T> subInterpolator : subInterpolators) {
85 if (sampleSize < subInterpolator.getNbInterpolationPoints()) {
86 throw new OrekitIllegalArgumentException(OrekitMessages.NOT_ENOUGH_DATA, sampleSize);
87 }
88 }
89 }
90
91 /**
92 * {@inheritDoc}
93 * <p>
94 * The stream must yield elements in chronological order.
95 */
96 @Override
97 public T interpolate(final FieldAbsoluteDate<KK> interpolationDate, final Stream<T> sample) {
98 return interpolate(interpolationDate, sample.collect(Collectors.toList()));
99 }
100
101 /**
102 * {@inheritDoc}
103 * <p>
104 * <strong>Precondition:</strong> {@code sample} must be sorted in chronological order. Passing an unsorted
105 * sample yields undefined neighbors and may throw
106 * {@link org.orekit.errors.TimeStampedCacheException}.
107 */
108 @Override
109 public T interpolate(final FieldAbsoluteDate<KK> interpolationDate, final Collection<T> sample) {
110 final InterpolationData interpolationData = new InterpolationData(interpolationDate, sample);
111 return interpolate(interpolationData);
112 }
113
114 /**
115 * Get the central date to use to find neighbors while taking into account extrapolation threshold.
116 *
117 * @param date interpolation date
118 * @param cachedSamples cached samples
119 * @param threshold extrapolation threshold
120 * @param <T> type of time stamped element
121 * @param <KK> type of calculus field element
122 *
123 * @return central date to use to find neighbors
124 * @since 12.0.1
125 */
126 public static <T extends FieldTimeStamped<KK>, KK extends CalculusFieldElement<KK>> FieldAbsoluteDate<KK> getCentralDate(
127 final FieldAbsoluteDate<KK> date,
128 final ImmutableFieldTimeStampedCache<T, KK> cachedSamples,
129 final double threshold) {
130 return getCentralDate(
131 date,
132 cachedSamples.getEarliest().getDate(),
133 cachedSamples.getLatest().getDate(),
134 threshold);
135 }
136
137 /**
138 * Get the central date to use to find neighbors while taking into account extrapolation threshold.
139 *
140 * @param date interpolation date
141 * @param minDate earliest date in the sample.
142 * @param maxDate latest date in the sample.
143 * @param threshold extrapolation threshold
144 * @param <KK> type of calculus field element
145 *
146 * @return central date to use to find neighbors
147 * @since 12.0.1
148 */
149 public static <KK extends CalculusFieldElement<KK>> FieldAbsoluteDate<KK> getCentralDate(
150 final FieldAbsoluteDate<KK> date,
151 final FieldAbsoluteDate<KK> minDate,
152 final FieldAbsoluteDate<KK> maxDate,
153 final double threshold) {
154 final FieldAbsoluteDate<KK> central;
155
156 if (date.compareTo(minDate) < 0 && FastMath.abs(date.durationFrom(minDate)).getReal() <= threshold) {
157 // avoid TimeStampedCacheException as we are still within the tolerance before minDate
158 central = minDate;
159 } else if (date.compareTo(maxDate) > 0 && FastMath.abs(date.durationFrom(maxDate)).getReal() <= threshold) {
160 // avoid TimeStampedCacheException as we are still within the tolerance after maxDate
161 central = maxDate;
162 } else {
163 central = date;
164 }
165
166 return central;
167 }
168
169 /** {@inheritDoc} */
170 public List<FieldTimeInterpolator<? extends FieldTimeStamped<KK>, KK>> getSubInterpolators() {
171 return Collections.singletonList(this);
172 }
173
174 /** {@inheritDoc} */
175 public int getNbInterpolationPoints() {
176 final List<FieldTimeInterpolator<? extends FieldTimeStamped<KK>, KK>> subInterpolators = getSubInterpolators();
177 // In case the interpolator does not have sub interpolators
178 if (subInterpolators.size() == 1) {
179 return interpolationPoints;
180 }
181 // Otherwise find maximum number of interpolation points among sub interpolators
182 else {
183 final Optional<Integer> optionalMaxNbInterpolationPoints =
184 subInterpolators.stream().map(FieldTimeInterpolator::getNbInterpolationPoints).max(Integer::compareTo);
185 if (optionalMaxNbInterpolationPoints.isPresent()) {
186 return optionalMaxNbInterpolationPoints.get();
187 } else {
188 // This should never happen
189 throw new OrekitInternalError(null);
190 }
191 }
192 }
193
194 /**
195 * Get the number of interpolation points for this instance only i.e., not taking into account sub-interpolators.
196 *
197 * @return required the number of interpolation points for this instance only i.e., not taking into account
198 * sub-interpolators.
199 */
200 public int getInternalNbInterpolationPoints() {
201 return interpolationPoints;
202 }
203
204 /** {@inheritDoc} */
205 public double getExtrapolationThreshold() {
206 return extrapolationThreshold;
207 }
208
209 /**
210 * Add all lowest level sub interpolators to the sub interpolator list.
211 *
212 * @param subInterpolator optional sub interpolator to add
213 * @param subInterpolators list of sub interpolators
214 * @param <S> type of the field element
215 */
216 protected <S extends CalculusFieldElement<S>> void addOptionalSubInterpolatorIfDefined(
217 final FieldTimeInterpolator<? extends FieldTimeStamped<S>, S> subInterpolator,
218 final List<FieldTimeInterpolator<? extends FieldTimeStamped<S>, S>> subInterpolators) {
219 // Add all lowest level sub interpolators
220 if (subInterpolator != null) {
221 subInterpolators.addAll(subInterpolator.getSubInterpolators());
222 }
223 }
224
225 /**
226 * Interpolate instance from given interpolation data.
227 *
228 * @param interpolationData interpolation data
229 *
230 * @return interpolated instance from given interpolation data.
231 */
232 protected abstract T interpolate(InterpolationData interpolationData);
233
234 /**
235 * Get the time parameter which lies between [0:1] by normalizing the difference between interpolating time and previous
236 * date by the Δt between tabulated values.
237 *
238 * @param interpolatingTime time at which we want to interpolate a value (between previous and next tabulated dates)
239 * @param previousDate previous tabulated value date
240 * @param nextDate next tabulated value date
241 *
242 * @return time parameter which lies between [0:1]
243 */
244 protected KK getTimeParameter(final FieldAbsoluteDate<KK> interpolatingTime,
245 final FieldAbsoluteDate<KK> previousDate,
246 final FieldAbsoluteDate<KK> nextDate) {
247
248 return interpolatingTime.durationFrom(previousDate).divide(nextDate.getDate().durationFrom(previousDate));
249 }
250
251 /**
252 * Nested class used to store interpolation data.
253 * <p>
254 * It makes the interpolator thread safe.
255 */
256 public class InterpolationData {
257
258 /** Interpolation date. */
259 private final FieldAbsoluteDate<KK> interpolationDate;
260
261 /** Unmodifiable list of neighbors. */
262 private final List<T> neighborList;
263
264 /** Field of the element. */
265 private final Field<KK> field;
266
267 /** Fielded zero. */
268 private final KK zero;
269
270 /** Fielded one. */
271 private final KK one;
272
273 /**
274 * Constructor (Collection variant).
275 * <p>
276 * If {@code sample} is already a {@link List}, it is used directly; otherwise it is copied into a new
277 * {@link ArrayList}. Forwards to {@link #InterpolationData(FieldAbsoluteDate, List)} — see that constructor
278 * for the sorted-sample precondition.
279 *
280 * @param interpolationDate interpolation date
281 * @param sample time stamped sample (chronologically sorted)
282 */
283 protected InterpolationData(final FieldAbsoluteDate<KK> interpolationDate, final Collection<T> sample) {
284 this(interpolationDate, (sample instanceof List) ? (List<T>) sample : new ArrayList<>(sample));
285 }
286
287 /**
288 * Constructor.
289 * <p>
290 * <strong>Precondition:</strong> {@code sample} must be sorted in chronological order. Passing an unsorted
291 * sample yields undefined neighbors and may throw
292 * {@link org.orekit.errors.TimeStampedCacheException}. Prior implementations silently sorted the input;
293 * this is no longer the case.
294 *
295 * @param interpolationDate interpolation date
296 * @param sample time stamped sample (chronologically sorted)
297 */
298 protected InterpolationData(final FieldAbsoluteDate<KK> interpolationDate, final List<T> sample) {
299
300 // Check if there is enough sample points
301 final int nbInterpolationPoints = getNbInterpolationPoints();
302 if (sample.size() < nbInterpolationPoints) {
303 throw new OrekitIllegalArgumentException(OrekitMessages.NOT_ENOUGH_CACHED_NEIGHBORS,
304 sample.size(), nbInterpolationPoints);
305 }
306
307 // Shortcut to see if sample size is equal to number of interpolation points
308 if (sample.size() == nbInterpolationPoints) {
309 this.neighborList = Collections.unmodifiableList(sample);
310 } else {
311 final FieldAbsoluteDate<KK> central = getCentralDate(interpolationDate,
312 sample.get(0).getDate(),
313 sample.get(sample.size() - 1).getDate(),
314 extrapolationThreshold);
315
316 // Trimmer returns a sublist view, so wrap (don't copy) for immutability.
317 final FieldSortedListTrimmer trimmer = new FieldSortedListTrimmer(nbInterpolationPoints);
318 this.neighborList = Collections.unmodifiableList(trimmer.getNeighborsSubList(central, sample));
319 }
320
321 // Extract field and useful terms
322 this.field = interpolationDate.getField();
323 this.zero = field.getZero();
324 this.one = field.getOne();
325
326 // Store interpolation date
327 this.interpolationDate = interpolationDate;
328 }
329
330 /** Get interpolation date.
331 * @return interpolation date
332 */
333 public FieldAbsoluteDate<KK> getInterpolationDate() {
334 return interpolationDate;
335 }
336
337 /** Get neighbor list.
338 * @return neighbor list
339 */
340 public List<T> getNeighborList() {
341 return neighborList;
342 }
343
344 /** Get field.
345 * @return field
346 */
347 public Field<KK> getField() {
348 return field;
349 }
350
351 /** Get zero.
352 * @return zero
353 */
354 public KK getZero() {
355 return zero;
356 }
357
358 /** Get one.
359 * @return one
360 */
361 public KK getOne() {
362 return one;
363 }
364 }
365 }