FieldEventsLogger.java

  1. /* Copyright 2002-2019 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.util.ArrayList;
  19. import java.util.List;

  20. import org.hipparchus.RealFieldElement;
  21. import org.hipparchus.ode.events.Action;
  22. import org.orekit.propagation.FieldSpacecraftState;
  23. import org.orekit.propagation.events.handlers.FieldEventHandler;
  24. import org.orekit.time.FieldAbsoluteDate;

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



  45.     /** List of occurred events. */
  46.     private final List<FieldLoggedEvent<T>> log;

  47.     /** Simple constructor.
  48.      * <p>
  49.      * Build an empty logger for events detectors.
  50.      * </p>
  51.      */
  52.     public FieldEventsLogger() {
  53.         log = new ArrayList<FieldEventsLogger.FieldLoggedEvent<T>>();
  54.     }

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

  80.     /** Clear the logged events.
  81.      */
  82.     public void clearLoggedEvents() {
  83.         log.clear();
  84.     }

  85.     /** Get an immutable copy of the logged events.
  86.      * <p>
  87.      * The copy is independent of the logger. It is preserved
  88.      * event if the {@link #clearLoggedEvents() clearLoggedEvents} method
  89.      * is called and the logger reused in another propagation.
  90.      * </p>
  91.      * @return an immutable copy of the logged events
  92.      */
  93.     public List<FieldLoggedEvent<T>> getLoggedEvents() {
  94.         return new ArrayList<FieldEventsLogger.FieldLoggedEvent<T>>(log);
  95.     }

  96.     /** Class for logged events entries. */
  97.     public static class FieldLoggedEvent <T extends RealFieldElement<T>> {

  98.         /** Event detector triggered. */
  99.         private final FieldEventDetector<T> detector;

  100.         /** Triggering state. */
  101.         private final FieldSpacecraftState<T> state;

  102.         /** Increasing/decreasing status. */
  103.         private final boolean increasing;

  104.         /** Simple constructor.
  105.          * @param detectorN detector for event that was triggered
  106.          * @param stateN state at event trigger date
  107.          * @param increasingN indicator if the event switching function was increasing
  108.          * or decreasing at event occurrence date
  109.          */
  110.         private FieldLoggedEvent(final FieldEventDetector<T> detectorN, final FieldSpacecraftState<T> stateN, final boolean increasingN) {
  111.             detector   = detectorN;
  112.             state      = stateN;
  113.             increasing = increasingN;
  114.         }

  115.         /** Get the event detector triggered.
  116.          * @return event detector triggered
  117.          */
  118.         public FieldEventDetector<T> getEventDetector() {
  119.             return detector;
  120.         }

  121.         /** Get the triggering state.
  122.          * @return triggering state
  123.          * @see FieldEventDetector#eventOccurred(FieldSpacecraftState, boolean)
  124.          */
  125.         public FieldSpacecraftState<T> getState() {
  126.             return state;
  127.         }

  128.         /** Get the Increasing/decreasing status of the event.
  129.          * @return increasing/decreasing status of the event
  130.          * @see FieldEventDetector#eventOccurred(FieldSpacecraftState, boolean)
  131.          */
  132.         public boolean isIncreasing() {
  133.             return increasing;
  134.         }

  135.     }

  136.     /** Internal wrapper for events detectors.
  137.      * @param <D> class type for the generic version
  138.      */
  139.     private class FieldLoggingWrapper<D extends FieldEventDetector<T>> extends FieldAbstractDetector<FieldLoggingWrapper<D>, T> {

  140.         /** Wrapped events detector. */
  141.         private final D detector;

  142.         /** Simple constructor.
  143.          * @param detector events detector to wrap
  144.          */
  145.         FieldLoggingWrapper(final D detector) {
  146.             this(detector.getMaxCheckInterval(), detector.getThreshold(),
  147.                  detector.getMaxIterationCount(), new FieldLocalHandler<>(),
  148.                  detector);
  149.         }

  150.         /** Private constructor with full parameters.
  151.          * <p>
  152.          * This constructor is private as users are expected to use the builder
  153.          * API with the various {@code withXxx()} methods to set up the instance
  154.          * in a readable manner without using a huge amount of parameters.
  155.          * </p>
  156.          * @param maxCheck maximum checking interval (s)
  157.          * @param threshold convergence threshold (s)
  158.          * @param maxIter maximum number of iterations in the event time search
  159.          * @param handler event handler to call at event occurrences
  160.          * @param detector events detector to wrap
  161.          * @since 6.1
  162.          */
  163.         private FieldLoggingWrapper(final T maxCheck, final T threshold,
  164.                                final int maxIter, final FieldEventHandler<? super FieldLoggingWrapper<D>, T> handler,
  165.                                final D detector) {
  166.             super(maxCheck, threshold, maxIter, handler);
  167.             this.detector = detector;
  168.         }

  169.         /** {@inheritDoc} */
  170.         @Override
  171.         protected FieldLoggingWrapper<D> create(final T newMaxCheck, final T newThreshold,
  172.                                            final int newMaxIter, final FieldEventHandler<? super FieldLoggingWrapper<D>, T> newHandler) {
  173.             return new FieldLoggingWrapper<>(newMaxCheck, newThreshold, newMaxIter, newHandler, detector);
  174.         }

  175.         /** Log an event.
  176.          * @param state state at event trigger date
  177.          * @param increasing indicator if the event switching function was increasing
  178.          */
  179.         public void logEvent(final FieldSpacecraftState<T> state, final boolean increasing) {
  180.             log.add(new FieldLoggedEvent<>(detector, state, increasing));
  181.         }

  182.         /** {@inheritDoc} */
  183.         public void init(final FieldSpacecraftState<T> s0,
  184.                          final FieldAbsoluteDate<T> t) {
  185.             super.init(s0, t);
  186.             detector.init(s0, t);
  187.         }

  188.         /** {@inheritDoc} */
  189.         public T g(final FieldSpacecraftState<T> s) {
  190.             return detector.g(s);
  191.         }

  192.     }

  193.     /** Local class for handling events.
  194.      * @param <D> class type for the generic version
  195.      */
  196.     private class FieldLocalHandler<D extends FieldEventDetector<T>> implements FieldEventHandler<FieldLoggingWrapper<D>, T> {

  197.         /** {@inheritDoc} */
  198.         public Action eventOccurred(final FieldSpacecraftState<T> s, final FieldLoggingWrapper<D> wrapper, final boolean increasing) {
  199.             wrapper.logEvent(s, increasing);
  200.             return wrapper.detector.eventOccurred(s, increasing);
  201.         }

  202.         /** {@inheritDoc} */
  203.         @Override
  204.         public FieldSpacecraftState<T> resetState(final FieldLoggingWrapper<D> wrapper, final FieldSpacecraftState<T> oldState) {
  205.             return wrapper.detector.resetState(oldState);
  206.         }

  207.     }

  208. }