`DopplerReal`#

class DopplerReal(name: str, instrument: Instrument, sigma: ArrayWUnits = None, meas_bias=None, state_definition=None, sequence_definition=None, epoch_sec=None, computed_measurements_dict=None, partials_finite_diff: bool = False, eps_dict: dict = None, media_corrections: MediaCorrections | None = None)#

Bases: Measurement

Models the real Doppler measurement model.

Generates computed Doppler observables between a DSN ground station and a spacecraft using the precise round-trip light-time (RTLT) formulation, including relativistic corrections and optional media corrections. Observables are expressed in Hz.

Count-interval observable

The measurement epoch \(t_3\) is the signal reception time. The count interval \(T_c\) defines a window \([t_{3,s},\,t_{3,e}] = [t_3 - T_c/2,\; t_3 + T_c/2]\). The precise RTLT back-propagates each endpoint to the uplink times \(t_{1,s}\) and \(t_{1,e}\).

The Doppler observable (Moyer 2000, Sec. 13.2) is

\[f_D = -\frac{M_2}{T_c} \int_{t_{1,s}}^{t_{1,e}} f_T(t)\, dt + b_{f_D}\]

where \(f_T(t)\) is the piecewise-linear uplink ramp frequency integrated via the ramp table, \(M_2 = M_{2,num}/M_{2,den}\) is the spacecraft transponder turn-around ratio, and \(b_{f_D}\) is an optional station Doppler bias (Hz).

Media corrections

When a MediaCorrections object is attached, the signed excess path delays at the count-interval endpoints (Moyer eq. 10-28, 10-29) are

\[\Delta\tau_{s/e} = \frac{1}{c}\bigl( p_{tropo,t_3} - p_{iono,t_3} + p_{tropo,t_1} - p_{iono,t_1} \bigr)_{s/e}\]

and the media-corrected observable becomes (Moyer eq. 13-58):

\[f_D^{corr} = f_D + \frac{M_2}{T_c} \bigl(f_{T,e}\,\Delta\tau_e - f_{T,s}\,\Delta\tau_s\bigr)\]

Note that the ionospheric contribution enters with a negative sign for Doppler (opposite to sequential ranging).

Parameters:

name (str) – Name of the measurement model.
instrument (Instrument) – Ground station or antenna instrument (e.g. GroundStation).
sigma (ArrayWUnits, optional) – Measurement standard deviation. Defaults to None.
meas_bias (numpy.ndarray, optional) – Range-rate bias of the ground station. Defaults to None.
state_definition (list, optional) – StateVector definition list. Defaults to None.
sequence_definition (list, optional) – Sequence definition list. Defaults to None.
epoch_sec (EpochArray, optional) – Epoch expressed in seconds of day. Defaults to None.
computed_measurements_dict (dict, optional) – Auxiliary dictionary for computed-measurement generation. Defaults to None.
partials_finite_diff (bool, optional) – When True, _partials are computed via finite differences. Defaults to False.
eps_dict (dict, optional) – Perturbation magnitudes for finite-difference _partials. Defaults to None.
media_corrections (MediaCorrections, optional) – Media-correction object (troposphere / ionosphere). Defaults to None.

See also

scarabaeus.Measurement: Abstract base class for all measurement models.
scarabaeus.SequentialRangingReal: Companion real ranging model.
scarabaeus.MediaCorrections: Tropospheric and ionospheric path-delay model.

Attributes:

computed_measurements_dict: Auxiliary dictionary needed for the generation of the computed measurements
epoch_sec: Observation epochs expressed as seconds of day.
instrument: The instrument.
media_corrections: Tropospheric and ionospheric path-delay model, or None if not set.
name: The name of the model.
sigma: The standard deviation of the measurement model.

Methods

`compress_doppler_to_60s`(t_sec, y, *[, t0, ...])	Compress Doppler samples to 60-s bins, unless already at ~60-s spacing.
`compute_partials`(target, epoch_array, frame)	Stacks together measurement _partials for an epoch array at different epochs.
`computed_measurements`(target, epoch_array, ...)	Generate the computed two-way DSN doppler measurement.
`generate_measurement_dataset`(dataset_name, ...)	Generates a MeasurementDataSet object that can be used by filters downstream.
`observed_measurements`(file_name, meas_name, ...)	Reads measurements from a .json file.
`residuals`(observed_meas, computed_meas)	Generates the measurement model's residuals given observed and computed ArrayWFrames.
`update_reference_state`(state_vector)	Call this once per iteration (before generate_measurement_dataset). The model will pull: - meas_bias_ideal_* (as ArrayWUnits) - gs_delta_location_ECEF_* (as ArrayWFrame) for this instrument (matching spice_id).
`write_observed_measurements`(target, ...)	Generates synthetic measurements and write them as a .json file.

