EventsLogger.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;

  19. import java.util.ArrayList;
  20. import java.util.List;

  22. import org.hipparchus.ode.events.Action;
  23. import org.orekit.propagation.SpacecraftState;
  24. import org.orekit.propagation.events.handlers.EventHandler;
  25. import org.orekit.time.AbsoluteDate;
  26. import org.orekit.time.TimeStamped;

  28. /** This class logs events detectors events during propagation.
  29.  *
  30.  * <p>As {@link EventDetector events detectors} are triggered during
  31.  * orbit propagation, an event specific {@link
  32.  * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
  33.  * method is called. This class can be used to add a global logging
  34.  * feature registering all events with their corresponding states in
  35.  * a chronological sequence (or reverse-chronological if propagation
  36.  * occurs backward).
  37.  * <p>This class works by wrapping user-provided {@link EventDetector
  38.  * events detectors} before they are registered to the propagator. The
  39.  * wrapper monitor the calls to {@link
  40.  * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
  41.  * and store the corresponding events as {@link LoggedEvent} instances.
  42.  * After propagation is complete, the user can retrieve all the events
  43.  * that have occurred at once by calling method {@link #getLoggedEvents()}.</p>
  44.  *
  45.  * @author Luc Maisonobe
  46.  */
  47. public class EventsLogger {

  49.     /** List of occurred events. */
  50.     private final List<LoggedEvent> log;

  52.     /** Simple constructor.
  53.      * <p>
  54.      * Build an empty logger for events detectors.
  55.      * </p>
  56.      */
  57.     public EventsLogger() {
  58.         log = new ArrayList<>();
  59.     }

  61.     /** Monitor an event detector.
  62.      * <p>
  63.      * In order to monitor an event detector, it must be wrapped thanks to
  64.      * this method as follows:
  65.      * </p>
  66.      * <pre>
  67.      * Propagator propagator = new XyzPropagator(...);
  68.      * EventsLogger logger = new EventsLogger();
  69.      * EventDetector detector = new UvwDetector(...);
  70.      * propagator.addEventDetector(logger.monitorDetector(detector));
  71.      * </pre>
  72.      * <p>
  73.      * Note that the event detector returned by the {@link
  74.      * LoggedEvent#getEventDetector() getEventDetector} method in
  75.      * {@link LoggedEvent LoggedEvent} instances returned by {@link
  76.      * #getLoggedEvents()} are the {@code monitoredDetector} instances
  77.      * themselves, not the wrapping detector returned by this method.
  78.      * </p>
  79.      * @param monitoredDetector event detector to monitor
  80.      * @return the wrapping detector to add to the propagator
  81.      * @param <T> class type for the generic version
  82.      */
  83.     public <T extends EventDetector> EventDetector monitorDetector(final T monitoredDetector) {
  84.         return new LoggingWrapper(monitoredDetector);
  85.     }

  87.     /** Clear the logged events.
  88.      */
  89.     public void clearLoggedEvents() {
  90.         log.clear();
  91.     }

  93.     /** Get an immutable copy of the logged events.
  94.      * <p>
  95.      * The copy is independent of the logger. It is preserved
  96.      * event if the {@link #clearLoggedEvents() clearLoggedEvents} method
  97.      * is called and the logger reused in another propagation.
  98.      * </p>
  99.      * @return an immutable copy of the logged events
  100.      */
  101.     public List<LoggedEvent> getLoggedEvents() {
  102.         return new ArrayList<>(log);
  103.     }

  105.     /** Class for logged events entries. */
  106.     public static class LoggedEvent implements TimeStamped {

  108.         /** Event detector triggered. */
  109.         private final EventDetector detector;

  111.         /** Triggering state. */
  112.         private final SpacecraftState state;

  114.         /** Increasing/decreasing status. */
  115.         private final boolean increasing;

  117.         /** Simple constructor.
  118.          * @param detector detector for event that was triggered
  119.          * @param state state at event trigger date
  120.          * @param increasing indicator if the event switching function was increasing
  121.          * or decreasing at event occurrence date
  122.          */
  123.         private LoggedEvent(final EventDetector detector, final SpacecraftState state, final boolean increasing) {
  124.             this.detector   = detector;
  125.             this.state      = state;
  126.             this.increasing = increasing;
  127.         }

  129.         /** Get the event detector triggered.
  130.          * @return event detector triggered
  131.          */
  132.         public EventDetector getEventDetector() {
  133.             return detector;
  134.         }

  136.         /** {@inheritDoc} */
  137.         @Override
  138.         public AbsoluteDate getDate() {
  139.             return state.getDate();
  140.         }

  142.         /** Get the triggering state.
  143.          * @return triggering state
  144.          * @see EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean)
  145.          */
  146.         public SpacecraftState getState() {
  147.             return state;
  148.         }

  150.         /** Get the Increasing/decreasing status of the event.
  151.          * @return increasing/decreasing status of the event
  152.          * @see EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean)
  153.          */
  154.         public boolean isIncreasing() {
  155.             return increasing;
  156.         }

  158.     }

  160.     /** Internal wrapper for events detectors. */
  161.     private class LoggingWrapper extends AbstractDetector<LoggingWrapper> {

  163.         /** Wrapped events detector. */
  164.         private final EventDetector detector;

  166.         /** Simple constructor.
  167.          * @param detector events detector to wrap
  168.          */
  169.         LoggingWrapper(final EventDetector detector) {
  170.             this(detector.getDetectionSettings(), null, detector);
  171.         }

  173.         /** Private constructor with full parameters.
  174.          * <p>
  175.          * This constructor is private as users are expected to use the builder
  176.          * API with the various {@code withXxx()} methods to set up the instance
  177.          * in a readable manner without using a huge amount of parameters.
  178.          * </p>
  179.          * @param detectionSettings detection settings
  180.          * @param handler event handler to call at event occurrences
  181.          * @param detector events detector to wrap
  182.          * @since 6.1
  183.          */
  184.         private LoggingWrapper(final EventDetectionSettings detectionSettings, final EventHandler handler,
  185.                                final EventDetector detector) {
  186.             super(detectionSettings, handler);
  187.             this.detector = detector;
  188.         }

  190.         /** {@inheritDoc} */
  191.         @Override
  192.         protected LoggingWrapper create(final AdaptableInterval newMaxCheck, final double newThreshold,
  193.                                         final int newMaxIter, final EventHandler newHandler) {
  194.             return new LoggingWrapper(new EventDetectionSettings(newMaxCheck, newThreshold, newMaxIter), newHandler, detector);
  195.         }

  197.         /** Log an event.
  198.          * @param state state at event trigger date
  199.          * @param increasing indicator if the event switching function was increasing
  200.          */
  201.         public void logEvent(final SpacecraftState state, final boolean increasing) {
  202.             log.add(new LoggedEvent(detector, state, increasing));
  203.         }

  205.         /** {@inheritDoc} */
  206.         @Override
  207.         public void init(final SpacecraftState s0,
  208.                          final AbsoluteDate t) {
  209.             super.init(s0, t);
  210.             detector.init(s0, t);
  211.         }

  213.         /** {@inheritDoc} */
  214.         public double g(final SpacecraftState s) {
  215.             return detector.g(s);
  216.         }

  218.         /** {@inheritDoc} */
  219.         @Override
  220.         public void finish(final SpacecraftState state) {
  221.             detector.finish(state);
  222.         }

  224.         /** {@inheritDoc} */
  225.         @Override
  226.         public EventHandler getHandler() {

  228.             final EventHandler handler = detector.getHandler();

  230.             return new EventHandler() {

  232.                 /** {@inheritDoc} */
  233.                 public Action eventOccurred(final SpacecraftState s, final EventDetector d, final boolean increasing) {
  234.                     logEvent(s, increasing);
  235.                     return handler.eventOccurred(s, detector, increasing);
  236.                 }

  238.                 /** {@inheritDoc} */
  239.                 @Override
  240.                 public SpacecraftState resetState(final EventDetector d, final SpacecraftState oldState) {
  241.                     return handler.resetState(detector, oldState);
  242.                 }

  244.             };
  245.         }

  247.     }

  249. }
Created with JaCoCo 0.8.12.202403310830