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.estimation.measurements.generation;
18  
19  import org.orekit.estimation.measurements.ObservedMeasurement;
20  import org.orekit.propagation.Propagator;
21  import org.orekit.propagation.SpacecraftState;
22  import org.orekit.propagation.events.AdapterDetector;
23  import org.orekit.propagation.events.EventDetector;
24  import org.orekit.propagation.events.handlers.EventHandler;
25  import org.orekit.time.AbsoluteDate;
26  import org.orekit.time.DatesSelector;
27  import org.orekit.utils.TimeSpanMap;
28  
29  
30  /** {@link Scheduler} based on {@link EventDetector} for generating measurements sequences.
31   * <p>
32   * Event-based schedulers generate measurements following a repetitive pattern when the
33   * a {@link EventDetector detector} provided at construction is in a {@link SignSemantic
34   * measurement feasible} state. It is important that the sign of the g function of the underlying
35   * event detector is not arbitrary, but has a semantic meaning, e.g. in or out,
36   * true or false. This class works well with event detectors that detect entry to or exit
37   * from a region, e.g. {@link org.orekit.propagation.events.EclipseDetector EclipseDetector},
38   * {@link org.orekit.propagation.events.ElevationDetector ElevationDetector}, {@link
39   * org.orekit.propagation.events.LatitudeCrossingDetector LatitudeCrossingDetector}. Using this
40   * scheduler with detectors that are not based on entry to or exit from a region, e.g. {@link
41   * org.orekit.propagation.events.DateDetector DateDetector}, {@link
42   * org.orekit.propagation.events.LongitudeCrossingDetector LongitudeCrossingDetector}, will likely
43   * lead to unexpected results.
44   * </p>
45   * <p>
46   * The repetitive pattern can be either a continuous stream of measurements separated by
47   * a constant step (for example one measurement every 60s), or several sequences of measurements
48   * at high rate up to a maximum number, with a rest period between sequences (for example
49   * sequences of up to 256 measurements every 100ms with 300s between each sequence).
50   * </p>
51   * @param <T> the type of the measurement
52   * @author Luc Maisonobe
53   * @since 9.3
54   */
55  public class EventBasedScheduler<T extends ObservedMeasurement<T>> extends AbstractScheduler<T> {
56  
57      /** Semantic of the detector g function sign to use. */
58      private final SignSemantic signSemantic;
59  
60      /** Feasibility status. */
61      private TimeSpanMap<Boolean> feasibility;
62  
63      /** Propagation direction. */
64      private boolean forward;
65  
66      /** Simple constructor.
67       * <p>
68       * The event detector instance should <em>not</em> be already bound to the propagator.
69       * It will be wrapped in an {@link AdapterDetector adapter} in order to manage time
70       * ranges when measurements are feasible. The wrapping adapter will be automatically
71       * {@link Propagator#addEventDetector(EventDetector) added} to the propagator by this
72       * constructor.
73       * </p>
74       * <p>
75       * BEWARE! Dates selectors often store internally the last selected dates, so they are not
76       * reusable across several {@link EventBasedScheduler instances}. A separate selector
77       * should be used for each scheduler.
78       * </p>
79       * @param builder builder for individual measurements
80       * @param selector selector for dates (beware that selectors are generally not
81       * reusable across several {@link EventBasedScheduler instances}, each selector should
82       * be dedicated to one scheduler
83       * @param propagator propagator associated with this scheduler
84       * @param detector detector for checking measurements feasibility
85       * @param signSemantic semantic of the detector g function sign to use
86       */
87      public EventBasedScheduler(final MeasurementBuilder<T> builder, final DatesSelector selector,
88                                 final Propagator propagator,
89                                 final EventDetector detector, final SignSemantic signSemantic) {
90          super(builder, selector);
91          this.signSemantic = signSemantic;
92          this.feasibility  = new TimeSpanMap<Boolean>(Boolean.FALSE);
93          this.forward      = true;
94          propagator.addEventDetector(new FeasibilityAdapter(detector));
95      }
96  
97      /** {@inheritDoc} */
98      @Override
99      public boolean measurementIsFeasible(final AbsoluteDate date) {
100         return feasibility.get(date);
101     }
102 
103     /** Adapter for managing feasibility status changes. */
104     private class FeasibilityAdapter extends AdapterDetector {
105 
106         /** Build an adaptor wrapping an existing detector.
107          * @param detector detector to wrap
108          */
109         FeasibilityAdapter(final EventDetector detector) {
110             super(detector);
111         }
112 
113         /** {@inheritDoc} */
114         @Override
115         public void init(final SpacecraftState s0, final AbsoluteDate t) {
116             super.init(s0, t);
117             forward     = t.compareTo(s0.getDate()) > 0;
118             feasibility = new TimeSpanMap<Boolean>(signSemantic.measurementIsFeasible(g(s0)));
119         }
120 
121         /** {@inheritDoc} */
122         @Override
123         public EventHandler getHandler() {
124 
125             final EventDetector rawDetector = getDetector();
126             final EventHandler  rawHandler  = rawDetector.getHandler();
127 
128             return (state, detector, increasing) -> {
129 
130                 // find the feasibility status AFTER the current date
131                 final boolean statusAfter = signSemantic.measurementIsFeasible(increasing ? +1 : -1);
132 
133                 // store either status or its opposite according to propagation direction
134                 if (forward) {
135                     // forward propagation
136                     feasibility.addValidAfter(statusAfter, state.getDate(), false);
137                 } else {
138                     // backward propagation
139                     feasibility.addValidBefore(!statusAfter, state.getDate(), false);
140                 }
141 
142                 // delegate to wrapped detector
143                 return rawHandler.eventOccurred(state, rawDetector, increasing);
144 
145             };
146 
147         }
148 
149     }
150 
151 }