11. RangeRateIdeal#

class RangeRateIdeal(name: str, instrument: Instrument, sigma: ArrayWUnits = None, gs_range_bias: float = None, state_definition: list = None, sequence_definition: list = None)#

Bases: Measurement

Models the ideal range rate measurement model.

It generates range-rate observables between an observer and a target. The range-rate observables are expressed in km/s and refers to the line-of-sight velocity between observer and target (plus noise, if added).

Parameters:

  • name (str) – The 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.

  • gs_range_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(`'The model name should consistently begin with 'GS``’ followed by a number and a space (e.g., ‘GS1 ``', '``GS2 ``') to designate the order of ground stations. The provided name does not adhere to this criterion.'): | Raised when the name for the measurement model is not consistent with standardized notation used across the rest of the code. :raises RuntimeError(``’multiple units are extracted from the measurements.’:py:class:`): | 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 = scb.Antenna("Antenna_for_radiometric", spice_id = Orbiter_spice_id)
Orbiter.addInstrument([antenna_sc])
Doppler_transmit_frequency = scb.ArrayWUnits(
    8.8 * 10**9, sec**-1
)

# Generate a Centroid measurement model
rangerate_sigma = scb.ArrayWUnits(1e-5, km / sec)

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

# Generate an ideal range measurement model
RangeRate_GS1 = scb.RangeRateIdeal(
    name="GS1 Ideal RangeRate Model", instrument=GS1, sigma=rangerate_sigma
)

# Write observed measurements in .json format
RangeRate_GS1.write_observed_measurements(
    target=Orbiter,
    epoch_array=epoch_array_rangerate,
    frame=J2000,
    noisy=True,
    prior_range_bias=None,
    file_name="ideal_range_rate",
)

# Read observed measurement in .json format
obs_quantities_rangerate = RangeRate_GS1.observed_measurements(
    file_name="data/dwn_data/ideal_range_rate.json", meas_name="meas_ideal", units=km / sec
)

# Generate computed measurements on a trajectory
computed_rangerate_GS1 = RangeRate_GS1.computed_measurements(
    target=Orbiter_perturbed,
    epoch_array=epoch_rangerate_GS1_et,
    frame=J2000,
)

# Compute the partials
rangerate_GS1_partials = RangeRate_GS1.compute_partials(
    target=Orbiter_perturbed, epoch_array=epoch_rangerate_GS1_et, frame=J2000
)

# Compute the residuals
residuals_rangerate_GS1 = RangeRate_GS1.residuals(observed_rangerate_GS1, computed_rangerate_GS1)

# Generate a measurement dataset
rangerate_dataset_GS1 = RangeRate_GS1.generate_measurement_dataset(
    "GS1 RangeRate",
    measurement_type="rangerate",
    target=Orbiter_perturbed,
    observed_meas=obs_quantities_rangerate,
)

Attributes

instrument

The instrument.

name

The name of the model.

sigma

Sigma of the measurement model

Methods

compute_h_tilde_dv_man(relative_state)

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate 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 rangerate measurement model with respect to the srp scaling factor (eta_srp).

compute_h_tilde_gs_location(relative_state)

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate 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 rangerate 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 rangerate 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 rangerate 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.

computed_measurements(target[, epoch_array, ...])

Compute the range rate measurement between the observer and a target spacecraft.

generate_measurement_dataset(dataset_name, ...)

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

