ancillary_settings¶

Some observation models require or can use additional quantities in addition to the time tag as input to the calculation of an observable, such a retransmission delay or a frequency band. In Tudat, we call these quantities ancillary settings. The functions in this module are used create objects of type ObservationAncillarySimulationSettings that contain these quantities. The full list of types on ancillary data that can be stored in this object is defined by the ObservationAncillarySimulationVariable enum. The main interface with Tudat is that these objects are can be added to ObservationSimulationSettings objects, which are in turn used as input to observation simulation (see observations_simulation_settings). The ancillary settings can be set in these objects directly using the ancillary_settings attribute, or by using the add_ancillary_settings_to_observable() and add_ancillary_settings_to_observable_for_link_ends() functions (which are functions of convenience to add the same ancillary settings to a set of observation simulation settings)

This module provides two manners in which to create ancillary settings objects:

# Code snippet to show the creation of an ObservationAncillarySimulationSettings object
from tudatpy.estimation.observations_setup import ancillary_settings

# Example 1: Create ObservationAncillarySimulationSettings object using ancillary_settings.n_way_range_ancillary_settings function
# In this case the frequency bands of the retransmitter - we set it to x band.
n_way_range_ancillary_settings = ancillary_settings.n_way_range_ancillary_settings(frequency_bands=[ancillary_settings.FrequencyBands.x_band])

# Show that this is indeed an ObservationAncillarySimulationSettings object
print(n_way_range_ancillary_settings)

# Example 2: Create ObservationAncillarySimulationSettings object using ancillary_settings.doppler_ancillary_settings function
# In this case the integration time (in seconds) has to be given as input - we set it to 60s
doppler_ancillary_settings = ancillary_settings.doppler_ancillary_settings(60)

# Show that this is indeed an ObservationAncillarySimulationSettings object
print(doppler_ancillary_settings)

Functions¶

doppler_ancillary_settings([integration_time])

Function for creating ancillary settings for averaged Doppler observable.

two_way_range_ancillary_settings([...])

Function for creating ancillary settings for two-way range observable.

two_way_doppler_ancillary_settings([...])

Function for creating ancillary settings for two-way averaged Doppler observable.

n_way_range_ancillary_settings(...)

Function for creating ancillary settings for n-way range observable.

n_way_doppler_ancillary_settings(...)

Function for creating ancillary settings for n-way averaged Doppler observable.

dsn_n_way_range_ancillary_settings(...)

Function for creating ancillary settings for DSN n-way range observable (dsn_n_way_range()).

dsn_n_way_doppler_ancillary_settings(...)

Function for creating ancillary settings for DSN n-way averaged Doppler observable (dsn_n_way_doppler_averaged()).

doppler_measured_frequency_ancillary_settings(...)

Function for creating ancillary settings for two-way Doppler frequency observable (two_way_doppler_instantaneous_frequency()).

add_ancillary_settings_to_observable(...)

Add ancillary settings to all observation simulation settings of a given observable type.

add_ancillary_settings_to_observable_for_link_ends(...)

Add ancillary settings to observation simulation settings for a specific observable type and link ends.

dsn_default_turnaround_ratios(uplink_band, ...)

Get the default DSN turnaround ratio for given uplink and downlink bands.

cassini_turnaround_ratios(uplink_band, ...)

Get the Cassini turnaround ratio for given uplink and downlink bands.
doppler_ancillary_settings(integration_time: float | SupportsIndex = 60.0) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for averaged Doppler observable.

Function for creating ancillary settings for an averaged Doppler observable. Specifically, this function can be used to create settings for the integration time \(\Delta t\) of the observable (see doppler_integration_time). Note: in case no retransmission delays (or other additional ancillary settings) are to be defined, this setting may be used for one-, two-, or N-way averaged Doppler.

Parameters:

integration_time (float, default = 60.0) – Integration time that is to be used for the averaged Doppler observable

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

ObservationAncillarySimulationSettings

two_way_range_ancillary_settings(retransmission_delay: float | SupportsIndex = 0.0) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for two-way range observable.

