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