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.ArrayList;
20 import java.util.Collections;
21 import java.util.List;
22
23 import org.hipparchus.ode.events.Action;
24 import org.orekit.errors.OrekitIllegalArgumentException;
25 import org.orekit.errors.OrekitMessages;
26 import org.orekit.propagation.SpacecraftState;
27 import org.orekit.propagation.events.functions.EventFunction;
28 import org.orekit.propagation.events.handlers.EventHandler;
29 import org.orekit.propagation.events.handlers.StopOnEvent;
30 import org.orekit.propagation.events.intervals.DateDetectionAdaptableIntervalFactory;
31 import org.orekit.time.AbsoluteDate;
32 import org.orekit.time.TimeStamped;
33
34 /** Finder for date events.
35 * <p>This class finds date events (i.e. occurrence of some predefined dates).</p>
36 * <p>As of version 5.1, it is an enhanced date detector:</p>
37 * <ul>
38 * <li>it can be defined without prior date ({@link #DateDetector(TimeStamped...)})</li>
39 * <li>several dates can be added ({@link #addEventDate(AbsoluteDate)})</li>
40 * </ul>
41 * <p>The gap between the added dates must be more than the minGap.</p>
42 * <p>The default implementation behavior is to {@link Action#STOP stop}
43 * propagation at the first event date occurrence. This can be changed by calling
44 * {@link #withHandler(EventHandler)} after construction.</p>
45 * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
46 * @author Luc Maisonobe
47 * @author Pascal Parraud
48 */
49 public class DateDetector extends AbstractDetector<DateDetector> implements TimeStamped {
50
51 /** Default value for max check.
52 * @since 12.0
53 */
54 public static final double DEFAULT_MAX_CHECK = DateDetectionAdaptableIntervalFactory.DEFAULT_MAX_CHECK;
55
56 /** Default value for minimum gap between added dates.
57 * @since 12.0
58 */
59 public static final double DEFAULT_MIN_GAP = 1.0;
60
61 /** Default value for convergence threshold.
62 * @since 12.0
63 */
64 public static final double DEFAULT_THRESHOLD = 1.0e-10;
65
66 /** Minimum gap between added dates.
67 * @since 12.0
68 */
69 private final double minGap;
70
71 /** Last date for g computation. */
72 private AbsoluteDate gDate;
73
74 /** List of event dates. */
75 private final ArrayList<EventDate> eventDateList;
76
77 /** Event function. */
78 private final EventFunction eventFunction;
79
80 /** Current event date. */
81 private int currentIndex;
82
83 /** Build a new instance.
84 * <p>First event dates are set here, but others can be
85 * added later with {@link #addEventDate(AbsoluteDate)}, although the max. check should probably be changed then.</p>
86 * @param dates list of event dates
87 * @see #addEventDate(AbsoluteDate)
88 * @since 12.0
89 */
90 public DateDetector(final TimeStamped... dates) {
91 this(new EventDetectionSettings(DateDetectionAdaptableIntervalFactory.getDatesDetectionConstantInterval(dates),
92 DEFAULT_THRESHOLD, EventDetectionSettings.DEFAULT_MAX_ITER),
93 new StopOnEvent(), DEFAULT_MIN_GAP, dates);
94 }
95
96 /** Build a new instance from a single time.
97 * <p>First event dates are set here, but others can be
98 * added later with {@link #addEventDate(AbsoluteDate)}, although the max. check should probably be changed then.</p>
99 * @param date event date
100 * @see #addEventDate(AbsoluteDate)
101 * @since 13.0
102 */
103 public DateDetector(final AbsoluteDate date) {
104 this((TimeStamped) date);
105 }
106
107 /** Build a new instance.
108 * <p>First event dates are set here, but others can be
109 * added later with {@link #addEventDate(AbsoluteDate)}, although the max. check should probably be changed then.</p>
110 * @param minGap minimum gap between added dates (s)
111 * @param dates list of event dates
112 * @see #addEventDate(AbsoluteDate)
113 * @since 13.0
114 */
115 public DateDetector(final double minGap, final TimeStamped... dates) {
116 this(new EventDetectionSettings(DateDetectionAdaptableIntervalFactory.getDatesDetectionConstantInterval(dates),
117 DEFAULT_THRESHOLD, EventDetectionSettings.DEFAULT_MAX_ITER),
118 new StopOnEvent(), minGap, dates);
119 }
120
121 /** Build a new instance from a single time.
122 * <p>First event dates are set here, but others can be
123 * added later with {@link #addEventDate(AbsoluteDate)}, although the max. check should probably be changed then.</p>
124 * @param minGap minimum gap between added dates (s)
125 * @param date event date
126 * @see #addEventDate(AbsoluteDate)
127 * @since 13.0
128 */
129 public DateDetector(final double minGap, final AbsoluteDate date) {
130 this(minGap, (TimeStamped) date);
131 }
132
133 /** Protected constructor with full parameters.
134 * <p>
135 * This constructor is not public as users are expected to use the builder
136 * API with the various {@code withXxx()} methods to set up the instance
137 * in a readable manner without using a huge amount of parameters.
138 * </p>
139 * @param detectionSettings detection settings
140 * @param handler event handler to call at event occurrences
141 * @param minGap minimum gap between added dates (s)
142 * @param dates list of event dates
143 * @since 12.2
144 */
145 protected DateDetector(final EventDetectionSettings detectionSettings,
146 final EventHandler handler, final double minGap, final TimeStamped... dates) {
147 super(detectionSettings, handler);
148 this.currentIndex = -1;
149 this.gDate = null;
150 this.eventDateList = new ArrayList<>();
151 this.minGap = minGap;
152 for (final TimeStamped ts : dates) {
153 final AbsoluteDate date = ts.getDate();
154 final boolean notPresentYet = eventDateList.stream().noneMatch(d -> d.getDate().isEqualTo(date));
155 if (notPresentYet) {
156 addEventDate(date);
157 }
158 }
159 this.eventFunction = new LocalEventFunction();
160 }
161
162 /**
163 * Setup minimum gap between added dates.
164 * @param newMinGap new minimum gap between added dates
165 * @return a new detector with updated configuration (the instance is not changed)
166 * @since 12.0
167 */
168 public DateDetector withMinGap(final double newMinGap) {
169 return new DateDetector(getDetectionSettings(), getHandler(), newMinGap,
170 eventDateList.toArray(new EventDate[0]));
171 }
172
173 /** {@inheritDoc} */
174 @Override
175 protected DateDetector create(final EventDetectionSettings detectionSettings, final EventHandler newHandler) {
176 return new DateDetector(detectionSettings, newHandler, minGap,
177 eventDateList.toArray(new EventDate[0]));
178 }
179
180 /** Get all event dates currently managed, in chronological order.
181 * @return all event dates currently managed, in chronological order
182 * @since 11.1
183 */
184 public List<TimeStamped> getDates() {
185 return Collections.unmodifiableList(eventDateList);
186 }
187
188 @Override
189 public EventFunction getEventFunction() {
190 return eventFunction;
191 }
192
193 /** Compute the value of the switching function.
194 * This function measures the difference between the current and the target date.
195 * @param s the current state information: date, kinematics, attitude
196 * @return value of the switching function
197 */
198 @Override
199 public double g(final SpacecraftState s) {
200 return eventFunction.value(s);
201 }
202
203 /** Get the current event date according to the propagator.
204 * @return event date
205 */
206 public AbsoluteDate getDate() {
207 return currentIndex < 0 ? null : eventDateList.get(currentIndex).getDate();
208 }
209
210 /** Get the minimum gap between added dates.
211 * @return the minimum gap between added dates (s)
212 */
213 public double getMinGap() {
214 return minGap;
215 }
216
217 /** Add an event date.
218 * <p>The date to add must be:</p>
219 * <ul>
220 * <li>less than the smallest already registered event date minus the maxCheck</li>
221 * <li>or more than the largest already registered event date plus the maxCheck</li>
222 * </ul>
223 * @param target target date
224 * @throws IllegalArgumentException if the date is too close from already defined interval
225 * @see #DateDetector(TimeStamped...)
226 */
227 public void addEventDate(final AbsoluteDate target) throws IllegalArgumentException {
228 final boolean increasing;
229 if (currentIndex < 0) {
230 increasing = (gDate == null) ? true : target.durationFrom(gDate) > 0.0;
231 currentIndex = 0;
232 eventDateList.add(new EventDate(target, increasing));
233 } else {
234 final int lastIndex = eventDateList.size() - 1;
235 final AbsoluteDate firstDate = eventDateList.get(0).getDate();
236 final AbsoluteDate lastDate = eventDateList.get(lastIndex).getDate();
237 if (firstDate.durationFrom(target) > minGap) {
238 increasing = !eventDateList.get(0).isgIncrease();
239 eventDateList.add(0, new EventDate(target, increasing));
240 currentIndex++;
241 } else if (target.durationFrom(lastDate) > minGap) {
242 increasing = !eventDateList.get(lastIndex).isgIncrease();
243 eventDateList.add(new EventDate(target, increasing));
244 } else {
245 throw new OrekitIllegalArgumentException(OrekitMessages.EVENT_DATE_TOO_CLOSE,
246 target,
247 firstDate,
248 lastDate,
249 minGap,
250 firstDate.durationFrom(target),
251 target.durationFrom(lastDate));
252 }
253 }
254 }
255
256 private class LocalEventFunction implements EventFunction {
257
258 @Override
259 public double value(final SpacecraftState state) {
260 gDate = state.getDate();
261 if (currentIndex < 0) {
262 return -1.0;
263 } else {
264 final EventDate event = getClosest(gDate);
265 return event.isgIncrease() ? gDate.durationFrom(event.getDate()) : event.getDate().durationFrom(gDate);
266 }
267 }
268
269 @Override
270 public boolean dependsOnTimeOnly() {
271 return true;
272 }
273
274 /** Get the closest EventDate to the target date.
275 * @param target target date
276 * @return current EventDate
277 */
278 private EventDate getClosest(final AbsoluteDate target) {
279 final double dt = target.durationFrom(eventDateList.get(currentIndex).getDate());
280 if (dt < 0.0 && currentIndex > 0) {
281 boolean found = false;
282 while (currentIndex > 0 && !found) {
283 if (target.durationFrom(eventDateList.get(currentIndex - 1).getDate()) < eventDateList.get(currentIndex).getDate().durationFrom(target)) {
284 currentIndex--;
285 } else {
286 found = true;
287 }
288 }
289 } else if (dt > 0.0 && currentIndex < eventDateList.size() - 1) {
290 final int maxIndex = eventDateList.size() - 1;
291 boolean found = false;
292 while (currentIndex < maxIndex && !found) {
293 if (target.durationFrom(eventDateList.get(currentIndex + 1).getDate()) > eventDateList.get(currentIndex).getDate().durationFrom(target)) {
294 currentIndex++;
295 } else {
296 found = true;
297 }
298 }
299 }
300 return eventDateList.get(currentIndex);
301 }
302 }
303
304 /** Event date specification. */
305 private static class EventDate implements TimeStamped {
306
307 /** Event date. */
308 private final AbsoluteDate date;
309
310 /** Flag for g function way around event date. */
311 private final boolean gIncrease;
312
313 /** Simple constructor.
314 * @param date date
315 * @param increase if true, g function increases around event date
316 */
317 EventDate(final AbsoluteDate date, final boolean increase) {
318 this.date = date;
319 this.gIncrease = increase;
320 }
321
322 /** Getter for event date.
323 * @return event date
324 */
325 public AbsoluteDate getDate() {
326 return date;
327 }
328
329 /** Getter for g function way at event date.
330 * @return g function increasing flag
331 */
332 public boolean isgIncrease() {
333 return gIncrease;
334 }
335
336 }
337
338 }