Function for creating ancillary settings for a two-way range observable. Specifically, this function can be used to create settings for the retransmission delay of the observable (see link_ends_delays). Note: this function is provided for convenience, and is equivalent to calling n_way_range_ancillary_settings() with a single retransmission delay.

Parameters:

retransmission_delay (float, default = 0.0) – Retransmission delay that is to be applied to the simulation of the two-way observable

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

ObservationAncillarySimulationSettings

two_way_doppler_ancillary_settings(integration_time: float | SupportsIndex = 60.0, retransmission_delay: float | SupportsIndex = 0.0) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for two-way averaged Doppler observable.

Function for creating ancillary settings for a two-way range observable. Specifically, this function can be used to create settings for the retransmission delay of the observable (see link_ends_delays). Note: this function is provided for convenience, and is equivalent to calling n_way_doppler_ancillary_settings() with a single retransmission delay.

Parameters:

  • integration_time (float, default = 60.0) – Integration time that is to be used for the averaged Doppler observable

  • retransmission_delay (float, default = 0.0) – Retransmission delay that is to be applied to the simulation of the two-way observable

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

ObservationAncillarySimulationSettings

n_way_range_ancillary_settings(link_end_delays: list[float | SupportsIndex] = [], frequency_bands: list[tudat::observation_models::FrequencyBands] = []) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for n-way range observable.

Function for creating ancillary settings for a n-way range observable. Specifically, this function can be used to create settings for the retransmission delays of the observable (see link_ends_delays), for each of the retransmitters.

Parameters:

retransmission_delays (list[ float ], default = None) – Retransmission delays that are to be applied to the simulation of the n-way observable. If kept empty, this results in 0 retransmission delay at each retransmitter. If defined, this list must be the same length as the number of retransmitters, and the \(i^{th}\) entry contains the retransmission delay of the \(i^{th}\) retrasmitter

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

ObservationAncillarySimulationSettings

n_way_doppler_ancillary_settings(integration_time: float | SupportsIndex = 60.0, link_end_delays: list[float | SupportsIndex] = [], frequency_bands: list[tudat::observation_models::FrequencyBands] = []) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for n-way averaged Doppler observable.

Function for creating ancillary settings for a n-way averaged Doppler observable. Specifically, this function can be used to create settings for the integration time of the observable (see doppler_integration_time), and the retransmission delays for each of the retransmitters (see link_ends_delays).

Parameters:

  • integration_time (float, default = 60.0) – Integration time that is to be used for the averaged Doppler observable

  • retransmission_delays (list[ float ], default = None) – Retransmission delays that are to be applied to the simulation of the n-way observable. If kept empty, this results in 0 retransmission delay at each retransmitter. If defined, this list must be the same length as the number of retransmitters, and the \(i^{th}\) entry contains the retransmission delay of the \(i^{th}\) retrasmitter

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

ObservationAncillarySimulationSettings

dsn_n_way_range_ancillary_settings(frequency_bands: list[tudat::observation_models::FrequencyBands], lowest_ranging_component: float | typing.SupportsIndex, link_end_delays: list[float | typing.SupportsIndex] = []) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for DSN n-way range observable (dsn_n_way_range()).

Parameters:
Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

tudatpy.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings

dsn_n_way_doppler_ancillary_settings(frequency_bands: list[tudat::observation_models::FrequencyBands], reference_frequency_band: tudat::observation_models::FrequencyBands, reference_frequency: float | typing.SupportsIndex, integration_time: float | typing.SupportsIndex = 60.0, link_end_delays: list[float | typing.SupportsIndex] = []) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for DSN n-way averaged Doppler observable (dsn_n_way_doppler_averaged()).

Parameters:
Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

tudatpy.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings

doppler_measured_frequency_ancillary_settings(frequency_bands: list[tudat::observation_models::FrequencyBands]) → tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings¶

Function for creating ancillary settings for two-way Doppler frequency observable (two_way_doppler_instantaneous_frequency()).

Parameters:

frequency_bands (list[tudatpy.estimation.observations_setup.ancillary_settings.FrequencyBands]) – List of frequency bands for each link.

Returns:

Instance of the ObservationAncillarySimulationSettings with the required settings.

Return type:

tudatpy.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings

add_ancillary_settings_to_observable(observation_simulation_settings_list: list[tudat::simulation_setup::ObservationSimulationSettings<tudat::Time>], ancillary_settings: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, observable_type: tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType) → None¶

Add ancillary settings to all observation simulation settings of a given observable type.

Parameters:

  • observation_simulation_settings_list (list[tudatpy.estimation.observations_setup.ObservationSimulationSettings]) – List of observation simulation settings to modify.

  • ancillary_settings (ObservationAncillarySimulationSettings) – Ancillary settings to add.

  • observable_type (ObservableType) – Observable type for which to add the ancillary settings.

Add ancillary settings to observation simulation settings for a specific observable type and link ends.

Parameters:

  • observation_simulation_settings_list (list[tudatpy.estimation.observations_setup.ObservationSimulationSettings]) – List of observation simulation settings to modify.

  • ancillary_settings (ObservationAncillarySimulationSettings) – Ancillary settings to add.

  • observable_type (ObservableType) – Observable type for which to add the ancillary settings.

  • link_ends (LinkDefinition) – Link ends for which to add the ancillary settings.

dsn_default_turnaround_ratios(uplink_band: tudatpy.kernel.estimation.observations_setup.ancillary_settings.FrequencyBands, downlink_band: tudatpy.kernel.estimation.observations_setup.ancillary_settings.FrequencyBands) → float¶

Get the default DSN turnaround ratio for given uplink and downlink bands.

Parameters:
Returns:

The turnaround ratio.

Return type:

float

cassini_turnaround_ratios(uplink_band: tudatpy.kernel.estimation.observations_setup.ancillary_settings.FrequencyBands, downlink_band: tudatpy.kernel.estimation.observations_setup.ancillary_settings.FrequencyBands) → float¶

Get the Cassini turnaround ratio for given uplink and downlink bands.

This function returns the specific Ka-band turnaround ratio for Cassini if both bands are Ka-band, otherwise it falls back to the DSN default turnaround ratios.

Parameters:
Returns:

The turnaround ratio.

Return type:

float

Enumerations¶

ObservationAncillarySimulationVariable

Enumeration of observation ancillary variable types.

ObservationIntermediateSimulationVariable

Enumeration of observation intermediate variable types.

FrequencyBands

Enumeration of frequency bands.
class ObservationAncillarySimulationVariable¶

Bases: pybind11_object

Enumeration of observation ancillary variable types.

Members:

link_ends_delays :

