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 org.orekit.propagation.SpacecraftState;
20  import org.orekit.propagation.events.handlers.EventHandler;
21  import org.orekit.time.AbsoluteDate;
22  
23  /** This interface represents space-dynamics aware events detectors.
24   *
25   * <p>It mirrors the {@link org.hipparchus.ode.events.ODEEventHandler
26   * ODEEventHandler} interface from <a href="https://hipparchus.org/">
27   * Hipparchus</a> but provides a space-dynamics interface to the
28   * methods.</p>
29   *
30   * <p>Events detectors are a useful solution to meet the requirements
31   * of propagators concerning discrete conditions. The state of each
32   * event detector is queried by the propagator from time to time, at least
33   * once every {@link #getMaxCheckInterval() max check interval} but it may
34   * be more frequent. When the sign of the underlying g switching function
35   * changes, a root-finding algorithm is run to precisely locate the event,
36   * down to a configured {@link #getThreshold() convergence threshold}. The
37   * {@link #getMaxCheckInterval() max check interval} is therefore devoted to
38   * separate roots and is often much larger than the  {@link #getThreshold()
39   * convergence threshold}.</p>
40   *
41   * <p>The physical meaning of the g switching function is not really used
42   * by the event detection algorithms. Its varies from event detector to
43   * event detector. One example would be a visibility detector that could use the
44   * angular elevation of the satellite above horizon as a g switching function.
45   * In this case, the function would switch from negative to positive when the
46   * satellite raises above horizon and it would switch from positive to negative
47   * when it sets backs below horizon. Another example would be an apside detector
48   * that could use the dot product of position and velocity. In this case, the
49   * function would switch from negative to positive when the satellite crosses
50   * periapsis and it would switch from positive to negative when the satellite
51   * crosses apoapsis.</p>
52   *
53   * <p>When the precise state at which the g switching function changes has been
54   * located, the corresponding event is triggered, by calling the {@link
55   * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
56   * method from the associated {@link #getHandler() handler}.
57   * The method can do whatever it needs with the event (logging it, performing
58   * some processing, ignore it ...). The return value of the method will be used by
59   * the propagator to stop or resume propagation, possibly changing the state vector.</p>
60   *
61   * @author Luc Maisonobe
62   * @author V&eacute;ronique Pommier-Maurussane
63   */
64  public interface EventDetector {
65  
66      /** Initialize event handler at the start of a propagation.
67       * <p>
68       * This method is called once at the start of the propagation. It
69       * may be used by the event handler to initialize some internal data
70       * if needed.
71       * </p>
72       * <p>
73       * The default implementation does nothing
74       * </p>
75       * @param s0 initial state
76       * @param t target time for the integration
77       *
78       */
79      default void init(SpacecraftState s0, AbsoluteDate t) {
80          // nothing by default
81      }
82  
83      /** Compute the value of the switching function.
84       * This function must be continuous (at least in its roots neighborhood),
85       * as the integrator will need to find its roots to locate the events.
86       * @param s the current state information: date, kinematics, attitude
87       * @return value of the switching function
88       */
89      double g(SpacecraftState s);
90  
91      /** Get the convergence threshold in the event time search.
92       * @return convergence threshold (s)
93       */
94      double getThreshold();
95  
96      /** Get maximal time interval between switching function checks.
97       * @return maximal time interval (s) between switching function checks
98       */
99      AdaptableInterval getMaxCheckInterval();
100 
101     /** Get maximal number of iterations in the event time search.
102      * @return maximal number of iterations in the event time search
103      */
104     int getMaxIterationCount();
105 
106     /** Get the handler.
107      * @return event handler to call at event occurrences
108      * @since 12.0
109      */
110     EventHandler getHandler();
111 
112 }