1   /* Copyright 2002-2021 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.ode.events.Action;
20  import org.orekit.propagation.SpacecraftState;
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 integrator at each step. When the
33   * sign of the underlying g switching function changes, the step is rejected
34   * and reduced, in order to make sure the sign changes occur only at steps
35   * boundaries.</p>
36   *
37   * <p>When step ends exactly at a switching function sign change, the corresponding
38   * event is triggered, by calling the {@link #eventOccurred(SpacecraftState, boolean)}
39   * method. The method can do whatever it needs with the event (logging it, performing
40   * some processing, ignore it ...). The return value of the method will be used by
41   * the propagator to stop or resume propagation, possibly changing the state vector.<p>
42   *
43   * @author Luc Maisonobe
44   * @author V&eacute;ronique Pommier-Maurussane
45   */
46  public interface EventDetector {
47  
48      /** Initialize event handler at the start of a propagation.
49       * <p>
50       * This method is called once at the start of the propagation. It
51       * may be used by the event handler to initialize some internal data
52       * if needed.
53       * </p>
54       * <p>
55       * The default implementation does nothing
56       * </p>
57       * @param s0 initial state
58       * @param t target time for the integration
59       *
60       */
61      default void init(SpacecraftState s0, AbsoluteDate t) {
62          // nothing by default
63      }
64  
65      /** Compute the value of the switching function.
66       * This function must be continuous (at least in its roots neighborhood),
67       * as the integrator will need to find its roots to locate the events.
68       * @param s the current state information: date, kinematics, attitude
69       * @return value of the switching function
70       */
71      double g(SpacecraftState s);
72  
73      /** Get the convergence threshold in the event time search.
74       * @return convergence threshold (s)
75       */
76      double getThreshold();
77  
78      /** Get maximal time interval between switching function checks.
79       * @return maximal time interval (s) between switching function checks
80       */
81      double getMaxCheckInterval();
82  
83      /** Get maximal number of iterations in the event time search.
84       * @return maximal number of iterations in the event time search
85       */
86      int getMaxIterationCount();
87  
88      /** Handle the event.
89       * @param s SpaceCraft state to be used in the evaluation
90       * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
91       * @return the Action that the calling detector should pass back to the evaluation system
92            * @since 7.0
93       */
94      Action eventOccurred(SpacecraftState s, boolean increasing);
95  
96      /** Reset the state prior to continue propagation.
97       * <p>This method is called after the step handler has returned and
98       * before the next step is started, but only when {@link
99       * #eventOccurred} has itself returned the {@link Action#RESET_STATE}
100      * indicator. It allows the user to reset the state for the next step,
101      * without perturbing the step handler of the finishing step. If the
102      * {@link #eventOccurred} never returns the {@link Action#RESET_STATE}
103      * indicator, this function will never be called, and it is safe to simply return null.</p>
104      * <p>
105      * The default implementation simply returns its argument.
106      * </p>
107      * @param oldState old state
108      * @return new state
109           * @since 7.0
110      */
111     default SpacecraftState resetState(SpacecraftState oldState) {
112         return oldState;
113     }
114 
115 }