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 org.orekit.propagation.SpacecraftState;
20  import org.orekit.propagation.events.handlers.EventHandler;
21  import org.orekit.propagation.events.intervals.AdaptableInterval;
22  import org.orekit.time.AbsoluteDate;
23  
24  /** This interface represents space-dynamics aware events detectors.
25   *
26   * <p>It mirrors the {@link org.hipparchus.ode.events.ODEEventHandler
27   * ODEEventHandler} interface from <a href="https://hipparchus.org/">
28   * Hipparchus</a> but provides a space-dynamics interface to the
29   * methods.</p>
30   *
31   * <p>Events detectors are a useful solution to meet the requirements
32   * of propagators concerning discrete conditions. The state of each
33   * event detector is queried by the propagator from time to time, at least
34   * once every {@link #getMaxCheckInterval() max check interval} but it may
35   * be more frequent. When the sign of the underlying g switching function
36   * changes, a root-finding algorithm is run to precisely locate the event,
37   * down to a configured {@link #getThreshold() convergence threshold}. The
38   * {@link #getMaxCheckInterval() max check interval} is therefore devoted to
39   * separate roots and is often much larger than the  {@link #getThreshold()
40   * convergence threshold}.</p>
41   *
42   * <p>The physical meaning of the g switching function is not really used
43   * by the event detection algorithms. Its varies from event detector to
44   * event detector. One example would be a visibility detector that could use the
45   * angular elevation of the satellite above horizon as a g switching function.
46   * In this case, the function would switch from negative to positive when the
47   * satellite raises above horizon and it would switch from positive to negative
48   * when it sets backs below horizon. Another example would be an apside detector
49   * that could use the dot product of position and velocity. In this case, the
50   * function would switch from negative to positive when the satellite crosses
51   * periapsis and it would switch from positive to negative when the satellite
52   * crosses apoapsis.</p>
53   *
54   * <p>When the precise state at which the g switching function changes has been
55   * located, the corresponding event is triggered, by calling the {@link
56   * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
57   * method from the associated {@link #getHandler() handler}.
58   * The method can do whatever it needs with the event (logging it, performing
59   * some processing, ignore it ...). The return value of the method will be used by
60   * the propagator to stop or resume propagation, possibly changing the state vector.</p>
61   *
62   * @author Luc Maisonobe
63   * @author V&eacute;ronique Pommier-Maurussane
64   */
65  public interface EventDetector {
66  
67      /** Initialize event detector at the start of a propagation.
68       * <p>
69       * This method is called once at the start of the propagation. It
70       * may be used by the event handler to initialize some internal data
71       * if needed.
72       * </p>
73       * <p>
74       * The default implementation initializes the handler.
75       * </p>
76       * @param s0 initial state
77       * @param t target time for the integration
78       *
79       */
80      default void init(final SpacecraftState s0, final AbsoluteDate t) {
81          getHandler().init(s0, t, this);
82      }
83  
84      /** Reset the event detector during propagation when the state is modified by an event or an additional data provider.
85       * <p>
86       * The default implementation does nothing.
87       * </p>
88       * @param state current state
89       * @param target target time for the integration
90       * @since 13.0
91       */
92      default void reset(final SpacecraftState state, final AbsoluteDate target) {
93          // nothing by default
94      }
95  
96      /**
97       * Method returning true if and only if the detection function g does not depend on dependent variables,
98       * just the independent one i.e. time. This information is used for performance in propagation
99       * and derivatives correction with switches in the dynamics.
100      * @return flag
101      * @since 13.1
102      */
103     default boolean dependsOnTimeOnly() {
104         return false;
105     }
106 
107     /**
108      * Method returning true if and only if the detection function g does not depend on dependent variables,
109      * other than the Cartesian coordinates (or equivalent), mass and attitude (excepts for its rates).
110      * It should thus return false if the STM is needed to evaluate the event.
111      * This information is used for performance in propagation.
112      * @return flag
113      * @since 14.0
114      */
115     default boolean dependsOnMainVariablesOnly() {
116         return true;
117     }
118 
119     /** Compute the value of the switching function.
120      * This function must be continuous (at least in its roots neighborhood),
121      * as the integrator will need to find its roots to locate the events.
122      * @param s the current state information: date, kinematics, attitude
123      * @return value of the switching function
124      */
125     double g(SpacecraftState s);
126 
127     /** Get the convergence threshold in the event time search.
128      * @return convergence threshold (s)
129      */
130     default double getThreshold() {
131         return getDetectionSettings().getThreshold();
132     }
133 
134     /** Get maximal time interval between switching function checks.
135      * @return maximal time interval (s) between switching function checks
136      */
137     default AdaptableInterval getMaxCheckInterval() {
138         return getDetectionSettings().getMaxCheckInterval();
139     }
140 
141     /** Get maximal number of iterations in the event time search.
142      * @return maximal number of iterations in the event time search
143      */
144     default int getMaxIterationCount() {
145         return getDetectionSettings().getMaxIterationCount();
146     }
147 
148     /** Get the handler.
149      * @return event handler to call at event occurrences
150      * @since 12.0
151      */
152     EventHandler getHandler();
153 
154     /**
155      * This method finalizes the event detector's job.
156      * @param state state at propagation end
157      * @since 12.2
158      */
159     default void finish(final SpacecraftState state) {
160         getHandler().finish(state, this);
161     }
162 
163     /**
164      * Getter for the settings.
165      * @return detection settings
166      * @since 12.2
167      */
168     default EventDetectionSettings getDetectionSettings() {
169         return EventDetectionSettings.getDefaultEventDetectionSettings();
170     }
171 }