`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.

Generates ranging observables between an observer and a target. The observable is expressed in km and equals the Euclidean distance between spacecraft and ground station (plus noise, if added).

Assuming no light-time delay and no media effects, the range is

\[\rho = \|\mathbf{r}_{sc}(t) - \mathbf{r}_{gs}(t)\|_2\]

where \(\mathbf{r}_{sc}\) and \(\mathbf{r}_{gs}\) are the inertial position vectors of the spacecraft and ground station respectively.

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. Defaults to None.
meas_bias (float, optional) – Ground station range bias. Defaults to None.
state_definition (list, optional) – StateVector definition list. Defaults to None.
sequence_definition (list, optional) – Sequence definition list. Defaults to None.

Raises:

RuntimeError – If the units extracted from the measurements are not consistent.
RuntimeError – If neither an EpochArray nor start/end Epochs are provided.

See also

scarabaeus.Measurement: Abstract base class for all measurement models.

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,
    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: Measurement noise standard deviation.

Methods

`compute_partials`(target, epoch_array, frame)	Stacks together measurement _partials for an epoch array at different epochs.
`computed_measurements`(target, epoch_array, ...)	Compute the range measurement between an observer and a target.
`generate_measurement_dataset`(dataset_name, ...)	Generates a MeasurementDataSet object that can be used by filters downstream.
`observed_measurements`(file_name, meas_name)	Load range measurements from a .json file.
`residuals`(observed_meas, computed_meas)	Generates the measurement model's residuals given observed and computed ArrayWFrames.
`set_pass_epochs`(pass_epochs)	Enable per-pass range biases.
`set_pass_index`(mapping)	Directly assign a pre-built `{epoch_value: pass_index}` mapping (or None to disable).
`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.

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, pass_epochs: list[list] | None = None) → ArrayWFrame#

Compute the range measurement between an observer and a target.

This function calculates the range measurement (distance) from the current spacecraft to a specified target spacecraft, taking into account optional parameters like specific epochs, time steps, reference frame, and noise settings.

Parameters:

target (Spacecraft) – The target spacecraft for which the range measurement is to be computed.
epoch_array (EpochArray) – An array of epochs (times) at which the range 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 range computation is performed.
noisy (bool) – Whether to add noise to the computed range measurement. Defaults to False.
antenna_name (str) – name of the antenna to be used for Doppler
ransmit_frequency (ArrayWUnits) – transmit frequency, used to compute the doppler count
receive_station (GroundStation) – receiving station object for three-way doppler, defaults to None

Returns:

The computed range measurement as an array with frames.

Return type:

ArrayWFrame

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=None, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), pass_epochs: list[list] | None = None)#

Load range measurements from a .json file.

pass_epochslist[list[float]], optional: Observation epochs grouped by tracking pass, e.g. [[t0, t1, t2], [t10, t11]]. Must be provided when the state vector contains a stacked range_bias_<suffix> entry (dim > 1).

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

set_pass_epochs(pass_epochs: list[list] | None)#

Enable per-pass range biases.

Parameters:: pass_epochs (list[list[float]] | None) – Observation epochs grouped by pass, e.g. [[t0, t1], [t10, t11]]. Pass None to revert to global-bias mode.

set_pass_index(mapping: dict | None)#: Directly assign a pre-built {epoch_value: pass_index} mapping (or None to disable).

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 instrument: Instrument#: The instrument.

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

property sigma: ArrayWUnits#: Measurement noise standard deviation.

RangeIdeal#

`RangeIdeal`#