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