viability

In many cases, whether an observation at a given time should be realized will depend on a number of constraints that must be satisfied. We have termed such constraints ‘observation viability conditions’ in Tudat. The functions in this module are used create objects of type ObservationViabilitySettings that contain settings for these viability conditions. 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 viability_settings_list attribute, or by using the add_viability_check_to_all(), add_viability_check_to_observable() and add_viability_check_to_observable_for_link_ends() functions (which are functions of convenience to add the same ancillary settings to a set of observation simulation settings)

As an example, an observation_simulation_settings_list can be modified such that only observations above a 15 degree elevation angle at New Norcia (NNO) are accepted:

from tudatpy.estimation.observations_setup import viability
from tudatpy.estimation.observable_models_setup import links
import numpy as np

# Create list of observation simulation settings (list[observations_simulation_settings.ObservationSimulationSettings])
observation_simulation_settings_list = ...

station_id = links.body_reference_point_link_end_id("Earth", "NNO")
viability_settings_list = list()
viability_settings_list.append(
    viability.elevation_angle_viability(
        station_id,
        np.deg2rad(15.0)
    )
)
viability.add_viability_check_to_all(
    observation_simulation_settings_list,
    viability_settings_list
)

Functions

elevation_angle_viability(link_end_id, ...)

Function for defining single elevation angle viability setting.

body_avoidance_viability(link_end_id, ...)

Function for defining body avoidance observation viability settings.

body_occultation_viability(link_end_id, ...)

Function for defining body occultation viability settings.

elevation_angle_viability_list(link_end_ids, ...)

Function for defining list of elevation angle viability settings, equivalent to a series of calls to elevation_angle_viability().

body_avoidance_viability_list(link_end_ids, ...)

Function for defining list of body avoidance viability settings, equivalent to a series of calls to body_avoidance_viability().

body_occultation_viability_list(...)

Function for defining body occultation viability settingsFunction for defining list of body avoidance viability settings, equivalent to a series of calls to body_occultation_viability().

add_viability_check_to_all(...)

Function for including viability checks into existing observation simulation settings.

add_viability_check_to_observable(...)

Function for including viability checks into existing observation simulation settings.

add_viability_check_to_observable_for_link_ends(...)

Function for including viability checks into existing observation simulation settings.
elevation_angle_viability(link_end_id: tuple[str, str], elevation_angle: float | SupportsIndex) → tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings

Function for defining single elevation angle viability setting.

Function for defining elevation angle viability settings for single link end. When simulating observations, this setting ensures that any applicable observations for which the local elevation angle at link end link_end_id is less than some limit value, will be omitted. Note that for (for instance) a two-way observable where the given link_end_id acts as both receiver and transmitter, the check will be performed both at reception and transmission time, and the observation will only be accepted if the elevation angle is sufficient at both epochs.

