/* Copyright 2002-2025 CS GROUP
    * Licensed to CS GROUP (CS) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * CS licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *   http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.orekit.propagation.events;
  
  import org.orekit.propagation.SpacecraftState;
  import org.orekit.propagation.events.functions.EventFunction;
  import org.orekit.propagation.events.handlers.ContinueOnEvent;
  import org.orekit.propagation.events.handlers.EventHandler;
  import org.orekit.propagation.events.intervals.AdaptableInterval;
  import org.orekit.time.AbsoluteDate;
  
  /** This interface represents space-dynamics aware events detectors.
   *
   * <p>It mirrors the {@link org.hipparchus.ode.events.ODEEventHandler
   * ODEEventHandler} interface from <a href="https://hipparchus.org/">
   * Hipparchus</a> but provides a space-dynamics interface to the
   * methods.</p>
   *
   * <p>Events detectors are a useful solution to meet the requirements
   * of propagators concerning discrete conditions. The state of each
   * event detector is queried by the propagator from time to time, at least
   * once every {@link #getMaxCheckInterval() max check interval} but it may
   * be more frequent. When the sign of the underlying g switching function
   * changes, a root-finding algorithm is run to precisely locate the event,
   * down to a configured {@link #getThreshold() convergence threshold}. The
   * {@link #getMaxCheckInterval() max check interval} is therefore devoted to
   * separate roots and is often much larger than the  {@link #getThreshold()
   * convergence threshold}.</p>
   *
   * <p>The physical meaning of the g switching function is not really used
   * by the event detection algorithms. Its varies from event detector to
   * event detector. One example would be a visibility detector that could use the
   * angular elevation of the satellite above horizon as a g switching function.
   * In this case, the function would switch from negative to positive when the
   * satellite raises above horizon and it would switch from positive to negative
   * when it sets backs below horizon. Another example would be an apside detector
   * that could use the dot product of position and velocity. In this case, the
   * function would switch from negative to positive when the satellite crosses
   * periapsis and it would switch from positive to negative when the satellite
   * crosses apoapsis.</p>
   *
   * <p>When the precise state at which the g switching function changes has been
   * located, the corresponding event is triggered, by calling the {@link
   * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
   * method from the associated {@link #getHandler() handler}.
   * The method can do whatever it needs with the event (logging it, performing
   * some processing, ignore it ...). The return value of the method will be used by
   * the propagator to stop or resume propagation, possibly changing the state vector.</p>
   *
   * @author Luc Maisonobe
   * @author V&eacute;ronique Pommier-Maurussane
   */
  public interface EventDetector {
  
      /**
       * Builds instance from event function only. Uses default handler and detection settings.
       * @param eventFunction event function
       * @return event detector
       * @since 14.0
       */
      static EventDetector of(final EventFunction eventFunction) {
          return of(eventFunction, new ContinueOnEvent());
      }
  
      /**
       * Builds instance from event function and handler. Uses default detection settings.
       * @param eventFunction event function
       * @param eventHandler handler
       * @return event detector
       * @since 14.0
       */
      static EventDetector of(final EventFunction eventFunction, final EventHandler eventHandler) {
          return of(eventFunction, eventHandler, EventDetectionSettings.getDefaultEventDetectionSettings());
      }
  
      /**
       * Builds instance from event function, handler and detection settings.
       * @param eventFunction event function
       * @param eventHandler handler
       * @param eventDetectionSettings detection settings
       * @return event detector
       * @since 14.0
       */
      static EventDetector of(final EventFunction eventFunction, final EventHandler eventHandler,
                              final EventDetectionSettings eventDetectionSettings) {
         return new EventDetector() {
 
             @Override
             public double g(final SpacecraftState s) {
                 return eventFunction.value(s);
             }
 
             @Override
             public EventFunction getEventFunction() {
                 return eventFunction;
             }
 
             @Override
             public EventDetectionSettings getDetectionSettings() {
                 return eventDetectionSettings;
             }
 
             @Override
             public EventHandler getHandler() {
                 return eventHandler;
             }
         };
     }
 
     /** Initialize event detector at the start of a propagation.
      * <p>
      * This method is called once at the start of the propagation. It
      * may be used by the event handler to initialize some internal data
      * if needed.
      * </p>
      * <p>
      * The default implementation initializes the handler.
      * </p>
      * @param s0 initial state
      * @param t target time for the integration
      *
      */
     default void init(final SpacecraftState s0, final AbsoluteDate t) {
         getHandler().init(s0, t, this);
     }
 
     /** Reset the event detector during propagation when the state is modified by an event or an additional data provider.
      * <p>
      * The default implementation does nothing.
      * </p>
      * @param state current state
      * @param target target time for the integration
      * @since 13.0
      */
     default void reset(final SpacecraftState state, final AbsoluteDate target) {
         // nothing by default
     }
 
     /** Compute the value of the switching function.
      * This function must be continuous (at least in its roots neighborhood),
      * as the integrator will need to find its roots to locate the events.
      * @param s the current state information: date, kinematics, attitude
      * @return value of the switching function
      */
     double g(SpacecraftState s);
 
     /**
      * Get the event function. It defines g both for double and Field.
      * @return event function
      * @since 14.0
      */
     default EventFunction getEventFunction() {
         return this::g;
     }
 
     /** Get the convergence threshold in the event time search.
      * @return convergence threshold (s)
      */
     default double getThreshold() {
         return getDetectionSettings().getThreshold();
     }
 
     /** Get maximal time interval between switching function checks.
      * @return maximal time interval (s) between switching function checks
      */
     default AdaptableInterval getMaxCheckInterval() {
         return getDetectionSettings().getMaxCheckInterval();
     }
 
     /** Get maximal number of iterations in the event time search.
      * @return maximal number of iterations in the event time search
      */
     default int getMaxIterationCount() {
         return getDetectionSettings().getMaxIterationCount();
     }
 
     /** Get the handler.
      * @return event handler to call at event occurrences
      * @since 12.0
      */
     EventHandler getHandler();
 
     /**
      * This method finalizes the event detector's job.
      * @param state state at propagation end
      * @since 12.2
      */
     default void finish(final SpacecraftState state) {
         getHandler().finish(state, this);
     }
 
     /**
      * Getter for the settings.
      * @return detection settings
      * @since 12.2
      */
     default EventDetectionSettings getDetectionSettings() {
         return EventDetectionSettings.getDefaultEventDetectionSettings();
     }
 }