4. 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 = True, eps_dict: dict = None, media_corrections: MediaCorrections | None = None)#

Bases: Measurement

Attributes

`computed_measurements_dict`	Auxiliary dictionary needed for the generation of the computed measurements
`epoch_sec`	EpochArray in seconds of day NEED MORE
`instrument`	The instrument.
`name`	The name of the model.
`sigma`	The standard deviation of the measurement model.

media_corrections

Methods

`build_perturbation_vector`(eps_override)	Constructs a 6-element perturbation vector [dx, dy, dz, dvx, dvy, dvz] as an ArrayWUnits from the given eps_override dictionary.
`compress_doppler_to_60s`(t_sec, y, *[, t0, ...])	Compress Doppler samples to 60-s bins, unless already at ~60-s spacing.
`compute_CN_lt`(receiver_pos, transmitter_id, ...)	Compute converged Newtonian one-way light time between a receiver and a transmiter at reception epoch t_rcv
`compute_GS_in_SSB_space_time_RLT`(gs_spice_id, t)	Method to compute GS state vector in a Solar System Barycentric space-time relativistic frame of reference.
`compute_RLT_BODIES_lt`(t2_t1, t3_t2, body_id, ...)	Compute Relativistic lightime delay due to different bodies.
`compute_RLT_SUN_lt`(r1_r2, r2_r3, r12_r23)	Compute Relativistic lightime delay due to the Sun.
`compute_RLT_lt`([components, r1_r2_vec, ...])	Compute Relativistic lightime delay due to the Sun and to different bodies.
`compute_delta_et_tai`(t, gs_spice_id[, method])	Method to compute the reltivistic time difference between Ephemeris Time (ET) and International Atomic Time (TAI) at a ground station on Earth.
`compute_partials`(target, epoch_array, frame)	Stacks together measurement partials for an epoch array at different epochs.
`compute_precise_RTLT`(sc_spice_id, ...)	Method to compute the precise Round-Trip Light-Time (RTLT) between a gs-based DSN antenna and a spacecraft. This method computes the RTLT for a 2-way path between: - A DSN antenna transmitting a signal at t1 - A spacecraft reflecting a signal at t2 - A DSN antenna receiving a signal at t3.
`compute_precise_RTLT_light`(sc_spice_id, ...)	Method to compute the precise Round-Trip Light-Time (RTLT) between a gs-based DSN antenna and a spacecraft.
`et_tai_debug`(t, gs_spice_id)	DEBUG Method to compute the time difference between Ephemeris Time (ET) and International Atomic Time (TAI) at a ground station on Earth.
`generate_electronic_delays_dictionary`(...)	Generate a dictionary of electronic delays as per [1]
`generate_measurement_dataset`(dataset_name, ...)	Generates a MeasurementDataSet object that can be used by filters downstream.
`get_bodies_for_RLT`(tx_h, tx_l, ...)	Generate the quantities of interest of the partecipating bodies for the GR delays
`observed_measurements`(file_name, meas_name, ...)	Reads measurements from a .json file.
`progress_monitor`(num_total[, desc, unit])	Returns a tqdm-based progress updater function.
`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.

static compute_CN_lt(receiver_pos: ndarray, transmitter_id: str, t_rcv: ndarray, delta: ndarray, way: str = 'up') → ndarray#

Compute converged Newtonian one-way light time between a receiver and a transmiter at reception epoch t_rcv

Parameters:

receiver_pos (np.ndarray) – Position of the receiving body (e.g., ground station (t3) or spacecraft (t2)).
transmitter_id (str) – Name of the emitting body (e.g., ground station (t2) or spacecraft(t3)).
t_rcv (np.ndarray) – Epoch(s) at which the signal is received [ET seconds past J2000].
delta (np.ndarray) – Perturbation vector for finite differencing [km, km/s].
way (str) – Signal path, can be “up” or “down”

Returns:

light_time – One-way geometric light time [s].

Return type:

np.ndarray

Note

All computations are internally defaulted to be executed in J2000

static compute_GS_in_SSB_space_time_RLT(gs_spice_id: str, t: float) → ndarray#

Method to compute GS state vector in a Solar System Barycentric space-time relativistic frame of reference.

Parameters:

gs_spice_id (str) – spice id string of the ground station
t (float) – time in ephemeris time

Returns:

rBC_state – State vector (velocity padded to zeros) ot the ground station

Return type:

np.ndarray

static compute_RLT_BODIES_lt(t2_t1: float, t3_t2: float, body_id, ssb_to_gs_t_31_RLT: ndarray, way: str = None, delta: ndarray = None) → ndarray#

Compute Relativistic lightime delay due to different bodies. The value computed in this method is equal to the third term of [Moyer 2000], eq.8-55. The second term corresponds to the one computed with “compute_RLT_SUN_lt”. The first term is the Newtonian component, that can be computed with “compute_CN_lt”.

Parameters:

t2_t1 (float) – Reflection time t2 (for way == ‘dwn’) or transmittion time t1 (for way == ‘up’)
t3_t2 (float) – Reception time t3 (for way == ‘dwn’) or reflection time t2 (for way == ‘up’)
ssb_to_gs_t_31_RLT (np.ndarray) – State vector (pos,vel) from SSB to GS at t3 (for way == ‘dwn’) or t1 (for way == ‘up’) in a SSB space-time relativistic frame of reference
ssb_to_gs_tx_RLTframe (np.ndarray) – State vector (pos,vel) from SSB to GS at tx in SSB space-time relativistic frame of reference
way (str) – Signal path, can be “up” for 1-2 or “dwn” for 2-3
delta (np.ndarray) – Perturbation vector for finite differencing [km, km/s]. This is used to compute the GR delay due to bodies other than the Sun.

Returns:

dt_GR_bodies – GR lightime delay due to bodies other than the Sun, as per Moyer 2000, eq.8-55

Return type:

float

static compute_RLT_SUN_lt(r1_r2: float, r2_r3: float, r12_r23: float) → float#

Compute Relativistic lightime delay due to the Sun. This effects takes into account the following General Relativity (GR) effects: 1) Curvature of the lightpath due to gravity 2) Reduction in the coordinate of the speed of light The value computed in this method is equal to the second term of [Moyer 2000], eq.8-55

Parameters:

r1_r2 (float) – Position vector. For way == ‘dwn’, r1_r2 is the norm of the position vector from the Sun to the spacecraft at reflection time t2. For way == ‘up’, r1_r2 is the norm of the position vector from the Sun to the ground-station at reception time t3.
r2_r3 (float) – Position vector. For way == ‘dwn’, r2_r3 is the norm of the position vector from the Sun to the ground-station at reception time t3. For way == ‘up’, r2_r3 is the norm of the position vector from the Sun to the spacecraft at reflection time t2.
r12_r23 (float) – Norm of the position vector difference between r2 and r1 or r3 and r2. See Moyer 2000, eq.8-57 and eq.8-58

Returns:

dt_GR – One-Way GR lightime delay [s]

Return type:

float

static compute_RLT_lt(components: str = 'RLT', r1_r2_vec: ndarray = None, r2_r3_vec: ndarray = None, t2_t1: float = None, t3_t2: float = None, sc_spice_id: str = None, ssb_to_gs_t_31_RLT: ndarray = None, way: str = None, delta: ndarray = None) → ndarray#

Compute Relativistic lightime delay due to the Sun and to different bodies. The value computed in this method is equal to the second and third terms of [Moyer 2000], eq.8-55. The second term corresponds to the one computed with “compute_RLT_SUN_lt”. The third term corresponds to the one computed with “compute_RLT_BODIES_lt”.

Parameters:

components (str) – input to control whether ‘SUN’,
r1_r2_vec (np.ndarray) – Position vector. For way == ‘dwn’, r1_r2_vec is the position vector from the body to the spacecraft at reflection time t2. For way == ‘up’, r1_r2_vec is the position vector from the body to the ground-station at reception time t3.
r2_r3_vec (np.ndarray) – Position vector. For way == ‘dwn’, r2_r3_vec is the position vector from the body to the ground-station at reception time t3. For way == ‘up’, r2_r3_vec is the position vector from the body to the spacecraft at reflection time t2.
t2_t1 (float) – Reflection time t2 (for way == ‘dwn’) or transmission time t1 (for way == ‘up’)
t3_t2 (float) – Reception time t3 (for way == ‘dwn’) or reflection time t2 (for way == ‘up’)
sc_spice_id (str) – Spice ID of the spacecraft
ssb_to_gs_t_31_RLT (np.ndarray) – State vector (pos,vel) from SSB to GS at t3 (for way == ‘dwn’) or t1 (for way == ‘up’) in a SSB space-time relativistic frame of reference
way (str) – Signal path, can be “up” for 1-2 or “dwn” for 2-3
delta (np.ndarray) – Perturbation vector for finite differencing [km, km/s]. This is used to compute the GR delay due to bodies other than the Sun.

Returns:

dt_GR_bodies (float) – GR lightime delay due to bodies and the Sun, as per Moyer 2000, eq.8-55
r32_r21_vec (np.ndarray) – r32 vector (for way == ‘dwn’) or r21 vector (for way == ‘up’). Used to determine convergence in the Moyer’s 32-steps algorithm for precise RTLT.

Note

for way == ‘dwn’:: r2_r1_vec = r2_vec = sun_to_sc_t2 r3_r2_vec = r3_vec = sun_to_gs_t3 r23_r12_vec = r32_vec = gs_to_sc (t3-t2), not defined in time
for way == ‘up’:: r2_r1_vec = r1_vec = sun_to_gs_t1 r3_r2_vec = r2_vec = sun_to_sc_t2 r23_r12_vec = r12_vec = sc_to_gs (t2-t1), not defined in time

static compute_delta_et_tai(t, gs_spice_id, method: int = 1) → ndarray#

Method to compute the reltivistic time difference between Ephemeris Time (ET) and International Atomic Time (TAI) at a ground station on Earth.

Parameters:

t (float) – ephemeris time when to compute the correction term
gs_spice_id (str) – spice id string of the ground station
method (int) – Method to be used amongst 1 (simplified), 2 (Vector expression, with GS in J2000), 3 (Vector expression, with GS in J2000 SSB relativisti space-time reference)

Returns:

dt – time difference in seconds between ET and TAI at a given epoch

Return type:

float

static compute_precise_RTLT(sc_spice_id: str, gs_spice_id: str, tt_et: float, electronic_delays_dict: dict, solar_corona_dict: dict, delta_partials: ArrayWUnits, gs_delta_awf: ArrayWFrame | None) → ndarray#

Method to compute the precise Round-Trip Light-Time (RTLT) between a gs-based DSN antenna and a spacecraft. This method computes the RTLT for a 2-way path between:

A DSN antenna transmitting a signal at t1

A spacecraft reflecting a signal at t2

A DSN antenna receiving a signal at t3

implement the necessary time delays between transmittion from a gs at (t1) and reception at the same gs at (t3).

Parameters:

sc_spice_id (str) – spice id string of the spacecraft
gs_spice_id (str) – spice id string of the ground station
tt_et (float) – time-tag in ephemeris time of the reception time at the gs (t3)
electronic_delays_dict (dict) – dictionary of electronic delays
solar_corona_dict (dict) – dictionary of solar corona parameters
delta (ArrayWUnits) – delta vector for position and velocity. Used to generate numeric partials

Returns:

rtlt (float) – Sum of the rtlt delays components as a single delay value in second between t1 and t3
rtlt_parts (np.array(17,1)) – rtlt decomposed in its components, expressed in seconds
gs_delta_awf (ArrayWFrame | None) – If not None, this is the delta vector for the ground station in the SSB space-time relativistic frame of reference.

Notes

See also the method SpiceManager.get_state_precise() which needs integer and fractional time for precise ephemeris retrivial

[1]: “TRK-2-34, DSN Tracking System Data Archival Format”, DSN No. 820-013, TRK-2-34, Rev. N

static compute_precise_RTLT_light(sc_spice_id: str, gs_spice_id: str, tt_et: float, electronic_delays_dict: dict, solar_corona_dict: dict, delta_partials: ArrayWUnits) → ndarray#

Method to compute the precise Round-Trip Light-Time (RTLT) between a gs-based DSN antenna and a spacecraft. Light variant, not following the Moyer 32 steps algorithm in Moyer 2000, Sec. 8.3.6

This method computes the RTLT for a 2-way path between:

A DSN antenna transmitting a signal at t1

A spacecraft reflecting a signal at t2

A DSN antenna receiving a signal at t3

implement the necessary time delays between transmittion from a gs at (t1) and reception at the same gs at (t3).

Parameters:

sc_spice_id (str) – spice id string of the spacecraft
gs_spice_id (str) – spice id string of the ground station
tt_et (float) – time-tag in ephemeris time of the reception time at the gs (t3)
electronic_delays_dict (dict) – dictionary of electronic delays
solar_corona_dict (dict) – dictionary of solar corona parameters
delta (ArrayWUnits) – delta vector for position and velocity. Used to generate numeric partials

Returns:

rtlt (float) – Sum of the rtlt delays components as a single delay value in second between t1 and t3
rtlt_parts (np.array(17,1)) – rtlt decomposed in its components, expressed in seconds

Notes

See also the method SpiceManager.get_state_precise() which needs integer and fractional time for precise ephemeris retrivial

[1]: “TRK-2-34, DSN Tracking System Data Archival Format”, DSN No. 820-013, TRK-2-34, Rev. N

static et_tai_debug(t: float, gs_spice_id: str) → ndarray#

DEBUG Method to compute the time difference between Ephemeris Time (ET) and International Atomic Time (TAI) at a ground station on Earth.

Parameters:

t (float) – ephemeris time at which to compute the time correction
gs_spice_id (str) – spice id string of the ground station

Returns:

t_et (float) – adjusted ephemeris times
dt (float) – et-tai correction
X_A_E (np.ndarray) – Ground station state

static generate_electronic_delays_dictionary(aux_dict, idx)#

Generate a dictionary of electronic delays as per [1]

Parameters:

aux_dict (dict) – Dictionary of auxiliary parameters for the computed measurements
ul_freq_i (float) – frequency to use in the seconds-to-RU conversion factor

Returns:

sranging_calib_corr – Value of the 2-way sequential ranging correction term in [1], Note 39.

Return type:

float

Notes

[1]: “TRK-2-34, DSN Tracking System Data Archival Format”, DSN No. 820-013, TRK-2-34, Rev. N

static get_bodies_for_RLT(tx_h: float, tx_l: float, ssb_to_gs_tx_RLTframe: ndarray)#

Generate the quantities of interest of the partecipating bodies for the GR delays

Parameters:

tx_h (float) – Integer part of the time tx at which to compute the geometric vectors
tx_l (float) – Fractional part of the time tx at which to compute the geometric vectors
ssb_to_gs_tx_RLTframe (np.ndarray) – State vector (pos,vel) from SSB to GS at tx in the SSB space-time relativistic frame of reference

Returns:

earth_to_gs_tx (np.ndarray) – state vector (pos,vel) from Earth to the GS at tx in J2000
moon_to_gs_tx (np.ndarray) – state vector (pos,vel) from the Moon to the GS at tx in J2000
mars_to_gs_tx (np.ndarray) – state vector (pos,vel) from Mars to the GS at tx in J2000
jupiter_to_gs_tx (np.ndarray) – state vector (pos,vel) from Jupiter to the GS at tx in J2000
saturn_to_gs_tx (np.ndarray) – state vector (pos,vel) from Saturn to the GS at tx in J2000

static progress_monitor(num_total: int, desc: str = 'Processing', unit: str = 'obs')#

Returns a tqdm-based progress updater function.

Parameters:

num_total (int) – Total number of items to process.
desc (str) – Description for the tqdm bar.
unit (str) – Unit label (e.g., ‘obs’, ‘steps’).

Returns:

update_fn (Callable[[int], None]) – A function to call with the current index.
close_fn (Callable[[], None]) – A function to finalize and close the bar.

build_perturbation_vector(eps_override: dict) → ArrayWUnits#

Constructs a 6-element perturbation vector [dx, dy, dz, dvx, dvy, dvz] as an ArrayWUnits from the given eps_override dictionary.

Parameters:: eps_override (dict) – Dictionary with keys like ‘dx’, ‘dvy’, etc., each mapped to an ArrayWUnits.
Returns:: delta – 1x6 perturbation vector with units.
Return type:: ArrayWUnits

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

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 = None, noisy: bool = False, file_name: str = 'ideal_measurement') → 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'.

Return type:

None

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

property epoch_sec: EpochArray#: EpochArray in seconds of day NEED MORE

property instrument: Instrument#: The instrument.

property media_corrections: MediaCorrections | None#

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

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

4. DopplerReal#

This Page