space_time

This module contains settings and helper functions for configuring space-time metric models used in relativistic dynamics.

The main interface with Tudat is the space_time_settings attribute (of type SpaceTimePropertiesSettings) of the body-list settings. The functions in this submodule are used to create these settings objects. When creating a system of bodies (typically using the create_system_of_bodies() function), an object of type SpaceTimeProperties is created and attached to the resulting space_time_properties attribute.

Unlike most submodules in environment_setup, the settings in this module are global to the full SystemOfBodies (not properties of individual Body objects). The resulting space-time properties are used by relativistic models such as relativistic_correction(), einstein_infeld_hofmann(), and relativistic time-converter setup functions (direct_relativistic_time_converter_settings(), set_relativistic_time_converters()).

The following code block gives an overview of the steps to define, create, and extract system-level space-time properties:

from tudatpy.dynamics import environment_setup

# Create body settings
body_settings = environment_setup.get_default_body_settings( ... )

# Define global space-time settings (base class type SpaceTimePropertiesSettings)
body_settings.space_time_settings = environment_setup.space_time.space_time_properties_settings(
    metric_settings=environment_setup.space_time.solar_system_metric_settings(
        first_order_bodies=["Sun", "Earth"],
        second_order_bodies=["Sun"]),
    ppn_parameter_set=environment_setup.space_time.ppn_parameter_set(
        parameter_gamma=1.0,
        parameter_beta=1.0 ) )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract global space-time properties from the SystemOfBodies
space_time_properties = bodies.space_time_properties

Functions

ppn_parameter_set([parameter_gamma, ...])	Create settings for PPN parameters used by system-level space-time properties.
space_time_properties_settings([...])	Create settings for system-level space-time properties.
schwarzschild_metric_settings(body[, ...])	Create settings for a harmonic Schwarzschild metric.
solar_system_metric_settings(first_order_bodies)	Create settings for a solar-system post-Newtonian metric.

ppn_parameter_set(parameter_gamma: float | SupportsIndex = 1.0, parameter_beta: float | SupportsIndex = 1.0, parameter_epsilon: float | SupportsIndex = 0.0) → tudatpy.kernel.dynamics.environment_setup.space_time.PPNParameterSet

Create settings for PPN parameters used by system-level space-time properties.

The returned object is typically assigned to ppn_parameter_set, which is then used to build space_time_properties.

Parameters:

• parameter_gamma (float, optional) – First-order PPN parameter \(\gamma\).

• parameter_beta (float, optional) – First-order PPN parameter \(\beta\).

• parameter_epsilon (float, optional) – Second-order post-Newtonian parameter \(\epsilon\).

Returns:

Settings object for PPN parameters.

Return type:

PPNParameterSet

space_time_properties_settings(metric_settings: tudatpy.kernel.dynamics.environment_setup.space_time.SpaceTimeMetricSettings = None, ppn_parameter_set: tudatpy.kernel.dynamics.environment_setup.space_time.PPNParameterSet = None, equivalence_principle_lpi_violation_parameter: float | SupportsIndex = 0.0) → tudatpy.kernel.dynamics.environment_setup.space_time.SpaceTimePropertiesSettings

Create settings for system-level space-time properties.

This function creates a SpaceTimePropertiesSettings object that is assigned to space_time_settings. During create_system_of_bodies(), these settings define space_time_properties.

Parameters:

• metric_settings (SpaceTimeMetricSettings, optional) – Settings that define the base metric model to be used.

• ppn_parameter_set (PPNParameterSet, optional) – PPN parameter settings used by relativistic models.

• equivalence_principle_lpi_violation_parameter (float, optional) – Local-position-invariance violation parameter for equivalence-principle models.

Returns:

Settings object used to initialize SystemOfBodies.space_time_properties.

Return type:

SpaceTimePropertiesSettings

schwarzschild_metric_settings(body: str, include_second_post_newtonian_order: bool = False) → tudatpy.kernel.dynamics.environment_setup.space_time.SchwarzschildSpaceTimeMetricSettings

Create settings for a harmonic Schwarzschild metric.

The implemented covariant metric perturbation is

\[h_{00} = 2\frac{U}{c^2} - 2\beta\frac{U^2}{c^4}\]

\[h_{ij} = 2\gamma\frac{U}{c^2}\delta_{ij} + 2\epsilon\frac{U^2}{c^4}\delta_{ij}\]

\[h_{0i} = 0\]

where \(U=\mu/r\) is the central-body potential, \(\mu=GM\), \(r\) is the distance from the central body, \(c\) is the speed of light, \(\delta_{ij}\) is the Kronecker delta, and \(\beta,\gamma,\epsilon\) are the PPN parameters.

Parameters:

• body (str) – Name of the central gravitating body used in the metric.

• include_second_post_newtonian_order (bool, optional) – If true, include second post-Newtonian terms.

Returns:

Settings object for the Schwarzschild metric model. This can be assigned to SpaceTimePropertiesSettings.metric_settings.

Return type:

SchwarzschildSpaceTimeMetricSettings

solar_system_metric_settings(first_order_bodies: list[str], second_order_bodies: list[str] = [], spherical_harmonic_expansions: dict[str, tuple[int | SupportsIndex, int | SupportsIndex]] = {}, angular_momentum_bodies: list[str] = [], use_body_accelerations: bool = True) → tudatpy.kernel.dynamics.environment_setup.space_time.SolarSystemSpaceTimeMetricSettings

