AttitudesSequence.java

  1. /* Copyright 2002-2013 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.attitudes;

  19. import java.util.ArrayList;
  20. import java.util.Collection;
  21. import java.util.HashMap;
  22. import java.util.Map;

  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.frames.Frame;
  26. import org.orekit.propagation.Propagator;
  27. import org.orekit.propagation.SpacecraftState;
  28. import org.orekit.propagation.events.AbstractReconfigurableDetector;
  29. import org.orekit.propagation.events.EventDetector;
  30. import org.orekit.propagation.events.handlers.EventHandler;
  31. import org.orekit.time.AbsoluteDate;
  32. import org.orekit.utils.PVCoordinatesProvider;

  34. /** This classes manages a sequence of different attitude providers that are activated
  35.  * in turn according to switching events.
  36.  * <p>Only one attitude provider in the sequence is in an active state. When one of
  37.  * the switch event associated with the active provider occurs, the active provider becomes
  38.  * the one specified with the event. A simple example is a provider for the sun lighted part
  39.  * of the orbit and another provider for the eclipse time. When the sun lighted provider is active,
  40.  * the eclipse entry event is checked and when it occurs the eclipse provider is activated.
  41.  * When the eclipse provider is active, the eclipse exit event is checked and when it occurs
  42.  * the sun lighted provider is activated again. This sequence is a simple loop.</p>
  43.  * <p>An active attitude provider may have several switch events and next provider settings, leading
  44.  * to different activation patterns depending on which events are triggered first. An example
  45.  * of this feature is handling switches to safe mode if some contingency condition is met, in
  46.  * addition to the nominal switches that correspond to proper operations. Another example
  47.  * is handling of maneuver mode.<p>
  48.  * @author Luc Maisonobe
  49.  * @since 5.1
  50.  */
  51. public class AttitudesSequence implements AttitudeProvider {

  53.     /** Serializable UID. */
  54.     private static final long serialVersionUID = 5140034224175180354L;

  56.     /** Active provider. */
  57.     private AttitudeProvider active;

  59.     /** Switching events map. */
  60.     private final Map<AttitudeProvider, Collection<Switch<?>>> switchingMap;

  62.     /** Constructor for an initially empty sequence.
  63.      */
  64.     public AttitudesSequence() {
  65.         active = null;
  66.         switchingMap = new HashMap<AttitudeProvider, Collection<Switch<?>>>();
  67.     }

  69.     /** Reset the active provider.
  70.      * @param provider providerprovider to activate
  71.      */
  72.     public void resetActiveProvider(final AttitudeProvider provider) {

  74.         // add the provider if not already known
  75.         if (!switchingMap.containsKey(provider)) {
  76.             switchingMap.put(provider, new ArrayList<Switch<?>>());
  77.         }

  79.         active = provider;

  81.     }

  83.     /** Register all wrapped switch events to the propagator.
  84.      * <p>
  85.      * This method must be called once before propagation, after the
  86.      * switching conditions have been set up by calls to {@link
  87.      * #addSwitchingCondition(AttitudeProvider, EventDetector, boolean, boolean, AttitudeProvider)}.
  88.      * </p>
  89.      * @param propagator propagator that will handle the events
  90.      */
  91.     public void registerSwitchEvents(final Propagator propagator) {
  92.         for (final Collection<Switch<?>> collection : switchingMap.values()) {
  93.             for (final Switch<?> s : collection) {
  94.                 propagator.addEventDetector(s);
  95.             }
  96.         }
  97.     }

  99.     /** Add a switching condition between two attitude providers.
  100.      * <p>
  101.      * An attitude provider may have several different switch events associated to
  102.      * it. Depending on which event is triggered, the appropriate provider is
  103.      * switched to.
  104.      * </p>
  105.      * <p>
  106.      * The switch events specified here must <em>not</em> be registered to the
  107.      * propagator directly. The proper way to register these events is to
  108.      * call {@link #registerSwitchEvents(Propagator)} once after all switching
  109.      * conditions have been set up. The reason for this is that the events will
  110.      * be wrapped before being registered.
  111.      * </p>
  112.      * @param before attitude provider before the switch event occurrence
  113.      * @param switchEvent event triggering the attitude providers switch (may be null
  114.      * for a provider without any ending condition, in this case the after provider
  115.      * is not referenced and may be null too)
  116.      * @param switchOnIncrease if true, switch is triggered on increasing event
  117.      * @param switchOnDecrease if true, switch is triggered on decreasing event
  118.      * @param after attitude provider to activate after the switch event occurrence
  119.      * (used only if switchEvent is non null)
  120.      * @param <T> class type for the generic version
  121.      */
  122.     public <T extends EventDetector> void addSwitchingCondition(final AttitudeProvider before,
  123.                                                                 final T switchEvent,
  124.                                                                 final boolean switchOnIncrease,
  125.                                                                 final boolean switchOnDecrease,
  126.                                                                 final AttitudeProvider after) {

  128.         // add the before provider if not already known
  129.         if (!switchingMap.containsKey(before)) {
  130.             switchingMap.put(before, new ArrayList<Switch<?>>());
  131.             if (active == null) {
  132.                 active = before;
  133.             }
  134.         }

  136.         if (switchEvent != null) {

  138.             // add the after provider if not already known
  139.             if (!switchingMap.containsKey(after)) {
  140.                 switchingMap.put(after, new ArrayList<Switch<?>>());
  141.             }

  143.             // add the switching condition
  144.             switchingMap.get(before).add(new Switch<T>(switchEvent, switchOnIncrease, switchOnDecrease, after));

  146.         }

  148.     }

  150.     /** {@inheritDoc} */
  151.     public Attitude getAttitude(final PVCoordinatesProvider pvProv,
  152.                                 final AbsoluteDate date, final Frame frame)
  153.         throws OrekitException {
  154.         // delegate attitude computation to the active provider
  155.         return active.getAttitude(pvProv, date, frame);
  156.     }

  158.     /** Switch specification.
  159.      * @param <T> class type for the generic version
  160.      */
  161.     private class Switch<T extends EventDetector> extends AbstractReconfigurableDetector<Switch<T>> {

  163.         /** Serializable UID. */
  164.         private static final long serialVersionUID = 20131118L;

  166.         /** Event. */
  167.         private final T event;

  169.         /** Event direction triggering the switch. */
  170.         private final boolean switchOnIncrease;

  172.         /** Event direction triggering the switch. */
  173.         private final boolean switchOnDecrease;

  175.         /** Next attitude provider. */
  176.         private final AttitudeProvider next;

  178.         /** Simple constructor.
  179.          * @param event event
  180.          * @param switchOnIncrease if true, switch is triggered on increasing event
  181.          * @param switchOnDecrease if true, switch is triggered on decreasing event
  182.          * otherwise switch is triggered on decreasing event
  183.          * @param next next attitude provider
  184.          */
  185.         public Switch(final T event,
  186.                       final boolean switchOnIncrease,
  187.                       final boolean switchOnDecrease,
  188.                       final AttitudeProvider next) {
  189.             this(event.getMaxCheckInterval(), event.getThreshold(), event.getMaxIterationCount(),
  190.                  new LocalHandler<T>(), event, switchOnIncrease, switchOnDecrease, next);
  191.         }

  193.         /** Private constructor with full parameters.
  194.          * <p>
  195.          * This constructor is private as users are expected to use the builder
  196.          * API with the various {@code withXxx()} methods to set up the instance
  197.          * in a readable manner without using a huge amount of parameters.
  198.          * </p>
  199.          * @param maxCheck maximum checking interval (s)
  200.          * @param threshold convergence threshold (s)
  201.          * @param maxIter maximum number of iterations in the event time search
  202.          * @param handler event handler to call at event occurrences
  203.          * @param event event
  204.          * @param switchOnIncrease if true, switch is triggered on increasing event
  205.          * @param switchOnDecrease if true, switch is triggered on decreasing event
  206.          * otherwise switch is triggered on decreasing event
  207.          * @param next next attitude provider
  208.          * @since 6.1
  209.          */
  210.         private Switch(final double maxCheck, final double threshold,
  211.                        final int maxIter, final EventHandler<Switch<T>> handler, final T event,
  212.                        final boolean switchOnIncrease, final boolean switchOnDecrease,
  213.                        final AttitudeProvider next) {
  214.             super(maxCheck, threshold, maxIter, handler);
  215.             this.event            = event;
  216.             this.switchOnIncrease = switchOnIncrease;
  217.             this.switchOnDecrease = switchOnDecrease;
  218.             this.next             = next;
  219.         }

  221.         /** {@inheritDoc} */
  222.         @Override
  223.         protected Switch<T> create(final double newMaxCheck, final double newThreshold,
  224.                                    final int newMaxIter, final EventHandler<Switch<T>> newHandler) {
  225.             return new Switch<T>(newMaxCheck, newThreshold, newMaxIter, newHandler,
  226.                                  event, switchOnIncrease, switchOnDecrease, next);
  227.         }

  229.         /** Perform the switch.
  230.          */
  231.         public void performSwitch() {
  232.             active = next;
  233.         }

  235.         /** {@inheritDoc} */
  236.         public void init(final SpacecraftState s0, final AbsoluteDate t) {
  237.             event.init(s0, t);
  238.         }

  240.         /** {@inheritDoc} */
  241.         public double g(final SpacecraftState s)
  242.             throws OrekitException {
  243.             return event.g(s);
  244.         }

  246.     }

  248.     /** Local handler.
  249.      * @param <T> class type for the generic version
  250.      */
  251.     private static class LocalHandler<T extends EventDetector> implements EventHandler<Switch<T>> {

  253.         /** {@inheritDoc} */
  254.         public EventHandler.Action eventOccurred(final SpacecraftState s, final Switch<T> sw, final boolean increasing)
  255.             throws OrekitException {

  257.             if ((increasing && sw.switchOnIncrease) || (!increasing && sw.switchOnDecrease)) {
  258.                 // switch to next attitude provider
  259.                 sw.performSwitch();
  260.             }

  262.             if (sw.event instanceof AbstractReconfigurableDetector) {
  263.                 @SuppressWarnings("unchecked")
  264.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) sw.event).getHandler();
  265.                 return handler.eventOccurred(s, sw.event, increasing);
  266.             } else {
  267.                 @SuppressWarnings("deprecation")
  268.                 final EventDetector.Action a = sw.event.eventOccurred(s, increasing);
  269.                 return AbstractReconfigurableDetector.convert(a);
  270.             }

  272.         }

  274.         /** {@inheritDoc} */
  275.         @Override
  276.         public SpacecraftState resetState(final Switch<T> sw, final SpacecraftState oldState)
  277.             throws OrekitException {
  278.             if (sw.event instanceof AbstractReconfigurableDetector) {
  279.                 @SuppressWarnings("unchecked")
  280.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) sw.event).getHandler();
  281.                 return handler.resetState(sw.event, oldState);
  282.             } else {
  283.                 @SuppressWarnings("deprecation")
  284.                 final SpacecraftState newState = sw.event.resetState(oldState);
  285.                 return newState;
  286.             }
  287.         }

  289.     }

  291. }
Created with JaCoCo 0.6.3.201306030806