The elevation angle used by this functionality can also be computed manually using this calculate_elevation_angle() function of the :class:~tudatpy.dynamics.environment.PointingAnglesCalculator` class, which can be extracted from a GroundStation object using pointing_angles_calculator()

Parameters:

  • link_end_id (tuple[str,str]) – Link end (as defined by body/reference point pair, see LinkEndId), for which the elevation angle viability setting is to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”].

  • elevation_angle (float) – Limit elevation angle, below which no observations are produced when using the simulate_observations() function. Note: this value must be in radians.

Returns:

Instance of the ObservationViabilitySettings class, defining the settings for observation viability

Return type:

ObservationViabilitySettings

body_avoidance_viability(link_end_id: tuple[str, str], body_to_avoid: str, avoidance_angle: float | SupportsIndex) → tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings

Function for defining body avoidance observation viability settings.

Function for defining body avoidance observation viability settings for single link ends. When simulating observations, this settings ensures that any applicable observations, for which the signal path passes ‘too close’ to a body, will be omitted. The definition of ‘too close’ is computed as the angle between:

  • The line-of-sight vector from a link end to a given third body

  • The line-of-sight between two link ends

This constraint is typically used to prevent the Sun from being too close to the field-of-view of the telescope(s), as defined by a so-called ‘SPE’ (Sun-Probe-Earth) angle constraint. The present viability setting generalizes this constraint.

The epoch at which the avoided body is evaluated is computed in an identical way as the epoch at which the occulted body is evaluated (see body_occultation_viability())

Parameters:

  • link_end_id (tuple[str,str]) – Link end (as defined by body/reference point pair, see LinkEndId ), for which the viability settings are to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”] is entry in this list. For each link end included in this list, it will be checked if a signal received by and/or transmitted (or reflected) by this link end passes too close to the specified body.

  • body_to_avoid (str) – Name of the body which the signal path should not pass ‘too close’ to.

  • avoidance_angle (float) – Limit angle (generalization of SPE angle), below which no observations are produced when using the simulate_observations() function. Note: this value must be in radians.

Returns:

Instance of the ObservationViabilitySettings, defining the settings for observation viability.

Return type:

ObservationViabilitySettings

body_occultation_viability(link_end_id: tuple[str, str], occulting_body: str) → tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings

Function for defining body occultation viability settings.

Function for defining body occultation viability settings for single link ends. When simulating observations, this setting ensures that any applicable observations, for which the signal path is occulted by a given body, will be omitted. The occultation is computed using the shape model of the specified body, using a spherical body approximation (using average_radius attribute of the shape model).

The epoch \(t_{\text{occ}}\) a which the ephemeris \(\mathbf{r}_{\text{occ}}\) of the occulting_body is evaluated to compute the occultation is defined as follows:

\[\begin{split}{r}_{\text{occ},1}&=||r_{\text{occ}}(t_{1})-\mathbf{r}_{1}(t_{1})||\\ {r}_{\text{occ},2}&=||r_{\text{occ}}(t_{2})-\mathbf{r}_{2}(t_{2})||\\ t_{\text{occ}}&=t_{1}\frac{{r}_{\text{occ},2}}{{r}_{\text{occ},1}+{r}_{\text{occ},2}}+t_{2}\frac{{r}_{\text{occ},1}}{{r}_{\text{occ},1}+{r}_{\text{occ},2}}\end{split}\]

for a link between link ends 1 and 2 (and transmission/reception epochs \(t_{1}\) and \(t_{2}\))

Parameters:

  • link_end_id (tuple[str,str]) – Link end (as defined by body/reference point pair, see LinkEndId), for which the viability settings are to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”] is entry in this list.

  • body_to_avoid (str) – Name of the body which the signal path should not be occulted by.

Returns:

Instance of the ObservationViabilitySettings, defining the settings for observation viability.

Return type:

ObservationViabilitySettings

elevation_angle_viability_list(link_end_ids: list[tuple[str, str]], elevation_angle: float | SupportsIndex) → list[tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings]

Function for defining list of elevation angle viability settings, equivalent to a series of calls to elevation_angle_viability().

Parameters:

  • link_end_ids (List[ tuple[str,str] ]) – List of individual link ends (as defined by body/reference point pair, see LinkEndId), for which the elevation angle viability setting is to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”]. For each link end included in this list, it will be checked if a signal received by and/or transmitted (or reflected) by this link end violates the minimum elevation angle constraint.

  • elevation_angle (float) – Limit elevation angle, below which no observations are produced when using the simulate_observations() function. Note: this value must be in radians.

Returns:

List of ObservationViabilitySettings objects, each defining the settings for observation viability of one link end.

Return type:

ObservationViabilitySettings

body_avoidance_viability_list(link_end_ids: list[tuple[str, str]], body_to_avoid: str, avoidance_angle: float | SupportsIndex) → list[tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings]

Function for defining list of body avoidance viability settings, equivalent to a series of calls to body_avoidance_viability().

Parameters:

  • link_end_ids (List[ tuple[str,str] ]) – List of individual link ends (as defined by body/reference point pair, see LinkEndId), for which the elevation angle viability setting is to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”].

  • body_to_avoid (str) – Name of the body which the signal path should not pass ‘too close’ to.

  • avoidance_angle (float) – Limit angle (generalization of SPE angle), below which no observations are produced when using the simulate_observations() function. Note: this value must be in radians.

Returns:

List of ObservationViabilitySettings objects, each defining the settings for observation viability of one link end.

Return type:

ObservationViabilitySettings

body_occultation_viability_list(link_end_ids: list[tuple[str, str]], occulting_body: str) → list[tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings]

Function for defining body occultation viability settingsFunction for defining list of body avoidance viability settings, equivalent to a series of calls to body_occultation_viability().

Parameters:

  • link_end_ids (List[ tuple[str,str] ]) – List of individual link ends (as defined by body/reference point pair, see LinkEndId), for which the viability settings are to be created. To apply these settings to all ground station on a given body (such as “Earth”), use [“Earth”, “”] is entry in this list. For each link end included in this list, it will be checked if a signal received by and/or transmitted (or reflected) by this link end is occulted by the specified body.

  • body_to_avoid (str) – Name of the body which the signal path should not be occulted by.

Returns:

List of ObservationViabilitySettings objects, each defining the settings for observation viability of one link end.

Return type:

ObservationViabilitySettings

add_viability_check_to_all(observation_simulation_settings_list: list[tudatpy.kernel.estimation.observations_setup.observations_simulation_settings.ObservationSimulationSettings], viability_settings: list[tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings]) → None

Function for including viability checks into existing observation simulation settings.

Function for adding viability checks to the observation simulation settings, such that only observations meeting certain conditions are retained. The viability settings are added to all ObservationSimulationSettings object(s) in the observation_simulation_settings_list list. Note: the ObservationSimulationSettings objects are modified in-place by this function, and thus the function does not return anything.

Parameters:
Returns:

The ObservationSimulationSettings object(s) are changed in-place.

Return type:

None

add_viability_check_to_observable(observation_simulation_settings_list: list[tudatpy.kernel.estimation.observations_setup.observations_simulation_settings.ObservationSimulationSettings], viability_settings: list[tudatpy.kernel.estimation.observations_setup.viability.ObservationViabilitySettings], observable_type: tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType) → None

Function for including viability checks into existing observation simulation settings.

As add_viability_check_to_all(), except that the function only adds viability settings to entries of the observation_simulation_settings_list list that matches the specified observable_type.

Parameters:
Returns:

The ObservationSimulationSettings object(s) are changed in-place.

Return type:

None

Function for including viability checks into existing observation simulation settings.

As add_viability_check_to_all(), except that the function only adds viability settings to entries of the observation_simulation_settings_list list that matches the specified observable_type and link_ends.

Parameters:
Return type:

None

Enumerations

ObservationViabilityType

Enumeration of observation viability criterion types.
class ObservationViabilityType

Bases: pybind11_object

Enumeration of observation viability criterion types.

Examples

# Code snippet to print all available Observation Viability Types
from tudatpy.estimation.observations_setup import viability

num_observation_viability_types = len(viability.ObservationViabilityType.__members__)
print(f'The length of all available Tudatpy Observation Viability Types is: {num_observation_viability_types}')

# Print all available Observation Viability Types using the "name" property
for i in range(num_observation_viability_types):
    print(i, viability.ObservationViabilityType(i).name)

Members:

minimum_elevation_angle

body_avoidance_angle

body_occultation

ObservationViabilityType.name -> str

Classes

ObservationViabilitySettings

Class for defining observation viability calculator settings.
class ObservationViabilitySettings

Bases: pybind11_object

Class for defining observation viability calculator settings.

Class for defining the settings for observation viability calculator creation. Instances of this class are typically be created through various dedicated functions,such as elevation_angle_viability(), body_avoidance_viability() and body_occultation_viability()

Examples

# Code snippet to show the creation of an ObservationViabilitySettings object
import numpy as np
from tudatpy.estimation.observations_setup import viability

# Create ObservationViabilitySettings object
# In this case, we exclude observations for which the local elevation angle at link end is less 15 degrees.
min_elevation = np.deg2rad(15)
# We apply these settings to every ground station on Earth using the following link_end_id: [“Earth”, “”]
viability_settings = viability.elevation_angle_viability(["Earth", ""], min_elevation)

# Show that this is indeed an ObservationViabilitySettings object
print(viability_settings)