1 /* Copyright 2002-2025 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 org.hipparchus.ode.events.Action;
20 import org.hipparchus.util.FastMath;
21 import org.hipparchus.util.MathUtils;
22 import org.orekit.frames.Frame;
23 import org.orekit.orbits.KeplerianOrbit;
24 import org.orekit.orbits.Orbit;
25 import org.orekit.orbits.OrbitType;
26 import org.orekit.orbits.PositionAngleType;
27 import org.orekit.propagation.SpacecraftState;
28 import org.orekit.propagation.events.handlers.EventHandler;
29 import org.orekit.propagation.events.handlers.StopOnIncreasing;
30 import org.orekit.propagation.events.intervals.AdaptableInterval;
31
32 /** Finder for node crossing events.
33 * <p>This class finds equator crossing events (i.e. ascending
34 * or descending node crossing).</p>
35 * <p>The default implementation behavior is to {@link Action#CONTINUE continue}
36 * propagation at descending node crossing and to {@link Action#STOP stop} propagation
37 * at ascending node crossing. This can be changed by calling
38 * {@link #withHandler(EventHandler)} after construction.</p>
39 * <p>Beware that node detection will fail for almost equatorial orbits. If
40 * for example a node detector is used to trigger an {@link
41 * org.orekit.forces.maneuvers.ImpulseManeuver ImpulseManeuver} and the maneuver
42 * turn the orbit plane to equator, then the detector may completely fail just
43 * after the maneuver has been performed! This is a real case that has been
44 * encountered during validation ...</p>
45 * @see org.orekit.propagation.Propagator#addEventDetector(EventDetector)
46 * @author Luc Maisonobe
47 */
48 public class NodeDetector extends AbstractDetector<NodeDetector> {
49
50 /** Default max check interval. */
51 private static final double DEFAULT_MAX_CHECK = 1800.0;
52
53 /** Default convergence threshold. */
54 private static final double DEFAULT_THRESHOLD = 1.0e-3;
55
56 /** Frame in which the equator is defined. */
57 private final Frame frame;
58
59 /** Build a new instance.
60 * <p>The default {@link #getMaxCheckInterval() max check interval}
61 * is set to 1800s, it can be changed using {@link #withMaxCheck(double)}
62 * in the fluent API. The default {@link #getThreshold() convergence threshold}
63 * is set to 1.0e-3s, it can be changed using {@link #withThreshold(double)}
64 * in the fluent API.</p>
65 * @param frame frame in which the equator is defined (typical
66 * values are {@link org.orekit.frames.FramesFactory#getEME2000() EME<sub>2000</sub>} or
67 * {@link org.orekit.frames.FramesFactory#getITRF(org.orekit.utils.IERSConventions, boolean) ITRF})
68 * @since 10.3
69 */
70 public NodeDetector(final Frame frame) {
71 this(new EventDetectionSettings(DEFAULT_MAX_CHECK, DEFAULT_THRESHOLD, EventDetectionSettings.DEFAULT_MAX_ITER),
72 new StopOnIncreasing(), frame);
73 }
74
75 /** Build a new instance.
76 * <p>The orbit is used only to set an upper bound for the max check interval
77 * to a value related to nodes separation (as computed by a Keplerian model)
78 * and to set the convergence threshold according to orbit size.</p>
79 * @param orbit initial orbit
80 * @param frame frame in which the equator is defined (typical
81 * values are {@link org.orekit.frames.FramesFactory#getEME2000() EME<sub>2000</sub>} or
82 * {@link org.orekit.frames.FramesFactory#getITRF(org.orekit.utils.IERSConventions, boolean) ITRF})
83 */
84 public NodeDetector(final Orbit orbit, final Frame frame) {
85 this(1.0e-13 * orbit.getKeplerianPeriod(), orbit, frame);
86 }
87
88 /** Build a new instance.
89 * <p>The orbit is used only to set an upper bound for the max check interval
90 * to a value related to nodes separation (as computed by a Keplerian model).</p>
91 * @param threshold convergence threshold (s)
92 * @param orbit initial orbit
93 * @param frame frame in which the equator is defined (typical
94 * values are {@link org.orekit.frames.FramesFactory#getEME2000() EME<sub>2000</sub>} or
95 * {@link org.orekit.frames.FramesFactory#getITRF(org.orekit.utils.IERSConventions, boolean) ITRF})
96 */
97 public NodeDetector(final double threshold, final Orbit orbit, final Frame frame) {
98 this(new EventDetectionSettings(AdaptableInterval.of(2 * estimateNodesTimeSeparation(orbit) / 3), threshold,
99 DEFAULT_MAX_ITER), new StopOnIncreasing(),
100 frame);
101 }
102
103 /** Protected constructor with full parameters.
104 * <p>
105 * This constructor is not public as users are expected to use the builder
106 * API with the various {@code withXxx()} methods to set up the instance
107 * in a readable manner without using a huge amount of parameters.
108 * </p>
109 * @param detectionSettings detection settings
110 * @param handler event handler to call at event occurrences
111 * @param frame frame in which the equator is defined (typical
112 * values are {@link org.orekit.frames.FramesFactory#getEME2000() EME<sub>2000</sub>} or
113 * {@link org.orekit.frames.FramesFactory#getITRF(org.orekit.utils.IERSConventions, boolean) ITRF})
114 * @since 12.2
115 */
116 protected NodeDetector(final EventDetectionSettings detectionSettings, final EventHandler handler,
117 final Frame frame) {
118 super(detectionSettings, handler);
119 this.frame = frame;
120 }
121
122 /** {@inheritDoc} */
123 @Override
124 protected NodeDetector create(final EventDetectionSettings detectionSettings, final EventHandler newHandler) {
125 return new NodeDetector(detectionSettings, newHandler, frame);
126 }
127
128 /** Find time separation between nodes.
129 * <p>
130 * The estimation of time separation is based on Keplerian motion, it is only
131 * used as a rough guess for a safe setting of default max check interval for
132 * event detection.
133 * </p>
134 * @param orbit initial orbit
135 * @return minimum time separation between nodes
136 */
137 private static double estimateNodesTimeSeparation(final Orbit orbit) {
138
139 final KeplerianOrbit keplerian = (KeplerianOrbit) OrbitType.KEPLERIAN.convertType(orbit);
140
141 // mean anomaly of ascending node
142 final double ascendingM = new KeplerianOrbit(keplerian.getA(), keplerian.getE(),
143 keplerian.getI(),
144 keplerian.getPerigeeArgument(),
145 keplerian.getRightAscensionOfAscendingNode(),
146 -keplerian.getPerigeeArgument(), PositionAngleType.TRUE,
147 keplerian.getFrame(), keplerian.getDate(),
148 keplerian.getMu()).getMeanAnomaly();
149
150 // mean anomaly of descending node
151 final double descendingM = new KeplerianOrbit(keplerian.getA(), keplerian.getE(),
152 keplerian.getI(),
153 keplerian.getPerigeeArgument(),
154 keplerian.getRightAscensionOfAscendingNode(),
155 FastMath.PI - keplerian.getPerigeeArgument(), PositionAngleType.TRUE,
156 keplerian.getFrame(), keplerian.getDate(),
157 keplerian.getMu()).getMeanAnomaly();
158
159 // differences between mean anomalies
160 final double delta1 = MathUtils.normalizeAngle(ascendingM, descendingM + FastMath.PI) - descendingM;
161 final double delta2 = 2 * FastMath.PI - delta1;
162
163 // minimum time separation between the two nodes
164 return FastMath.min(delta1, delta2) / keplerian.getKeplerianMeanMotion();
165
166 }
167
168 /** Get the frame in which the equator is defined.
169 * @return the frame in which the equator is defined
170 */
171 public Frame getFrame() {
172 return frame;
173 }
174
175 /** Compute the value of the switching function.
176 * This function computes the Z position in the defined frame.
177 * @param s the current state information: date, kinematics, attitude
178 * @return value of the switching function
179 */
180 public double g(final SpacecraftState s) {
181 return s.getPosition(frame).getZ();
182 }
183
184 }