10. RangeIdeal#

class RangeIdeal(name: str, instrument: Instrument, sigma: ArrayWUnits = None, meas_bias=None, state_definition=None, sequence_definition=None)#

Bases: Measurement

Models the ideal range measurement model. It generates ranging observables between an observer and a target. The ranging observables are expressed in km and refers to the norm of the relative position vector between the two (plus noise, if added).

Parameters:

name (str) – name of the measurement model
instrument (Instrument) – instrument object from scarabaeus. An ‘antenna’ instrument is used for radiometric measurement models.
sigma (ArrayWUnits, optional) – Measurement standard deviation. Optional, defaults to None.
meas_bias (float, optional) – ground station range bias. Optional, defaults to None.
state_definition (list, optional) – StateVector definition list. Optional, defaults to None.
sequence_definition (list, optional) – sequence definition list. Optional, defaults to None.

:raises RuntimeError(`'multiple units are extracted from the measurements.'): | Raised when the units extracted from the measurements are not consistent with each other. :raises RuntimeError(``’Please provide an EpochArray or provide start and end Epochs.’``:py:class:`): | Raised when the time on which to generate measurements is not an EpochArray object or is not passed as a begin and end pair.

See also

scarabaeus.Measurement: parent class of each specific measurement model.

Examples

# import libraries
import scarabaeus as scb

# Generate an antenna object and link it to an existing orbiter
Orbiter_spice_id = -64
antenna_sc = Antenna("Antenna_for_radiometric", spice_id = Orbiter_spice_id)
Orbiter.addInstrument([antenna_sc])
Doppler_transmit_frequency = ArrayWUnits(
    8.8 * 10**9, sec**-1
)

# Generate a Centroid measurement model
range_sigma = ArrayWUnits(1e-3, km)

# Generate a ground-station object
GS1 = GroundStation("DSS-14")

# Generate an ideal range measurement model
Range_GS1 = RangeIdeal(
    name="GS1 Ideal Range Model", instrument=GS1, sigma=range_sigma
)

# Write observed measurements in .json format
Range_GS1.write_observed_measurements(
    target=Orbiter,
    epoch_array=epoch_array_range,
    frame=J2000,
    noisy=True,
    file_name="ideal_range",
)

# Read observed measurement in .json format
obs_quantities_range = Range_GS1.observed_measurements(
    file_name="data/dwn_data/ideal_range.json", meas_name="meas_ideal", units=km
)

# Generate computed measurements on a trajectory
computed_range_GS1 = Range_GS1.computed_measurements(
    target=Orbiter_perturbed,
    epoch_array=epoch_range_GS1_et,
    frame=J2000,
)

# Compute the partials
range_GS1_partials = Range_GS1.compute_partials(
    target=Orbiter_perturbed, epoch_array=epoch_range_GS1_et, frame=J2000
)

# Compute the residuals
residuals_range_GS1 = Range_GS1.residuals(observed_range_GS1, computed_range_GS1)

# Generate a measurement dataset
range_dataset_GS1 = Range_GS1.generate_measurement_dataset(
    "GS1 Range",
    target=Orbiter_perturbed,
    observed_meas=obs_quantities_range,
)

Attributes

`instrument`	The instrument.
`name`	The name of the model.
`sigma`	Standard deviation of the measurement model.

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.
`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_h_tilde_dv_man`()	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the maneuver DV components.
`compute_h_tilde_eta_srp`()	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the srp scaling factor (eta_srp).
`compute_h_tilde_gs_delta_location`(relative_state)	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the ground station position components.
`compute_h_tilde_pos`(relative_state)	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the position components.
`compute_h_tilde_range_bias`()	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the range bias.
`compute_h_tilde_vel`(relative_state)	This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the velocity components.
`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.
`computed_measurements`(target, epoch_array, ...)	Compute the range measurement between an observer and a target.
`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.
`partials`(target, epoch, frame)	This method groups toghether the different components of measurement partials in the global H-tilde.
`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 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_h_tilde_dv_man() → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal range measurement model with respect to the maneuver DV components.

Returns:: The (3,) vector the partial derivatives of the measurement model by the position maneuver DV components
Return type:: np.array

References