AbstractAnalyticalPropagator.java

  1. /* Copyright 2002-2020 CS GROUP
  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.analytical;

  19. import java.util.ArrayList;
  20. import java.util.Collection;
  21. import java.util.Collections;
  22. import java.util.Comparator;
  23. import java.util.List;
  24. import java.util.PriorityQueue;
  25. import java.util.Queue;

  27. import org.hipparchus.exception.MathRuntimeException;
  28. import org.hipparchus.ode.events.Action;
  29. import org.hipparchus.util.FastMath;
  30. import org.orekit.attitudes.Attitude;
  31. import org.orekit.attitudes.AttitudeProvider;
  32. import org.orekit.errors.OrekitException;
  33. import org.orekit.errors.OrekitInternalError;
  34. import org.orekit.frames.Frame;
  35. import org.orekit.orbits.Orbit;
  36. import org.orekit.propagation.AbstractPropagator;
  37. import org.orekit.propagation.AdditionalStateProvider;
  38. import org.orekit.propagation.BoundedPropagator;
  39. import org.orekit.propagation.SpacecraftState;
  40. import org.orekit.propagation.events.EventDetector;
  41. import org.orekit.propagation.events.EventState;
  42. import org.orekit.propagation.events.EventState.EventOccurrence;
  43. import org.orekit.propagation.sampling.OrekitStepInterpolator;
  44. import org.orekit.time.AbsoluteDate;
  45. import org.orekit.utils.PVCoordinatesProvider;
  46. import org.orekit.utils.TimeStampedPVCoordinates;

  48. /** Common handling of {@link org.orekit.propagation.Propagator} methods for analytical propagators.
  49.  * <p>
  50.  * This abstract class allows to provide easily the full set of {@link
  51.  * org.orekit.propagation.Propagator Propagator} methods, including all propagation
  52.  * modes support and discrete events support for any simple propagation method. Only
  53.  * two methods must be implemented by derived classes: {@link #propagateOrbit(AbsoluteDate)}
  54.  * and {@link #getMass(AbsoluteDate)}. The first method should perform straightforward
  55.  * propagation starting from some internally stored initial state up to the specified target date.
  56.  * </p>
  57.  * @author Luc Maisonobe
  58.  */
  59. public abstract class AbstractAnalyticalPropagator extends AbstractPropagator {

  61.     /** Provider for attitude computation. */
  62.     private PVCoordinatesProvider pvProvider;

  64.     /** Start date of last propagation. */
  65.     private AbsoluteDate lastPropagationStart;

  67.     /** End date of last propagation. */
  68.     private AbsoluteDate lastPropagationEnd;

  70.     /** Initialization indicator of events states. */
  71.     private boolean statesInitialized;

  73.     /** Indicator for last step. */
  74.     private boolean isLastStep;

  76.     /** Event steps. */
  77.     private final Collection<EventState<?>> eventsStates;

  79.     /** Build a new instance.
  80.      * @param attitudeProvider provider for attitude computation
  81.      */
  82.     protected AbstractAnalyticalPropagator(final AttitudeProvider attitudeProvider) {
  83.         setAttitudeProvider(attitudeProvider);
  84.         pvProvider               = new LocalPVProvider();
  85.         lastPropagationStart     = AbsoluteDate.PAST_INFINITY;
  86.         lastPropagationEnd       = AbsoluteDate.FUTURE_INFINITY;
  87.         statesInitialized        = false;
  88.         eventsStates             = new ArrayList<EventState<?>>();
  89.     }

  91.     /** {@inheritDoc} */
  92.     public BoundedPropagator getGeneratedEphemeris() {
  93.         return new BoundedPropagatorView(lastPropagationStart, lastPropagationEnd);
  94.     }

  96.     /** {@inheritDoc} */
  97.     public <T extends EventDetector> void addEventDetector(final T detector) {
  98.         eventsStates.add(new EventState<T>(detector));
  99.     }

  101.     /** {@inheritDoc} */
  102.     public Collection<EventDetector> getEventsDetectors() {
  103.         final List<EventDetector> list = new ArrayList<EventDetector>();
  104.         for (final EventState<?> state : eventsStates) {
  105.             list.add(state.getEventDetector());
  106.         }
  107.         return Collections.unmodifiableCollection(list);
  108.     }

  110.     /** {@inheritDoc} */
  111.     public void clearEventsDetectors() {
  112.         eventsStates.clear();
  113.     }

  115.     /** {@inheritDoc} */
  116.     public SpacecraftState propagate(final AbsoluteDate start, final AbsoluteDate target) {
  117.         try {

  119.             initializePropagation();

  121.             lastPropagationStart = start;

  123.             final double dt       = target.durationFrom(start);
  124.             final double epsilon  = FastMath.ulp(dt);
  125.             SpacecraftState state = updateAdditionalStates(basicPropagate(start));

  127.             // evaluate step size
  128.             final double stepSize;
  129.             if (getMode() == MASTER_MODE) {
  130.                 if (Double.isNaN(getFixedStepSize())) {
  131.                     stepSize = FastMath.copySign(state.getKeplerianPeriod() / 100, dt);
  132.                 } else {
  133.                     stepSize = FastMath.copySign(getFixedStepSize(), dt);
  134.                 }
  135.             } else {
  136.                 stepSize = dt;
  137.             }

  139.             // initialize event detectors
  140.             for (final EventState<?> es : eventsStates) {
  141.                 es.init(state, target);
  142.             }

  144.             // initialize step handler
  145.             if (getStepHandler() != null) {
  146.                 getStepHandler().init(state, target);
  147.             }

  149.             // iterate over the propagation range
  150.             statesInitialized = false;
  151.             isLastStep = false;
  152.             do {

  154.                 // go ahead one step size
  155.                 final SpacecraftState previous = state;
  156.                 AbsoluteDate t = previous.getDate().shiftedBy(stepSize);
  157.                 if ((dt == 0) || ((dt > 0) ^ (t.compareTo(target) <= 0)) ||
  158.                         (FastMath.abs(target.durationFrom(t)) <= epsilon)) {
  159.                     // current step exceeds target
  160.                     // or is target to within double precision
  161.                     t = target;
  162.                 }
  163.                 final SpacecraftState current = updateAdditionalStates(basicPropagate(t));
  164.                 final OrekitStepInterpolator interpolator = new BasicStepInterpolator(dt >= 0, previous, current);


  167.                 // accept the step, trigger events and step handlers
  168.                 state = acceptStep(interpolator, target, epsilon);

  170.                 // Update the potential changes in the spacecraft state due to the events
  171.                 // especially the potential attitude transition
  172.                 state = updateAdditionalStates(basicPropagate(state.getDate()));

  174.             } while (!isLastStep);

  176.             // return the last computed state
  177.             lastPropagationEnd = state.getDate();
  178.             setStartDate(state.getDate());
  179.             return state;

  181.         } catch (MathRuntimeException mrte) {
  182.             throw OrekitException.unwrap(mrte);
  183.         }
  184.     }

  186.     /** Accept a step, triggering events and step handlers.
  187.      * @param interpolator interpolator for the current step
  188.      * @param target final propagation time
  189.      * @param epsilon threshold for end date detection
  190.      * @return state at the end of the step
  191.           * @exception MathRuntimeException if an event cannot be located
  192.      */
  193.     protected SpacecraftState acceptStep(final OrekitStepInterpolator interpolator,
  194.                                          final AbsoluteDate target, final double epsilon)
  195.         throws MathRuntimeException {

  197.         SpacecraftState       previous = interpolator.getPreviousState();
  198.         final SpacecraftState current  = interpolator.getCurrentState();
  199.         OrekitStepInterpolator restricted = interpolator;


  202.         // initialize the events states if needed
  203.         if (!statesInitialized) {

  205.             if (!eventsStates.isEmpty()) {
  206.                 // initialize the events states
  207.                 for (final EventState<?> state : eventsStates) {
  208.                     state.reinitializeBegin(interpolator);
  209.                 }
  210.             }

  212.             statesInitialized = true;

  214.         }

  216.         // search for next events that may occur during the step
  217.         final int orderingSign = interpolator.isForward() ? +1 : -1;
  218.         final Queue<EventState<?>> occurringEvents = new PriorityQueue<>(new Comparator<EventState<?>>() {
  219.             /** {@inheritDoc} */
  220.             @Override
  221.             public int compare(final EventState<?> es0, final EventState<?> es1) {
  222.                 return orderingSign * es0.getEventDate().compareTo(es1.getEventDate());
  223.             }
  224.         });

  226.         boolean doneWithStep = false;
  227.         resetEvents:
  228.         do {

  230.             // Evaluate all event detectors for events
  231.             occurringEvents.clear();
  232.             for (final EventState<?> state : eventsStates) {
  233.                 if (state.evaluateStep(interpolator)) {
  234.                     // the event occurs during the current step
  235.                     occurringEvents.add(state);
  236.                 }
  237.             }

  239.             do {

  241.                 eventLoop:
  242.                 while (!occurringEvents.isEmpty()) {

  244.                     // handle the chronologically first event
  245.                     final EventState<?> currentEvent = occurringEvents.poll();

  247.                     // get state at event time
  248.                     SpacecraftState eventState = restricted.getInterpolatedState(currentEvent.getEventDate());

  250.                     // restrict the interpolator to the first part of the step, up to the event
  251.                     restricted = restricted.restrictStep(previous, eventState);

  253.                     // try to advance all event states to current time
  254.                     for (final EventState<?> state : eventsStates) {
  255.                         if (state != currentEvent && state.tryAdvance(eventState, interpolator)) {
  256.                             // we need to handle another event first
  257.                             // remove event we just updated to prevent heap corruption
  258.                             occurringEvents.remove(state);
  259.                             // add it back to update its position in the heap
  260.                             occurringEvents.add(state);
  261.                             // re-queue the event we were processing
  262.                             occurringEvents.add(currentEvent);
  263.                             continue eventLoop;
  264.                         }
  265.                     }
  266.                     // all event detectors agree we can advance to the current event time

  268.                     final EventOccurrence occurrence = currentEvent.doEvent(eventState);
  269.                     final Action action = occurrence.getAction();
  270.                     isLastStep = action == Action.STOP;

  272.                     if (isLastStep) {
  273.                         // ensure the event is after the root if it is returned STOP
  274.                         // this lets the user integrate to a STOP event and then restart
  275.                         // integration from the same time.
  276.                         eventState = interpolator.getInterpolatedState(occurrence.getStopDate());
  277.                         restricted = restricted.restrictStep(previous, eventState);
  278.                     }

  280.                     // handle the first part of the step, up to the event
  281.                     if (getStepHandler() != null) {
  282.                         getStepHandler().handleStep(restricted, isLastStep);
  283.                     }

  285.                     if (isLastStep) {
  286.                         // the event asked to stop integration
  287.                         return eventState;
  288.                     }

  290.                     if (action == Action.RESET_DERIVATIVES || action == Action.RESET_STATE) {
  291.                         // some event handler has triggered changes that
  292.                         // invalidate the derivatives, we need to recompute them
  293.                         final SpacecraftState resetState = occurrence.getNewState();
  294.                         if (resetState != null) {
  295.                             resetIntermediateState(resetState, interpolator.isForward());
  296.                             return resetState;
  297.                         }
  298.                     }
  299.                     // at this point action == Action.CONTINUE or Action.RESET_EVENTS

  301.                     // prepare handling of the remaining part of the step
  302.                     previous = eventState;
  303.                     restricted = new BasicStepInterpolator(restricted.isForward(), eventState, current);

  305.                     if (action == Action.RESET_EVENTS) {
  306.                         continue resetEvents;
  307.                     }

  309.                     // at this point action == Action.CONTINUE
  310.                     // check if the same event occurs again in the remaining part of the step
  311.                     if (currentEvent.evaluateStep(restricted)) {
  312.                         // the event occurs during the current step
  313.                         occurringEvents.add(currentEvent);
  314.                     }

  316.                 }

  318.                 // last part of the step, after the last event. Advance all detectors to
  319.                 // the end of the step. Should only detect a new event here if an event
  320.                 // modified the g function of another detector. Detecting such events here
  321.                 // is unreliable and RESET_EVENTS should be used instead. Might as well
  322.                 // re-check here because we have to loop through all the detectors anyway
  323.                 // and the alternative is to throw an exception.
  324.                 for (final EventState<?> state : eventsStates) {
  325.                     if (state.tryAdvance(current, interpolator)) {
  326.                         occurringEvents.add(state);
  327.                     }
  328.                 }

  330.             } while (!occurringEvents.isEmpty());

  332.             doneWithStep = true;
  333.         } while (!doneWithStep);

  335.         isLastStep = target.equals(current.getDate());

  337.         // handle the remaining part of the step, after all events if any
  338.         if (getStepHandler() != null) {
  339.             getStepHandler().handleStep(interpolator, isLastStep);
  340.         }

  342.         return current;

  344.     }

  346.     /** Get the mass.
  347.      * @param date target date for the orbit
  348.      * @return mass mass
  349.      */
  350.     protected abstract double getMass(AbsoluteDate date);

  352.     /** Get PV coordinates provider.
  353.      * @return PV coordinates provider
  354.      */
  355.     public PVCoordinatesProvider getPvProvider() {
  356.         return pvProvider;
  357.     }

  359.     /** Reset an intermediate state.
  360.      * @param state new intermediate state to consider
  361.      * @param forward if true, the intermediate state is valid for
  362.      * propagations after itself
  363.      */
  364.     protected abstract void resetIntermediateState(SpacecraftState state, boolean forward);

  366.     /** Extrapolate an orbit up to a specific target date.
  367.      * @param date target date for the orbit
  368.      * @return extrapolated parameters
  369.      */
  370.     protected abstract Orbit propagateOrbit(AbsoluteDate date);

  372.     /** Propagate an orbit without any fancy features.
  373.      * <p>This method is similar in spirit to the {@link #propagate} method,
  374.      * except that it does <strong>not</strong> call any handler during
  375.      * propagation, nor any discrete events, not additional states. It always
  376.      * stop exactly at the specified date.</p>
  377.      * @param date target date for propagation
  378.      * @return state at specified date
  379.      */
  380.     protected SpacecraftState basicPropagate(final AbsoluteDate date) {
  381.         try {

  383.             // evaluate orbit
  384.             final Orbit orbit = propagateOrbit(date);

  386.             // evaluate attitude
  387.             final Attitude attitude =
  388.                 getAttitudeProvider().getAttitude(pvProvider, date, orbit.getFrame());

  390.             // build raw state
  391.             return new SpacecraftState(orbit, attitude, getMass(date));

  393.         } catch (OrekitException oe) {
  394.             throw new OrekitException(oe);
  395.         }
  396.     }

  398.     /** Internal PVCoordinatesProvider for attitude computation. */
  399.     private class LocalPVProvider implements PVCoordinatesProvider {

  401.         /** {@inheritDoc} */
  402.         public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate date, final Frame frame) {
  403.             return propagateOrbit(date).getPVCoordinates(frame);
  404.         }

  406.     }

  408.     /** {@link BoundedPropagator} view of the instance. */
  409.     private class BoundedPropagatorView extends AbstractAnalyticalPropagator implements BoundedPropagator {

  411.         /** Min date. */
  412.         private final AbsoluteDate minDate;

  414.         /** Max date. */
  415.         private final AbsoluteDate maxDate;

  417.         /** Simple constructor.
  418.          * @param startDate start date of the propagation
  419.          * @param endDate end date of the propagation
  420.          */
  421.         BoundedPropagatorView(final AbsoluteDate startDate, final AbsoluteDate endDate) {
  422.             super(AbstractAnalyticalPropagator.this.getAttitudeProvider());
  423.             if (startDate.compareTo(endDate) <= 0) {
  424.                 minDate = startDate;
  425.                 maxDate = endDate;
  426.             } else {
  427.                 minDate = endDate;
  428.                 maxDate = startDate;
  429.             }

  431.             try {
  432.                 // copy the same additional state providers as the original propagator
  433.                 for (AdditionalStateProvider provider : AbstractAnalyticalPropagator.this.getAdditionalStateProviders()) {
  434.                     addAdditionalStateProvider(provider);
  435.                 }
  436.             } catch (OrekitException oe) {
  437.                 // as the providers are already compatible with each other,
  438.                 // this should never happen
  439.                 throw new OrekitInternalError(null);
  440.             }

  442.         }

  444.         /** {@inheritDoc} */
  445.         public AbsoluteDate getMinDate() {
  446.             return minDate;
  447.         }

  449.         /** {@inheritDoc} */
  450.         public AbsoluteDate getMaxDate() {
  451.             return maxDate;
  452.         }

  454.         /** {@inheritDoc} */
  455.         protected Orbit propagateOrbit(final AbsoluteDate target) {
  456.             return AbstractAnalyticalPropagator.this.propagateOrbit(target);
  457.         }

  459.         /** {@inheritDoc} */
  460.         public double getMass(final AbsoluteDate date) {
  461.             return AbstractAnalyticalPropagator.this.getMass(date);
  462.         }

  464.         /** {@inheritDoc} */
  465.         public TimeStampedPVCoordinates getPVCoordinates(final AbsoluteDate date, final Frame frame) {
  466.             return propagate(date).getPVCoordinates(frame);
  467.         }

  469.         /** {@inheritDoc} */
  470.         public void resetInitialState(final SpacecraftState state) {
  471.             AbstractAnalyticalPropagator.this.resetInitialState(state);
  472.         }

  474.         /** {@inheritDoc} */
  475.         protected void resetIntermediateState(final SpacecraftState state, final boolean forward) {
  476.             AbstractAnalyticalPropagator.this.resetIntermediateState(state, forward);
  477.         }

  479.         /** {@inheritDoc} */
  480.         public SpacecraftState getInitialState() {
  481.             return AbstractAnalyticalPropagator.this.getInitialState();
  482.         }

  484.         /** {@inheritDoc} */
  485.         public Frame getFrame() {
  486.             return AbstractAnalyticalPropagator.this.getFrame();
  487.         }

  489.     }

  491.     /** Internal class for local propagation. */
  492.     private class BasicStepInterpolator implements OrekitStepInterpolator {

  494.         /** Previous state. */
  495.         private final SpacecraftState previousState;

  497.         /** Current state. */
  498.         private final SpacecraftState currentState;

  500.         /** Forward propagation indicator. */
  501.         private final boolean forward;

  503.         /** Simple constructor.
  504.          * @param isForward integration direction indicator
  505.          * @param previousState start of the step
  506.          * @param currentState end of the step
  507.          */
  508.         BasicStepInterpolator(final boolean isForward,
  509.                               final SpacecraftState previousState,
  510.                               final SpacecraftState currentState) {
  511.             this.forward         = isForward;
  512.             this.previousState   = previousState;
  513.             this.currentState    = currentState;
  514.         }

  516.         /** {@inheritDoc} */
  517.         @Override
  518.         public SpacecraftState getPreviousState() {
  519.             return previousState;
  520.         }

  522.         /** {@inheritDoc} */
  523.         @Override
  524.         public boolean isPreviousStateInterpolated() {
  525.             // no difference in analytical propagators
  526.             return false;
  527.         }

  529.         /** {@inheritDoc} */
  530.         @Override
  531.         public SpacecraftState getCurrentState() {
  532.             return currentState;
  533.         }

  535.         /** {@inheritDoc} */
  536.         @Override
  537.         public boolean isCurrentStateInterpolated() {
  538.             // no difference in analytical propagators
  539.             return false;
  540.         }

  542.         /** {@inheritDoc} */
  543.         @Override
  544.         public SpacecraftState getInterpolatedState(final AbsoluteDate date) {

  546.             // compute the basic spacecraft state
  547.             final SpacecraftState basicState = basicPropagate(date);

  549.             // add the additional states
  550.             return updateAdditionalStates(basicState);

  552.         }

  554.         /** {@inheritDoc} */
  555.         @Override
  556.         public boolean isForward() {
  557.             return forward;
  558.         }

  560.         /** {@inheritDoc} */
  561.         @Override
  562.         public BasicStepInterpolator restrictStep(final SpacecraftState newPreviousState,
  563.                                                   final SpacecraftState newCurrentState) {
  564.             return new BasicStepInterpolator(forward, newPreviousState, newCurrentState);
  565.         }

  567.     }

  569. }
Created with JaCoCo 0.8.6.202009150832