`acceleration`¶

Here, you will find a list of all acceleration models available in Tudat. The functions here all create settings objects for accelerations that are provided as input to the create_acceleration_models() function. For more details on how these accelerations interface with the rest of the Tudat propagation framework, see our user guide page on translational dynamics

Mathematical model descriptions are provided either directly here per acceleration, or on a dedicated page of the Tudat user guide for

The functions in this submodule create objects of type AccelerationSettings or (in case more information than only the type of acceleration is needed to create the acceleration), one of its derived classes.

Functions¶

`point_mass_gravity`()	Creates settings for the point-mass gravity acceleration.
`spherical_harmonic_gravity`(maximum_degree, ...)	Creates settings for the spherical harmonic gravity acceleration.
`mutual_spherical_harmonic_gravity`(...[, ...])	Creates settings for the mutual spherical harmonic gravity acceleration.
`aerodynamic`()	Creates settings for the aerodynamic acceleration.
`radiation_pressure`(target_type)	Creates settings for the radiation pressure acceleration.
`polyhedron_gravity`()	Creates settings for the polyhedron gravity acceleration.
`ring_gravity`()	Creates settings for the ring gravity acceleration.
`relativistic_correction`([use_schwarzschild, ...])	Creates settings for the relativistic acceleration correction.
`einstein_infeld_hofmann`()	Creates settings for the Einstein-Infeld-Hoffman acceleration.
`empirical`([constant_acceleration, ...])	Creates settings for empirical acceleration.
`custom_acceleration`(acceleration_function)	Creates settings for custom acceleration.
`direct_tidal_dissipation_acceleration`(*args, ...)	Overloaded function.
`quasi_impulsive_shots_acceleration`(...)	Creates settings for incorporating quasi-impulsive shots into the acceleration.
`thrust_from_engines`(engine_names)	Creates settings for thrust acceleration using a list of engine models.
`thrust_from_engine`(engine_name)	Creates settings for thrust acceleration using a single engine models.
`thrust_from_all_engines`()	Creates settings for thrust acceleration using a single engine models.
`yarkovsky`(yarkovsky_parameter)	Creates settings for the Yarkovsky acceleration.

point_mass_gravity() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the point-mass gravity acceleration.

Creates settings for the point-mass gravity acceleration. The direct acceleration (acceleration w.r.t. an inertial frame) is computed from:

\[\mathbf{a}=\frac{\mu}{{r}^{2}}\hat{\mathbf{r}}\]

with \(\mathbf{r}\) the position vector measured from the center of mass of the body exerting the acceleration, and \(\mu\) this body’s gravitational parameter.

Depending on the body undergoing the acceleration \(A\), the body exerting the acceleration \(B\), and the central body of propagation \(C\), choosing this option may create a direct point-mass attraction (\(\mu=\mu_{B}\)), a central point-mass attraction (\(\mu=\mu_{B}+\mu_{A}\)) or a third-body point-mass attraction (see dedicated user guide page for more details).

The body exerting the acceleration needs to have a gravity field model (gravity_field module) defined to use this acceleration.

Returns:: Acceleration settings object.
Return type:: AccelerationSettings

Examples

In this example, we define the point mass gravity acceleration exerted by the Earth on the vehicle:

# Create acceleration dict
accelerations_acting_on_vehicle = dict()
# Add point-mass gravity acceleration exerted by Earth
accelerations_acting_on_vehicle["Earth"] = [propagation_setup.acceleration.point_mass_gravity()]

spherical_harmonic_gravity(maximum_degree: int, maximum_order: int) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the spherical harmonic gravity acceleration.

Creates settings for the spherical harmonic gravity acceleration, accounting for a finite (given as input) number of degrees and orders. The direct acceleration (acceleration w.r.t. an inertial origin) is computed from:

\[\mathbf{a}=\mathbf{R}^{(I/B)}\nabla^{(B)}U(\mathbf{r})\]

with \(\mathbf{r}\) the position vector measured from the center of mass of the body exerting the acceleration, \(\mathbf{R}^{(I/B)}\) the rotation matrix from body-fixed to inertial frame, and \(\nabla^{(B)}\) the gradient operator in a body-fixed frame, and \(U\) the spherical harmonic gravitational potential (see spherical_harmonic), expanded up to the provided maximum_degree and maximum_order.

Depending on the body undergoing the acceleration \(A\), the body exerting the acceleration \(B\), and the central body of propagation \(C\), choosing this option may create a direct spherical harmonic attraction (\(\mu=\mu_{B}\)), a central spherical harmonic attraction (\(\mu=\mu_{B}+\mu_{A}\)) or a third-body spherical harmonic attraction (see dedicated user guide page for more details).

The body exerting the acceleration needs to have a spherical harmonic gravity field model with coefficients up to at least the maximum_degree and maximum_order provided (see spherical_harmonic) and a rotation model (rotation_model module) defined.

Note that, if the body exerting the acceleration has any gravity_field_variation defines, the influence of these variations on the acceleration is automatically accounted for.

Parameters:

maximum_degree (int) – Maximum degree of the spherical harmonic expansion.
maximum_order (int) – Maximum order of the spherical harmonic expansion.

Returns:

Spherical harmonic acceleration settings object.

Return type:

SphericalHarmonicAccelerationSettings

Examples

In this example, we define the spherical harmonic gravity acceleration (where the gravity field is expanded up to degree 12 and order 6) exerted by the Earth on the vehicle:

# Define the maximum degree and order
maximum_degree = 12
maximum_order = 6
# Create acceleration dict
accelerations_acting_on_vehicle = dict()
# Add aerodynamic acceleration exerted by Earth
accelerations_acting_on_vehicle["Earth"] = [propagation_setup.acceleration.spherical_harmonic_gravity(
     maximum_degree,
     maximum_order)]

mutual_spherical_harmonic_gravity(maximum_degree_body_exerting: int, maximum_order_body_exerting: int, maximum_degree_body_undergoing: int, maximum_order_body_undergoing: int, maximum_degree_central_body: int = 0, maximum_order_central_body: int = 0) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the mutual spherical harmonic gravity acceleration.

Creates settings for the mutual spherical harmonic gravity acceleration. This model computes the total spherical harmonic acceleration exerted by a body \(B\) on a body \(A\), where the influence of the gravity field coefficients of body \(A\) itself has been included. The model includes couplings between the mass of each body, and the gravity field coefficients of the other body. It does not include the ‘figure-figure’ interactions (coupling between the two-bodies’ gravity field coefficients). It corresponds to the model presented by [6, 14] The model combines the spherical harmonic accelerations of the two bodies (see spherical_harmonic_gravity()) on each other. The direct acceleration (acceleration w.r.t. an inertial origin) is computed from:

\[\mathbf{a}={-\frac{\mu_{B}}{{r}^{2}}\hat{\mathbf{r}}}+{\mathbf{R}^{(I/B)}\nabla^{(B)}U_{\hat{B}}(\mathbf{r})}-{\frac{\mu_{B}}{\mu_{_{A}}}\mathbf{R}^{(I/A)}\nabla^{(A)}U_{\hat{A}}(-\mathbf{r})}\]

where \(U_{\hat{B}}\) and \(U_{\hat{A}}\) denote the spherical harmonic gravity fields a degree \(>=1\) of bodies \(B\) and \(A\), respectively. Both the body exerting the acceleration and the body undergoing it need to have spherical harmonic gravity field and rotation models defined.

Depending on the body undergoing the acceleration \(A\), the body exerting the acceleration \(B\), and the central body of propagation \(C\), choosing this option may create a direct spherical harmonic attraction (as above), a central spherical harmonic attraction (\(\mu_{B}\rightarrow\mu_{B}+\mu_{A}\), in the above equation and in \(U_{\hat{B}}\)) or a third-body spherical harmonic attraction (see dedicated user guide page for more details).

For the case where a third-body mutual spherical harmonic acceleration, additional parameters have to be provided that denote the expansion degree/order of the central body (maximum_degree_central_body and maximum_order_central_body)

Parameters:

maximum_degree_body_exerting (int) – Maximum degree of the spherical harmonic expansion for the body exerting the acceleration.
maximum_order_body_exerting (int) – Maximum order of the spherical harmonic expansion for the body exerting the acceleration.
maximum_degree_body_undergoing (int) – Maximum degree of the spherical harmonic expansion for the body undergoing the acceleration.
maximum_order_body_undergoing (int) – Maximum order of the spherical harmonic expansion for the body undergoing the acceleration.
maximum_degree_central_body (int, default=0) – Maximum degree of the spherical harmonic expansion for the central body, if needed.
maximum_order_central_body (int, default=0) – Maximum order of the spherical harmonic expansion for the central body, if needed.

Returns:

Spherical harmonic acceleration settings object.

Return type:

MutualSphericalHarmonicAccelerationSettings

Examples

In this example, we define the spherical harmonic gravity accelerations exerted on Io by Jupiter and vice-versa.

# Define the maximum degree and order for both bodies
maximum_degree_of_io = 12
maximum_order_of_io = 12
maximum_degree_of_jupiter = 4
maximum_order_of_jupiter = 4
# Create acceleration dict
acceleration_settings_on_io = dict()
# Add mutual spherical harmonic acceleration exerted by Jupiter
acceleration_settings_on_io["Jupiter"] = [propagation_setup.acceleration.mutual_spherical_harmonic_gravity(
     maximum_degree_of_jupiter,
     maximum_order_of_jupiter,
     maximum_degree_of_io,
     maximum_order_of_io)]

For the case where the mutual spherical harmonic acceleration is a third-body acceleration, additional parameters have to be provided to denote the expansion of the spherical harmonics of the central body. In the following example, we consider the mutual spherical harmonic gravity acceleration exerted on Io by Ganymede when propagating w.r.t. Jupiter:

# Define the maximum degree and order for both bodies
maximum_degree_of_jupiter = 4
maximum_order_of_jupiter = 4
maximum_degree_of_ganymede = 4
maximum_order_of_ganymede = 4
maximum_degree_of_io = 12
maximum_order_of_io = 12
# Create acceleration dict
acceleration_settings_on_io = dict()
# Add the acceleration to the dict
acceleration_settings_on_io["Ganymede"] = [propagation_setup.acceleration.mutual_spherical_harmonic_gravity(
    maximum_degree_of_ganymede,
    maximum_order_of_ganymede,
    maximum_degree_of_io,
    maximum_order_of_io,
    maximum_degree_of_jupiter,
    maximum_order_of_jupiter)]

aerodynamic() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the aerodynamic acceleration.

Creates settings for the aerodynamic acceleration. The acceleration is computed from:

\[\begin{split}\mathbf{a}=-\frac{1}{m}\mathbf{R}^{(I/\text{Aero})}\left(\frac{1}{2}\rho v_{\text{air}}^{2}S_{ref}\begin{pmatrix} C_{D} \\ C_{S} \\ C_{L}\end{pmatrix}\right)\end{split}\]

