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