EventDetector.java

  1. /* Copyright 2002-2018 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. import java.io.Serializable;

  19. import org.orekit.errors.OrekitException;
  20. import org.orekit.propagation.SpacecraftState;
  21. import org.orekit.propagation.events.handlers.EventHandler.Action;
  22. import org.orekit.time.AbsoluteDate;

  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 extends Serializable {

  47.     /** Initialize event handler at the start of a propagation.
  48.      * <p>
  49.      * This method is called once at the start of the propagation. It
  50.      * may be used by the event handler to initialize some internal data
  51.      * if needed.
  52.      * </p>
  53.      * <p>
  54.      * The default implementation does nothing
  55.      * </p>
  56.      * @param s0 initial state
  57.      * @param t target time for the integration
  58.      *
  59.      * @throws OrekitException if some specific error occurs
  60.      */
  61.     default void init(SpacecraftState s0, AbsoluteDate t) throws OrekitException {
  62.         // nothing by default
  63.     }

  64.     /** Compute the value of the switching function.
  65.      * This function must be continuous (at least in its roots neighborhood),
  66.      * as the integrator will need to find its roots to locate the events.
  67.      * @param s the current state information: date, kinematics, attitude
  68.      * @return value of the switching function
  69.      * @exception OrekitException if some specific error occurs
  70.      */
  71.     double g(SpacecraftState s) throws OrekitException;

  72.     /** Get the convergence threshold in the event time search.
  73.      * @return convergence threshold (s)
  74.      */
  75.     double getThreshold();

  76.     /** Get maximal time interval between switching function checks.
  77.      * @return maximal time interval (s) between switching function checks
  78.      */
  79.     double getMaxCheckInterval();

  80.     /** Get maximal number of iterations in the event time search.
  81.      * @return maximal number of iterations in the event time search
  82.      */
  83.     int getMaxIterationCount();

  84.     /** Handle the event.
  85.      * @param s SpaceCraft state to be used in the evaluation
  86.      * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
  87.      * @return the Action that the calling detector should pass back to the evaluation system
  88.      * @exception OrekitException if some specific error occurs
  89.      * @since 7.0
  90.      */
  91.     Action eventOccurred(SpacecraftState s, boolean increasing) throws OrekitException;

  92.     /** Reset the state prior to continue propagation.
  93.      * <p>This method is called after the step handler has returned and
  94.      * before the next step is started, but only when {@link
  95.      * #eventOccurred} has itself returned the {@link Action#RESET_STATE}
  96.      * indicator. It allows the user to reset the state for the next step,
  97.      * without perturbing the step handler of the finishing step. If the
  98.      * {@link #eventOccurred} never returns the {@link Action#RESET_STATE}
  99.      * indicator, this function will never be called, and it is safe to simply return null.</p>
  100.      * <p>
  101.      * The default implementation simply returns its argument.
  102.      * </p>
  103.      * @param oldState old state
  104.      * @return new state
  105.      * @exception OrekitException if the state cannot be reseted
  106.      * @since 7.0
  107.      */
  108.     default SpacecraftState resetState(SpacecraftState oldState) throws OrekitException {
  109.         return oldState;
  110.     }

  111. }