static compress_doppler_to_60s(t_sec, y, *, t0=None, agg='mean', sample_dt=None, min_coverage=0.8)#

Compress Doppler samples to 60-s bins, unless already at ~60-s spacing.

Parameters:

t_sec (array-like) – Sample mid-times [s].
y (array-like) – Observable per sample (e.g., Hz). NaNs are ignored.
t0 (float or None) – Bin alignment epoch [s]. If None, uses floor(min(t)/60)*60.
agg (str) – Aggregation method for 1-s input: “mean”,”median”,”sum”,”min”,”max”.
sample_dt (float or None) – Nominal spacing of input samples. If None, it is estimated from median diff.
min_coverage (float) – Required fraction of expected samples (60/sample_dt). If coverage is lower, output value is set to NaN.

Returns:

t60_mid (np.ndarray) – 60-s bin mid-times [s].
y60 (np.ndarray) – Aggregated values per bin.
n_used (np.ndarray) – Number of samples per bin.

compute_partials(target: Spacecraft, epoch_array: EpochArray, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER)) → list#

Stacks together measurement _partials for an epoch array at different epochs.

Parameters:

target (Spacecraft) – The target spacecraft.
epoch_array (EpochArray) – The epochs.
frame (Frame, optional) – The reference frame. Defaults to a J2000 Frame object.

Returns:

_partials – A list with all the _partials evaluated at different epochs in the epoch_array.

Return type:

list

computed_measurements(target: Spacecraft, epoch_array: EpochArray = None, epoch_start: EpochArray = None, epoch_end: EpochArray = None, tstep: float = 1, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False, eps_override: dict = None) → ArrayWFrame#

Generate the computed two-way DSN doppler measurement.

Parameters:

target (Spacecraft) – target spacecraft for the two-way measurement model
epoch_array (EpochArray) – An array of epochs (times) at which the measurements should be computed. If provided, it overrides epoch_start, epoch_end, and tstep.
epoch_start (Epoch) – The starting epoch for the range measurement computations. Required if epoch_array is not provided.
epoch_end (Epoch) – The ending epoch for the range measurement computations. Required if epoch_array is not provided.
tstep (float) – The time step, in seconds, between consecutive range measurements. If epoch_array is not provided. Defaults to 1 second.
frame (Frame) – The reference frame in which the measurement is generated.
noisy (bool) – Whether to add noise to the computed range measurement. Defaults to False.
eps_override (dict) – Dictionary of delta’s to compute the numeric _partials

Returns:

computed_meas – An ArrayWFrame object with the computed measurement values expressed in Hz

Return type:

ArrayWFrame

:raises TypeError(`'The noise model can't be used on a computed model of :py:class:`a real measurement.’): | Raised when noise is enabled on a computed model of a real measurement type

Notes

This model has been developed following the details in Moyer 2000. [1]: “TRK-2-34, DSN Tracking System Data Archival Format”, DSN No. 820-013, TRK-2-34, Rev. N

generate_measurement_dataset(dataset_name: str, target: Body, observed_meas: tuple | list | None = None, epochs: EpochArray | None = None, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False) → list[MeasurementDataSet]#

Generates a MeasurementDataSet object that can be used by filters downstream.

Parameters:

dataset_name (str) – The name of the MeasurementDataSet.
target (Spacecraft) – The target spacecraft.
epoch_list (EpochArray, optional) – The epochs. Defaults to None.
epoch_start (EpochArray, optional) – The starting epoch. Defaults to None.
epoch_end (EpochArray, optional) – The end epoch. Defaults to None.
tstep (int, optional) – The integration timestep. Defaults to 1.
observed_measurements (list, optional) – The observed measurements. Defaults to None.
frame (Frame, optional) – The reference frame. Defaults to a J2000 Frame object.
noisy (bool, optional) – Indicates if noise is added to the measurements or not. Defaults to False.

Returns:

mds_list – A list of MeasurementDataSet objects representing the measurements with their key properties to be used by a filter.

Return type:

list[MeasurementDataSet]

:raises If the observed_meas list is only made by 3 elements`, it throws an error because it needs the 4th element in the list for the indices of :py:class:`the outlier_flag:

Notes

