EventEnablingPredicateFilter.java

  1. /* Copyright 2002-2025 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.Arrays;

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

  26. /** Wrapper used to detect events only when enabled by an external predicated function.
  27.  *
  28.  * <p>General {@link EventDetector events} are defined implicitly
  29.  * by a {@link EventDetector#g(SpacecraftState) g function} crossing
  30.  * zero. This implies that during an orbit propagation, events are
  31.  * triggered at all zero crossings.
  32.  * </p>
  33.  *
  34.  * <p>Sometimes, users would like to enable or disable events by themselves,
  35.  * for example to trigger them only for certain orbits, or to check elevation
  36.  * maximums only when elevation itself is positive (i.e. they want to
  37.  * discard elevation maximums below ground). In these cases, looking precisely
  38.  * for all events location and triggering events that will later be ignored
  39.  * is a waste of computing time.</p>
  40.  *
  41.  * <p>Users can wrap a regular {@link EventDetector event detector} in
  42.  * an instance of this class and provide this wrapping instance to
  43.  * a {@link org.orekit.propagation.Propagator}
  44.  * in order to avoid wasting time looking for uninteresting events.
  45.  * The wrapper will intercept the calls to the {@link
  46.  * EventDetector#g(SpacecraftState) g function} and to the {@link
  47.  * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean)
  48.  * eventOccurred} method in order to ignore uninteresting events. The
  49.  * wrapped regular {@link EventDetector event detector} will the see only
  50.  * the interesting events, i.e. either only events that occur when a
  51.  * user-provided event enabling predicate function is true, ignoring all events
  52.  * that occur when the event enabling predicate function is false. The number of
  53.  * calls to the {@link EventDetector#g(SpacecraftState) g function} will also be
  54.  * reduced.</p>
  55.  * @see EventSlopeFilter
  56.  * @since 7.1
  57.  */

  59. public class EventEnablingPredicateFilter implements DetectorModifier {

  61.     /** Number of past transformers updates stored. */
  62.     private static final int HISTORY_SIZE = 100;

  64.     /** Wrapped event detector. */
  65.     private final EventDetector rawDetector;

  67.     /** Enabling predicate function. */
  68.     private final EnablingPredicate predicate;

  70.     /** Transformers of the g function. */
  71.     private final Transformer[] transformers;

  73.     /** Update time of the transformers. */
  74.     private final AbsoluteDate[] updates;

  76.     /** Event detection settings. */
  77.     private final EventDetectionSettings detectionSettings;

  79.     /** Specialized event handler. */
  80.     private final LocalHandler handler;

  82.     /** Indicator for forward integration. */
  83.     private boolean forward;

  85.     /** Extreme time encountered so far. */
  86.     private AbsoluteDate extremeT;

  88.     /** Detector function value at extremeT. */
  89.     private double extremeG;

  91.     /** Wrap an {@link EventDetector event detector}.
  92.      * @param rawDetector event detector to wrap (its detection settings are taken as well)
  93.      * @param enabler event enabling predicate function to use
  94.      */
  95.     public EventEnablingPredicateFilter(final EventDetector rawDetector,
  96.                                         final EnablingPredicate enabler) {
  97.         this(rawDetector.getDetectionSettings(), rawDetector, enabler);
  98.     }

  100.     /** Constructor with full parameters.
  101.      * @param detectionSettings event detection settings
  102.      * @param rawDetector event detector to wrap
  103.      * @param enabler event enabling function to use
  104.      * @since 13.0
  105.      */
  106.     public EventEnablingPredicateFilter(final EventDetectionSettings detectionSettings,
  107.                                         final EventDetector rawDetector, final EnablingPredicate enabler) {
  108.         this.detectionSettings = detectionSettings;
  109.         this.handler = new LocalHandler();
  110.         this.rawDetector  = rawDetector;
  111.         this.predicate = enabler;
  112.         this.transformers = new Transformer[HISTORY_SIZE];
  113.         this.updates      = new AbsoluteDate[HISTORY_SIZE];
  114.     }

  116.     /**
  117.      * Builds a new instance from the input detection settings.
  118.      * @param settings event detection settings to be used
  119.      * @return a new detector
  120.      */
  121.     public EventEnablingPredicateFilter withDetectionSettings(final EventDetectionSettings settings) {
  122.         return new EventEnablingPredicateFilter(settings, rawDetector, predicate);
  123.     }

  125.     /**
  126.      * Get the wrapped raw detector.
  127.      * @return the wrapped raw detector
  128.      * @since 11.1
  129.      */
  130.     @Override
  131.     public EventDetector getDetector() {
  132.         return rawDetector;
  133.     }

  135.     /** {@inheritDoc} */
  136.     @Override
  137.     public EventHandler getHandler() {
  138.         return handler;
  139.     }

  141.     /** {@inheritDoc} */
  142.     @Override
  143.     public EventDetectionSettings getDetectionSettings() {
  144.         return detectionSettings;
  145.     }

  147.     /**
  148.      * Getter for the enabling predicate.
  149.      * @return predicate
  150.      * @since 13.1
  151.      */
  152.     public EnablingPredicate getPredicate() {
  153.         return predicate;
  154.     }

  156.     /**  {@inheritDoc} */
  157.     @Override
  158.     public boolean dependsOnTimeOnly() {
  159.         return false;  // cannot know what predicate needs
  160.     }

  162.     /**  {@inheritDoc} */
  163.     @Override
  164.     public void init(final SpacecraftState s0, final AbsoluteDate t) {
  165.         DetectorModifier.super.init(s0, t);

  167.         // initialize events triggering logic
  168.         forward  = AbstractDetector.checkIfForward(s0, t);
  169.         extremeT = forward ? AbsoluteDate.PAST_INFINITY : AbsoluteDate.FUTURE_INFINITY;
  170.         extremeG = Double.NaN;

  172.         Arrays.fill(transformers, Transformer.UNINITIALIZED);
  173.         Arrays.fill(updates, extremeT);

  175.     }

  177.     /**  {@inheritDoc} */
  178.     @Override
  179.     public void reset(final SpacecraftState state, final AbsoluteDate target) {
  180.         DetectorModifier.super.reset(state, target);
  181.         forward  = AbstractDetector.checkIfForward(state, target);
  182.         extremeT = forward ? AbsoluteDate.PAST_INFINITY : AbsoluteDate.FUTURE_INFINITY;
  183.         extremeG = Double.NaN;
  184.     }

  186.     /**  {@inheritDoc} */
  187.     @Override
  188.     public double g(final SpacecraftState s) {

  190.         final double  rawG      = rawDetector.g(s);
  191.         final boolean isEnabled = predicate.eventIsEnabled(s, rawDetector, rawG);
  192.         if (Double.isNaN(extremeG)) {
  193.             extremeG = rawG;
  194.         }

  196.         // search which transformer should be applied to g
  197.         if (isForward()) {
  198.             final int last = transformers.length - 1;
  199.             if (extremeT.compareTo(s.getDate()) < 0) {
  200.                 // we are at the forward end of the history

  202.                 // check if enabled status has changed
  203.                 final Transformer previous = transformers[last];
  204.                 final Transformer next     = selectTransformer(previous, extremeG, isEnabled);
  205.                 if (next != previous) {
  206.                     // there is a status change somewhere between extremeT and t.
  207.                     // the new transformer is valid for t (this is how we have just computed
  208.                     // it above), but it is in fact valid on both sides of the change, so
  209.                     // it was already valid before t and even up to previous time. We store
  210.                     // the switch at extremeT for safety, to ensure the previous transformer
  211.                     // is not applied too close of the root
  212.                     System.arraycopy(updates,      1, updates,      0, last);
  213.                     System.arraycopy(transformers, 1, transformers, 0, last);
  214.                     updates[last]      = extremeT;
  215.                     transformers[last] = next;
  216.                 }

  218.                 extremeT = s.getDate();
  219.                 extremeG = rawG;

  221.                 // apply the transform
  222.                 return next.transformed(rawG);

  224.             } else {
  225.                 // we are in the middle of the history

  227.                 // select the transformer
  228.                 for (int i = last; i > 0; --i) {
  229.                     if (updates[i].compareTo(s.getDate()) <= 0) {
  230.                         // apply the transform
  231.                         return transformers[i].transformed(rawG);
  232.                     }
  233.                 }

  235.                 return transformers[0].transformed(rawG);

  237.             }
  238.         } else {
  239.             if (s.getDate().compareTo(extremeT) < 0) {
  240.                 // we are at the backward end of the history

  242.                 // check if a new rough root has been crossed
  243.                 final Transformer previous = transformers[0];
  244.                 final Transformer next     = selectTransformer(previous, extremeG, isEnabled);
  245.                 if (next != previous) {
  246.                     // there is a status change somewhere between extremeT and t.
  247.                     // the new transformer is valid for t (this is how we have just computed
  248.                     // it above), but it is in fact valid on both sides of the change, so
  249.                     // it was already valid before t and even up to previous time. We store
  250.                     // the switch at extremeT for safety, to ensure the previous transformer
  251.                     // is not applied too close of the root
  252.                     System.arraycopy(updates,      0, updates,      1, updates.length - 1);
  253.                     System.arraycopy(transformers, 0, transformers, 1, transformers.length - 1);
  254.                     updates[0]      = extremeT;
  255.                     transformers[0] = next;
  256.                 }

  258.                 extremeT = s.getDate();
  259.                 extremeG = rawG;

  261.                 // apply the transform
  262.                 return next.transformed(rawG);

  264.             } else {
  265.                 // we are in the middle of the history

  267.                 // select the transformer
  268.                 for (int i = 0; i < updates.length - 1; ++i) {
  269.                     if (s.getDate().compareTo(updates[i]) <= 0) {
  270.                         // apply the transform
  271.                         return transformers[i].transformed(rawG);
  272.                     }
  273.                 }

  275.                 return transformers[updates.length - 1].transformed(rawG);

  277.             }
  278.         }

  280.     }

  282.     /** Get next function transformer in the specified direction.
  283.      * @param previous transformer active on the previous point with respect
  284.      * to integration direction (may be null if no previous point is known)
  285.      * @param previousG value of the g function at the previous point
  286.      * @param isEnabled if true the event should be enabled now
  287.      * @return next transformer transformer
  288.      */
  289.     private Transformer selectTransformer(final Transformer previous, final double previousG, final boolean isEnabled) {
  290.         if (isEnabled) {
  291.             // we need to select a transformer that can produce zero crossings,
  292.             // so it is either Transformer.PLUS or Transformer.MINUS
  293.             switch (previous) {
  294.                 case UNINITIALIZED :
  295.                     return Transformer.PLUS; // this initial choice is arbitrary, it could have been Transformer.MINUS
  296.                 case MIN :
  297.                     return previousG >= 0 ? Transformer.MINUS : Transformer.PLUS;
  298.                 case MAX :
  299.                     return previousG >= 0 ? Transformer.PLUS : Transformer.MINUS;
  300.                 default :
  301.                     return previous;
  302.             }
  303.         } else {
  304.             // we need to select a transformer that cannot produce any zero crossings,
  305.             // so it is either Transformer.MAX or Transformer.MIN
  306.             switch (previous) {
  307.                 case UNINITIALIZED :
  308.                     return Transformer.MAX; // this initial choice is arbitrary, it could have been Transformer.MIN
  309.                 case PLUS :
  310.                     return previousG >= 0 ? Transformer.MAX : Transformer.MIN;
  311.                 case MINUS :
  312.                     return previousG >= 0 ? Transformer.MIN : Transformer.MAX;
  313.                 default :
  314.                     return previous;
  315.             }
  316.         }
  317.     }

  319.     /** Check if the current propagation is forward or backward.
  320.      * @return true if the current propagation is forward
  321.      */
  322.     public boolean isForward() {
  323.         return forward;
  324.     }

  326.     /** Local handler. */
  327.     private static class LocalHandler implements EventHandler {

  329.         /** {@inheritDoc} */
  330.         public Action eventOccurred(final SpacecraftState s, final EventDetector detector, final boolean increasing) {
  331.             final EventEnablingPredicateFilter ef = (EventEnablingPredicateFilter) detector;
  332.             final Transformer transformer = ef.isForward() ? ef.transformers[ef.transformers.length - 1] : ef.transformers[0];
  333.             return ef.rawDetector.getHandler().eventOccurred(s, ef.rawDetector, transformer == Transformer.PLUS ? increasing : !increasing);
  334.         }

  336.         /** {@inheritDoc} */
  337.         @Override
  338.         public SpacecraftState resetState(final EventDetector detector, final SpacecraftState oldState) {
  339.             final EventEnablingPredicateFilter ef = (EventEnablingPredicateFilter) detector;
  340.             return ef.rawDetector.getHandler().resetState(ef.rawDetector, oldState);
  341.         }

  343.     }

  345. }
Created with JaCoCo 0.8.12.202403310830