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
19 import java.util.ArrayList;
20 import java.util.List;
21
22 import org.hipparchus.ode.events.Action;
23 import org.orekit.propagation.SpacecraftState;
24 import org.orekit.propagation.events.handlers.EventHandler;
25 import org.orekit.time.AbsoluteDate;
26 import org.orekit.time.TimeStamped;
27
28 /** This class logs events detectors events during propagation.
29 *
30 * <p>As {@link EventDetector events detectors} are triggered during
31 * orbit propagation, an event specific {@link
32 * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
33 * method is called. This class can be used to add a global logging
34 * feature registering all events with their corresponding states in
35 * a chronological sequence (or reverse-chronological if propagation
36 * occurs backward).
37 * <p>This class works by wrapping user-provided {@link EventDetector
38 * events detectors} before they are registered to the propagator. The
39 * wrapper monitor the calls to {@link
40 * EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean) eventOccurred}
41 * and store the corresponding events as {@link LoggedEvent} instances.
42 * After propagation is complete, the user can retrieve all the events
43 * that have occurred at once by calling method {@link #getLoggedEvents()}.</p>
44 *
45 * @author Luc Maisonobe
46 */
47 public class EventsLogger {
48
49 /** List of occurred events. */
50 private final List<LoggedEvent> log;
51
52 /** Simple constructor.
53 * <p>
54 * Build an empty logger for events detectors.
55 * </p>
56 */
57 public EventsLogger() {
58 log = new ArrayList<EventsLogger.LoggedEvent>();
59 }
60
61 /** Monitor an event detector.
62 * <p>
63 * In order to monitor an event detector, it must be wrapped thanks to
64 * this method as follows:
65 * </p>
66 * <pre>
67 * Propagator propagator = new XyzPropagator(...);
68 * EventsLogger logger = new EventsLogger();
69 * EventDetector detector = new UvwDetector(...);
70 * propagator.addEventDetector(logger.monitorDetector(detector));
71 * </pre>
72 * <p>
73 * Note that the event detector returned by the {@link
74 * LoggedEvent#getEventDetector() getEventDetector} method in
75 * {@link LoggedEvent LoggedEvent} instances returned by {@link
76 * #getLoggedEvents()} are the {@code monitoredDetector} instances
77 * themselves, not the wrapping detector returned by this method.
78 * </p>
79 * @param monitoredDetector event detector to monitor
80 * @return the wrapping detector to add to the propagator
81 * @param <T> class type for the generic version
82 */
83 public <T extends EventDetector> EventDetector monitorDetector(final T monitoredDetector) {
84 return new LoggingWrapper(monitoredDetector);
85 }
86
87 /** Clear the logged events.
88 */
89 public void clearLoggedEvents() {
90 log.clear();
91 }
92
93 /** Get an immutable copy of the logged events.
94 * <p>
95 * The copy is independent of the logger. It is preserved
96 * event if the {@link #clearLoggedEvents() clearLoggedEvents} method
97 * is called and the logger reused in another propagation.
98 * </p>
99 * @return an immutable copy of the logged events
100 */
101 public List<LoggedEvent> getLoggedEvents() {
102 return new ArrayList<EventsLogger.LoggedEvent>(log);
103 }
104
105 /** Class for logged events entries. */
106 public static class LoggedEvent implements TimeStamped {
107
108 /** Event detector triggered. */
109 private final EventDetector detector;
110
111 /** Triggering state. */
112 private final SpacecraftState state;
113
114 /** Increasing/decreasing status. */
115 private final boolean increasing;
116
117 /** Simple constructor.
118 * @param detector detector for event that was triggered
119 * @param state state at event trigger date
120 * @param increasing indicator if the event switching function was increasing
121 * or decreasing at event occurrence date
122 */
123 private LoggedEvent(final EventDetector detector, final SpacecraftState state, final boolean increasing) {
124 this.detector = detector;
125 this.state = state;
126 this.increasing = increasing;
127 }
128
129 /** Get the event detector triggered.
130 * @return event detector triggered
131 */
132 public EventDetector getEventDetector() {
133 return detector;
134 }
135
136 /** {@inheritDoc} */
137 @Override
138 public AbsoluteDate getDate() {
139 return state.getDate();
140 }
141
142 /** Get the triggering state.
143 * @return triggering state
144 * @see EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean)
145 */
146 public SpacecraftState getState() {
147 return state;
148 }
149
150 /** Get the Increasing/decreasing status of the event.
151 * @return increasing/decreasing status of the event
152 * @see EventHandler#eventOccurred(SpacecraftState, EventDetector, boolean)
153 */
154 public boolean isIncreasing() {
155 return increasing;
156 }
157
158 }
159
160 /** Internal wrapper for events detectors. */
161 private class LoggingWrapper extends AbstractDetector<LoggingWrapper> {
162
163 /** Wrapped events detector. */
164 private final EventDetector detector;
165
166 /** Simple constructor.
167 * @param detector events detector to wrap
168 */
169 LoggingWrapper(final EventDetector detector) {
170 this(detector.getMaxCheckInterval(), detector.getThreshold(),
171 detector.getMaxIterationCount(), null,
172 detector);
173 }
174
175 /** Private constructor with full parameters.
176 * <p>
177 * This constructor is private as users are expected to use the builder
178 * API with the various {@code withXxx()} methods to set up the instance
179 * in a readable manner without using a huge amount of parameters.
180 * </p>
181 * @param maxCheck maximum checking interval
182 * @param threshold convergence threshold (s)
183 * @param maxIter maximum number of iterations in the event time search
184 * @param handler event handler to call at event occurrences
185 * @param detector events detector to wrap
186 * @since 6.1
187 */
188 private LoggingWrapper(final AdaptableInterval maxCheck, final double threshold,
189 final int maxIter, final EventHandler handler,
190 final EventDetector detector) {
191 super(maxCheck, threshold, maxIter, handler);
192 this.detector = detector;
193 }
194
195 /** {@inheritDoc} */
196 @Override
197 protected LoggingWrapper create(final AdaptableInterval newMaxCheck, final double newThreshold,
198 final int newMaxIter, final EventHandler newHandler) {
199 return new LoggingWrapper(newMaxCheck, newThreshold, newMaxIter, newHandler, detector);
200 }
201
202 /** Log an event.
203 * @param state state at event trigger date
204 * @param increasing indicator if the event switching function was increasing
205 */
206 public void logEvent(final SpacecraftState state, final boolean increasing) {
207 log.add(new LoggedEvent(detector, state, increasing));
208 }
209
210 /** {@inheritDoc} */
211 public void init(final SpacecraftState s0,
212 final AbsoluteDate t) {
213 super.init(s0, t);
214 detector.init(s0, t);
215 }
216
217 /** {@inheritDoc} */
218 public double g(final SpacecraftState s) {
219 return detector.g(s);
220 }
221
222 /** {@inheritDoc} */
223 public EventHandler getHandler() {
224
225 final EventHandler handler = detector.getHandler();
226
227 return new EventHandler() {
228
229 /** {@inheritDoc} */
230 public Action eventOccurred(final SpacecraftState s, final EventDetector d, final boolean increasing) {
231 logEvent(s, increasing);
232 return handler.eventOccurred(s, detector, increasing);
233 }
234
235 /** {@inheritDoc} */
236 @Override
237 public SpacecraftState resetState(final EventDetector d, final SpacecraftState oldState) {
238 return handler.resetState(detector, oldState);
239 }
240
241 };
242 }
243
244 }
245
246 }