The MeasurementDataSet output is generated in 6 steps:

Computed measurements
Partials
Residuals
Sigmas
Outlier flag
Pack everything in a list
Pack the list in a MeasurementDataSet object

observed_measurements(file_name, meas_name: str = 'meas_ideal', units: Units = unitless, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER)) → Tuple[EpochArray, ndarray, ArrayWFrame]#

Reads measurements from a .json file.

Parameters:

file_name (str) – The filename of the .json file containig the measurement information.
meas_name (str, optional) – The name of the measurement data to access from the dictionary. Defaults to 'meas_ideal'.
units (Units, optional) – Units to be used to write the output AWU. Defaults to unitless.
frame (Frame, optional) – Frame to be used to write the output AWF. Defaults to a J2000 Frame object.

Returns:

meas_time_et, meas_sec, meas_obs – A tuple with the following values corresponding to their respective indices:

[0] = meas_time_etEpochArray
The time in ephemeris time.
[1] = meas_Secnumpy.ndarray
The times in seconds.
[2] = meas_obsArrayWFrame
An AWF with the quantities in AWU.
[3] = meas_outliersnumpy.ndarray
The np.array of measurements outliers

Return type:

Tuple[EpochArray, numpy.ndarray, ArrayWFrame]

Notes

The writing of the json assumes or requires units and frames.

residuals(observed_meas: ArrayWFrame, computed_meas: ArrayWFrame) → ArrayWFrame#

Generates the measurement model’s residuals given observed and computed ArrayWFrames.

Parameters:

observed_meas (ArrayWFrame) – The observed measurements values (O).
computed_meas (ArrayWFrame) – The computed measurements values (C).

Returns:

residuals – AWF with the residual O-C.

Return type:

ArrayWFrame

update_reference_state(state_vector: StateArray)#

Call this once per iteration (before generate_measurement_dataset). The model will pull:

meas_bias_ideal_* (as ArrayWUnits)

gs_delta_location_ECEF_* (as ArrayWFrame)

for this instrument (matching spice_id).

write_observed_measurements(target: Spacecraft, epoch_array: EpochArray = None, epoch_start: EpochArray = None, epoch_end: EpochArray = None, tstep: float = 1, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False, file_name: str = 'ideal_measurement', check_visibility: bool = False, elevation_mask: float = 10.0, folder_path_override: str = None) → None#

Generates synthetic measurements and write them as a .json file. The input of this method encapsulate the ones needed for the “computed_meas” method in each measurement model class.

Parameters:

target (Spacecraft) – The target spacecraft for which the range measurement is to be computed.
epoch_array (EpochArray, optional) – An array of epochs (times) at which the range measurements should be computed. If provided, overrides epoch_start, epoch_end, and tstep.
epoch_start (EpochArray, optional) – The starting epoch for the range measurement computations. Required if epoch_array is not provided.
epoch_end (EpochArray, optional) – The ending epoch for the range measurement computations. Required if epoch_array is not provided.
tstep (float, optional) – The time step, in seconds, between consecutive range measurements. If epoch_array is not provided. Defaults to 1 second.
frame (Frame , optional) – The reference frame in which the range computation is performed. Defaults to None.
noisy (bool , optional) – Whether to add noise to the computed range measurement. Defaults to False.
file_name (str, optional) – The filename of the JSON in which the measurement is saved, Defaults to 'ideal_measurement'.
check_visibility (bool, optional) – When True, epochs where the instrument cannot observe the target are removed before generating measurements. The specific check is instrument-dependent: GroundStation uses an elevation-angle test; Camera uses a FOV projection test. Defaults to False.
elevation_mask (float, optional) – Minimum elevation angle in degrees used by the GroundStation visibility check. Ignored for Camera instruments. Only relevant when check_visibility=True. Defaults to 10.0.
folder_path_override (str, optional) – If provided, the JSON file is saved directly to this path instead of the default data/measurements/radiometric or data/measurements/optical folder. The directory is created automatically if it does not exist. Defaults to None.

Return type:

None

property computed_measurements_dict: dict#: Auxiliary dictionary needed for the generation of the computed measurements

property epoch_sec: EpochArray#: Observation epochs expressed as seconds of day.

property instrument: Instrument#: The instrument.

property media_corrections: MediaCorrections | None#: Tropospheric and ionospheric path-delay model, or None if not set.

property name: str#: The name of the model.

property sigma: ArrayWUnits#: The standard deviation of the measurement model.

DopplerReal#

`DopplerReal`#