Create settings for a solar-system post-Newtonian metric.

The implemented metric uses the standard post-Newtonian decomposition with scalar potential \(w\) and vector potential \(\mathbf{w}\). The formulation follows the IAU-relativistic framework conventions summarized by Soffel et al. [22].

\[h_{00} = 2\frac{w}{c^2} - 2\beta\frac{w^2}{c^4}\]

\[h_{0i} = -2(\gamma + 1)\frac{w_i}{c^3}\]

\[h_{ij} = 2\gamma\frac{w}{c^2}\delta_{ij} + 2(\gamma^2 + \beta - 1)\frac{\left(w_{\mathrm{(2)}}\right)^2}{c^4}\delta_{ij} + 2(\gamma + 1)\frac{q_{ij}}{c^4}\]

In Tudat, these quantities are evaluated as

\[w = \sum_{a\in\mathcal{F}} w_a\]

\[\begin{split}w_a = \begin{cases} \mu_a/R_a, & \text{point-mass term}, \\ U_a^{\mathrm{SH}}, & \text{if spherical-harmonic expansion is configured}, \end{cases}\end{split}\]

\[\mathbf{w} = \sum_{a\in\mathcal{F}} w_a\,\mathbf{v}_a - \sum_{k\in\mathcal{A}} \frac{G}{2R_k^3}\left(\mathbf{S}_k\times\mathbf{r}_k\right)\]

\[w_i = (\mathbf{w})_i\]

\[\left(w_{\mathrm{(2)}}\right)^2 = \sum_{b\in\mathcal{S}} \left(w_b\right)^2\]

\[q_{ij} = \sum_{b\in\mathcal{S}} q^{(b)}_{ij}\]

\[q^{(b)}_{ij} = \frac{\mu_b^2}{4R_b^2} \left(\frac{r_{b,i}r_{b,j}}{R_b^2} - \delta_{ij}\right)\]

where \(\mathcal{F}\) is the set of bodies in first_order_bodies, \(\mathcal{S}\) is the set of bodies in second_order_bodies, \(\mathcal{A}\) is the set of bodies in angular_momentum_bodies, \(\mu_a=GM_a\) is the gravitational parameter of body \(a\), \(\mathbf{r}_a\) is the relative position vector from body \(a\) to the metric evaluation point, \(R_a=\lVert\mathbf{r}_a\rVert\), \(\mathbf{v}_a\) is the barycentric velocity of body \(a\), \(\mathbf{S}_k\) is the angular-momentum vector of body \(k\), \(U_a^{\mathrm{SH}}\) is the configured spherical-harmonic scalar potential contribution, \(w_b\) follows the same definition as \(w_a\) but evaluated for body \(b\), \(\delta_{ij}\) is the Kronecker delta, \(c\) is the speed of light, \(G\) is the gravitational constant, and \(\beta,\gamma\) are the PPN parameters.

Parameters:

• first_order_bodies (list[str]) – Bodies included in the first-order post-Newtonian terms.

• second_order_bodies (list[str], optional) – Bodies included in second-order terms.

• spherical_harmonic_expansions (dict[str, tuple[int, int]], optional) – Optional spherical-harmonic degree/order settings per body.

• angular_momentum_bodies (list[str], optional) – Bodies for which angular-momentum terms are included.

• use_body_accelerations (bool, optional) – Whether body-acceleration terms are included in the metric model.

Returns:

Settings object for the solar-system metric model. This can be assigned to SpaceTimePropertiesSettings.metric_settings.

Return type:

SolarSystemSpaceTimeMetricSettings

Classes

PPNParameterSet	Container class for PPN parameters used in relativistic models.
SpaceTimeMetricType	Members:
SpaceTimeMetricSettings	Base class for space-time metric settings.
SpaceTimePropertiesSettings	Settings assigned to space_time_settings, for initializing space_time_properties.
SchwarzschildSpaceTimeMetricSettings	Settings for a harmonic Schwarzschild metric.
SolarSystemSpaceTimeMetricSettings	Settings for a solar-system post-Newtonian metric.

class PPNParameterSet

Bases: pybind11_object

Container class for PPN parameters used in relativistic models. These parameters are assigned through space_time_properties.

The first-order PPN parameters \(\gamma\) and \(\beta\) follow the conventions summarized by Will [31]. The parameter \(\epsilon\) is used here as a second-order post-Newtonian parameter.

property parameter_beta

PPN parameter \(\beta\).

property parameter_epsilon

Second-order post-Newtonian parameter \(\epsilon\).

property parameter_gamma

PPN parameter \(\gamma\).

class SpaceTimeMetricType

Bases: pybind11_object

Members:

schwarzschild_metric

solar_system_metric

SpaceTimeMetricType.name -> str

class SpaceTimeMetricSettings

Bases: pybind11_object

Base class for space-time metric settings.

class SpaceTimePropertiesSettings

Bases: pybind11_object

Settings assigned to space_time_settings, for initializing space_time_properties.

class SchwarzschildSpaceTimeMetricSettings

Bases: SpaceTimeMetricSettings

Settings for a harmonic Schwarzschild metric.

class SolarSystemSpaceTimeMetricSettings

Bases: SpaceTimeMetricSettings

Settings for a solar-system post-Newtonian metric.