BooleanDetector.java

  1. /* Contributed in the public domain.
  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;


  20. import java.util.ArrayList;
  21. import java.util.Arrays;
  22. import java.util.Collection;
  23. import java.util.List;
  24. import java.util.NoSuchElementException;

  26. import org.hipparchus.util.FastMath;
  27. import org.orekit.errors.OrekitException;
  28. import org.orekit.propagation.SpacecraftState;
  29. import org.orekit.propagation.events.handlers.ContinueOnEvent;
  30. import org.orekit.propagation.events.handlers.EventHandler;
  31. import org.orekit.time.AbsoluteDate;

  33. /**
  34.  * This class provides AND and OR operations for event detectors. This class treats
  35.  * positive values of the g function as true and negative values as false.
  36.  *
  37.  * <p> One example for an imaging satellite might be to only detect events when a
  38.  * satellite is overhead (elevation &gt; 0) AND when the ground point is sunlit (Sun
  39.  * elevation &gt; 0). Another slightly contrived example using the OR operator would be to
  40.  * detect access to a set of ground stations and only report events when the satellite
  41.  * enters or leaves the field of view of the set, but not hand-offs between the ground
  42.  * stations.
  43.  *
  44.  * <p> For the BooleanDetector is important that the sign of the g function of the
  45.  * underlying event detector is not arbitrary, but has a semantic meaning, e.g. in or out,
  46.  * true or false. This class works well with event detectors that detect entry to or exit
  47.  * from a region, e.g. {@link EclipseDetector}, {@link ElevationDetector}, {@link
  48.  * LatitudeCrossingDetector}. Using this detector with detectors that are not based on
  49.  * entry to or exit from a region, e.g. {@link DateDetector}, {@link
  50.  * LongitudeCrossingDetector}, will likely lead to unexpected results. To apply conditions
  51.  * to this latter type of event detectors a {@link EventEnablingPredicateFilter} is
  52.  * usually more appropriate.
  53.  *
  54.  * @author Evan Ward
  55.  * @see #andCombine(Collection)
  56.  * @see #orCombine(Collection)
  57.  * @see #notCombine(EventDetector)
  58.  * @see EventEnablingPredicateFilter
  59.  * @see EventSlopeFilter
  60.  */
  61. public class BooleanDetector extends AbstractDetector<BooleanDetector> {

  63.     /** Serializable UID. */
  64.     private static final long serialVersionUID = 20170410L;

  66.     /** Original detectors: the operands. */
  67.     private final List<EventDetector> detectors;

  69.     /** The composition function. Should be associative for predictable behavior. */
  70.     private final Operator operator;

  72.     /**
  73.      * Private constructor with all the parameters.
  74.      *
  75.      * @param detectors    the operands.
  76.      * @param operator     reduction operator to apply to value of the g function of the
  77.      *                     operands.
  78.      * @param newMaxCheck  max check interval in seconds.
  79.      * @param newThreshold convergence threshold in seconds.
  80.      * @param newMaxIter   max iterations.
  81.      * @param newHandler   event handler.
  82.      */
  83.     private BooleanDetector(final List<EventDetector> detectors,
  84.                             final Operator operator,
  85.                             final double newMaxCheck,
  86.                             final double newThreshold,
  87.                             final int newMaxIter,
  88.                             final EventHandler<? super BooleanDetector> newHandler) {
  89.         super(newMaxCheck, newThreshold, newMaxIter, newHandler);
  90.         this.detectors = detectors;
  91.         this.operator = operator;
  92.     }

  94.     /**
  95.      * Create a new event detector that is the logical AND of the given event detectors.
  96.      *
  97.      * <p> The created event detector's g function is positive if and only if the g
  98.      * functions of all detectors in {@code detectors} are positive.
  99.      *
  100.      * <p> The starting interval, threshold, and iteration count are set to the most
  101.      * stringent (minimum) of all the {@code detectors}. The event handlers of the
  102.      * underlying {@code detectors} are not used, instead the default handler is {@link
  103.      * ContinueOnEvent}.
  104.      *
  105.      * @param detectors the operands. Must contain at least one detector.
  106.      * @return a new event detector that is the logical AND of the operands.
  107.      * @throws NoSuchElementException if {@code detectors} is empty.
  108.      * @see BooleanDetector
  109.      * @see #andCombine(Collection)
  110.      * @see #orCombine(EventDetector...)
  111.      * @see #notCombine(EventDetector)
  112.      */
  113.     public static BooleanDetector andCombine(final EventDetector... detectors) {
  114.         return andCombine(Arrays.asList(detectors));
  115.     }

  117.     /**
  118.      * Create a new event detector that is the logical AND of the given event detectors.
  119.      *
  120.      * <p> The created event detector's g function is positive if and only if the g
  121.      * functions of all detectors in {@code detectors} are positive.
  122.      *
  123.      * <p> The starting interval, threshold, and iteration count are set to the most
  124.      * stringent (minimum) of the {@code detectors}. The event handlers of the
  125.      * underlying {@code detectors} are not used, instead the default handler is {@link
  126.      * ContinueOnEvent}.
  127.      *
  128.      * @param detectors the operands. Must contain at least one detector.
  129.      * @return a new event detector that is the logical AND of the operands.
  130.      * @throws NoSuchElementException if {@code detectors} is empty.
  131.      * @see BooleanDetector
  132.      * @see #andCombine(EventDetector...)
  133.      * @see #orCombine(Collection)
  134.      * @see #notCombine(EventDetector)
  135.      */
  136.     public static BooleanDetector andCombine(final Collection<? extends EventDetector> detectors) {

  138.         return new BooleanDetector(new ArrayList<>(detectors), // copy for immutability
  139.                 Operator.AND,
  140.                 detectors.stream().map(EventDetector::getMaxCheckInterval).min(Double::compareTo).get(),
  141.                 detectors.stream().map(EventDetector::getThreshold).min(Double::compareTo).get(),
  142.                 detectors.stream().map(EventDetector::getMaxIterationCount).min(Integer::compareTo).get(),
  143.                 new ContinueOnEvent<>());
  144.     }

  146.     /**
  147.      * Create a new event detector that is the logical OR or the given event detectors.
  148.      *
  149.      * <p> The created event detector's g function is positive if and only if at least
  150.      * one of g functions of the event detectors in {@code detectors} is positive.
  151.      *
  152.      * <p> The starting interval, threshold, and iteration count are set to the most
  153.      * stringent (minimum) of the {@code detectors}. The event handlers of the
  154.      * underlying EventDetectors are not used, instead the default handler is {@link
  155.      * ContinueOnEvent}.
  156.      *
  157.      * @param detectors the operands. Must contain at least one detector.
  158.      * @return a new event detector that is the logical OR of the operands.
  159.      * @throws NoSuchElementException if {@code detectors} is empty.
  160.      * @see BooleanDetector
  161.      * @see #orCombine(Collection)
  162.      * @see #andCombine(EventDetector...)
  163.      * @see #notCombine(EventDetector)
  164.      */
  165.     public static BooleanDetector orCombine(final EventDetector... detectors) {
  166.         return orCombine(Arrays.asList(detectors));
  167.     }

  169.     /**
  170.      * Create a new event detector that is the logical OR or the given event detectors.
  171.      *
  172.      * <p> The created event detector's g function is positive if and only if at least
  173.      * one of g functions of the event detectors in {@code detectors} is positive.
  174.      *
  175.      * <p> The starting interval, threshold, and iteration count are set to the most
  176.      * stringent (minimum) of the {@code detectors}. The event handlers of the
  177.      * underlying EventDetectors are not used, instead the default handler is {@link
  178.      * ContinueOnEvent}.
  179.      *
  180.      * @param detectors the operands. Must contain at least one detector.
  181.      * @return a new event detector that is the logical OR of the operands.
  182.      * @throws NoSuchElementException if {@code detectors} is empty.
  183.      * @see BooleanDetector
  184.      * @see #orCombine(EventDetector...)
  185.      * @see #andCombine(Collection)
  186.      * @see #notCombine(EventDetector)
  187.      */
  188.     public static BooleanDetector orCombine(final Collection<? extends EventDetector> detectors) {

  190.         return new BooleanDetector(new ArrayList<>(detectors), // copy for immutability
  191.                 Operator.OR,
  192.                 detectors.stream().map(EventDetector::getMaxCheckInterval).min(Double::compareTo).get(),
  193.                 detectors.stream().map(EventDetector::getThreshold).min(Double::compareTo).get(),
  194.                 detectors.stream().map(EventDetector::getMaxIterationCount).min(Integer::compareTo).get(),
  195.                 new ContinueOnEvent<>());
  196.     }

  198.     /**
  199.      * Create a new event detector that negates the g function of another detector.
  200.      *
  201.      * <p> This detector will be initialized with the same {@link
  202.      * EventDetector#getMaxCheckInterval()}, {@link EventDetector#getThreshold()}, and
  203.      * {@link EventDetector#getMaxIterationCount()} as {@code detector}. The event handler
  204.      * of the underlying detector is not used, instead the default handler is {@link
  205.      * ContinueOnEvent}.
  206.      *
  207.      * @param detector to negate.
  208.      * @return an new event detector whose g function is the same magnitude but opposite
  209.      * sign of {@code detector}.
  210.      * @see #andCombine(Collection)
  211.      * @see #orCombine(Collection)
  212.      * @see BooleanDetector
  213.      */
  214.     public static NegateDetector notCombine(final EventDetector detector) {
  215.         return new NegateDetector(detector);
  216.     }

  218.     @Override
  219.     public double g(final SpacecraftState s) throws OrekitException {
  220.         // can't use stream/lambda here because g(s) throws a checked exception
  221.         // so write out and combine the map and reduce loops
  222.         double ret = Double.NaN; // return value
  223.         boolean first = true;
  224.         for (final EventDetector detector : detectors) {
  225.             if (first) {
  226.                 ret = detector.g(s);
  227.                 first = false;
  228.             } else {
  229.                 ret = operator.combine(ret, detector.g(s));
  230.             }
  231.         }
  232.         // return the result of applying the operator to all operands
  233.         return ret;
  234.     }

  236.     @Override
  237.     protected BooleanDetector create(final double newMaxCheck,
  238.                                      final double newThreshold,
  239.                                      final int newMaxIter,
  240.                                      final EventHandler<? super BooleanDetector> newHandler) {
  241.         return new BooleanDetector(detectors, operator, newMaxCheck, newThreshold,
  242.                 newMaxIter, newHandler);
  243.     }

  245.     @Override
  246.     public void init(final SpacecraftState s0,
  247.                      final AbsoluteDate t) throws OrekitException {
  248.         super.init(s0, t);
  249.         for (final EventDetector detector : detectors) {
  250.             detector.init(s0, t);
  251.         }
  252.     }

  254.     /** Local, serializable class for operator. */
  255.     private enum Operator {

  257.         /** And operator. */
  258.         AND() {

  260.             @Override
  261.             /** {@inheritDoc} */
  262.             public double combine(final double g1, final double g2) {
  263.                 return FastMath.min(g1, g2);
  264.             }

  266.         },

  268.         /** Or operator. */
  269.         OR() {

  271.             @Override
  272.             /** {@inheritDoc} */
  273.             public double combine(final double g1, final double g2) {
  274.                 return FastMath.max(g1, g2);
  275.             }

  277.         };

  279.         /** Combine two g functions evaluations.
  280.          * @param g1 first evaluation
  281.          * @param g2 second evaluation
  282.          * @return combined evaluation
  283.          */
  284.         public abstract double combine(double g1, double g2);

  286.     };

  288. }
Created with JaCoCo 0.7.9.201702052155