EventFilter.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF 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.  */

  18. package org.orekit.propagation.events;

  20. import java.util.Arrays;

  22. import org.orekit.errors.OrekitException;
  23. import org.orekit.propagation.SpacecraftState;
  24. import org.orekit.propagation.events.handlers.EventHandler;
  25. import org.orekit.time.AbsoluteDate;

  27. /** Wrapper used to detect only increasing or decreasing events.
  28.  *
  29.  * <p>This class is heavily based on the class with the same name from the
  30.  * Apache Commons Math library. The changes performed consist in replacing
  31.  * raw types (double and double arrays) with space dynamics types
  32.  * ({@link AbsoluteDate}, {@link SpacecraftState}).</p>
  33.  *
  34.  * <p>General {@link EventDetector events} are defined implicitely
  35.  * by a {@link EventDetector#g(SpacecraftState) g function} crossing
  36.  * zero. This function needs to be continuous in the event neighborhood,
  37.  * and its sign must remain consistent between events. This implies that
  38.  * during an ODE integration, events triggered are alternately events
  39.  * for which the function increases from negative to positive values,
  40.  * and events for which the function decreases from positive to
  41.  * negative values.
  42.  * </p>
  43.  *
  44.  * <p>Sometimes, users are only interested in one type of event (say
  45.  * increasing events for example) and not in the other type. In these
  46.  * cases, looking precisely for all events location and triggering
  47.  * events that will later be ignored is a waste of computing time.</p>
  48.  *
  49.  * <p>Users can wrap a regular {@link EventDetector event detector} in
  50.  * an instance of this class and provide this wrapping instance to
  51.  * a {@link org.orekit.propagation.Propagator}
  52.  * in order to avoid wasting time looking for uninteresting events.
  53.  * The wrapper will intercept the calls to the {@link
  54.  * EventDetector#g(SpacecraftState) g function} and to the {@link
  55.  * EventDetector#eventOccurred(SpacecraftState, boolean)
  56.  * eventOccurred} method in order to ignore uninteresting events. The
  57.  * wrapped regular {@link EventDetector event detector} will the see only
  58.  * the interesting events, i.e. either only {@code increasing} events or
  59.  * {@code decreasing} events. the number of calls to the {@link
  60.  * EventDetector#g(SpacecraftState) g function} will also be reduced.</p>
  61.  *
  62.  */

  64. public class EventFilter<T extends EventDetector> extends AbstractReconfigurableDetector<EventFilter<T>> {

  66.     /** Serializable UID. */
  67.     private static final long serialVersionUID = 20130409L;

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

  72.     /** Wrapped event detector. */
  73.     private final T rawDetector;

  75.     /** Filter to use. */
  76.     private final FilterType filter;

  78.     /** Transformers of the g function. */
  79.     private final Transformer[] transformers;

  81.     /** Update time of the transformers. */
  82.     private final AbsoluteDate[] updates;

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

  87.     /** Extreme time encountered so far. */
  88.     private AbsoluteDate extremeT;

  90.     /** Wrap an {@link EventDetector event detector}.
  91.      * @param rawDetector event detector to wrap
  92.      * @param filter filter to use
  93.      */
  94.     public EventFilter(final T rawDetector, final FilterType filter) {
  95.         this(rawDetector.getMaxCheckInterval(), rawDetector.getThreshold(),
  96.              rawDetector.getMaxIterationCount(), new LocalHandler<T>(),
  97.              rawDetector, filter);
  98.     }

  100.     /** Private constructor with full parameters.
  101.      * <p>
  102.      * This constructor is private as users are expected to use the builder
  103.      * API with the various {@code withXxx()} methods to set up the instance
  104.      * in a readable manner without using a huge amount of parameters.
  105.      * </p>
  106.      * @param maxCheck maximum checking interval (s)
  107.      * @param threshold convergence threshold (s)
  108.      * @param maxIter maximum number of iterations in the event time search
  109.      * @param handler event handler to call at event occurrences
  110.      * @param rawDetector event detector to wrap
  111.      * @param filter filter to use
  112.      * @since 6.1
  113.      */
  114.     private EventFilter(final double maxCheck, final double threshold,
  115.                         final int maxIter, final EventHandler<EventFilter<T>> handler,
  116.                         final T rawDetector, final FilterType filter) {
  117.         super(maxCheck, threshold, maxIter, handler);
  118.         this.rawDetector  = rawDetector;
  119.         this.filter       = filter;
  120.         this.transformers = new Transformer[HISTORY_SIZE];
  121.         this.updates      = new AbsoluteDate[HISTORY_SIZE];
  122.     }

  124.     /** {@inheritDoc} */
  125.     @Override
  126.     protected EventFilter<T> create(final double newMaxCheck, final double newThreshold,
  127.                                  final int newMaxIter, final EventHandler<EventFilter<T>> newHandler) {
  128.         return new EventFilter<T>(newMaxCheck, newThreshold, newMaxIter, newHandler, rawDetector, filter);
  129.     }

  131.     /**  {@inheritDoc} */
  132.     public void init(final SpacecraftState s0, final AbsoluteDate t) {

  134.         // delegate to raw detector
  135.         rawDetector.init(s0, t);

  137.         // initialize events triggering logic
  138.         forward  = t.compareTo(s0.getDate()) >= 0;
  139.         extremeT = forward ? AbsoluteDate.PAST_INFINITY : AbsoluteDate.FUTURE_INFINITY;
  140.         Arrays.fill(transformers, Transformer.UNINITIALIZED);
  141.         Arrays.fill(updates, extremeT);

  143.     }

  145.     /**  {@inheritDoc} */
  146.     public double g(final SpacecraftState s) throws OrekitException {

  148.         final double rawG = rawDetector.g(s);

  150.         // search which transformer should be applied to g
  151.         if (forward) {
  152.             final int last = transformers.length - 1;
  153.             if (extremeT.compareTo(s.getDate()) < 0) {
  154.                 // we are at the forward end of the history

  156.                 // check if a new rough root has been crossed
  157.                 final Transformer previous = transformers[last];
  158.                 final Transformer next     = filter.selectTransformer(previous, rawG, forward);
  159.                 if (next != previous) {
  160.                     // there is a root somewhere between extremeT end t
  161.                     // the new transformer, which is valid on both sides of the root,
  162.                     // so it is valid for t (this is how we have just computed it above),
  163.                     // but it was already valid before, so we store the switch at extremeT
  164.                     // for safety, to ensure the previous transformer is not applied too
  165.                     // close of the root
  166.                     System.arraycopy(updates,      1, updates,      0, last);
  167.                     System.arraycopy(transformers, 1, transformers, 0, last);
  168.                     updates[last]      = extremeT;
  169.                     transformers[last] = next;
  170.                 }

  172.                 extremeT = s.getDate();

  174.                 // apply the transform
  175.                 return next.transformed(rawG);

  177.             } else {
  178.                 // we are in the middle of the history

  180.                 // select the transformer
  181.                 for (int i = last; i > 0; --i) {
  182.                     if (updates[i].compareTo(s.getDate()) <= 0) {
  183.                         // apply the transform
  184.                         return transformers[i].transformed(rawG);
  185.                     }
  186.                 }

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

  190.             }
  191.         } else {
  192.             if (s.getDate().compareTo(extremeT) < 0) {
  193.                 // we are at the backward end of the history

  195.                 // check if a new rough root has been crossed
  196.                 final Transformer previous = transformers[0];
  197.                 final Transformer next     = filter.selectTransformer(previous, rawG, forward);
  198.                 if (next != previous) {
  199.                     // there is a root somewhere between extremeT end t
  200.                     // the new transformer, which is valid on both sides of the root,
  201.                     // so it is valid for t (this is how we have just computed it above),
  202.                     // but it was already valid before, so we store the switch at extremeT
  203.                     // for safety, to ensure the previous transformer is not applied too
  204.                     // close of the root
  205.                     System.arraycopy(updates,      0, updates,      1, updates.length - 1);
  206.                     System.arraycopy(transformers, 0, transformers, 1, transformers.length - 1);
  207.                     updates[0]      = extremeT;
  208.                     transformers[0] = next;
  209.                 }

  211.                 extremeT = s.getDate();

  213.                 // apply the transform
  214.                 return next.transformed(rawG);

  216.             } else {
  217.                 // we are in the middle of the history

  219.                 // select the transformer
  220.                 for (int i = 0; i < updates.length - 1; ++i) {
  221.                     if (s.getDate().compareTo(updates[i]) <= 0) {
  222.                         // apply the transform
  223.                         return transformers[i].transformed(rawG);
  224.                     }
  225.                 }

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

  229.             }
  230.         }

  232.     }

  234.     /** Local handler. */
  235.     private static class LocalHandler<T extends EventDetector> implements EventHandler<EventFilter<T>> {

  237.         /** {@inheritDoc} */
  238.         public Action eventOccurred(final SpacecraftState s, final EventFilter<T> ef, final boolean increasing)
  239.             throws OrekitException {
  240.             if (ef.rawDetector instanceof AbstractReconfigurableDetector) {
  241.                 @SuppressWarnings("unchecked")
  242.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) ef.rawDetector).getHandler();
  243.                 return handler.eventOccurred(s, ef.rawDetector, ef.filter.getTriggeredIncreasing());
  244.             } else {
  245.                 @SuppressWarnings("deprecation")
  246.                 final EventDetector.Action a = ef.rawDetector.eventOccurred(s, ef.filter.getTriggeredIncreasing());
  247.                 return AbstractReconfigurableDetector.convert(a);
  248.             }
  249.         }

  251.         /** {@inheritDoc} */
  252.         @Override
  253.         public SpacecraftState resetState(final EventFilter<T> ef, final SpacecraftState oldState)
  254.             throws OrekitException {
  255.             if (ef.rawDetector instanceof AbstractReconfigurableDetector) {
  256.                 @SuppressWarnings("unchecked")
  257.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) ef.rawDetector).getHandler();
  258.                 return handler.resetState(ef.rawDetector, oldState);
  259.             } else {
  260.                 @SuppressWarnings("deprecation")
  261.                 final SpacecraftState newState = ef.rawDetector.resetState(oldState);
  262.                 return newState;
  263.             }
  264.         }

  266.     }

  268. }
Created with JaCoCo 0.6.3.201306030806