FieldEventEnablingPredicateFilter.java

  1. /* Copyright 2022-2025 Luc Maisonobe
  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.lang.reflect.Array;
  20. import java.util.Arrays;

  22. import org.hipparchus.CalculusFieldElement;
  23. import org.hipparchus.ode.events.Action;
  24. import org.orekit.propagation.FieldSpacecraftState;
  25. import org.orekit.propagation.events.handlers.FieldEventHandler;
  26. import org.orekit.time.FieldAbsoluteDate;

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

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

  66.     /** Wrapped event detector. */
  67.     private final FieldEventDetector<T> rawDetector;

  69.     /** Enabling predicate function. */
  70.     private final FieldEnablingPredicate<T> predicate;

  72.     /** Transformers of the g function. */
  73.     private final Transformer[] transformers;

  75.     /** Update time of the transformers. */
  76.     private final FieldAbsoluteDate<T>[] updates;

  78.     /** Event detection settings. */
  79.     private final FieldEventDetectionSettings<T> detectionSettings;

  81.     /** Specialized event handler. */
  82.     private final LocalHandler<T> handler;

  84.     /** Indicator for forward integration. */
  85.     private boolean forward;

  87.     /** Extreme time encountered so far. */
  88.     private FieldAbsoluteDate<T> extremeT;

  90.     /** Detector function value at extremeT. */
  91.     private T extremeG;

  93.     /** Wrap an {@link EventDetector event detector}.
  94.      * @param rawDetector event detector to wrap
  95.      * @param enabler event enabling predicate function to use
  96.      */
  97.     public FieldEventEnablingPredicateFilter(final FieldEventDetector<T> rawDetector,
  98.                                              final FieldEnablingPredicate<T> enabler) {
  99.         this(rawDetector.getDetectionSettings(), rawDetector, enabler);
  100.     }

  102.     /** Constructor with full parameters.
  103.      * @param detectionSettings event detection settings
  104.      * @param rawDetector event detector to wrap
  105.      * @param enabler event enabling function to use
  106.      * @since 13.0
  107.      */
  108.     @SuppressWarnings("unchecked")
  109.     public FieldEventEnablingPredicateFilter(final FieldEventDetectionSettings<T> detectionSettings,
  110.                                              final FieldEventDetector<T> rawDetector,
  111.                                              final FieldEnablingPredicate<T> enabler) {
  112.         this.detectionSettings = detectionSettings;
  113.         this.handler = new LocalHandler<>();
  114.         this.rawDetector  = rawDetector;
  115.         this.predicate = enabler;
  116.         this.transformers = new Transformer[HISTORY_SIZE];
  117.         this.updates      = (FieldAbsoluteDate<T>[]) Array.newInstance(FieldAbsoluteDate.class, HISTORY_SIZE);
  118.     }

  120.     /**
  121.      * Builds a new instance from the input detection settings.
  122.      * @param settings event detection settings to be used
  123.      * @return a new detector
  124.      */
  125.     public FieldEventEnablingPredicateFilter<T> withDetectionSettings(final FieldEventDetectionSettings<T> settings) {
  126.         return new FieldEventEnablingPredicateFilter<>(settings, rawDetector, predicate);
  127.     }

  129.     /**
  130.      * Get the wrapped raw detector.
  131.      * @return the wrapped raw detector
  132.      */
  133.     public FieldEventDetector<T> getDetector() {
  134.         return rawDetector;
  135.     }

  137.     /**  {@inheritDoc} */
  138.     @Override
  139.     public FieldEventHandler<T> getHandler() {
  140.         return handler;
  141.     }

  143.     /**  {@inheritDoc} */
  144.     @Override
  145.     public FieldEventDetectionSettings<T> getDetectionSettings() {
  146.         return detectionSettings;
  147.     }

  149.     /**
  150.      * Getter for the enabling predicate.
  151.      * @return predicate
  152.      * @since 13.1
  153.      */
  154.     public FieldEnablingPredicate<T> getPredicate() {
  155.         return predicate;
  156.     }

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

  164.     /**  {@inheritDoc} */
  165.     @Override
  166.     public void init(final FieldSpacecraftState<T> s0, final FieldAbsoluteDate<T> t) {
  167.         FieldDetectorModifier.super.init(s0, t);

  169.         // initialize events triggering logic
  170.         forward  = FieldAbstractDetector.checkIfForward(s0, t);
  171.         extremeT = forward ?
  172.                    FieldAbsoluteDate.getPastInfinity(t.getField()) :
  173.                    FieldAbsoluteDate.getFutureInfinity(t.getField());
  174.         extremeG = t.getField().getZero().newInstance(Double.NaN);
  175.         Arrays.fill(transformers, Transformer.UNINITIALIZED);
  176.         Arrays.fill(updates, extremeT);

  178.     }

  180.     @Override
  181.     public void reset(final FieldSpacecraftState<T> state, final FieldAbsoluteDate<T> target) {
  182.         FieldDetectorModifier.super.reset(state, target);
  183.         forward  = FieldAbstractDetector.checkIfForward(state, target);
  184.         extremeT = forward ?
  185.                 FieldAbsoluteDate.getPastInfinity(target.getField()) :
  186.                 FieldAbsoluteDate.getFutureInfinity(target.getField());
  187.         extremeG = target.getField().getZero().newInstance(Double.NaN);
  188.     }

  190.     /**  {@inheritDoc} */
  191.     @Override
  192.     public T g(final FieldSpacecraftState<T> s) {

  194.         final T       rawG      = rawDetector.g(s);
  195.         final boolean isEnabled = predicate.eventIsEnabled(s, rawDetector, rawG);
  196.         if (extremeG.isNaN()) {
  197.             extremeG = rawG;
  198.         }

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

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

  222.                 extremeT = s.getDate();
  223.                 extremeG = rawG;

  225.                 // apply the transform
  226.                 return next.transformed(rawG);

  228.             } else {
  229.                 // we are in the middle of the history

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

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

  241.             }
  242.         } else {
  243.             if (s.getDate().compareTo(extremeT) < 0) {
  244.                 // we are at the backward end of the history

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

  262.                 extremeT = s.getDate();
  263.                 extremeG = rawG;

  265.                 // apply the transform
  266.                 return next.transformed(rawG);

  268.             } else {
  269.                 // we are in the middle of the history

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

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

  281.             }
  282.         }

  284.     }

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

  323.     /** Check if the current propagation is forward or backward.
  324.      * @return true if the current propagation is forward
  325.      */
  326.     public boolean isForward() {
  327.         return forward;
  328.     }

  330.     /** Local handler.
  331.      * @param <T> type of the field elements
  332.      */
  333.     private static class LocalHandler<T extends CalculusFieldElement<T>> implements FieldEventHandler<T> {

  335.         /** {@inheritDoc} */
  336.         public Action eventOccurred(final FieldSpacecraftState<T> s, final FieldEventDetector<T> detector, final boolean increasing) {
  337.             final FieldEventEnablingPredicateFilter<T> ef = (FieldEventEnablingPredicateFilter<T>) detector;
  338.             final Transformer transformer = ef.forward ? ef.transformers[ef.transformers.length - 1] : ef.transformers[0];
  339.             return ef.rawDetector.getHandler().eventOccurred(s, ef.rawDetector, transformer == Transformer.PLUS ? increasing : !increasing);
  340.         }

  342.         /** {@inheritDoc} */
  343.         @Override
  344.         public FieldSpacecraftState<T> resetState(final FieldEventDetector<T> detector, final FieldSpacecraftState<T> oldState) {
  345.             final FieldEventEnablingPredicateFilter<T> ef = (FieldEventEnablingPredicateFilter<T>) detector;
  346.             return ef.rawDetector.getHandler().resetState(ef.rawDetector, oldState);
  347.         }

  349.     }

  351. }
Created with JaCoCo 0.8.12.202403310830