EventShifter.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 org.hipparchus.util.FastMath;
  19. import org.orekit.propagation.SpacecraftState;
  20. import org.orekit.propagation.events.handlers.EventHandler;
  21. import org.orekit.time.AbsoluteDate;

  22. /** Wrapper shifting events occurrences times.
  23.  * <p>This class wraps an {@link EventDetector event detector} to slightly
  24.  * shift the events occurrences times. A typical use case is for handling
  25.  * operational delays before or after some physical event really occurs.</p>
  26.  * <p>For example, the satellite attitude mode may be switched from sun pointed
  27.  * to spin-stabilized a few minutes before eclipse entry, and switched back
  28.  * to sun pointed a few minutes after eclipse exit. This behavior is handled
  29.  * by wrapping an {@link EclipseDetector eclipse detector} into an instance
  30.  * of this class with a positive times shift for increasing events (eclipse exit)
  31.  * and a negative times shift for decreasing events (eclipse entry).</p>
  32.  * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
  33.  * @see EventDetector
  34.  * @param <T> class type for the generic version
  35.  * @author Luc Maisonobe
  36.  */
  37. public class EventShifter<T extends EventDetector> extends AbstractDetector<EventShifter<T>> {

  38.     /** Serializable UID. */
  39.     private static final long serialVersionUID = 20131118L;

  40.     /** Event detector for the raw unshifted event. */
  41.     private final T detector;

  42.     /** Indicator for using shifted or unshifted states at event occurrence. */
  43.     private final boolean useShiftedStates;

  44.     /** Offset to apply to find increasing events. */
  45.     private final double increasingOffset;

  46.     /** Offset to apply to find decreasing events. */
  47.     private final double decreasingOffset;

  48.     /** Build a new instance.
  49.      * <p>The {@link #getMaxCheckInterval() max check interval}, the
  50.      * {@link #getThreshold() convergence threshold} of the raw unshifted
  51.      * events will be used for the shifted event. When an event occurs,
  52.      * the {@link #eventOccurred(SpacecraftState, boolean) eventOccurred}
  53.      * method of the raw unshifted events will be called (with spacecraft
  54.      * state at either the shifted or the unshifted event date depending
  55.      * on the <code>useShiftedStates</code> parameter).</p>
  56.      * @param detector event detector for the raw unshifted event
  57.      * @param useShiftedStates if true, the state provided to {@link
  58.      * #eventOccurred(SpacecraftState, boolean) eventOccurred} method of
  59.      * the <code>detector</code> will remain shifted, otherwise it will
  60.      * be <i>unshifted</i> to correspond to the underlying raw event.
  61.      * @param increasingTimeShift increasing events time shift.
  62.      * @param decreasingTimeShift decreasing events time shift.
  63.      */
  64.     public EventShifter(final T detector, final boolean useShiftedStates,
  65.                         final double increasingTimeShift, final double decreasingTimeShift) {
  66.         this(detector.getMaxCheckInterval(), detector.getThreshold(),
  67.              detector.getMaxIterationCount(), new LocalHandler<T>(),
  68.              detector, useShiftedStates, increasingTimeShift, decreasingTimeShift);
  69.     }

  70.     /** Private constructor with full parameters.
  71.      * <p>
  72.      * This constructor is private as users are expected to use the builder
  73.      * API with the various {@code withXxx()} methods to set up the instance
  74.      * in a readable manner without using a huge amount of parameters.
  75.      * </p>
  76.      * @param maxCheck maximum checking interval (s)
  77.      * @param threshold convergence threshold (s)
  78.      * @param maxIter maximum number of iterations in the event time search
  79.      * @param handler event handler to call at event occurrences
  80.      * @param detector event detector for the raw unshifted event
  81.      * @param useShiftedStates if true, the state provided to {@link
  82.      * #eventOccurred(SpacecraftState, boolean) eventOccurred} method of
  83.      * the <code>detector</code> will remain shifted, otherwise it will
  84.      * be <i>unshifted</i> to correspond to the underlying raw event.
  85.      * @param increasingTimeShift increasing events time shift.
  86.      * @param decreasingTimeShift decreasing events time shift.
  87.      * @since 6.1
  88.      */
  89.     private EventShifter(final double maxCheck, final double threshold,
  90.                          final int maxIter, final EventHandler<? super EventShifter<T>> handler,
  91.                          final T detector, final boolean useShiftedStates,
  92.                          final double increasingTimeShift, final double decreasingTimeShift) {
  93.         super(maxCheck, threshold, maxIter, handler);
  94.         this.detector         = detector;
  95.         this.useShiftedStates = useShiftedStates;
  96.         this.increasingOffset = -increasingTimeShift;
  97.         this.decreasingOffset = -decreasingTimeShift;
  98.     }

  99.     /** {@inheritDoc} */
  100.     @Override
  101.     protected EventShifter<T> create(final double newMaxCheck, final double newThreshold,
  102.                                      final int newMaxIter, final EventHandler<? super EventShifter<T>> newHandler) {
  103.         return new EventShifter<T>(newMaxCheck, newThreshold, newMaxIter, newHandler,
  104.                                    detector, useShiftedStates, -increasingOffset, -decreasingOffset);
  105.     }

  106.     /** Get the increasing events time shift.
  107.      * @return increasing events time shift
  108.      */
  109.     public double getIncreasingTimeShift() {
  110.         return -increasingOffset;
  111.     }

  112.     /** Get the decreasing events time shift.
  113.      * @return decreasing events time shift
  114.      */
  115.     public double getDecreasingTimeShift() {
  116.         return -decreasingOffset;
  117.     }

  118.     /** {@inheritDoc} */
  119.     public void init(final SpacecraftState s0,
  120.                      final AbsoluteDate t) {
  121.         super.init(s0, t);
  122.         detector.init(s0, t);
  123.     }

  124.     /** {@inheritDoc} */
  125.     public double g(final SpacecraftState s) {
  126.         final double incShiftedG = detector.g(s.shiftedBy(increasingOffset));
  127.         final double decShiftedG = detector.g(s.shiftedBy(decreasingOffset));
  128.         return (increasingOffset >= decreasingOffset) ?
  129.                FastMath.max(incShiftedG, decShiftedG) : FastMath.min(incShiftedG, decShiftedG);
  130.     }

  131.     /** Local class for handling events. */
  132.     private static class LocalHandler<T extends EventDetector> implements EventHandler<EventShifter<T>> {

  133.         /** Shifted state at even occurrence. */
  134.         private SpacecraftState shiftedState;

  135.         /** {@inheritDoc} */
  136.         public Action eventOccurred(final SpacecraftState s, final EventShifter<T> shifter, final boolean increasing) {

  137.             if (shifter.useShiftedStates) {
  138.                 // the state provided by the caller already includes the time shift
  139.                 shiftedState = s;
  140.             } else {
  141.                 // we need to "unshift" the state
  142.                 final double offset = increasing ? shifter.increasingOffset : shifter.decreasingOffset;
  143.                 shiftedState = s.shiftedBy(offset);
  144.             }

  145.             return shifter.detector.eventOccurred(shiftedState, increasing);

  146.         }

  147.         /** {@inheritDoc} */
  148.         @Override
  149.         public SpacecraftState resetState(final EventShifter<T> shifter, final SpacecraftState oldState) {
  150.             return shifter.detector.resetState(shiftedState);
  151.         }

  152.     }

  153. }