1 /* Copyright 2002-2025 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.propagation.events;
18
19 import java.util.List;
20 import java.util.stream.Collectors;
21
22 import org.hipparchus.CalculusFieldElement;
23 import org.hipparchus.Field;
24 import org.hipparchus.util.FastMath;
25 import org.orekit.errors.OrekitException;
26 import org.orekit.errors.OrekitMessages;
27 import org.orekit.propagation.FieldSpacecraftState;
28 import org.orekit.propagation.events.handlers.FieldEventHandler;
29 import org.orekit.propagation.events.handlers.FieldStopOnEvent;
30 import org.orekit.time.AbsoluteDate;
31 import org.orekit.utils.DateDriver;
32 import org.orekit.utils.ParameterDriver;
33 import org.orekit.utils.ParameterObserver;
34 import org.orekit.utils.TimeSpanMap;
35 import org.orekit.utils.TimeSpanMap.Span;
36
37 /** Detector for date intervals that may be offset thanks to parameter drivers.
38 * <p>
39 * Two dual views can be used for date intervals: either start date/stop date or
40 * median date/duration. {@link #getStartDriver() start}/{@link #getStopDriver() stop}
41 * drivers and {@link #getMedianDriver() median}/{@link #getDurationDriver() duration}
42 * drivers work in pair. Both drivers in one pair can be selected and their changes will
43 * be propagated to the other pair, but attempting to select drivers in both
44 * pairs at the same time will trigger an exception. Changing the value of a driver
45 * that is not selected should be avoided as it leads to inconsistencies between the pairs.
46 * </p>
47 * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
48 * @param <T> type of the field elements
49 * @author Luc Maisonobe
50 * @since 11.1
51 */
52 public class FieldParameterDrivenDateIntervalDetector<T extends CalculusFieldElement<T>>
53 extends FieldAbstractDetector<FieldParameterDrivenDateIntervalDetector<T>, T> {
54
55 /** Default suffix for start driver. */
56 public static final String START_SUFFIX = "_START";
57
58 /** Default suffix for stop driver. */
59 public static final String STOP_SUFFIX = "_STOP";
60
61 /** Default suffix for median driver. */
62 public static final String MEDIAN_SUFFIX = "_MEDIAN";
63
64 /** Default suffix for duration driver. */
65 public static final String DURATION_SUFFIX = "_DURATION";
66
67 /** Reference interval start driver. */
68 private DateDriver start;
69
70 /** Reference interval stop driver. */
71 private DateDriver stop;
72
73 /** Median date driver. */
74 private DateDriver median;
75
76 /** Duration driver. */
77 private ParameterDriver duration;
78
79 /** Build a new instance.
80 * @param field field to which the elements belong
81 * @param prefix prefix to use for parameter drivers names
82 * @param refMedian reference interval median date
83 * @param refDuration reference duration
84 */
85 public FieldParameterDrivenDateIntervalDetector(final Field<T> field, final String prefix,
86 final AbsoluteDate refMedian, final double refDuration) {
87 this(field, prefix,
88 refMedian.shiftedBy(-0.5 * refDuration),
89 refMedian.shiftedBy(+0.5 * refDuration));
90 }
91
92 /** Build a new instance.
93 * @param field field to which the elements belong
94 * @param prefix prefix to use for parameter drivers names
95 * @param refStart reference interval start date
96 * @param refStop reference interval stop date
97 */
98 public FieldParameterDrivenDateIntervalDetector(final Field<T> field, final String prefix,
99 final AbsoluteDate refStart, final AbsoluteDate refStop) {
100 this(new FieldEventDetectionSettings<>(field, EventDetectionSettings.getDefaultEventDetectionSettings()),
101 new FieldStopOnEvent<>(),
102 new DateDriver(refStart, prefix + START_SUFFIX, true),
103 new DateDriver(refStop, prefix + STOP_SUFFIX, false),
104 new DateDriver(refStart.shiftedBy(0.5 * refStop.durationFrom(refStart)), prefix + MEDIAN_SUFFIX, true),
105 new ParameterDriver(prefix + DURATION_SUFFIX, refStop.durationFrom(refStart), 1.0, 0.0, Double.POSITIVE_INFINITY));
106 }
107
108 /** Protected constructor with full parameters.
109 * <p>
110 * This constructor is not public as users are expected to use the builder
111 * API with the various {@code withXxx()} methods to set up the instance
112 * in a readable manner without using a huge amount of parameters.
113 * </p>
114 * @param detectionSettings event detection settings
115 * @param handler event handler to call at event occurrences
116 * @param start reference interval start driver
117 * @param stop reference interval stop driver
118 * @param median median date driver
119 * @param duration duration driver
120 * @since 13.0
121 */
122 protected FieldParameterDrivenDateIntervalDetector(final FieldEventDetectionSettings<T> detectionSettings,
123 final FieldEventHandler<T> handler,
124 final DateDriver start, final DateDriver stop,
125 final DateDriver median, final ParameterDriver duration) {
126 super(detectionSettings, handler);
127 this.start = start;
128 this.stop = stop;
129 this.median = median;
130 this.duration = duration;
131
132 // set up delegation between drivers
133 replaceBindingObserver(start, new StartObserver());
134 replaceBindingObserver(stop, new StopObserver());
135 replaceBindingObserver(median, new MedianObserver());
136 replaceBindingObserver(duration, new DurationObserver());
137
138 }
139
140 /** Replace binding observers.
141 * @param driver driver for whose binding observers should be replaced
142 * @param bindingObserver new binding observer
143 */
144 private void replaceBindingObserver(final ParameterDriver driver, final BindingObserver bindingObserver) {
145
146 // remove the previous binding observers
147 final List<ParameterObserver> original = driver.
148 getObservers().
149 stream().
150 filter(observer -> observer instanceof FieldParameterDrivenDateIntervalDetector.BindingObserver).
151 collect(Collectors.toList());
152 original.forEach(driver::removeObserver);
153
154 driver.addObserver(bindingObserver);
155
156 }
157
158 /** {@inheritDoc} */
159 @Override
160 protected FieldParameterDrivenDateIntervalDetector<T> create(final FieldEventDetectionSettings<T> detectionSettings,
161 final FieldEventHandler<T> newHandler) {
162 return new FieldParameterDrivenDateIntervalDetector<>(detectionSettings, newHandler,
163 start, stop, median, duration);
164 }
165
166 /** Get the driver for start date.
167 * <p>
168 * Note that the start date is automatically adjusted if either
169 * {@link #getMedianDriver() median date} or {@link #getDurationDriver() duration}
170 * are {@link ParameterDriver#isSelected() selected} and changed.
171 * </p>
172 * @return driver for start date
173 */
174 public DateDriver getStartDriver() {
175 return start;
176 }
177
178 /** Get the driver for stop date.
179 * <p>
180 * Note that the stop date is automatically adjusted if either
181 * {@link #getMedianDriver() median date} or {@link #getDurationDriver() duration}
182 * are {@link ParameterDriver#isSelected() selected} changed.
183 * </p>
184 * @return driver for stop date
185 */
186 public DateDriver getStopDriver() {
187 return stop;
188 }
189
190 /** Get the driver for median date.
191 * <p>
192 * Note that the median date is automatically adjusted if either
193 * {@link #getStartDriver()} start date or {@link #getStopDriver() stop date}
194 * are {@link ParameterDriver#isSelected() selected} changed.
195 * </p>
196 * @return driver for median date
197 */
198 public DateDriver getMedianDriver() {
199 return median;
200 }
201
202 /** Get the driver for duration.
203 * <p>
204 * Note that the duration is automatically adjusted if either
205 * {@link #getStartDriver()} start date or {@link #getStopDriver() stop date}
206 * are {@link ParameterDriver#isSelected() selected} changed.
207 * </p>
208 * @return driver for duration
209 */
210 public ParameterDriver getDurationDriver() {
211 return duration;
212 }
213
214 /** Compute the value of the switching function.
215 * <p>
216 * The function is positive for dates within the interval defined
217 * by applying the parameter drivers shifts to reference dates,
218 * and negative for dates outside of this interval. Note that
219 * if Δt_start - Δt_stop is less than ref_stop.durationFrom(ref_start),
220 * then the interval degenerates to empty and the function never
221 * reaches positive values.
222 * </p>
223 * @param s the current state information: date, kinematics, attitude
224 * @return value of the switching function
225 */
226 public T g(final FieldSpacecraftState<T> s) {
227 return FastMath.min(s.getDate().durationFrom(start.getDate()),
228 s.getDate().durationFrom(stop.getDate()).negate());
229 }
230
231 /** Base observer. */
232 private abstract class BindingObserver implements ParameterObserver {
233
234 /** {@inheritDoc} */
235 @Override
236 public void valueChanged(final double previousValue, final ParameterDriver driver, final AbsoluteDate date) {
237 if (driver.isSelected()) {
238 setDelta(driver.getValue(date) - previousValue, date);
239 }
240 }
241
242 /** {@inheritDoc} */
243 @Override
244 public void valueSpanMapChanged(final TimeSpanMap<Double> previousValue, final ParameterDriver driver) {
245 if (driver.isSelected()) {
246 for (Span<Double> span = driver.getValueSpanMap().getFirstSpan(); span != null; span = span.next()) {
247 setDelta(span.getData() - previousValue.get(span.getStart()), span.getStart());
248 }
249 }
250 }
251
252 /** {@inheritDoc} */
253 @Override
254 public void selectionChanged(final boolean previousSelection, final ParameterDriver driver) {
255 if ((start.isSelected() || stop.isSelected()) &&
256 (median.isSelected() || duration.isSelected())) {
257 throw new OrekitException(OrekitMessages.INCONSISTENT_SELECTION,
258 start.getName(), stop.getName(),
259 median.getName(), duration.getName());
260 }
261 }
262
263 /** Change a value.
264 * @param date date for which the value wants to be change
265 * @param delta change of value
266 */
267 protected abstract void setDelta(double delta, AbsoluteDate date);
268
269 }
270
271 /** Observer for start date. */
272 private class StartObserver extends BindingObserver {
273 /** {@inheritDoc} */
274 @Override
275 protected void setDelta(final double delta, final AbsoluteDate date) {
276 median.setValue(median.getValue(date) + 0.5 * delta, date);
277 duration.setValue(duration.getValue(date) - delta, date);
278 }
279 }
280
281 /** Observer for stop date. */
282 private class StopObserver extends BindingObserver {
283 /** {@inheritDoc} */
284 @Override
285 protected void setDelta(final double delta, final AbsoluteDate date) {
286 median.setValue(median.getValue(date) + 0.5 * delta, date);
287 duration.setValue(duration.getValue(date) + delta, date);
288 }
289 }
290
291 /** Observer for median date. */
292 private class MedianObserver extends BindingObserver {
293 /** {@inheritDoc} */
294 @Override
295 protected void setDelta(final double delta, final AbsoluteDate date) {
296 start.setValue(start.getValue(date) + delta, date);
297 stop.setValue(stop.getValue(date) + delta, date);
298 }
299 }
300
301 /** Observer for duration. */
302 private class DurationObserver extends BindingObserver {
303 /** {@inheritDoc} */
304 @Override
305 protected void setDelta(final double delta, final AbsoluteDate date) {
306 start.setValue(start.getValue(date) - 0.5 * delta, date);
307 stop.setValue(stop.getValue(date) + 0.5 * delta, date);
308 }
309 }
310
311 }