1   /* Copyright 2002-2013 CS Systèmes d'Information
2    * Licensed to CS Systèmes d'Information (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 java.io.Serializable;
20  
21  import org.orekit.errors.OrekitException;
22  import org.orekit.propagation.SpacecraftState;
23  import org.orekit.time.AbsoluteDate;
24  
25  /** This interface represents space-dynamics aware events detectors.
26   *
27   * <p>It mirrors the {@link org.apache.commons.math3.ode.events.EventHandler
28   * EventHandler} interface from <a href="http://commons.apache.org/math/">
29   * Apache Commons Math</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 integrator at each step. When the
35   * sign of the underlying g switching function changes, the step is rejected
36   * and reduced, in order to make sure the sign changes occur only at steps
37   * boundaries.</p>
38   *
39   * <p>When step ends exactly at a switching function sign change, the corresponding
40   * event is triggered, by calling the {@link #eventOccurred(SpacecraftState, boolean)}
41   * method. The method can do whatever it needs with the event (logging it, performing
42   * some processing, ignore it ...). The return value of the method will be used by
43   * the propagator to stop or resume propagation, possibly changing the state vector.<p>
44   *
45   * @author Luc Maisonobe
46   * @author V&eacute;ronique Pommier-Maurussane
47   */
48  public interface EventDetector extends Serializable {
49  
50      /** Enumerate for actions to be performed when an event occurs.
51       * @deprecated as of 6.1, replaced with {@link org.orekit.propagation.events.handlers.EventHandler.Action}
52       */
53      @Deprecated
54      public enum Action {
55  
56          /** Stop indicator.
57           * <p>This value should be used as the return value of the {@link
58           * #eventOccurred eventOccurred} method when the propagation should be
59           * stopped after the event ending the current step.</p>
60           */
61          STOP,
62  
63          /** Reset state indicator.
64           * <p>This value should be used as the return value of the {@link
65           * #eventOccurred eventOccurred} method when the propagation should
66           * go on after the event ending the current step, with a new state
67           * (which will be retrieved thanks to the {@link #resetState
68           * resetState} method).</p>
69           */
70          RESET_STATE,
71  
72          /** Reset derivatives indicator.
73           * <p>This value should be used as the return value of the {@link
74           * #eventOccurred eventOccurred} method when the propagation should
75           * go on after the event ending the current step, with recomputed
76           * derivatives vector.</p>
77           */
78          RESET_DERIVATIVES,
79  
80          /** Continue indicator.
81           * <p>This value should be used as the return value of the {@link
82           * #eventOccurred eventOccurred} method when the propagation should go
83           * on after the event ending the current step.</p>
84           */
85          CONTINUE;
86  
87      }
88  
89      /** Initialize event handler at the start of a propagation.
90       * <p>
91       * This method is called once at the start of the propagation. It
92       * may be used by the event handler to initialize some internal data
93       * if needed.
94       * </p>
95       * @param s0 initial state
96       * @param t target time for the integration
97       */
98      void init(SpacecraftState s0, AbsoluteDate t);
99  
100     /** Compute the value of the switching function.
101      * This function must be continuous (at least in its roots neighborhood),
102      * as the integrator will need to find its roots to locate the events.
103      * @param s the current state information: date, kinematics, attitude
104      * @return value of the switching function
105      * @exception OrekitException if some specific error occurs
106      */
107     double g(SpacecraftState s) throws OrekitException;
108 
109     /** Handle an event and choose what to do next.
110 
111      * <p>The scheduling between this method and the {@link
112      * org.orekit.propagation.sampling.OrekitStepHandler OrekitStepHandler} method {@link
113      * org.orekit.propagation.sampling.OrekitStepHandler#handleStep(
114      * org.orekit.propagation.sampling.OrekitStepInterpolator, boolean)
115      * handleStep(interpolator, isLast)} is to call this method first and
116      * <code>handleStep</code> afterwards. This scheduling allows the propagator to
117      * pass <code>true</code> as the <code>isLast</code> parameter to the step
118      * handler to make it aware the step will be the last one if this method
119      * returns {@link EventDetector.Action#STOP}. As the interpolator may be used to navigate back
120      * throughout the last step (as {@link
121      * org.orekit.propagation.sampling.OrekitStepNormalizer OrekitStepNormalizer}
122      * does for example), user code called by this method and user
123      * code called by step handlers may experience apparently out of order values
124      * of the independent time variable. As an example, if the same user object
125      * implements both this {@link EventDetector EventDetector} interface and the
126      * {@link org.orekit.propagation.sampling.OrekitFixedStepHandler OrekitFixedStepHandler}
127      * interface, a <em>forward</em> integration may call its
128      * <code>eventOccurred</code> method with a state at 2000-01-01T00:00:10 first
129      * and call its <code>handleStep</code> method with a state at 2000-01-01T00:00:09
130      * afterwards. Such out of order calls are limited to the size of the
131      * integration step for {@link
132      * org.orekit.propagation.sampling.OrekitStepHandler variable step handlers} and
133      * to the size of the fixed step for {@link
134      * org.orekit.propagation.sampling.OrekitFixedStepHandler fixed step handlers}.</p>
135 
136      * @param s the current state information : date, kinematics, attitude
137      * @param increasing if true, the value of the switching function increases
138      * when times increases around event (note that increase is measured with respect
139      * to physical time, not with respect to propagation which may go backward in time)
140      * @return one of {@link EventDetector.Action#STOP}, {@link EventDetector.Action#RESET_STATE},
141      * {@link EventDetector.Action#RESET_DERIVATIVES} or {@link EventDetector.Action#CONTINUE}
142      * @exception OrekitException if some specific error occurs
143      * @deprecated as of 6.1 replaced by {@link
144      * org.orekit.propagation.events.handlers.EventHandler#eventOccurred(SpacecraftState,
145      * EventDetector, boolean)}
146      */
147     @Deprecated
148     Action eventOccurred(SpacecraftState s, boolean increasing) throws OrekitException;
149 
150     /** Reset the state prior to continue propagation.
151      * <p>This method is called after the step handler has returned and
152      * before the next step is started, but only when {@link
153      * #eventOccurred} has itself returned the {@link EventDetector.Action#RESET_STATE}
154      * indicator. It allows the user to reset the state for the next step,
155      * without perturbing the step handler of the finishing step. If the
156      * {@link #eventOccurred} never returns the {@link EventDetector.Action#RESET_STATE}
157      * indicator, this function will never be called, and it is safe to simply return null.</p>
158      * @param oldState old state
159      * @return new state
160      * @exception OrekitException if the state cannot be reseted
161      * @deprecated as of 6.1 replaced by {@link
162      * org.orekit.propagation.events.handlers.EventHandler#resetState(EventDetector, SpacecraftState)}
163      */
164     @Deprecated
165     SpacecraftState resetState(SpacecraftState oldState) throws OrekitException;
166 
167     /** Get the convergence threshold in the event time search.
168      * @return convergence threshold (s)
169      */
170     double getThreshold();
171 
172     /** Get maximal time interval between switching function checks.
173      * @return maximal time interval (s) between switching function checks
174      */
175     double getMaxCheckInterval();
176 
177     /** Get maximal number of iterations in the event time search.
178      * @return maximal number of iterations in the event time search
179      */
180     int getMaxIterationCount();
181 
182 }