with \(\mathbf{R}^{(I/\text{Aero})}\) the rotation matrix from the aerodynamic frame of the body undergoing acceleration to the inertial frame, see :[15] or AerodynamicsReferenceFrames, \(\rho\) the local freestream atmospheric density, \(v_{\text{air}}\) the airspeed, \(C_{D,S,L}\) the drag, side and lift coefficients (which may depend on any number of properties of the body/environment) with reference area \(S_{ref}\), and \(m\) the mass of the body undergoing acceleration The body exerting the acceleration needs to have an atmosphere (atmosphere module), shape (shape module) and rotation model (rotation_model module) defined. The body undergoing the acceleration needs to have aerodynamic coefficients (aerodynamic_coefficients module) defined.

Returns:: Acceleration settings object.
Return type:: AccelerationSettings

Examples

In this example, we define the aerodynamic acceleration exerted by the Earth on the vehicle:

# Create acceleration dict
accelerations_acting_on_vehicle = dict()
# Add aerodynamic acceleration exerted by Earth
accelerations_acting_on_vehicle["Earth"] = [propagation_setup.acceleration.aerodynamic()]

radiation_pressure(target_type: tudatpy.kernel.numerical_simulation.environment_setup.radiation_pressure.RadiationPressureTargetModelType = <RadiationPressureTargetModelType.undefined_target: 3>) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the radiation pressure acceleration.

Creates settings for the radiation pressure acceleration. This function takes the source model of the body exerting the acceleration, and the target model of the body undergoing the acceleration, and links these models to set up the specific acceleration model, regardless of how the source and target models are defined.

Settings for how to define the source and target model are provided in the radiation_pressure module. The source model is used to compute the irradiance \(\Phi\) at the location of the target. Typical source models are the isotropic_radiation_source() (typically used for the Sun), which computes a single irradiance value \(Phi\) and the panelled_extended_radiation_source() (typically used for planetary radiation pressure), which computes a separate irradiance value from each of the panels on the source body. Typical target models are the cannonball_radiation_target() model and the panelled_radiation_target() target models.

For more extensive details on how this is done, check out the radiation pressure acceleration page.

Parameters:: target_type (RadiationPressureTargetModelType) – The type of target model that is to be used. Typically this entry can be left undefined (at its default). It is only relevant if the body undergoing acceleration has multiple target models defined (and the user has to choose one to use for this specific source).
Returns:: Acceleration settings object.
Return type:: AccelerationSettings

polyhedron_gravity() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the polyhedron gravity acceleration.

Creates settings for the polyhedron gravity acceleration, which follows from defining a body to have polyhedral gravity. The model is described in e.g. Werner and Scheeres [25], and the acceleration implememtation is from Eq. (16) of that reference.

Summarizing, it is computed from using combinations of geometric quantities associated with the polyhedron’s edges and faces.

The quantity \(\mathbf{E}_e\) is the edge contribution tensor for edge \(e\), defined as

\[\mathbf{E}_e = \hat{\mathbf{n}}_A \hat{\mathbf{n}}_{Ae} + \hat{\mathbf{n}}_B \hat{\mathbf{n}}_{Be},\]

where \(\hat{\mathbf{n}}_A\) and \(\hat{\mathbf{n}}_B\) are the outward unit normal vectors of the two faces that share edge \(e\), and \(\hat{\mathbf{n}}_{Ae}\) and \(\hat{\mathbf{n}}_{Be}\) are the outward-pointing unit vectors perpendicular to edge \(e\) and lying within the planes of faces \(A\) and \(B\), respectively. The outer product notation \(\hat{\mathbf{a}} \hat{\mathbf{b}}\) denotes a rank-2 tensor (or matrix)

The face contribution rank-2 tensor \(\mathbf{F}_f\) for face \(f\) is given by

\[\mathbf{F}_f = \hat{\mathbf{n}}_f \hat{\mathbf{n}}_f,\]

where \(\hat{\mathbf{n}}_f\) is the outward unit normal to the face \(f\).

\[L_e = \ln \left( \frac{r_i + r_j + e}{r_i + r_j - l_e} \right),\]

where \(r_i\) and \(r_j\) are the distances from the body undergoing acceleration to the two vertices (\(i\) and \(j\)) at the ends of edge \(e\), and \(l_e\) is the length of the edge.

The scalar \(\omega_f\) is the signed solid angle subtended by face \(f\) as seen from the body undergoing acceleration. Its value encodes both the visibility of the face and whether the field point lies in front of or behind the face.

The acceleration (in the gravity-field fixed frame) then becomes:

\[\mathbf{a}^{(B)} = -G \rho\left( \sum_{e \in \text{edges}} \mathbf{E}_e \cdot \mathbf{r}_e L_e - \sum_{f \in \text{faces}} \mathbf{F}_f \cdot \mathbf{r}_f \omega_f \right)\]

where two summation are over all edges and faces of the polygon, respectively; \(\mathbf{r}_e\) is the vector from the middle of the edge \(e\) to the body undergoing acceleration, and \(\mathbf{r}_f\) is the vector from the face centroid \(f\) to the body undergoing acceleration

This acceleration is then rotated to the inertial orientation using the body-fixed to inertial rotation associated with the gravity field (equal to the rotation model of the body that is endowed with a gravity model)

Returns:: Acceleration settings object.
Return type:: AccelerationSettings

ring_gravity() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the ring gravity acceleration.

