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é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(SpacecraftState s0, 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(SpacecraftState state, AbsoluteDate target) {
93 // nothing by default
94 }
95
96 /** Compute the value of the switching function.
97 * This function must be continuous (at least in its roots neighborhood),
98 * as the integrator will need to find its roots to locate the events.
99 * @param s the current state information: date, kinematics, attitude
100 * @return value of the switching function
101 */
102 double g(SpacecraftState s);
103
104 /** Get the convergence threshold in the event time search.
105 * @return convergence threshold (s)
106 */
107 default double getThreshold() {
108 return getDetectionSettings().getThreshold();
109 }
110
111 /** Get maximal time interval between switching function checks.
112 * @return maximal time interval (s) between switching function checks
113 */
114 default AdaptableInterval getMaxCheckInterval() {
115 return getDetectionSettings().getMaxCheckInterval();
116 }
117
118 /** Get maximal number of iterations in the event time search.
119 * @return maximal number of iterations in the event time search
120 */
121 default int getMaxIterationCount() {
122 return getDetectionSettings().getMaxIterationCount();
123 }
124
125 /** Get the handler.
126 * @return event handler to call at event occurrences
127 * @since 12.0
128 */
129 EventHandler getHandler();
130
131 /**
132 * This method finalizes the event detector's job.
133 * @param state state at propagation end
134 * @since 12.2
135 */
136 default void finish(SpacecraftState state) {
137 getHandler().finish(state, this);
138 }
139
140 /**
141 * Getter for the settings.
142 * @return detection settings
143 * @since 12.2
144 */
145 default EventDetectionSettings getDetectionSettings() {
146 return EventDetectionSettings.getDefaultEventDetectionSettings();
147 }
148 }