FieldEventDetector.java

  1. /* Copyright 2002-2022 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. import org.hipparchus.CalculusFieldElement;
  19. import org.hipparchus.ode.events.Action;
  20. import org.orekit.propagation.FieldSpacecraftState;
  21. import org.orekit.time.FieldAbsoluteDate;

  22. /** This interface represents space-dynamics aware events detectors.
  23.  *
  24.  * <p>It mirrors the {@link org.hipparchus.ode.events.FieldODEEventHandler
  25.  * FieldODEEventHandler} interface from <a href="https://hipparchus.org/">
  26.  * Hipparchus</a> but provides a space-dynamics interface to the
  27.  * methods.</p>
  28.  *
  29.  * <p>Events detectors are a useful solution to meet the requirements
  30.  * of propagators concerning discrete conditions. The state of each
  31.  * event detector is queried by the integrator at each step. When the
  32.  * sign of the underlying g switching function changes, the step is rejected
  33.  * and reduced, in order to make sure the sign changes occur only at steps
  34.  * boundaries.</p>
  35.  *
  36.  * <p>When step ends exactly at a switching function sign change, the corresponding
  37.  * event is triggered, by calling the {@link #eventOccurred(FieldSpacecraftState, boolean)}
  38.  * method. The method can do whatever it needs with the event (logging it, performing
  39.  * some processing, ignore it ...). The return value of the method will be used by
  40.  * the propagator to stop or resume propagation, possibly changing the state vector.<p>
  41.  *
  42.  * @author Luc Maisonobe
  43.  * @author V&eacute;ronique Pommier-Maurussane
  44.  */
  45. public interface FieldEventDetector <T extends CalculusFieldElement<T>> {

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

  63.     /** Compute the value of the switching function.
  64.      * This function must be continuous (at least in its roots neighborhood),
  65.      * as the integrator will need to find its roots to locate the events.
  66.      * @param s the current state information: date, kinematics, attitude
  67.      * @return value of the switching function
  68.      */
  69.     T g(FieldSpacecraftState<T> s);

  70.     /** Get the convergence threshold in the event time search.
  71.      * @return convergence threshold (s)
  72.      */
  73.     T getThreshold();

  74.     /** Get maximal time interval between switching function checks.
  75.      * @return maximal time interval (s) between switching function checks
  76.      */
  77.     T getMaxCheckInterval();

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

  82.     /** Handle the event.
  83.      * @param s SpaceCraft state to be used in the evaluation
  84.      * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
  85.      * @return the Action that the calling detector should pass back to the evaluation system
  86.           * @since 7.0
  87.      */
  88.     Action eventOccurred(FieldSpacecraftState<T> s, boolean increasing);

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

  107. }