Creates settings for the ring gravity acceleration, an infinitely thin circular mass with constant linear mass distribution (e.g. along its circumference). This acceleration model requires a body have a ring gravity field model (create using the ring_model() gravity field setting) The ring acceleration is computed according to the model presented by Fukushima [8]. For a ring mass \(m\) and ring radius \(a\), it is computed by first calculating the quantities:

\[\begin{split}r &\equiv \sqrt{x^2 + y^2}, \\ p &\equiv \sqrt{(r + a)^2 + z^2},\\ q &\equiv \sqrt{(r - a)^2 + z^2},\\ \lambda &= \frac{G}{2\pi a}\\ A_r &= \frac{8 \lambda a}{p^3} \left[ \left( \frac{r^2 + z^2 - a^2}{q^2} \right) B(m) + \left( \frac{2a(r + a)}{p^2} \right) S(m) \right]\\ A_z &= \frac{4\lambda aE(m)}{pq^{2}}\end{split}\]

with \(G\) the gravitational constant, and \(\mathbf{r}=[x,y,z]\) the position of the body undergoing the acceleration in the ring-fixed frame (which has its origin at the center of the ring). The acceleration is then computed in the ring-fixed frame from:

\[\begin{split}\mathbf{a}^{(B)}=\begin{pmatrix}-A_{r}x\\-A_{r}y\\-A_{z}z\end{pmatrix}\end{split}\]

This acceleration is then rotated to the inertial orientation using the body-fixed to inertial rotation associated with the ring gravity field (equal to the rotation model of the body that is endowed with a ring gravity model)

in the above \(B(m), S(m), E(M)\) are elliptical integrals, see Fukushima [8] for details.

Returns:: Acceleration settings object.
Return type:: AccelerationSettings

einstein_infeld_hofmann() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the Einstein-Infeld-Hoffman acceleration.

Creates settings for the Einstein-Infeld-Hoffman (EIH) acceleration, which is the first-order post-Newtonian (expanded to order \(1/c^{2}\)) expansion of the gravitational interaction between point masses in barycentric coordinates, in the framework of general relativity. The equations are parameterized by the Parametrized Post-Newtonian (PPN) parameters \(\beta\) and \(\gamma\).

The formulation for the EIH acceleration exerted on body \(a\) is (see e.g. Will [26]):

\[\begin{split}\ddot{\mathbf{r}}_a = & -G \sum_{\substack{b=1 \\ b \neq a}}^N m_b \frac{\mathbf{r}_{ab}}{r_{ab}^3} \Bigg[ 1 - \frac{1}{c^2} \left( (1 + 2\gamma) \sum_{\substack{c=1}}^N \frac{G m_c}{r_{bc}} + (1 + 2\beta) \sum_{\substack{c=1}}^N \frac{G m_c}{r_{ac}} \right) \\ & + \frac{1}{2c^2} \left( v_a^2 + v_b^2 - 4\gamma \, \mathbf{v}_a \cdot \mathbf{v}_b - \frac{3}{2} (\mathbf{n}_{ab} \cdot \mathbf{v}_b)^2 \right) \Bigg] \\ & + \frac{G}{c^2} \sum_{\substack{b=1 \\ b \neq a}}^N m_b \left[ \frac{\mathbf{r}_{ab}}{r_{ab}^3} (\mathbf{r}_{ab} \cdot (\mathbf{a}_a - \mathbf{a}_b)) + \frac{7}{2} \frac{\mathbf{a}_b}{r_{ab}} \right]\end{split}\]

where:

\(\mathbf{r}_a\): position of body \(a\)
\(\mathbf{v}_a = \dot{\mathbf{x}}_a\): velocity of body \(a\)
\(\mathbf{a}_a = \ddot{\mathbf{x}}_a\): acceleration of body \(a\)
\(\mathbf{r}_{ab} = \mathbf{r}_a - \mathbf{r}_b\), \(r_{ab} = |\mathbf{r}_{ab}|\)
\(\mathbf{n}_{ab} = \mathbf{r}_{ab} / r_{ab}\): unit vector from \(b\) to \(a\)
\(G\): Newtonian gravitational constant
\(c\): speed of light

Note that this acceleration includes the mutual point mass atrraction.

Technically, these equations are implicit, since the terms \(\mathbf{a}_{a}\) and \(\mathbf{a}_{b}\) occur on the left- and right-hand sides of the equations (when evaluating the above for a set of bodies). We simplify this by using the partial acceleration (above formulation without the acceleration-dependence on the RHS) to fill in the accelerations on the right-hand side. The error induced by this approximation is of order \(1/c^{4}\)

At present, the implementation of the EIH equation computes the full accelerations for all bodies that are involved in an EIH acceleration. In other words, if 10 bodies have an EIH acceleration as body undergoing an acceleration, but 100 bodies are used (including the 10 bodies undergoing acceleration) to exert the EIH acceleration, the implementation will compute the acceleration for all 100 bodies (and only 10 of these accelerations will be used in the propagation). Therefore, be aware that the implementation is designed for a set of mutually interacting bodies (e.g. propagating all bodies that are exerting an EIH acceleration). Other user cases are supported, but less computationally efficient.

