AbstractDetector.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.orekit.errors.OrekitException;
  19. import org.orekit.errors.OrekitMessages;
  20. import org.orekit.propagation.SpacecraftState;
  21. import org.orekit.propagation.events.handlers.EventHandler;
  22. import org.orekit.time.AbsoluteDate;

  23. /** Common parts shared by several orbital events finders.
  24.  * @param <T> type of the detector
  25.  * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
  26.  * @author Luc Maisonobe
  27.  */
  28. public abstract class AbstractDetector<T extends AbstractDetector<T>> implements EventDetector {

  29.     /** Default maximum checking interval (s). */
  30.     public static final double DEFAULT_MAXCHECK = EventDetectionSettings.DEFAULT_MAXCHECK;

  31.     /** Default convergence threshold (s). */
  32.     public static final double DEFAULT_THRESHOLD = EventDetectionSettings.DEFAULT_THRESHOLD;

  33.     /** Default maximum number of iterations in the event time search. */
  34.     public static final int DEFAULT_MAX_ITER = EventDetectionSettings.DEFAULT_MAX_ITER;

  35.     /** Detection settings. */
  36.     private final EventDetectionSettings eventDetectionSettings;

  37.     /** Default handler for event overrides. */
  38.     private final EventHandler handler;

  39.     /** Propagation direction. */
  40.     private boolean forward;

  41.     /** Build a new instance.
  42.      * @param maxCheck maximum checking interval, must be strictly positive (s)
  43.      * @param threshold convergence threshold (s)
  44.      * @param maxIter maximum number of iterations in the event time search
  45.      * @param handler event handler to call at event occurrences
  46.      */
  47.     protected AbstractDetector(final double maxCheck, final double threshold, final int maxIter,
  48.                                final EventHandler handler) {
  49.         this(new EventDetectionSettings(maxCheck, threshold, maxIter), handler);
  50.     }

  51.     /** Build a new instance.
  52.      * @param maxCheck maximum checking interval
  53.      * @param threshold convergence threshold (s)
  54.      * @param maxIter maximum number of iterations in the event time search
  55.      * @param handler event handler to call at event occurrences
  56.      * @since 12.0
  57.      * @deprecated as of 12.2
  58.      */
  59.     @Deprecated
  60.     protected AbstractDetector(final AdaptableInterval maxCheck, final double threshold, final int maxIter,
  61.                                final EventHandler handler) {
  62.         this(new EventDetectionSettings(maxCheck, threshold, maxIter), handler);
  63.     }

  64.     /** Build a new instance.
  65.      * @param detectionSettings event detection settings
  66.      * @param handler event handler to call at event occurrences
  67.      * @since 12.2
  68.      */
  69.     protected AbstractDetector(final EventDetectionSettings detectionSettings, final EventHandler handler) {
  70.         checkStrictlyPositive(detectionSettings.getThreshold());
  71.         this.eventDetectionSettings = detectionSettings;
  72.         this.handler   = handler;
  73.         this.forward   = true;
  74.     }

  75.     /** Check value is strictly positive.
  76.      * @param value value to check
  77.      * @exception OrekitException if value is not strictly positive
  78.      * @since 11.2
  79.      */
  80.     private void checkStrictlyPositive(final double value) throws OrekitException {
  81.         if (value <= 0.0) {
  82.             throw new OrekitException(OrekitMessages.NOT_STRICTLY_POSITIVE, value);
  83.         }
  84.     }

  85.     /**
  86.      * {@inheritDoc}
  87.      *
  88.      * <p> This implementation sets the direction of propagation and initializes the event
  89.      * handler. If a subclass overrides this method it should call {@code
  90.      * super.init(s0, t)}.
  91.      */
  92.     @Override
  93.     public void init(final SpacecraftState s0,
  94.                      final AbsoluteDate t) {
  95.         forward = t.durationFrom(s0.getDate()) >= 0.0;
  96.         getHandler().init(s0, t, this);
  97.     }

  98.     /** {@inheritDoc} */
  99.     @Override
  100.     public EventDetectionSettings getDetectionSettings() {
  101.         return eventDetectionSettings;
  102.     }

  103.     /** {@inheritDoc} */
  104.     public AdaptableInterval getMaxCheckInterval() {
  105.         return getDetectionSettings().getMaxCheckInterval();
  106.     }

  107.     /** {@inheritDoc} */
  108.     public int getMaxIterationCount() {
  109.         return getDetectionSettings().getMaxIterationCount();
  110.     }

  111.     /** {@inheritDoc} */
  112.     public double getThreshold() {
  113.         return getDetectionSettings().getThreshold();
  114.     }

  115.     /**
  116.      * Set up the maximum checking interval.
  117.      * <p>
  118.      * This will override a maximum checking interval if it has been configured previously.
  119.      * </p>
  120.      * @param newMaxCheck maximum checking interval (s)
  121.      * @return a new detector with updated configuration (the instance is not changed)
  122.      * @since 6.1
  123.      */
  124.     public T withMaxCheck(final double newMaxCheck) {
  125.         return withMaxCheck(AdaptableInterval.of(newMaxCheck));
  126.     }

  127.     /**
  128.      * Set up the maximum checking interval.
  129.      * <p>
  130.      * This will override a maximum checking interval if it has been configured previously.
  131.      * </p>
  132.      * @param newMaxCheck maximum checking interval (s)
  133.      * @return a new detector with updated configuration (the instance is not changed)
  134.      * @since 12.0
  135.      */
  136.     public T withMaxCheck(final AdaptableInterval newMaxCheck) {
  137.         return create(new EventDetectionSettings(newMaxCheck, getThreshold(), getMaxIterationCount()), getHandler());
  138.     }

  139.     /**
  140.      * Set up the maximum number of iterations in the event time search.
  141.      * <p>
  142.      * This will override a number of iterations if it has been configured previously.
  143.      * </p>
  144.      * @param newMaxIter maximum number of iterations in the event time search
  145.      * @return a new detector with updated configuration (the instance is not changed)
  146.      * @since 6.1
  147.      */
  148.     public T withMaxIter(final int newMaxIter) {
  149.         return create(new EventDetectionSettings(getMaxCheckInterval(), getThreshold(), newMaxIter), getHandler());
  150.     }

  151.     /**
  152.      * Set up the convergence threshold.
  153.      * <p>
  154.      * This will override a convergence threshold if it has been configured previously.
  155.      * </p>
  156.      * @param newThreshold convergence threshold (s)
  157.      * @return a new detector with updated configuration (the instance is not changed)
  158.      * @since 6.1
  159.      */
  160.     public T withThreshold(final double newThreshold) {
  161.         return create(new EventDetectionSettings(getMaxCheckInterval(), newThreshold, getMaxIterationCount()), getHandler());
  162.     }

  163.     /**
  164.      * Set up the event detection settings.
  165.      * <p>
  166.      * This will override settings previously configured.
  167.      * </p>
  168.      * @param newSettings new event detection settings
  169.      * @return a new detector with updated configuration (the instance is not changed)
  170.      * @since 12.2
  171.      */
  172.     public T withDetectionSettings(final EventDetectionSettings newSettings) {
  173.         return create(new EventDetectionSettings(newSettings.getMaxCheckInterval(), newSettings.getThreshold(), newSettings.getMaxIterationCount()),
  174.                 getHandler());
  175.     }

  176.     /**
  177.      * Set up the event handler to call at event occurrences.
  178.      * <p>
  179.      * This will override a handler if it has been configured previously.
  180.      * </p>
  181.      * @param newHandler event handler to call at event occurrences
  182.      * @return a new detector with updated configuration (the instance is not changed)
  183.      * @since 6.1
  184.      */
  185.     public T withHandler(final EventHandler newHandler) {
  186.         return create(getDetectionSettings(), newHandler);
  187.     }

  188.     /** {@inheritDoc} */
  189.     @Override
  190.     public EventHandler getHandler() {
  191.         return handler;
  192.     }

  193.     /** Build a new instance.
  194.      * @param newMaxCheck maximum checking interval (s)
  195.      * @param newThreshold convergence threshold (s)
  196.      * @param newMaxIter maximum number of iterations in the event time search
  197.      * @param newHandler event handler to call at event occurrences
  198.      * @return a new instance of the appropriate sub-type
  199.      * @deprecated as of 12.2. Will be removed in 13.0 and only the other signature shall remain
  200.      */
  201.     @Deprecated
  202.     protected abstract T create(AdaptableInterval newMaxCheck, double newThreshold, int newMaxIter,
  203.                                 EventHandler newHandler);

  204.     /** Build a new instance.
  205.      * @param detectionSettings detection settings
  206.      * @param newHandler event handler to call at event occurrences
  207.      * @return a new instance of the appropriate sub-type
  208.      * @since 12.2
  209.      */
  210.     protected T create(final EventDetectionSettings detectionSettings, final EventHandler newHandler) {
  211.         return create(detectionSettings.getMaxCheckInterval(), detectionSettings.getThreshold(), detectionSettings.getMaxIterationCount(),
  212.             newHandler);
  213.     }

  214.     /** Check if the current propagation is forward or backward.
  215.      * @return true if the current propagation is forward
  216.      * @since 7.2
  217.      */
  218.     public boolean isForward() {
  219.         return forward;
  220.     }

  221. }