observed_measurements(file_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.

residuals(observed_meas, computed_meas)

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

write_observed_measurements(target[, ...])

Generates synthetic measurements and write them as a .json file.
compute_h_tilde_dv_man(relative_state: ArrayWUnits) → list#

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

Parameters:

relative_state (scb.ArrayWUnits) – relative state between self and target

Returns:

The (3,) vector the partial derivatives of the measurement model by the maneuver DV components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

Notes

In theory, this partial derivative isn’t zero during thrusting, but we assume no spacecraft measurements are taken then due to power constraints, so adding an if conditional here isn’t necessary; this can be improved later if needed. relative_pos = relative_state[0:3] range_val = relative_state[0:3].norm() h_tilde = [(relative_pos[i] / range_val).values for i in range(3)]

compute_h_tilde_eta_srp() → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate measurement model with respect to the srp scaling factor (eta_srp).

Parameters:

Returns:

The (1,) scalar partial derivative of the measurement model by the position components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

compute_h_tilde_gs_location(relative_state: ArrayWUnits) → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate measurement model with respect to the ground station position components.

Parameters:

relative_state (scb.ArrayWUnits) – relative state between self and target

Returns:

The (3,) vector the partial derivatives of the measurement model by the position components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

compute_h_tilde_pos(relative_state: ArrayWUnits) → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate measurement model with respect to the position components.

Parameters:

relative_state (scb.ArrayWUnits) – relative state between self and target

Returns:

The (3,) vector the partial derivatives of the measurement model by the position components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

compute_h_tilde_range_bias() → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate measurement model with respect to the range bias.

Returns:

The (1,) vector the partial derivatives of the measurement model by the position components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

compute_h_tilde_vel(relative_state: ArrayWUnits) → list#

This method generate the portion in the h_tilde matrix relative to the partial of the ideal rangerate measurement model with respect to the velocity components.

Parameters:

relative_state (scb.ArrayWUnits) – relative state between self and target

Returns:

The (3,) vector the partial derivatives of the measurement model by the velocity components

Return type:

np.array

References

“Statistical Orbit Determination”, B. D. Tapley, B. E. Schutz, and G. H. Born, 2004 (pg. 161, eq. 4.2.6)

compute_partials(target: ~scarabaeus.spacecraft.Spacecraft.Spacecraft, epoch_array: ~scarabaeus.timeAndFrame.EpochArray.EpochArray, frame: ~scarabaeus.timeAndFrame.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: ~scarabaeus.spacecraft.Spacecraft.Spacecraft, epoch_array: ~scarabaeus.timeAndFrame.EpochArray.EpochArray = None, epoch_start: ~scarabaeus.timeAndFrame.EpochArray.EpochArray = None, epoch_end: ~scarabaeus.timeAndFrame.EpochArray.EpochArray = None, tstep: float = 1, frame: ~scarabaeus.timeAndFrame.Frame.Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False, prior_range_bias: float = None) → ArrayWFrame#

Compute the range rate measurement between the observer and a target spacecraft.

This function calculates the range rate 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 (scb.Spacecraft) – The target spacecraft for which the range rate measurement is to be computed.

  • epoch_array (scb.EpochArray, optional) – An array of epochs (times) at which the range rate measurements should be computed. If provided, it overrides epoch_start, epoch_end, and tstep.

  • epoch_start (scb.Epoch, optional) – The starting epoch for the range ratemeasurement computations. Required if epoch_array is not provided.

  • epoch_end (scb.Epoch, optional) – The ending epoch for the range ratemeasurement computations. Required if epoch_array is not provided.

  • tstep (float, optional) – The time step, in seconds, between consecutive range ratemeasurements if epoch_array is not provided. Defaults to 1 second.

  • frame (scb.Frame, optional) – The reference frame in which the range rate computation is performed.

  • noisy (bool, optional) – Whether to add noise to the computed range rate measurement. Defaults to False.

  • prior_range_bias (float, optional) – A prior bias value to add to the computed range rate measurements. Defaults to None.

  • antenna_name (str) – name of the antenna to be used for Doppler

  • transmit_frequency (scb.ArrayWUnits) – transmit frequency, used to compute the doppler count

  • receive_station (scb.GroundStation) – receiving station object for three-way doppler, defaults to None

Raises:

ValueError – An EpochArray is not provided

Returns:

The computed range rate measurement as an array with frames.

Return type:

scb.ArrayWFrame

generate_measurement_dataset(dataset_name: str, measurement_type: str, target: ~scarabaeus.body.Body.Body, observed_meas: ~scarabaeus.timeAndFrame.ArrayWFrame.ArrayWFrame = None, frame: ~scarabaeus.timeAndFrame.Frame.Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False, prior_range_bias=None) → 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]

Notes

The MeasurementDataSet output is generated in 6 steps:

  1. Computed measurements

  2. Partials

  3. Residuals

  4. Sigmas

  5. Pack everything in a list

  6. Pack the list in a MeasurementDataSet object

observed_measurements(file_name, meas_name: str = 'meas_ideal', units: ~scarabaeus.units.Units.Units = unitless, frame: ~scarabaeus.timeAndFrame.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.

Return type:

Tuple[EpochArray, numpy.ndarray, ArrayWFrame]

Notes

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

partials(target: ~scarabaeus.spacecraft.Spacecraft.Spacecraft, epoch: ~scarabaeus.timeAndFrame.EpochArray.EpochArray, frame: ~scarabaeus.timeAndFrame.Frame.Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER)) → list#

This method groups toghether the different components of measurement partials in the global H-tilde. It returns the H-tilde array for the modelled measurement.

Parameters:

  • target (scb.Body, scb.Spacecraft) – target spacecraft as scb Spacecraft/Body object

  • epoch (scb.Epoch) – epochs as scb Epoch object

  • frame (scb.Frame) – reference frame as scb Frame object

Returns:

The H-tilde array with all measurements partials from this model by component

Return type:

list

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

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, prior_range_bias: float = None, 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.

  • prior_range_bias (float, optional) – A prior bias value to add to the computed range measurements. Defaults to None.

  • file_name (str, optional) – The filename of the JSON in which the measurement is saved, Defaults to 'ideal_measurement'.

Return type:

None

ECLIPJ2000 = ECLIPJ2000 (0 - SOLAR SYSTEM BARYCENTER)#
IAUEARTH = IAU_EARTH (399 - EARTH)#
ITRF93 = ITRF93 (399 - EARTH)#
J2000 = J2000 (0 - SOLAR SYSTEM BARYCENTER)#
property instrument: Instrument#

The instrument.

property name: str#

The name of the model.

property sigma#

Sigma of the measurement model

Base:

sigma

Type:

ArrayWUnits