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.estimation.measurements;
18
19 import java.util.Arrays;
20
21 import org.hipparchus.analysis.differentiation.Gradient;
22 import org.orekit.propagation.SpacecraftState;
23 import org.orekit.time.AbsoluteDate;
24 import org.orekit.utils.Constants;
25 import org.orekit.utils.ParameterDriver;
26 import org.orekit.utils.TimeSpanMap.Span;
27 import org.orekit.utils.TimeStampedFieldPVCoordinates;
28 import org.orekit.utils.TimeStampedPVCoordinates;
29
30 /** Class modeling a range measurement from a ground station.
31 * <p>
32 * For one-way measurements, a signal is emitted by the satellite
33 * and received by the ground station. The measurement value is the
34 * elapsed time between emission and reception multiplied by c where
35 * c is the speed of light.
36 * </p>
37 * <p>
38 * For two-way measurements, the measurement is considered to be a signal
39 * emitted from a ground station, reflected on spacecraft, and received
40 * on the same ground station. Its value is the elapsed time between
41 * emission and reception multiplied by c/2 where c is the speed of light.
42 * </p>
43 * <p>
44 * The motion of both the station and the spacecraft during the signal
45 * flight time are taken into account. The date of the measurement
46 * corresponds to the reception on ground of the emitted or reflected signal.
47 * </p>
48 * <p>
49 * The clock offsets of both the ground station and the satellite are taken
50 * into account. These offsets correspond to the values that must be subtracted
51 * from station (resp. satellite) reading of time to compute the real physical
52 * date. These offsets have two effects:
53 * </p>
54 * <ul>
55 * <li>as measurement date is evaluated at reception time, the real physical date
56 * of the measurement is the observed date to which the receiving ground station
57 * clock offset is subtracted</li>
58 * <li>as range is evaluated using the total signal time of flight, for one-way
59 * measurements the observed range is the real physical signal time of flight to
60 * which (Δtg - Δts) ⨯ c is added, where Δtg (resp. Δts) is the clock offset for the
61 * receiving ground station (resp. emitting satellite). A similar effect exists in
62 * two-way measurements but it is computed as (Δtg - Δtg) ⨯ c / 2 as the same ground
63 * station clock is used for initial emission and final reception and therefore it evaluates
64 * to zero.</li>
65 * </ul>
66 * @author Thierry Ceolin
67 * @author Luc Maisonobe
68 * @author Maxime Journot
69 * @since 8.0
70 */
71 public class Range extends GroundReceiverMeasurement<Range> {
72
73 /** Type of the measurement. */
74 public static final String MEASUREMENT_TYPE = "Range";
75
76 /** Simple constructor.
77 * @param station ground station from which measurement is performed
78 * @param twoWay flag indicating whether it is a two-way measurement
79 * @param date date of the measurement
80 * @param range observed value
81 * @param sigma theoretical standard deviation
82 * @param baseWeight base weight
83 * @param satellite satellite related to this measurement
84 * @since 9.3
85 */
86 public Range(final GroundStation station, final boolean twoWay, final AbsoluteDate date,
87 final double range, final double sigma, final double baseWeight,
88 final ObservableSatellite satellite) {
89 super(station, twoWay, date, range, sigma, baseWeight, satellite);
90 }
91
92 /** {@inheritDoc} */
93 @Override
94 protected EstimatedMeasurementBase<Range> theoreticalEvaluationWithoutDerivatives(final int iteration,
95 final int evaluation,
96 final SpacecraftState[] states) {
97
98 final GroundReceiverCommonParametersWithoutDerivatives common = computeCommonParametersWithout(states[0]);
99 final TimeStampedPVCoordinates transitPV = common.getTransitState().getPVCoordinates();
100
101 // prepare the evaluation
102 final EstimatedMeasurementBase<Range> estimated;
103 final double range;
104
105 if (isTwoWay()) {
106
107 // Station at transit state date (derivatives of tauD taken into account)
108 final TimeStampedPVCoordinates stationAtTransitDate = common.getStationDownlink().shiftedBy(-common.getTauD());
109 // Uplink delay
110 final double tauU = signalTimeOfFlightAdjustableEmitter(stationAtTransitDate, transitPV.getPosition(),
111 transitPV.getDate(), common.getState().getFrame());
112 final TimeStampedPVCoordinates stationUplink = common.getStationDownlink().shiftedBy(-common.getTauD() - tauU);
113
114 // Prepare the evaluation
115 estimated = new EstimatedMeasurementBase<>(this, iteration, evaluation,
116 new SpacecraftState[] {
117 common.getTransitState()
118 }, new TimeStampedPVCoordinates[] {
119 stationUplink,
120 transitPV,
121 common.getStationDownlink()
122 });
123
124 // Range value
125 final double cOver2 = 0.5 * Constants.SPEED_OF_LIGHT;
126 final double tau = common.getTauD() + tauU;
127 range = tau * cOver2;
128
129 } else {
130
131 estimated = new EstimatedMeasurementBase<>(this, iteration, evaluation,
132 new SpacecraftState[] {
133 common.getTransitState()
134 }, new TimeStampedPVCoordinates[] {
135 transitPV,
136 common.getStationDownlink()
137 });
138
139 // Clock offsets
140 final ObservableSatellite satellite = getSatellites().get(0);
141 final double dts = satellite.getClockOffsetDriver().getValue(common.getState().getDate());
142 final double dtg = getStation().getClockOffsetDriver().getValue(common.getState().getDate());
143
144 // Range value
145 range = (common.getTauD() + dtg - dts) * Constants.SPEED_OF_LIGHT;
146
147 }
148
149 estimated.setEstimatedValue(range);
150
151 return estimated;
152
153 }
154
155 /** {@inheritDoc} */
156 @Override
157 protected EstimatedMeasurement<Range> theoreticalEvaluation(final int iteration,
158 final int evaluation,
159 final SpacecraftState[] states) {
160
161 final SpacecraftState state = states[0];
162
163 // Range derivatives are computed with respect to spacecraft state in inertial frame
164 // and station parameters
165 // ----------------------
166 //
167 // Parameters:
168 // - 0..2 - Position of the spacecraft in inertial frame
169 // - 3..5 - Velocity of the spacecraft in inertial frame
170 // - 6..n - measurements parameters (clock offset, station offsets, pole, prime meridian, sat clock offset...)
171 final GroundReceiverCommonParametersWithDerivatives common = computeCommonParametersWithDerivatives(state);
172 final int nbParams = common.getTauD().getFreeParameters();
173 final TimeStampedFieldPVCoordinates<Gradient> transitPV = common.getTransitPV();
174
175 // prepare the evaluation
176 final EstimatedMeasurement<Range> estimated;
177 final Gradient range;
178
179 if (isTwoWay()) {
180
181 // Station at transit state date (derivatives of tauD taken into account)
182 final TimeStampedFieldPVCoordinates<Gradient> stationAtTransitDate =
183 common.getStationDownlink().shiftedBy(common.getTauD().negate());
184 // Uplink delay
185 final Gradient tauU =
186 signalTimeOfFlightAdjustableEmitter(stationAtTransitDate, transitPV.getPosition(), transitPV.getDate(),
187 state.getFrame());
188 final TimeStampedFieldPVCoordinates<Gradient> stationUplink =
189 common.getStationDownlink().shiftedBy(-common.getTauD().getValue() - tauU.getValue());
190
191 // Prepare the evaluation
192 estimated = new EstimatedMeasurement<>(this, iteration, evaluation,
193 new SpacecraftState[] {
194 common.getTransitState()
195 }, new TimeStampedPVCoordinates[] {
196 stationUplink.toTimeStampedPVCoordinates(),
197 transitPV.toTimeStampedPVCoordinates(),
198 common.getStationDownlink().toTimeStampedPVCoordinates()
199 });
200
201 // Range value
202 final double cOver2 = 0.5 * Constants.SPEED_OF_LIGHT;
203 final Gradient tau = common.getTauD().add(tauU);
204 range = tau.multiply(cOver2);
205
206 } else {
207
208 estimated = new EstimatedMeasurement<>(this, iteration, evaluation,
209 new SpacecraftState[] {
210 common.getTransitState()
211 }, new TimeStampedPVCoordinates[] {
212 transitPV.toTimeStampedPVCoordinates(),
213 common.getStationDownlink().toTimeStampedPVCoordinates()
214 });
215
216 // Clock offsets
217 final ObservableSatellite satellite = getSatellites().get(0);
218 final Gradient dts = satellite.getClockOffsetDriver().getValue(nbParams, common.getIndices(), state.getDate());
219 final Gradient dtg = getStation().getClockOffsetDriver().getValue(nbParams, common.getIndices(), state.getDate());
220
221 // Range value
222 range = common.getTauD().add(dtg).subtract(dts).multiply(Constants.SPEED_OF_LIGHT);
223
224 }
225
226 estimated.setEstimatedValue(range.getValue());
227
228 // Range first order derivatives with respect to state
229 final double[] derivatives = range.getGradient();
230 estimated.setStateDerivatives(0, Arrays.copyOfRange(derivatives, 0, 6));
231
232 // Set first order derivatives with respect to parameters
233 for (final ParameterDriver driver : getParametersDrivers()) {
234 for (Span<String> span = driver.getNamesSpanMap().getFirstSpan(); span != null; span = span.next()) {
235 final Integer index = common.getIndices().get(span.getData());
236 if (index != null) {
237 estimated.setParameterDerivatives(driver, span.getStart(), derivatives[index]);
238 }
239 }
240 }
241
242 return estimated;
243
244 }
245
246 }