Retransmission delays at the retransmitter link ends (in seconds), typically for an n-way range or Doppler observation. For a set of link ends consisting of \(N\) one-way link ends (for instance transmitter->``retransmitter``->``receiver`` for \(N=2\), this ancillary setting is a list of length \(N-1\) representing the time in seconds between signal reception and subsequent retransmission/reflection at a link end. This ancillary setting is retrieved and set using the get_float_list_settings and set_float_list_settings

doppler_integration_time :

Time interval \(\Delta t\) in seconds over which averaged Doppler observables (see model_settings for _averaged observation models) are averaged. This quantity is also termed the count time. This ancillary setting is retrieved and set using the get_float_settings and set_float_settings

doppler_reference_frequency :

Reference frequency \(f_{\text{ref}}\) w.r.t. which the Doppler observable is computed for the dsn_n_way_doppler_averaged() observation model. This ancillary setting is retrieved and set using the get_float_settings and set_float_settings

frequency_bands :

Frequency bands for the up and down-link of a radio observable, used to compute the turnaround ratio \(M_{2}\) at the retransmitter (so that the received frequency \(f_{1}\) and the retransmitted frequency \(f_{2}\) are related as \(f_{2}=M_{2}\cdot f_{1}\). This ancillary setting is retrieved and set using the get_float_list_settings and set_float_list_settings the mapping of the FrequencyBands enum to integers (with s-band equal to 1, x-band to 1, ku band to 2, ka-band to 3). So, for an s-band up and x-band downlink, this ancillary setting gets the value [0, 1]

reception_reference_frequency_band :

Receiver reference frequency band w.r.t. which the reference turnaround ratio \(M_{2,R}\) is computed for the dsn_n_way_doppler_averaged() observation model. This ancillary setting is retrieved and set using the get_float_settings and set_float_settings

sequential_range_lowest_ranging_component :

Lowest sequential ranging component \(n\) used for the dsn_n_way_range() observation model. This ancillary setting is retrieved and set using the get_float_settings and set_float_settings

ObservationAncillarySimulationVariable.name -> str
class ObservationIntermediateSimulationVariable¶

Bases: pybind11_object

Enumeration of observation intermediate variable types.

This enum lists variables that are computed during the observation simulation process and can be stored for later analysis.

Members:

transmitter_frequency_intermediate

received_frequency_intermediate

ObservationIntermediateSimulationVariable.name -> str
class FrequencyBands¶

Bases: pybind11_object

Enumeration of frequency bands.

This enum lists common frequency bands used in deep space navigation.

Members:

s_band

x_band

ka_band

ku_band

FrequencyBands.name -> str

Classes¶

ObservationAncillarySimulationSettings

Class for holding ancillary settings for observation simulation (see module level documentation for typical usage and creation).
class ObservationAncillarySimulationSettings¶

Bases: pybind11_object

Class for holding ancillary settings for observation simulation (see module level documentation for typical usage and creation).

This class holds both single-valued (float) and multi-valued (list of floats) ancillary settings

get_float_list_settings(self: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, setting_type: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationVariable, throw_exception: bool = True) → list[float]¶

Function to retrieve a multi-valued (list of float) ancillary setting value

Parameters:

  • setting_type (ObservationAncillarySimulationVariable) – Type of the setting for which the value is to be returned

  • throw_exception (bool, default = false) – Boolean defining whether to throw an exception if the requested setting does not exist, or does not exist as list of floating point values.

Returns:

Value of the requested ancillary variable (or empty list if it does not exist and throw_exception is false)

Return type:

list[ float ]

Examples

# Code snippet to show how to retrieve ObservationAncillarySimulationSettings info
# using the ObservationAncillarySimulationSettings.get_float_settings function

from tudatpy.estimation.observations_setup import ancillary_settings

# Create Ancillary Settings
n_way_range_ancillary_settings = ancillary_settings.n_way_range_ancillary_settings(frequency_bands=[ancillary_settings.FrequencyBands.x_band])

# Verify that we indeed added Frequency Bands as Ancillary Simulation Variables, using n_way_range_ancillary_settings.get_float_list_settings
list_num = n_way_range_ancillary_settings.get_float_list_settings(ancillary_settings.ObservationAncillarySimulationVariable.frequency_bands)
for num in list_num:
    name = ancillary_settings.ObservationAncillarySimulationVariable(int(num)).name
    print(f'Ancillary Simulation Variable(s): {name}, corresponding to enumeration object n. {int(num)} of the ObservationAncillarySimulationVariable Enumeration')
get_float_settings(self: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, setting_type: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationVariable, throw_exception: bool = True) → float¶

Function to retrieve a single-valued (float) ancillary setting value

Parameters:

  • setting_type (ObservationAncillarySimulationVariable) – Type of the setting for which the value is to be returned

  • throw_exception (bool, default = false) – Boolean defining whether to throw an exception if the requested setting does not exist, or does not exist as a floating point value.

Returns:

Value of the requested ancillary variable (or NaN if it does not exist and throw_exception is false)

Return type:

float

set_float_list_settings(self: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, variable: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationVariable, value: list[float | SupportsIndex]) → None¶

Function to set a single-valued ancillary setting value in this object

Parameters:
set_float_settings(self: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, variable: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationVariable, value: float | SupportsIndex) → None¶

Function to set a multi-valued ancillary setting in this object

Parameters:
set_intermediate_double_data(self: tudatpy.kernel.estimation.observations_setup.ancillary_settings.ObservationAncillarySimulationSettings, variable: tudat::observation_models::ObservationIntermediateSimulationVariable, value: float | SupportsIndex) → None¶