FieldEventDetector.java

  1. /* Copyright 2002-2024 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.orekit.propagation.FieldSpacecraftState;
  20. import org.orekit.propagation.events.handlers.FieldEventHandler;
  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 propagator from time to time, at least
  32.  * once every {@link #getMaxCheckInterval() max check interval} but it may
  33.  * be more frequent. When the sign of the underlying g switching function
  34.  * changes, a root-finding algorithm is run to precisely locate the event,
  35.  * down to a configured {@link #getThreshold() convergence threshold}. The
  36.  * {@link #getMaxCheckInterval() max check interval} is therefore devoted to
  37.  * separate roots and is often much larger than the  {@link #getThreshold()
  38.  * convergence threshold}.</p>
  39.  *
  40.  * <p>The physical meaning of the g switching function is not really used
  41.  * by the event detection algorithms. Its varies from event detector to
  42.  * event detector. One example would be a visibility detector that could use the
  43.  * angular elevation of the satellite above horizon as a g switching function.
  44.  * In this case, the function would switch from negative to positive when the
  45.  * satellite raises above horizon and it would switch from positive to negative
  46.  * when it sets backs below horizon. Another example would be an apside detector
  47.  * that could use the dot product of position and velocity. In this case, the
  48.  * function would switch from negative to positive when the satellite crosses
  49.  * periapsis and it would switch from positive to negative when the satellite
  50.  * crosses apoapsis.</p>
  51.  *
  52.  * <p>When the precise state at which the g switching function changes has been
  53.  * located, the corresponding event is triggered, by calling the {@link
  54.  * FieldEventHandler#eventOccurred(FieldSpacecraftState, FieldEventDetector, boolean)
  55.  * eventOccurred} method from the associated {@link #getHandler() handler}.
  56.  * The method can do whatever it needs with the event (logging it, performing
  57.  * some processing, ignore it ...). The return value of the method will be used by
  58.  * the propagator to stop or resume propagation, possibly changing the state vector.</p>
  59.  *
  60.  * @param <T> type of the field element
  61.  * @author Luc Maisonobe
  62.  * @author V&eacute;ronique Pommier-Maurussane
  63.  */
  64. public interface FieldEventDetector <T extends CalculusFieldElement<T>> {

  65.     /** Initialize event handler at the start of a propagation.
  66.      * <p>
  67.      * This method is called once at the start of the propagation. It
  68.      * may be used by the event handler to initialize some internal data
  69.      * if needed.
  70.      * </p>
  71.      * <p>
  72.      * The default implementation does nothing
  73.      * </p>
  74.      * @param s0 initial state
  75.      * @param t target time for the integration
  76.      *
  77.      */
  78.     default void init(FieldSpacecraftState<T> s0,
  79.                       FieldAbsoluteDate<T> t) {
  80.         // nothing by default
  81.     }

  82.     /** Compute the value of the switching function.
  83.      * This function must be continuous (at least in its roots neighborhood),
  84.      * as the integrator will need to find its roots to locate the events.
  85.      * @param s the current state information: date, kinematics, attitude
  86.      * @return value of the switching function
  87.      */
  88.     T g(FieldSpacecraftState<T> s);

  89.     /** Get the convergence threshold in the event time search.
  90.      * @return convergence threshold (s)
  91.      */
  92.     T getThreshold();

  93.     /** Get maximal time interval between switching function checks.
  94.      * @return maximal time interval (s) between switching function checks
  95.      */
  96.     FieldAdaptableInterval<T> getMaxCheckInterval();

  97.     /** Get maximal number of iterations in the event time search.
  98.      * @return maximal number of iterations in the event time search
  99.      */
  100.     int getMaxIterationCount();

  101.     /** Get the handler.
  102.      * @return event handler to call at event occurrences
  103.      * @since 12.0
  104.      */
  105.     FieldEventHandler<T> getHandler();

  106. }