FieldEclipseDetector.java

  1. /* Copyright 2002-2024 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.events;

  18. import org.hipparchus.CalculusFieldElement;
  19. import org.hipparchus.Field;
  20. import org.hipparchus.ode.events.Action;
  21. import org.orekit.bodies.OneAxisEllipsoid;
  22. import org.orekit.propagation.FieldSpacecraftState;
  23. import org.orekit.propagation.events.handlers.FieldEventHandler;
  24. import org.orekit.propagation.events.handlers.FieldStopOnIncreasing;
  25. import org.orekit.utils.ExtendedPVCoordinatesProvider;
  26. import org.orekit.utils.OccultationEngine;

  27. /** Finder for satellite eclipse related events.
  28.  * <p>This class finds eclipse events, i.e. satellite within umbra (total
  29.  * eclipse) or penumbra (partial eclipse).</p>
  30.  * <p>The default implementation behavior is to {@link Action#CONTINUE continue}
  31.  * propagation when entering the eclipse and to {@link Action#STOP stop} propagation
  32.  * when exiting the eclipse. This can be changed by calling {@link
  33.  * #withHandler(FieldEventHandler)} after construction.</p>
  34.  * @param <T> the type of the field elements
  35.  * @see org.orekit.propagation.FieldPropagator#addEventDetector(FieldEventDetector)
  36.  * @author Pascal Parraud
  37.  */
  38. public class FieldEclipseDetector<T extends CalculusFieldElement<T>> extends FieldAbstractDetector<FieldEclipseDetector<T>, T> {

  39.     /** Occultation engine.
  40.      * @since 12.0
  41.      */
  42.     private final OccultationEngine occultationEngine;

  43.     /** Umbra, if true, or penumbra, if false, detection flag. */
  44.     private boolean totalEclipse;

  45.     /** Margin to apply to eclipse angle. */
  46.     private final T margin;

  47.     /** Build a new eclipse detector.
  48.      * <p>The new instance is a total eclipse (umbra) detector with default
  49.      * values for maximal checking interval ({@link #DEFAULT_MAXCHECK})
  50.      * and convergence threshold ({@link #DEFAULT_THRESHOLD}).</p>
  51.      * @param field field used by default
  52.      * @param occulted the body to be occulted
  53.      * @param occultedRadius the radius of the body to be occulted (m)
  54.      * @param occulting the occulting body
  55.      * @since 12.0
  56.      */
  57.     public FieldEclipseDetector(final Field<T> field,
  58.                                 final ExtendedPVCoordinatesProvider occulted, final double occultedRadius,
  59.                                 final OneAxisEllipsoid occulting) {
  60.         this(field, new OccultationEngine(occulted, occultedRadius, occulting));
  61.     }

  62.     /** Build a new eclipse detector.
  63.      * <p>The new instance is a total eclipse (umbra) detector with default
  64.      * values for maximal checking interval ({@link #DEFAULT_MAXCHECK})
  65.      * and convergence threshold ({@link #DEFAULT_THRESHOLD}).</p>
  66.      * @param field field used by default
  67.      * @param occultationEngine occultation engine
  68.      * @since 12.0
  69.      */
  70.     public FieldEclipseDetector(final Field<T> field, final OccultationEngine occultationEngine) {
  71.         this(FieldAdaptableInterval.of(DEFAULT_MAXCHECK), field.getZero().newInstance(DEFAULT_THRESHOLD),
  72.              DEFAULT_MAX_ITER, new FieldStopOnIncreasing<>(),
  73.              occultationEngine, field.getZero(), true);
  74.     }

  75.     /** Protected constructor with full parameters.
  76.      * <p>
  77.      * This constructor is not public as users are expected to use the builder
  78.      * API with the various {@code withXxx()} methods to set up the instance
  79.      * in a readable manner without using a huge amount of parameters.
  80.      * </p>
  81.      * @param maxCheck maximum checking interval
  82.      * @param threshold convergence threshold (s)
  83.      * @param maxIter maximum number of iterations in the event time search
  84.      * @param handler event handler to call at event occurrences
  85.      * @param occultationEngine occultation engine
  86.      * @param margin to apply to eclipse angle (rad)
  87.      * @param totalEclipse umbra (true) or penumbra (false) detection flag
  88.      * @since 12.0
  89.      */
  90.     protected FieldEclipseDetector(final FieldAdaptableInterval<T> maxCheck, final T threshold,
  91.                                    final int maxIter, final FieldEventHandler<T> handler,
  92.                                    final OccultationEngine occultationEngine, final T margin, final boolean totalEclipse) {
  93.         super(maxCheck, threshold, maxIter, handler);
  94.         this.occultationEngine = occultationEngine;
  95.         this.margin            = margin;
  96.         this.totalEclipse      = totalEclipse;
  97.     }

  98.     /** {@inheritDoc} */
  99.     @Override
  100.     protected FieldEclipseDetector<T> create(final FieldAdaptableInterval<T> newMaxCheck, final T newThreshold, final int nawMaxIter,
  101.                                              final FieldEventHandler<T> newHandler) {
  102.         return new FieldEclipseDetector<>(newMaxCheck, newThreshold, nawMaxIter, newHandler,
  103.                                           occultationEngine, margin, totalEclipse);
  104.     }

  105.     /**
  106.      * Setup the detector to full umbra detection.
  107.      * <p>
  108.      * This will override a penumbra/umbra flag if it has been configured previously.
  109.      * </p>
  110.      * @return a new detector with updated configuration (the instance is not changed)
  111.      * @see #withPenumbra()
  112.      * @since 6.1
  113.      */
  114.     public FieldEclipseDetector<T> withUmbra() {
  115.         return new FieldEclipseDetector<>(getMaxCheckInterval(), getThreshold(), getMaxIterationCount(), getHandler(),
  116.                                           occultationEngine, margin, true);
  117.     }

  118.     /**
  119.      * Setup the detector to penumbra detection.
  120.      * <p>
  121.      * This will override a penumbra/umbra flag if it has been configured previously.
  122.      * </p>
  123.      * @return a new detector with updated configuration (the instance is not changed)
  124.      * @see #withUmbra()
  125.      * @since 6.1
  126.      */
  127.     public FieldEclipseDetector<T> withPenumbra() {
  128.         return new FieldEclipseDetector<>(getMaxCheckInterval(), getThreshold(), getMaxIterationCount(), getHandler(),
  129.                                           occultationEngine, margin, false);
  130.     }

  131.     /**
  132.      * Setup a margin to angle detection.
  133.      * <p>
  134.      * A positive margin implies eclipses are "larger" hence entry occurs earlier and exit occurs later
  135.      * than a detector with 0 margin.
  136.      * </p>
  137.      * @param newMargin angular margin to apply to eclipse detection (rad)
  138.      * @return a new detector with updated configuration (the instance is not changed)
  139.      * @since 12.0
  140.      */
  141.     public FieldEclipseDetector<T> withMargin(final T newMargin) {
  142.         return new FieldEclipseDetector<>(getMaxCheckInterval(), getThreshold(), getMaxIterationCount(), getHandler(),
  143.                                           occultationEngine, newMargin, totalEclipse);
  144.     }

  145.     /** Get the angular margin used for eclipse detection.
  146.      * @return angular margin used for eclipse detection (rad)
  147.      * @since 12.0
  148.      */
  149.     public T getMargin() {
  150.         return margin;
  151.     }

  152.     /** Get the occultation engine.
  153.      * @return occultation engine
  154.      * @since 12.0
  155.      */
  156.     public OccultationEngine getOccultationEngine() {
  157.         return occultationEngine;
  158.     }

  159.     /** Get the total eclipse detection flag.
  160.      * @return the total eclipse detection flag (true for umbra events detection,
  161.      * false for penumbra events detection)
  162.      */
  163.     public boolean getTotalEclipse() {
  164.         return totalEclipse;
  165.     }

  166.     /** Compute the value of the switching function.
  167.      * This function becomes negative when entering the region of shadow
  168.      * and positive when exiting.
  169.      * @param s the current state information: date, kinematics, attitude
  170.      * @return value of the switching function
  171.      */
  172.     public T g(final FieldSpacecraftState<T> s) {
  173.         final OccultationEngine.FieldOccultationAngles<T> angles = occultationEngine.angles(s);
  174.         return totalEclipse ?
  175.                angles.getSeparation().subtract(angles.getLimbRadius()).add(angles.getOccultedApparentRadius().add(margin)) :
  176.                angles.getSeparation().subtract(angles.getLimbRadius()).subtract(angles.getOccultedApparentRadius().add(margin));
  177.     }

  178. }