EventState.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.  */
  17. package org.orekit.propagation.events;

  19. import java.io.Serializable;

  21. import org.apache.commons.math3.analysis.UnivariateFunction;
  22. import org.apache.commons.math3.analysis.solvers.AllowedSolution;
  23. import org.apache.commons.math3.analysis.solvers.BracketingNthOrderBrentSolver;
  24. import org.apache.commons.math3.exception.NoBracketingException;
  25. import org.apache.commons.math3.exception.TooManyEvaluationsException;
  26. import org.apache.commons.math3.util.FastMath;
  27. import org.orekit.errors.OrekitException;
  28. import org.orekit.propagation.SpacecraftState;
  29. import org.orekit.propagation.events.handlers.EventHandler;
  30. import org.orekit.propagation.sampling.OrekitStepInterpolator;
  31. import org.orekit.time.AbsoluteDate;

  33. /** This class handles the state for one {@link EventDetector
  34.  * event detector} during integration steps.
  35.  *
  36.  * <p>This class is heavily based on the class with the same name from the
  37.  * Apache Commons Math library. The changes performed consist in replacing
  38.  * raw types (double and double arrays) with space dynamics types
  39.  * ({@link AbsoluteDate}, {@link SpacecraftState}).</p>
  40.  * <p>Each time the propagator proposes a step, the event detector
  41.  * should be checked. This class handles the state of one detector
  42.  * during one propagation step, with references to the state at the
  43.  * end of the preceding step. This information is used to determine if
  44.  * the detector should trigger an event or not during the proposed
  45.  * step (and hence the step should be reduced to ensure the event
  46.  * occurs at a bound rather than inside the step).</p>
  47.  * @author Luc Maisonobe
  48.  * @param <T> class type for the generic version
  49.  */
  50. public class EventState<T extends EventDetector> implements Serializable {

  52.     /** Serializable version identifier. */
  53.     private static final long serialVersionUID = 4489391420715269318L;

  55.     /** Event detector. */
  56.     private T detector;

  58.     /** Time of the previous call to g. */
  59.     private AbsoluteDate lastT;

  61.     /** Value from the previous call to g. */
  62.     private double lastG;

  64.     /** Time at the beginning of the step. */
  65.     private AbsoluteDate t0;

  67.     /** Value of the event detector at the beginning of the step. */
  68.     private double g0;

  70.     /** Simulated sign of g0 (we cheat when crossing events). */
  71.     private boolean g0Positive;

  73.     /** Indicator of event expected during the step. */
  74.     private boolean pendingEvent;

  76.     /** Occurrence time of the pending event. */
  77.     private AbsoluteDate pendingEventTime;

  79.     /** Occurrence time of the previous event. */
  80.     private AbsoluteDate previousEventTime;

  82.     /** Integration direction. */
  83.     private boolean forward;

  85.     /** Variation direction around pending event.
  86.      *  (this is considered with respect to the integration direction)
  87.      */
  88.     private boolean increasing;

  90.     /** Next action indicator. */
  91.     private EventHandler.Action nextAction;

  93.     /** Simple constructor.
  94.      * @param detector monitored event detector
  95.      */
  96.     public EventState(final T detector) {
  97.         this.detector     = detector;

  99.         // some dummy values ...
  100.         t0                = null;
  101.         g0                = Double.NaN;
  102.         g0Positive        = true;
  103.         pendingEvent      = false;
  104.         pendingEventTime  = null;
  105.         previousEventTime = null;
  106.         increasing        = true;
  107.         nextAction        = EventHandler.Action.CONTINUE;

  109.     }

  111.     /** Get the underlying event detector.
  112.      * @return underlying event detector
  113.      */
  114.     public T getEventDetector() {
  115.         return detector;
  116.     }

  118.     /** Initialize event handler at the start of a propagation.
  119.      * <p>
  120.      * This method is called once at the start of the propagation. It
  121.      * may be used by the event handler to initialize some internal data
  122.      * if needed.
  123.      * </p>
  124.      * @param s0 initial state
  125.      * @param t target time for the integration
  126.      */
  127.     public void init(final SpacecraftState s0, final AbsoluteDate t) {
  128.         detector.init(s0, t);
  129.         lastT = AbsoluteDate.PAST_INFINITY;
  130.         lastG = Double.NaN;
  131.     }

  133.     /** Compute the value of the switching function.
  134.      * This function must be continuous (at least in its roots neighborhood),
  135.      * as the integrator will need to find its roots to locate the events.
  136.      * @param s the current state information: date, kinematics, attitude
  137.      * @return value of the switching function
  138.      * @exception OrekitException if some specific error occurs
  139.      */
  140.     private double g(final SpacecraftState s) throws OrekitException {
  141.         if (!s.getDate().equals(lastT)) {
  142.             lastT = s.getDate();
  143.             lastG = detector.g(s);
  144.         }
  145.         return lastG;
  146.     }

  148.     /** Reinitialize the beginning of the step.
  149.      * @param state0 state value at the beginning of the step
  150.      * @param isForward if true, step will be forward
  151.      * @exception OrekitException if the event detector
  152.      * value cannot be evaluated at the beginning of the step
  153.      */
  154.     public void reinitializeBegin(final SpacecraftState state0, final boolean isForward)
  155.         throws OrekitException {
  156.         this.t0 = state0.getDate();
  157.         g0 = g(state0);
  158.         if (g0 == 0) {
  159.             // extremely rare case: there is a zero EXACTLY at interval start
  160.             // we will use the sign slightly after step beginning to force ignoring this zero
  161.             g0 = g(state0.shiftedBy((isForward ? 0.5 : -0.5) * detector.getThreshold()));
  162.         }
  163.         g0Positive = g0 >= 0;
  164.     }

  166.     /** Evaluate the impact of the proposed step on the event detector.
  167.      * @param interpolator step interpolator for the proposed step
  168.      * @return true if the event detector triggers an event before
  169.      * the end of the proposed step (this implies the step should be
  170.      * rejected)
  171.      * @exception OrekitException if the switching function
  172.      * cannot be evaluated
  173.      * @exception TooManyEvaluationsException if an event cannot be located
  174.      * @exception NoBracketingException if bracketing cannot be performed
  175.      */
  176.     public boolean evaluateStep(final OrekitStepInterpolator interpolator)
  177.         throws OrekitException, TooManyEvaluationsException, NoBracketingException {

  179.         try {

  181.             final double convergence    = detector.getThreshold();
  182.             final int maxIterationcount = detector.getMaxIterationCount();
  183.             if (forward ^ interpolator.isForward()) {
  184.                 forward = !forward;
  185.                 pendingEvent      = false;
  186.                 pendingEventTime  = null;
  187.                 previousEventTime = null;
  188.             }
  189.             final AbsoluteDate t1 = interpolator.getCurrentDate();
  190.             final double dt = t1.durationFrom(t0);
  191.             if (FastMath.abs(dt) < convergence) {
  192.                 // we cannot do anything on such a small step, don't trigger any events
  193.                 return false;
  194.             }
  195.             final int    n = FastMath.max(1, (int) FastMath.ceil(FastMath.abs(dt) / detector.getMaxCheckInterval()));
  196.             final double h = dt / n;

  198.             final UnivariateFunction f = new UnivariateFunction() {
  199.                 public double value(final double t) throws LocalWrapperException {
  200.                     try {
  201.                         interpolator.setInterpolatedDate(t0.shiftedBy(t));
  202.                         return g(interpolator.getInterpolatedState());
  203.                     } catch (OrekitException oe) {
  204.                         throw new LocalWrapperException(oe);
  205.                     }
  206.                 }
  207.             };

  209.             final BracketingNthOrderBrentSolver solver =
  210.                     new BracketingNthOrderBrentSolver(convergence, 5);

  212.             AbsoluteDate ta = t0;
  213.             double ga = g0;
  214.             for (int i = 0; i < n; ++i) {

  216.                 // evaluate detector value at the end of the substep
  217.                 final AbsoluteDate tb = t0.shiftedBy((i + 1) * h);
  218.                 interpolator.setInterpolatedDate(tb);
  219.                 final double gb = g(interpolator.getInterpolatedState());

  221.                 // check events occurrence
  222.                 if (g0Positive ^ (gb >= 0)) {
  223.                     // there is a sign change: an event is expected during this step

  225.                     // variation direction, with respect to the integration direction
  226.                     increasing = gb >= ga;

  228.                     // find the event time making sure we select a solution just at or past the exact root
  229.                     final double dtA = ta.durationFrom(t0);
  230.                     final double dtB = tb.durationFrom(t0);
  231.                     final double dtRoot = forward ?
  232.                                           solver.solve(maxIterationcount, f, dtA, dtB, AllowedSolution.RIGHT_SIDE) :
  233.                                           solver.solve(maxIterationcount, f, dtB, dtA, AllowedSolution.LEFT_SIDE);
  234.                     final AbsoluteDate root = t0.shiftedBy(dtRoot);

  236.                     if ((previousEventTime != null) &&
  237.                         (FastMath.abs(root.durationFrom(ta)) <= convergence) &&
  238.                         (FastMath.abs(root.durationFrom(previousEventTime)) <= convergence)) {
  239.                         // we have either found nothing or found (again ?) a past event,
  240.                         // retry the substep excluding this value
  241.                         ta = forward ? ta.shiftedBy(convergence) : ta.shiftedBy(-convergence);
  242.                         ga = f.value(ta.durationFrom(t0));
  243.                         --i;
  244.                     } else if ((previousEventTime == null) ||
  245.                                (FastMath.abs(previousEventTime.durationFrom(root)) > convergence)) {
  246.                         pendingEventTime = root;
  247.                         pendingEvent = true;
  248.                         return true;
  249.                     } else {
  250.                         // no sign change: there is no event for now
  251.                         ta = tb;
  252.                         ga = gb;
  253.                     }

  255.                 } else {
  256.                     // no sign change: there is no event for now
  257.                     ta = tb;
  258.                     ga = gb;
  259.                 }

  261.             }

  263.             // no event during the whole step
  264.             pendingEvent     = false;
  265.             pendingEventTime = null;
  266.             return false;

  268.         } catch (LocalWrapperException lwe) {
  269.             throw lwe.getWrappedException();
  270.         }

  272.     }

  274.     /** Get the occurrence time of the event triggered in the current
  275.      * step.
  276.      * @return occurrence time of the event triggered in the current
  277.      * step.
  278.      */
  279.     public AbsoluteDate getEventTime() {
  280.         return pendingEventTime;
  281.     }

  283.     /** Acknowledge the fact the step has been accepted by the propagator.
  284.      * @param state value of the state vector at the end of the step
  285.      * @exception OrekitException if the value of the switching
  286.      * function cannot be evaluated
  287.      */
  288.     public void stepAccepted(final SpacecraftState state)
  289.         throws OrekitException {

  291.         t0 = state.getDate();
  292.         g0 = g(state);

  294.         if (pendingEvent) {
  295.             // force the sign to its value "just after the event"
  296.             previousEventTime = state.getDate();
  297.             g0Positive        = increasing;
  298.             if (detector instanceof AbstractReconfigurableDetector) {
  299.                 @SuppressWarnings("unchecked")
  300.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) detector).getHandler();
  301.                 nextAction = handler.eventOccurred(state, detector, !(increasing ^ forward));
  302.             } else {
  303.                 @SuppressWarnings("deprecation")
  304.                 final EventHandler.Action a =
  305.                     AbstractReconfigurableDetector.convert(detector.eventOccurred(state, !(increasing ^ forward)));
  306.                 nextAction = a;
  307.             }
  308.         } else {
  309.             g0Positive = g0 >= 0;
  310.             nextAction = EventHandler.Action.CONTINUE;
  311.         }
  312.     }

  314.     /** Check if the propagation should be stopped at the end of the
  315.      * current step.
  316.      * @return true if the propagation should be stopped
  317.      */
  318.     public boolean stop() {
  319.         return nextAction == EventHandler.Action.STOP;
  320.     }

  322.     /** Let the event detector reset the state if it wants.
  323.      * @param oldState value of the state vector at the beginning of the next step
  324.      * @return new state (null if no reset is needed)
  325.      * @exception OrekitException if the state cannot be reset by the event
  326.      * detector
  327.      */
  328.     public SpacecraftState reset(final SpacecraftState oldState)
  329.         throws OrekitException {

  331.         if (!pendingEvent) {
  332.             return null;
  333.         }

  335.         final SpacecraftState newState;
  336.         if (nextAction != EventHandler.Action.RESET_STATE) {
  337.             newState = null;
  338.         } else {
  339.             if (detector instanceof AbstractReconfigurableDetector) {
  340.                 @SuppressWarnings("unchecked")
  341.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) detector).getHandler();
  342.                 newState = handler.resetState(detector, oldState);
  343.             } else {
  344.                 @SuppressWarnings("deprecation")
  345.                 final SpacecraftState s = detector.resetState(oldState);
  346.                 newState = s;
  347.             }
  348.         }

  350.         pendingEvent      = false;
  351.         pendingEventTime  = null;

  353.         return newState;

  355.     }

  357.     /** Local runtime exception wrapping OrekitException. */
  358.     private static class LocalWrapperException extends RuntimeException {

  360.         /** Serializable UID. */
  361.         private static final long serialVersionUID = 2734331164409224983L;

  363.         /** Wrapped exception. */
  364.         private final OrekitException wrappedException;

  366.         /** Simple constructor.
  367.          * @param wrapped wrapped exception
  368.          */
  369.         public LocalWrapperException(final OrekitException wrapped) {
  370.             this.wrappedException = wrapped;
  371.         }

  373.         /** Get the wrapped exception.
  374.          * @return wrapped exception
  375.          */
  376.         public OrekitException getWrappedException() {
  377.             return wrappedException;
  378.         }

  380.     }

  382. }
Created with JaCoCo 0.6.3.201306030806