The EIH acceleration formulation is slightly different from other accelerations. If \(N\) bodies have EIH accelerations exerted on them (by a common set of exerting bodies, which may include (a subset of) the \(N\) propagated bodies themselves, these accelerations are evaluated concurrently. This does not imply any different interaction on the side of the user, but impacts the implementation of the underlying acceleration model.

Returns:: Acceleration settings object.
Return type:: AccelerationSettings

relativistic_correction(use_schwarzschild: bool = False, use_lense_thirring: bool = False, use_de_sitter: bool = False, de_sitter_central_body: str = '', lense_thirring_angular_momentum: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the relativistic acceleration correction.

Creates settings for typical relativistic acceleration corrections: the Schwarzschild, Lense-Thirring and de Sitter terms, where each of the three terms can be toggled on or of. It implements the model of 2010 Conventions (chapter 10, section 3).

For the Schwarzschild correction, we have:

\[\mathbf{a}=\frac{\mu_{B}}{c^{2}r^{3}}\left(\left(2(\beta+\gamma)\frac{\mu_{B}}{r}-\gamma(\mathbf{v}\cdot\mathbf{v}) \right)\mathbf{r} +2(1+\gamma)(\mathbf{r}\cdot\mathbf{v})\mathbf{v}\right)\]

For the Lense-Thirring correction, we have:

\[\mathbf{a}=(1+\gamma)\frac{\mu_{B}}{c^{2}r^{3}}\left(\frac{3}{r^{2}}\left(\mathbf{r}\times\mathbf{v} \right)(\mathbf{r}\cdot\mathbf{h}_{B})+(\mathbf{v}\times\mathbf{h}_{B})\right)\]

For the de Sitter correction, we have:

\[\mathbf{a}=(1 + 2\gamma) \left(\mathbf{R}_{S} \times \left( \frac{-\mu_{S} \mathbf{R}_{S}}{c^2 R_{S}^3} \right) \right) \times \mathbf{v}\]

where \(\gamma\) and \(beta\) are the Parametrized Post-Newtonian (PPN) parameters, \(\mathbf{v}\) and \(\mathbf{r}\) are velocity and position of the body undergoing the acceleration w.r.t. the body exerting the acceleration, \(\mu_{B}\) is the gravitational parameter of the body undergoing the acceleration, \(h`_{B}\) is the angular momentum vector per unit mass of the body exerting the acceleration (in the global frame orientation), and \(\mu_{S}\) and \(\mathbf{R}_{S}\) are the gravitational parameter of the ‘de Sitter central body’ and the position of the body exerting the acceleration w.r.t. the ‘de Sitter central body’. For normal applications, the ‘de Sitter central body’ should be set as the Sun, if the body exerting the acceleration is a natural solar system body (except the Sun itself)

Parameters:

use_schwarzschild (bool, default=False) – Boolean defining whether or not to use the Schwarzschild contribution to the acceleration correction
use_lense_thirring (bool, default=False) – Boolean defining whether or not to use the Lense-Thirring contribution to the acceleration correction
use_de_sitter (bool, default=False) – Boolean defining whether or not to use the de Sitter contribution to the acceleration correction
de_sitter_central_body (str, default="") – Body used as ‘third body’ in the calculation of the de Sitter acceleration. For the case of (for instance) an Earth-orbiting satellite, this would be the Sun (and only the Sun)
lense_thirring_angular_momentum (numpy.ndarray, default=numpy.array([0, 0, 0])) – Angular momentum vector per unit mass (in global frame) that is to be used for the calculation of the Lense-Thirring acceleration

Returns:

Relativistic acceleration correction settings object.

Return type:

RelativisticAccelerationCorrectionSettings

Examples

In this example, we define the relativistic correction acceleration for a Mars orbiter:

# Select terms to be used
use_schwarzschild = True
use_lense_thirring = True
use_de_sitter = True
# Define central body for De-Sitter term
de_sitter_central_body = "Sun"
# Define angular momentum for the Lense-Thirring term
lense_thirring_angular_momentum = ... # numpy.ndarray 3D vector
# Create acceleration dict
acceleration_settings_on_vehicle = dict()
# Add the acceleration to the dict
acceleration_settings_on_vehicle["Mars"] = [propagation_setup.acceleration.relativistic_correction(
   use_schwarzschild,
   use_lense_thirring,
   use_de_sitter,
   de_sitter_central_body,
   lense_thirring_angular_momentum)]

empirical(constant_acceleration: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), sine_acceleration: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), cosine_acceleration: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for empirical acceleration.

Creates settings for empirical accelerations. These are expressed in the RSW frame, for which the magnitude is determined empirically (typically during an orbit determination process). The acceleration components are defined according to Montenbruck and Gill (2000), with a total of 9 components: a constant, sine and cosine term (with true anomaly as argument) for each of the three independent directions of the RSW frame. The empirical acceleration is calculated as:

\[\mathbf{a}=R^{I/RSW}\left(\mathbf{a}_{\text{const.}}+\mathbf{a}_{\sin}\sin\theta+\mathbf{a}_{\cos}\cos\theta \right)\]

Here, \(R^{I/RSW}\) is the rotation matrix from the RSW frame (of the body undergoing the acceleration w.r.t. the body exerting the acceleration), \(theta\) is the true anomaly, and the three constituent acceleration vectors are the inputs provided in the above code block. The body ‘exerting’ the acceleration is considered to be the central body, w.r.t. which the true anomaly is calculated.

Parameters:

constant_acceleration (numpy.ndarray, default=numpy.array([0, 0, 0])) – Constant term, defined in the RSW frame.
sine_acceleration (numpy.ndarray, default=numpy.array([0, 0, 0])) – Sine term (function of the true anomaly), defined in the RSW frame..
cosine_acceleration (numpy.ndarray, default=numpy.array([0, 0, 0])) – Cosine term (function of the true anomaly), defined in the RSW frame..

Returns:

Empirical acceleration settings object.

Return type:

EmpiricalAccelerationSettings

Examples

In this example, we define the empirical acceleration acting on the vehicle. The body that ‘exerts’ the acceleration is here used to determine the body w.r.t. which the true anomaly has o be calculated when determining the sine/cosine contributions. This central body must be endowed with a gravity field (so that it possesses a gravitational parameter for the Cartesian to Keplerian conversion)

# Define the nine terms (constant, sine and cosine)
constant_acceleration = ... # 3D numpy.ndarray vector
sine_acceleration = ... # 3D numpy.ndarray vector
cosine_acceleration = ... # 3D numpy.ndarray vector
# Create acceleration dict
acceleration_settings_on_vehicle = dict()
# Add the acceleration to the dict
acceleration_settings_on_vehicle["Sun"] = [propagation_setup.acceleration.empirical(
    constant_acceleration,
    sine_acceleration,
    cosine_acceleration)]

custom_acceleration(acceleration_function: Callable[[float], numpy.ndarray[numpy.float64[3, 1]]]) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for custom acceleration.

Creates settings for a custom accelerations, this acceleration must be parameterized as a function of time, and expressed with an inertial orientation.

Parameters:: acceleration_function (callable[[float], list]) – Custom acceleration function with time as an independent variable, returning the acceleration in an inertial frame (e.g. with global frame orientation) as a function of time.
Returns:: Custom acceleration settings object.
Return type:: CustomAccelerationSettings

Examples

In this example, we define a simple, standalone, custom acceleration (depending only on time), with the following (arbitrary, for the sake of example) mathematical definition:

\[\begin{split}\mathbf{a}=\begin{pmatrix}C\\0\\0 \end{pmatrix}\sin\left(\frac{t-t_{0}}{T}\right)\end{split}\]

with \(C=10^{-8}\), \(t_{0}=0\) and \(T=86400\). More complex custom acceleration functions can be created by, for instance, extracting the custom function from a user-defined class, which may in turn have other simulation objects (e.g. SystemOfBodies) as members, allowing the custom acceleration to depend on the current simulation state/environment

# Define custom function
def custom_function( current_time ):
    period = 86400.0
    reference_time = 0.0
    phase = np.pi * ( current_time - reference_time ) / period
    return np.array([1.0E-8, 0.0, 0.0]) * np.sin(phase)

acceleration_settings_on_vehicle["Vehicle"] = [propagation_setup.acceleration.custom_acceleration(
    custom_function)]

direct_tidal_dissipation_acceleration(*args, **kwargs)¶

Overloaded function.

direct_tidal_dissipation_acceleration(k2_love_number: float, time_lag: float, include_direct_radial_component: bool = True, use_tide_raised_on_planet: bool = True, explicit_libraional_tide_on_satellite: bool = False) -> tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings

Creates settings for tidal acceleration.

Creates settings for tidal accelerations. The direct of tidal effects in a satellite system is applied directly as an acceleration (as opposed to a modification of spherical harmonic coefficients). The model is based on Lainey et al. (2007, 2012). It can compute the acceleration due to tides, and in particular tidal dissipation, on a planetary satellite. The acceleration computed can account for either the effect of tide raised on the satellite by the planet or on the planet by the satellite. The satellite is assumed to be tidally locked to the planet.

Parameters:

k2_love_number (float) – Value of the k2 Love number.
time_lag (float) – Value of the tidal time lag.
include_direct_radial_component (bool, default=True) – It denotes whether the term independent of the time lag is to be computed.
use_tide_raised_on_planet (bool, default=True) – It denotes whether the tide raised on the planet is to be modelled (if true) or the tide raised on the satellite (if false).

Returns:

Direct tidal dissipation acceleration settings object.

Return type:

DirectTidalDissipationAccelerationSettings

Examples

In this example, we define the tidal dissipation exerted by Jupiter on Io directly, instead of computing it through the spherical harmonic gravity:

# Define parameters
love_number = 0.1
time_lag = 100.0
# Add entry to acceleration settings dict
acceleration_settings_on_io["Jupiter"] = [propagation_setup.acceleration.direct_tidal_dissipation(
love_number,
time_lag,
False,
False)]

direct_tidal_dissipation_acceleration(k2_love_number: float, inverse_tidal_quality_factor: float, tidal_period: float, include_direct_radial_component: bool = True, use_tide_raised_on_planet: bool = True, explicit_libraional_tide_on_satellite: bool = False) -> tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings

Creates settings for tidal acceleration.

Parameters:

k2_love_number (float) – Value of the k2 Love number.
time_lag (float) – Value of the tidal time lag.
include_direct_radial_component (bool, default=True) – It denotes whether the term independent of the time lag is to be computed.
use_tide_raised_on_planet (bool, default=True) – It denotes whether the tide raised on the planet is to be modelled (if true) or the tide raised on the satellite (if false).

Returns:

Direct tidal dissipation acceleration settings object.

Return type:

DirectTidalDissipationAccelerationSettings

Examples

In this example, we define the tidal dissipation exerted by Jupiter on Io directly, instead of computing it through the spherical harmonic gravity:

# Define parameters
love_number = 0.1
time_lag = 100.0
# Add entry to acceleration settings dict
acceleration_settings_on_io["Jupiter"] = [propagation_setup.acceleration.direct_tidal_dissipation(
    love_number,
    time_lag,
    False,
    False)]

quasi_impulsive_shots_acceleration(thrust_mid_times: list[float], delta_v_values: list[numpy.ndarray[numpy.float64[3, 1]]], total_maneuver_time: float, maneuver_rise_time: float) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for incorporating quasi-impulsive shots into the acceleration.

The acceleration model is purpose-built to represent short bursts of thrust, such as a momentum wheel desaturation. A typical use case is precise orbit determination, but the functionality can be used just as well in propagation (for instance to model an impulsive manuever in a continuous manner when going from preliminary modelling to full modelling).

The thrust is modelled similarly to Fig. 3 of [2], with the main difference being that a third-order polynomial to go from zero acceleration to the maximum acceleration level is employed. By using a 3rd-order polynomial and imposing continuity in the value and first derivative of the acceleration, defining the rise time (time it takes acceleration to go from 0 to its maximum level), the total time where there is non-zero thrust (total maneuver time), and the total \(\Delta V\) exerted by a single maneuver, the acceleration profile is fully defined.

Specifically, for each thrust arc \(i\) centered at \(t_{i}\), with \(\Delta \mathbf{V}_{i}\), maneuver duration \(t_{M}\) and maneuver rise time \(t_{R}\) a maximum acceleration \(\mathbf{a}_{i}\) is computed from

\[\mathbf{a}_{i}=\Delta \mathbf{V}_{i}/(t_{M}+t_{R})\]

such that the integrated thrust over the maneuver duration equals \(\Delta \mathbf{V}_{i}\). The acceleration is only non-zero at a time \(t\) if there exists an \(i\), such

\[t_{i}-t_{M}/2-t_{R}\le t \le t_{i}+t_{M}/2+t_{R}\]

if we have furthermore \(t_{i}-t_{M}/2\le t \le t_{i}-t_{M}/2\), we have

\[\mathbf{a}=\mathbf{a}_{i}\]

for this acceleration (thrust is at its maximum for the shot) Otherwise, if the epoch is during the rise time (either at the beginning or end of the thrust interval), we have

\[\mathbf{a}=T^{2}(3-2T)\mathbf{a}_{i}\]

with \(T=\Delta t/t_{R}\) (for which by definition \(0\le T\le 1), with :math:\)Delta t` the positive time interval length from the maneuver start \(t_{i}-t_{M}/2-t_{R}\) (or end \(t_{i}+t_{M}/2+t_{R}\))

Parameters:

thrust_mid_times (list[float]) – Set of middle point in times \(t_{i}\) in the maneuver denoting the epoch of each maneuver.
delta_v_values (list[numpy.ndarray]) – Set of delta V values \(\Delta \mathbf{V}_{i}\), one for each maneuver.
total_maneuver_time (float) – Total duration of every maneuver \(t_{M}\).
maneuver_rise_time (float) – Time \(t_{R}\) taken by the acceleration to go from zero to its maximum level.

Returns:

Momentum wheel desaturation acceleration settings object.

Return type:

MomentumWheelDesaturationAccelerationSettings

Examples

In this example, we define an acceleration model to represent two quasi-impulsive shots, with a total duration of 30 seconds, and a rise time of 5 seconds. The maneuvers are to be done at \(t=86400\) and \(t=2*86400\). The first maneuver is exclusively in \(x\)-direction, and the second one exclusively in \(y\)-direction, with both maneuvers having a magnitude of 1 mm/s

# Define the quasi-impulsive shot settings
mid_times = [ 86400.0, 2.0 * 86400.0]
delta_v_values = [ np.array([1.0E-3, 0.0, 0.0]), np.array([0.0, 1.0E-3, 0.0]) ]
maneuver_duration = 30
maneuver_duration = 5

# Create acceleration dict
acceleration_settings_on_spacecraft = dict()

# Add quasi-impulsive acceleration exerted by Spacecraft itself (!)
acceleration_settings_on_spacecraft["Spacecraft"] = [propagation_setup.acceleration.quasi_impulsive_shots_acceleration(
     mid_times,
     delta_v_values,
     maneuver_duration,
     maneuver_duration)]

thrust_from_engines(engine_names: list[str]) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for thrust acceleration using a list of engine models.

Creates settings for thrust acceleration using a list of engine models. See the user guide for more details on the definition of a thrust model in Tudat.

Parameters:: engine_names (List[str]) – List of engine names to use when computing thrust.
Returns:: Thrust acceleration settings object.
Return type:: ThrustAccelerationSettings

thrust_from_engine(engine_name: str) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for thrust acceleration using a single engine models.

Creates settings for thrust acceleration using a single engine models. See the user guide for more details on the definition of a thrust model in Tudat.

Parameters:: engine_name (str) – Name of engine to use when computing thrust.
Returns:: Thrust acceleration settings object.
Return type:: ThrustAccelerationSettings

thrust_from_all_engines() → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for thrust acceleration using a single engine models.

Creates settings for thrust acceleration by combining thrust from all engines defined in the body. See the user guide for more details on the definition of a thrust model in Tudat.

Returns:: Thrust acceleration settings object.
Return type:: ThrustAccelerationSettings

yarkovsky(yarkovsky_parameter: float) → tudatpy.kernel.numerical_simulation.propagation_setup.acceleration.AccelerationSettings¶

Creates settings for the Yarkovsky acceleration.

Creates settings for the Yarkovsky acceleration, which is calculated based on [18]. The acceleration is computed to lie fully in the tangential direction \(\hat{\mathbf{t}}\) and is computed as:

\[\mathbf{a}=A_{2}\left(\frac{r_{0}}{r_{S}}\right)^{2}\hat{\mathbf{t}}\]

where \(A_{2}\) is the Yarkovsky parameter, \(r_{0} = 1\) AU and \(r_{S}\) is the heliocentric distance in AU.

Parameters:: yarkovsky_parameter (float) – Value of the Yarkovsky parameter.
Returns:: Acceleration settings object.
Return type:: AccelerationSettings

Enumerations¶

AvailableAcceleration

Enumeration of available acceleration types.

class AvailableAcceleration¶

Enumeration of available acceleration types.

Enumeration of acceleration types supported by tudat. This enum is not used directly by the user to create accelerations, but is used in other parts of the library where a type of acceleration is to be identified (for instance in single_acceleration() to save an acceleration as dependent variable`

Members:

undefined_acceleration_type :

point_mass_gravity_type :

aerodynamic_type :

cannonball_radiation_pressure_type :

spherical_harmonic_gravity_type :

mutual_spherical_harmonic_gravity_type :

polyhedron_gravity_type :

ring_gravity_type :

thrust_acceleration_type :

relativistic_correction_acceleration_type :

empirical_acceleration_type :

direct_tidal_dissipation_in_central_body_acceleration_type :

direct_tidal_dissipation_in_orbiting_body_acceleration_type :

quasi_impulsive_shots_acceleration_type :

custom_acceleration_type :

radiation_pressure_type :

einstein_infeld_hoffmann_acceleration_type :

yarkovsky_acceleration_type :

property name¶

Classes¶

`AccelerationSettings`	Functional base class to define settings for accelerations.
`SphericalHarmonicAccelerationSettings`	AccelerationSettings-derived class to define settings for the spherical harmonic acceleration.
`MutualSphericalHarmonicAccelerationSettings`	AccelerationSettings-derived class to define settings for the mutual spherical harmonic acceleration.
`RelativisticAccelerationCorrectionSettings`	AccelerationSettings-derived class to define settings for the relativistic acceleration correction.
`EmpiricalAccelerationSettings`	AccelerationSettings-derived class to define settings for the empirical acceleration.
`CustomAccelerationSettings`	AccelerationSettings-derived class to define settings for custom acceleration.
`DirectTidalDissipationAccelerationSettings`	AccelerationSettings-derived class to define settings for direct tidal dissipation acceleration.
`ThrustAccelerationSettings`	AccelerationSettings-derived class to define settings for thrust acceleration, listing the engine models that are to be used
`MomentumWheelDesaturationAccelerationSettings`	AccelerationSettings-derived class to define settings for momentum wheel desaturation acceleration.

class AccelerationSettings¶

Functional base class to define settings for accelerations.

Class for providing settings for acceleration model. This class is a functional (base) class for settings of acceleration models that require no information in addition to their type. Classes defining settings for acceleration models requiring additional information must be derived from this class. Bodies exerting and undergoing acceleration are set externally from this class. This class can be used for the easy setup of acceleration models (see createAccelerationModels.h), but users may also chose to do so manually. (Derived) Class members are all public, for ease of access and modification.

class SphericalHarmonicAccelerationSettings¶

AccelerationSettings-derived class to define settings for the spherical harmonic acceleration.

Class for providing settings for spherical harmonics acceleration model, including the maximum degree and order up to which the field is to be expanded. Note that the minimum degree and order are currently always set to zero.

class MutualSphericalHarmonicAccelerationSettings¶

AccelerationSettings-derived class to define settings for the mutual spherical harmonic acceleration.

Class for providing settings for the mutual spherical harmonics acceleration model, including the maximum degree and order up to which the fields of the bodies are to be expanded. Note that the minimum degree and order are currently always set to zero.

class RelativisticAccelerationCorrectionSettings¶

AccelerationSettings-derived class to define settings for the relativistic acceleration correction.

Class to provide settings for typical relativistic corrections to the dynamics of an orbiter: the Schwarzschild, Lense-Thirring and de Sitter terms (see ‘General relativity and Space Geodesy’ by L. Combrinck, 2012).

class EmpiricalAccelerationSettings¶

AccelerationSettings-derived class to define settings for the empirical acceleration.

Class to provide settings for empirical accelerations. These are expressed in the RSW frame, for which the magnitude is determined empirically (typically during an orbit determination process). The acceleration components are defined according to Montenbruck and Gill (2000), with a total of 9 components: a constant, sine and cosine term (with true anomaly as argument) for each of the three independent directions of the RSW frame.

class CustomAccelerationSettings¶

AccelerationSettings-derived class to define settings for custom acceleration.

Class to provide settings for custom accelerations. This is done by means of a function and, if necessary, an associated scaling function.

class DirectTidalDissipationAccelerationSettings¶

AccelerationSettings-derived class to define settings for direct tidal dissipation acceleration.

Class to provide settings for direct tidal dissipation accelerations. Creates settings for tidal accelerations. The direct of tidal effects in a satellite system is applied directly as an acceleration (as opposed to a modification of spherical harmonic coefficients).

class ThrustAccelerationSettings¶

AccelerationSettings-derived class to define settings for thrust acceleration, listing the engine models that are to be used

Class to provide settings for thrust acceleration, listing the engine models that are to be used

class MomentumWheelDesaturationAccelerationSettings¶

AccelerationSettings-derived class to define settings for momentum wheel desaturation acceleration.

Class to provide settings for momentum wheel desaturation acceleration. Settings for the direction and magnitude of the thrust are included.

acceleration¶

Functions¶

Enumerations¶

Classes¶

`acceleration`¶