`rotation_model`¶

This module contains a set of factory functions for setting up the rotation models of bodies in an environment.

The main interfaces with Tudat is the rotation_model_settings attribute (of type RotationModelSettings) of the body settings, which defines settings for the rotation model of a body. The functions in this submodule are used to create these settings objects. When creating a body (typically using the create_system_of_bodies() function), an object of type RotationalEphemeris (or a derived class) is created and added to the associated Body object based on the settings object, which can be retrieved using the rotation_model attribute.

The following code block gives an overview of the steps to define, create, and extract a rotation model, for the specific example of a simple rotation model: (constant rotation rate and pole orientation), extracted from the Earth’s pole and rotation rate according to the SPICE IAU_Earth frame at the given reference epoch. The resulting rotation model has J2000 as inertial frame, and the identifier IAU_Earth_simplified as Earth-fixed frame.

from tudatpy.dynamics import environment_setup
from tudatpy.astro import time_representation

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify rotation model settings (base class type RotationModelSettings)
body_settings.get( 'Earth' ).rotation_model_settings = environment_setup.rotation_model.simple_from_spice(
    base_frame = 'J2000',
    target_frame = 'IAU_Earth',
    target_frame_spice = 'IAU_Earth_simplified',
    initial_time = time_representation.DateTime.from_iso_string( '2020-09-08T14:00:00.0' ).to_epoch( ) )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract rotation model (base class type RotationalEphemeris) from Earth
earth_rotation_model = bodies.get( 'Earth' ).rotation_model

Tudat has a broad range of rotation models available. In principle, these models can be assigned to both celestial bodies and natural bodies. However, a subset of these models is typically only applied to natural or artificial bodies. Rotation models have a wide range of, sometimes indirect, influences on the dynamics

A spherical harmonic acceleration exerted by a central body is first evaluated in a body-fixed frame, and the transformed to an inertial frame. Consequently, the central body’s rotation has a fundamental influence on the exerted spherical harmonic acceleration
A thrust acceleration in Tudat is calculated from two models: (1) an engine model, which defined the body-fixed direction of the thrust, and the magnitude of the thrust (2) the orientation of the body in space, defined by its rotation model
For a non-spherical central body shape models, the current orientation of this central body has an indirect influence on the altitude at which a vehicle with a given inertial state is located

Rotation and thrust Two rotation models, which are typically used for vehicles under thrust, and/or vehicles undergoing aerodynamic forces, are the following:

The rotation model aerodynamic_angle_based(), which calculates the body’s rotation based on the angle of attack, sideslip angle and bank angle. Note that these angles are defined w.r.t. the relative wind. This model is typical when using, for instance, a re-entry simulation. It imposes these three angles, and calculates the body orientation by combination with the latitude, longitude, heading angle, flight path angles. There is a related model, zero_pitch_moment_aerodynamic_angle_based(), that uses the same setup, but does not impose the angle of attack, but calculates by imposing aerodynamic pitch trim (zero pitch moment).
The rotation model custom_inertial_direction_based(), which is typical when calculating dynamics of a vehicle under thrust. It is based on linking a body-fixed direction (now limited to the body-fixed x-axis) to an arbitrary inertial direction. This allows the thrust (assuming that this is aligned with this same body-fixed direction) to be guided in an inertial direction determined by a user-defined model.

Relation to gravity field When modifying the rotation model settings, the name of the body-fixed frame may also be changed (as is the case for, for instance, the gcrs_to_itrs(), where the body-fixed frame has the name “ITRS”). One consequence of this is that you may get an error from the spherical harmonic gravity field, which can no longer find the frame to which it is associated. This can be resolved by (for instance) associating the gravity field to the new frame. For the above example, this would be done by the following:

body_settings.get( "Earth" ).gravity_field_settings.associated_reference_frame = "ITRS"

High-accuracy Earth rotation model The gcrs_to_itrs() creates a high accuracy rotation model, following the IERS 2010 Conventions. This includes small variations that are not predicted by models, but are instead measured by geodetic techniques and published as tabulated data by the IERS. If so desired, the exact files used for these corrections may be adapted by the user (see EarthOrientationAnglesCalculator()), which includes specific settings for daily variations in earth rotation angle, which influences the UTC - UT1 time conversion.

Using the rotation model outside the propagation In various cases, the rotation model object is useful to use independently of the propagation. Details can be found in the API entry for RotationalEphemeris, but we provide a short example here as well.

bodies = .... // Create system of bodies
earth_rotation_model = bodies.get('Earth').rotation_model
earth_rotation_at_epoch = earth_rotation_model.body_fixed_to_inertial_rotation( epoch )

where the epoch input is (as always in Tudat) the time in seconds since J2000. The specific rotation model provides the orientation from the inertial_frame_name to the body_fixed_frame_name frames. In the above example, the rotation matrix from the body-fixed to the inertial frame is extracted. Other functions are available in the RotationalEphemeris to extract the inverse rotation, its time-derivative, and the angular velocity vector of the body-fixed frame. Finally, note that the transform_to_inertial_orientation(), which uses the rotation model to rotation a body-fixed to an inertial state, may be useful in this context for some applications.

Functions¶

`simple`(base_frame, target_frame, ...)	Function for creating simple rotation model settings.
`simple_from_spice`(base_frame, target_frame, ...)	Function for creating simple rotation model settings using initial orientation and rotation rates from Spice.
`synchronous`(central_body_name, base_frame, ...)	Function for creating synchronous rotational ephemeris settings.
`spice`(base_frame, target_frame[, ...])	Function for creating rotation model settings from the Spice interface.
`gcrs_to_itrs`(precession_nutation_theory, ...)	Function for creating high-accuracy Earth rotation model settings.
`constant_rotation_model`(base_frame, ...)	Function for creating simple rotation model settings for target-frames with constant orientation.
`custom_rotation_model`(base_frame, ...)	Function for creating rotation model settings based on custom definition of rotation matrix.
`aerodynamic_angle_based`(central_body, ...[, ...])	Function for creating rotation model settings based on custom aerodynamic angles (attack, sideslip, bank).
`zero_pitch_moment_aerodynamic_angle_based`(...)	Function for creating rotation model settings based on an angle of attack calculated from pitch-trim, and custom aerodynamic angles sideslip, bank.
`custom_inertial_direction_based`(...[, ...])	Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in a user-defined inertial direction
`orbital_state_direction_based`(central_body, ...)	Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in the direction of a relative position or velocity vector.
`mars_high_accuracy`([base_frame, target_frame])	Function for creating high-accuracy Mars rotation model settings.
`mars_high_accuracy_custom_angles`(base_frame, ...)	Function for creating high-accuracy Mars rotation model settings with custom angles.
`mars_high_accuracy_full_custom`(base_frame, ...)	Function for creating fully customizable high-accuracy Mars rotation model settings.
`iau_rotation_model`(base_frame, target_frame, ...)	Function for creating a body rotation model using the typical formulation used by the IAU

simple(base_frame: str, target_frame: str, initial_orientation: numpy.ndarray[numpy.float64[3, 3]], initial_time: float | SupportsIndex, rotation_rate: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating simple rotation model settings.

Function for settings object, defining a basic rotation model with constant orientation of the rotation axis and constant rotation rate about this axis. Rotation from original (inertial) to target (body-fixed) frame at some reference time initial_time (\(t_{0}\)) is defined by the initial_orientation (\(\mathbf{R}^{(B/I)}(t_{0})\)) rotation matrix. Rotation about the body-fixed z-axis is defined by the rotation_rate (\(\omega\)) float variable (in rad/s). The rotation matrix is computed from:

\[\mathbf{R}^{(B/I)}(t)=\mathbf{R}_{z}(\omega(t-t_{0}))(t_{0})\mathbf{R}^{(B/I)}(t_{0})\]

where \(\mathbf{R}^{(B/I)}\) denotes the rotation matrix from inertial to body-fixed frame, and \(\mathbf{R}_{z}\) denotes a rotation matrix about the z-axis.

The matrix \(\mathbf{R}^{(B/I)}(t_{0})\) is sometimes parameterized by pole right ascension and declination (\(\alpha\) and \(\delta\)), as well as the meridian of date \(W_{0}\) with

\[\mathbf{R}^{(B/I)}(t_{0})=\mathbf{R}_{z}(W_{0})\mathbf{R}_{x}(\pi/2-\delta)\mathbf{R}_{z}(\pi/2+\alpha)\]

Parameters:

base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
initial_orientation (numpy.ndarray[numpy.float64[3, 3]]) – Orientation of target frame in base frame at initial time.
initial_time (astro.time_representation.Time) – Initial time (reference epoch for rotation matrices, as Time object representing seconds since J2000 TDB).
rotation_rate (float) – Constant rotation rate [rad/s] about rotational axis.

Returns:

Instance of the RotationModelSettings derived SimpleRotationModelSettings class

Return type:

SimpleRotationModelSettings

Examples

# Set parameters describing the rotation between the two frames
initial_orientation = np.array([[1, 0, 0], [0, -1, 0], [0, 0, 1]])
initial_time = 12345 # [sec since J2000]
rotation_rate = 2e-5 # [rad/s]
original_frame = "J2000"
target_frame = "Earth_Fixed_Simplified"
# Create the rotation model settings and assign to body settings of "Earth"
body_settings.get( "Earth" ).rotation_model_settings = environment_setup.rotation_model.simple(
    original_frame,
    target_frame,
    initial_orientation,
    initial_time,
    rotation_rate)

simple_from_spice(base_frame: str, target_frame: str, target_frame_spice: str, initial_time: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating simple rotation model settings using initial orientation and rotation rates from Spice.

Function for settings object, defining a simple() rotation model with the added functionality that the initial orientation and rotation rate are extracted from Spice, as opposed to provided manually. Note that only the initial orientation and rotation rate ( at the time defined by initial_time ) are extracted from Spice - for the full Spice rotation model see spice(). Also note the distinction between the target_frame and target_frame_spice parameters.

Parameters:

base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Target frame of rotation model - name of frame that Tudat assigns to the body-fixed frame
target_frame_spice (str) – Spice reference of target frame - name of the frame in Spice for which the initial orientation and rotation rate are extracted.
initial_time (astro.time_representation.Time) – Initial time (reference epoch for rotation matrices, as Time object representing seconds since J2000 TDB).

Returns:

Instance of the RotationModelSettings derived SimpleRotationModelSettings class

Return type:

SimpleRotationModelSettings

Notes

In order to create a SimpleRotationModelSettings object which describes a synchronous rotation w.r.t. some central_body, we require an ephemeris_settings attribute to the BodySettings object of the central_body.

Examples

In this example, we create RotationModelSettings for Earth, using a simple rotation model with constant orientation of the rotation axis (body-fixed z-axis), and constant rotation rate about this axis. The initial orientation and rotation rate are extracted from Spice at the time defined by initial_time:

# set parameters for time at which initial data is extracted from spice
initial_time = 12345
# set parameters for defining the rotation between frames
original_frame = "J2000"
target_frame = "IAU_Earth_Simplified"
target_frame_spice = "IAU_Earth"
# create rotation model settings and assign to body settings of "Earth"
body_settings.get( "Earth" ).rotation_model_settings = environment_setup.rotation_model.simple_from_spice(
original_frame, target_frame, target_frame_spice, initial_time)

synchronous(central_body_name: str, base_frame: str, target_frame: str) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating synchronous rotational ephemeris settings.

Function for settings object, defining a synchronous rotation model where rotation of a body is defined from its relative orbit w.r.t. some central body. Specifically - the body-fixed x-axis is always pointing towards the central body - the body-fixed z-axis is always perpendicular to the orbital plane (along the direction of \(\mathbf{x}\times\mathbf{v}\) ) - the body-fixed y-axis completes the right-handed reference frame

Such a model can be useful for, for instance, approximate rotation of tidally locked natural satellites or nadir-pointing spacecraft.

Parameters:

central_body_name (str) – Name of the central body of synchronous rotation.
base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Spice reference of target frame.

Returns:

Instance of the RotationModelSettings derived SynchronousRotationModelSettings class

Return type:

SynchronousRotationModelSettings

Examples

In this example, we create RotationModelSettings for the martian moon Phobos, We do so by assigning a synchronous rotation model to the rotation model settings of Phobos, using in this case "ECLIPJ2000" as the base frame, and "Phobos_Fixed" as the target frame.

# define parameters describing the synchronous rotation model
central_body_name = "Mars"
original_frame = "ECLIPJ2000"
target_frame = "Phobos_Fixed"
# create rotation model settings for target frame and assign to body settings of "Phobos"
body_settings.get( "Phobos" ).rotation_model_settings = environment_setup.rotation_model.synchronous(
central_body_name, original_frame, target_frame)

spice(base_frame: str, target_frame: str, spice_frame_name: str = '') → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings from the Spice interface.

Function for settings object, defining a rotation model directly (and entirely) from Spice interface.

Parameters:

base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
spice_frame_name (str, default = "") – Name of the spice reference frame name that will be used to compute the rotation to the target frame. For instance, if target_frame is set to “IAU_Earth”, and spice_frame_name is set to “IAU_Mars”, Tudat will extract the rotation to the IAU_Mars frame from Spice, and assign this rotation to the “IAU_Earth” frame in Tudat. By default, this input is left empty, which corresponds to it being equal to the target_frame.

Returns:

Instance of RotationModelSettings class.

Return type:

RotationModelSettings

Examples

In this example, we create RotationModelSettings for Earth, using full rotation model data from Spice:

# define parameters describing the rotation between frames
original_frame = "J2000"
target_frame = "IAU_Earth"
# create rotation model settings and assign to body settings of "Earth"
body_settings.get( "Earth" ).rotation_model_settings = environment_setup.rotation_model.spice(
original_frame, target_frame)

gcrs_to_itrs(precession_nutation_theory: tudatpy.kernel.dynamics.environment_setup.rotation_model.IAUConventions = <IAUConventions.iau_2006: 2>, base_frame: str = 'GCRS', cio_interpolation_settings: tudatpy.kernel.math.interpolators.InterpolatorGenerationSettings = None, tdb_to_tt_interpolation_settings: tudatpy.kernel.math.interpolators.InterpolatorGenerationSettings = None, short_term_eop_interpolation_settings: tudatpy.kernel.math.interpolators.InterpolatorGenerationSettings = None) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating high-accuracy Earth rotation model settings.

Function for settings object, defining high-accuracy Earth rotation model according to the IERS Conventions 2010. The model computes the rotation from ITRS to GCRS (with rotation matrix \(\mathbf{R}^{(\text{GCRS}/\text{ITRS})}\)) and its inverse from:

\[\mathbf{R}^{(\text{GCRS}/\text{ITRS})} = \mathbf{R}^{(\text{GCRS}/\text{CIRS})}(X,Y,s)\mathbf{R}^{(\text{CIRS}/\text{TIRS})}(\theta_{E})\mathbf{R}^{(\text{TIRS}/\text{ITRS})}(x_{p}, y_{p}, s')\]

using the intermediate frames TIRS (Terrestrial Intermediate Reference System) and CIRS (Celestial Intermediate Reference System) where (with equations referring to the IERS 2010 Conventions) \(\mathbf{R}^{(\text{GCRS}/\text{CIRS})}\) implements Eq. (5.10), \(\mathbf{R}^{(\text{CIRS}/\text{TIRS})}\) implements Eq. (5.5), and \(\mathbf{R}^{(\text{TIRS}/\text{ITRS})}\) implements Eq. (5.3). The inputs to these rotation matrices are :

\(X\), \(Y\): Celestial pole position elements
\(s\): The CIO (Celestial Intermediate Origin)
\(\theta_{E}\): Earth rotation angle (denoted as \(ERA\) in IERS Conventions)
\(x_{p}\), \(y_{p}\): Polar motion components
\(s'\): The TIO (Terrestrial Intermediate Origin)

Depending on the selected precession_nutation_theory input, the SOFA function iauXys00a, iauXys00b or iauXys06a is used to compute \(X,Y,s\), when selecting IAUConventions iau_2000a, iau_2000b or iau_2006, respectively. For epoch 01-01-1962 and later, corrections to the nominal values of \(X,Y\) are applied using linear interpolation of daily corrections for \(X,Y\) from the eopc04_14_IAU2000.62-now.txt file. The quantity \(s'\) is computed from Eq. (5.13) (implemented in SOFA’s iauSp00 function).

The value of \(\theta_{E}\) is computed directly from UTC-UT1, which is computed using settings given in default_time_scale_converter(), the computation of \(\theta_{E}\) from this quantity follows from Eq. (5.15), implemented by SOFA’s iauEra00 function.

The polar motion components \(x_{p}\), \(y_{p}\) are computed from:

Corrections for semi-diurnal variations due to libration for a non-rigid Earth as per Table 5.1a (with \(n=2\)) of IERS Conventions 2010
Corrections diurnal and semidiurnal variations due to ocean tides as per Tables 8.1a and 8.1b of the IERS Conventions 2010
Linear interpolation (correcting for discontinuities during days with leap seconds) of daily corrections for \(x_{p}, y_{p}\): from the eopc04_14_IAU2000.62-now.txt file in the tudat-resources directory (for epoch 01-01-1962 and later, zero otherwise)

Note that for this model the original frame must be J2000 or GCRS (in the case of the former, the frame bias between GCRS and J2000 is automatically corrected for). The target frame (e.g. body-fixed frame) name is ITRS. The target frame (e.g. body-fixed frame) name is ITRS.

Alternative options to modify the input (not exposed here) include the EOP correction file, input time scale, short period UT1 and polar motion variations.

Parameters:

precession_nutation_theory (IAUConventions, default=tba::iau_2006) – Setting theory for modelling Earth nutation.
base_frame (str, default='GCRS') – Base frame of rotation model

Returns:

Instance of the RotationModelSettings derived GcrsToItrsRotationModelSettings class

Return type:

GcrsToItrsRotationModelSettings

Examples

In this example, we create RotationModelSettings for Earth, using a high-accuracy Earth rotation model as defined by IERS Conventions 2010:

# define parameters describing the rotation between frames
precession_nutation_theory = environment_setup.rotation_model.IAUConventions.iau_2006
original_frame = "J2000"
# create rotation model settings and assign to body settings of "Earth"
body_settings.get( "Earth" ).rotation_model_settings = environment_setup.rotation_model.gcrs_to_itrs(
precession_nutation_theory, original_frame)

constant_rotation_model(base_frame: str, target_frame: str, initial_orientation: numpy.ndarray[numpy.float64[3, 3]]) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating simple rotation model settings for target-frames with constant orientation.

Function for settings object, defining simple rotation model setting objects with constant rotation matrix. These model settings are for target frames which do not have a rotational rate in the base frame and are fully defined by their initial orientation.

Parameters:

base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
initial_orientation (numpy.ndarray[numpy.float64[3, 3]]) – Rotation matrix from inertial to body-fixed (base to target) frame at initial time (constant throughout).

Returns:

Instance of the RotationModelSettings derived SimpleRotationModelSettings class.

Return type:

SimpleRotationModelSettings

Examples

In this example, we create RotationModelSettings for Earth, using a constant rotation matrix between Earth-fixed and inertial frame:

# define parameters describing the constant orientation between frames
original_frame = "ECLIPJ2000"
target_frame = "Earth_fixed"
constant_orientation = np.array([[1, 0, 0], [0, -1, 0], [0, 0, 1]])
# create rotation model settings and assign to body settings of "Earth"
body_settings.get( "Earth" ).rotation_model_settings = environment_setup.rotation_model.constant(
    original_frame,
    target_frame,
    constant_orientation )

custom_rotation_model(base_frame: str, target_frame: str, custom_rotation_matrix_function: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[3, 3]]], finite_difference_time_step: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings based on custom definition of rotation matrix.

Function for creating rotation model settings based on custom definition of rotation matrix. The user provides a custom function that computes the rotation matrix from body-fixed to inertial frame as a function of time. This function can depend on any quantities of the user’s choosing, for details on how to link the properties of the environment to this function, see our user guide. Since this function only computes the rotation matrix directly, the rotation matrix time derivative (and consequently, the angular velocity) are computed numerically, using a second order finite-difference method. Note that this computation of time derivative will only take into account the explicit time-dependence of thh custom rotation matrix.

Parameters:

base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
custom_rotation_matrix_function (callable[[Time], numpy.ndarray[numpy.float64[3, 3]]]) – Function computing the body-fixed to inertial rotation matrix as a function of time (Time object representing seconds since J2000 TDB)
finite_difference_time_step (float) – Step size to use when computing the rotation matrix derivative numerically

Returns:

Instance of the RotationModelSettings derived CustomRotationModelSettings class, which defines the required settings for the rotation model.

Return type:

CustomRotationModelSettings

aerodynamic_angle_based(central_body: str, base_frame: str, target_frame: str, angle_funcion: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[3, 1]]] = None) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings based on custom aerodynamic angles (attack, sideslip, bank).

Function for creating rotation model settings based on custom aerodynamic angles: angle of attack \(\alpha\), sideslip angle \(\beta\) and bank angle \(\sigma\). The use of this function is typical for simulating the dynamics of a (guided) re-entry vehicle. It calculates the rotation matrix from inertial frame to the body-fixed frame of the current body B (typically a vehicle) w.r.t. the body-fixed frame of a central body C (e.g., the body at which the re-entry is taking place. The full algorithm for \(R^{(I/B)}\) is described by Mooij (1994), and is composed of:

The rotation from inertial frame to the body fixed frame of body C, using the existing rotation model of body C
The rotation from body-fixed frame of body C to the vehicle’s vertical frame V. This rotation uses the current latitude and longitude angles.
The rotation of the vehicle’s vertical frame V to its trajectory frame T. This rotation uses the current heading and flight path angles.
The rotation of the vehicle’s trajectory frame T to its aerodynamic frame A. This rotation uses the current bank angle
The rotation of the vehicle’s aerodynamic frame A to its body-fixed frame. This rotation uses the current angle of attack and sideslip angles

In the above algorithm, the latitude, longitude, heading and flight-path angles are computed from the vehicle’s current translational state, in the body-fixed frame of body C. The angle of attack, sideslip angle and bank angle are to be defined by the user, through a single custom function that is passed to the angle_function argument of this functions

Parameters:

central_body (str) – Name of the central body C that is to be used.
base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
angle_function (callable[[Time], numpy.ndarray[numpy.float64[3, 1]]], default = None) – Custom function provided by the user, which returns an array of three values as a function of time (as Time object). The output of this function must be ordered as \([\alpha,\beta,\sigma]\). If this input is left empty, these angles are both fixed to 0.

Returns:

Instance of the RotationModelSettings derived CustomRotationModelSettings class, which defines the required settings for the rotation model.

Return type:

CustomRotationModelSettings

zero_pitch_moment_aerodynamic_angle_based(central_body: str, base_frame: str, target_frame: str, angle_funcion: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[2, 1]]] = None) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings based on an angle of attack calculated from pitch-trim, and custom aerodynamic angles sideslip, bank.

Function for creating rotation model settings based on an angle of attack calculated from pitch-trim, and custom aerodynamic angles sideslip, bank. This function is largely identical to the aerodynamic_angle_based(), with the difference that the angle of attack \(\alpha\) is not provided as a custom value by the user, but is calculated from the body’s aerodynamic moment coefficients, such that we have \(C_{m}=0\). This requires aerodynamic moment coefficients to be defined for the vehicle that depend on (among others) the body’s angle of attack

Parameters:

central_body (str) – Name of the central body C that is to be used.
base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
angle_funcion (callable[[Time], numpy.ndarray[numpy.float64[2, 1]]], default = None) – Custom function provided by the user, which returns an array of three values as a function of time (as Time object). The output of this function must be ordered as \([\beta,\sigma]\). If this input is left empty, these angles are both fixed to 0.

Returns:

Instance of the RotationModelSettings derived CustomRotationModelSettings class, which defines the required settings for the rotation model.

Return type:

CustomRotationModelSettings

custom_inertial_direction_based(inertial_body_axis_direction: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[3, 1]]], base_frame: str, target_frame: str, free_rotation_angle_function: Callable[[float | SupportsIndex], float] = None) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in a user-defined inertial direction

Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in a user-defined inertial direction \(\hat{\mathbf{T}}_{I}\). Specifically, it ensures that the rotation matrix from body-fixed to inertial frame is set up such that \(\hat{\mathbf{T}}_{I}=R^{(I/B)}\hat{\mathbf{i}}\) (where \(\mathbf{i}\) is the unit-vector in local x-direction). The complete rotation matrix requires an additional angle \(\phi\) (rotation of the body about its body-fixed x-axis), which is set to 0 by default.

The full rotation matrix is computed from a 3-2-1 Euler angle rotation \(R^{(I/B)}=R_{z}(\psi)R_{y}(\theta)R_{x}(\phi)\), with \(\psi\) and \(\theta\) computed from the suitable decomposition of \(\hat{\mathbf{T}}_{I}\). This function is typically used for simulating the (guided) dynamics of a spacecraft under thrust, where the thrust is provided in the x-direction of the body-fixed frame. By providing a suitable inertial_body_axis_direction, this thrust can be defined to point in an arbitrary direction (typically defined by a guidance algorithm) in the inertial frame as a function of time.

NOTE: the inertial_body_axis_direction is called with a NaN input at the start of each function evaluation of the full state derivative. This signals the start of a new evaluation and can be used to make custom models more efficient if multiple (related) custom functions are implemented in a single class custom model user guide. However, this does require that calling the inertial_body_axis_direction with NaN input does not result in an exception.

Parameters:

inertial_body_axis_direction (callable[[Time], numpy.ndarray[numpy.float64[3, 1]]]) – Custom function defined by the user, which imposes the inertial orientation of the body-fixed x-axis, by providing \(\hat{\mathbf{T}}_{I}(t)\).
base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
free_rotation_angle_function (callable[[Time], float], default = None) – Custom function provided by the user, which returns a value for the free rotation angle \(\phi\) about the body-fixed x-axis as a function of time. If this input is left empty, this angle is fixed to 0.

Returns:

Instance of the RotationModelSettings derived BodyFixedDirectionBasedRotationSettings class, which defines the required settings for the rotation model.

Return type:

BodyFixedDirectionBasedRotationSettings

orbital_state_direction_based(central_body: str, is_colinear_with_velocity: bool, direction_is_opposite_to_vector: bool, base_frame: str, target_frame: str = '', free_rotation_angle_function: Callable[[float | SupportsIndex], float] = None) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in the direction of a relative position or velocity vector.

Function for creating rotation model settings where the body-fixed x-axis is imposed to lie in the direction of a relative position or velocity vector. This function is similar to the custom_inertial_direction_based() function, with the exception that the \(\hat{\mathbf{T}}_{I}\) vector is not defined by thee user, but is defined by the relative position vector \(\mathbf{r}_{C}\) or velocity vector \(\mathbf{r}_{C}\) of the vehicle w.r.t. some body C. The inputs to this function allow \(\hat{\mathbf{T}}_{I}\) to be set to \(\pm\mathbf{r}_{C}\) or \(\pm\mathbf{v}_{C}\), for any body C. It is typically used for simplified or preliminary thrust analyses.

Parameters:

central_body (str) – Name of central body w.r.t. which the position/velocity vector is to be computed
is_colinear_with_velocity (bool) – Boolean defining whether \(\hat{\mathbf{T}}_{I}\) is to be aligned with velocity (if true) or position (if false)
direction_is_opposite_to_vector (bool) – Boolean defining whether \(\hat{\mathbf{T}}_{I}\) is to be in the same direction as position/velocity (if false), or in the opposite direction (if true).
base_frame (str) – Name of the base frame of rotation model.
target_frame (str) – Name of the target frame of rotation model.
free_rotation_angle_function (callable[[Time], float], default = None) – Custom function provided by the user, which returns a value for the free rotation angle \(\phi\) about the body-fixed x-axis as a function of time (as Time object). If this input is left empty, this angle is fixed to 0.

Returns:

Instance of the RotationModelSettings derived BodyFixedDirectionBasedRotationSettings class, which defines the required settings for the rotation model.

Return type:

BodyFixedDirectionBasedRotationSettings

mars_high_accuracy(base_frame: str = 'J2000', target_frame: str = 'Mars_Fixed') → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating high-accuracy Mars rotation model settings.

Function for settings object, defining a high-accuracy rotation model for Mars according to Konopliv et al. (2016). This model includes corrections for nutation, polar motion, and libration with the latest parameters.

Parameters:

base_frame (str, default="J2000") – Name of the base frame of rotation model (typically “J2000” or “ECLIPJ2000”).
target_frame (str, default="Mars_Fixed") – Name of the target (body-fixed) frame of rotation model.

Returns:

Instance of the RotationModelSettings derived PlanetaryRotationModelSettings class.

Return type:

RotationModelSettings

Examples

In this example, we create rotation model settings for Mars using the high-accuracy model:

# define parameters describing the rotation between frames
base_frame = "J2000"
target_frame = "Mars_Fixed"

# create rotation model settings
mars_rotation_settings = environment_setup.rotation_model.mars_high_accuracy(
    base_frame, target_frame)

mars_high_accuracy_custom_angles(base_frame: str, target_frame: str, angle_n: float | SupportsIndex, angle_j: float | SupportsIndex, angle_psi_at_epoch: float | SupportsIndex, angle_psi_rate_at_epoch: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating high-accuracy Mars rotation model settings with custom angles.

Function for settings object, defining a high-accuracy rotation model for Mars with user-provided values for the basic angles (right ascension of pole, declination of pole, prime meridian angle and rate).

Parameters:

base_frame (str) – Name of the base frame of rotation model (typically “J2000” or “ECLIPJ2000”).
target_frame (str) – Name of the target (body-fixed) frame of rotation model.
angle_n (float) – Right ascension of Mars’ rotation axis (radians).
angle_j (float) – Declination of Mars’ rotation axis (radians).
angle_psi_at_epoch (float) – Prime meridian angle at epoch (radians).
angle_psi_rate_at_epoch (float) – Prime meridian rotation rate (radians/s).

Returns:

Instance of the RotationModelSettings derived PlanetaryRotationModelSettings class.

Return type:

RotationModelSettings

Examples

In this example, we create rotation model settings for Mars using the high-accuracy model with custom basic angles:

import numpy as np

# define parameters
base_frame = "J2000"
target_frame = "Mars_Fixed_Custom"
angle_n = np.radians(3.37919183)  # Right ascension in radians
angle_j = np.radians(24.67682669)  # Declination in radians
angle_psi_at_epoch = np.radians(81.9683988)  # Initial prime meridian angle
angle_psi_rate_at_epoch = -7608.3 * np.pi/(180.0*1000.0*3600.0) / 31557600.0  # Rotation rate

# create rotation model settings with custom angles
mars_rotation_settings = environment_setup.rotation_model.mars_high_accuracy_custom_angles(
    base_frame, target_frame, angle_n, angle_j, angle_psi_at_epoch, angle_psi_rate_at_epoch)

mars_high_accuracy_full_custom(base_frame: str, target_frame: str, angle_n: float | SupportsIndex, angle_j: float | SupportsIndex, angle_psi_at_epoch: float | SupportsIndex, angle_psi_rate_at_epoch: float | SupportsIndex, nutation_correction_settings: dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]], mean_motion_time_dependent_phase_nutation_corrections: list[dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]]], rotation_rate_corrections: dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]], x_polar_motion_coefficients: dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]], y_polar_motion_coefficients: dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]]) → tudatpy.kernel.dynamics.environment_setup.rotation_model.RotationModelSettings¶

Function for creating fully customizable high-accuracy Mars rotation model settings.

Function for settings object, defining a high-accuracy rotation model for Mars with user-provided values for all parameters, including basic angles and all correction coefficients for nutation, polar motion, and libration.

Parameters:

base_frame (str) – Name of the base frame of rotation model (typically “J2000” or “ECLIPJ2000”).
target_frame (str) – Name of the target (body-fixed) frame of rotation model.
angle_n (float) – Right ascension of Mars’ rotation axis (radians).
angle_j (float) – Declination of Mars’ rotation axis (radians).
angle_psi_at_epoch (float) – Prime meridian angle at epoch (radians).
angle_psi_rate_at_epoch (float) – Prime meridian rotation rate (radians/s).
nutation_correction_settings (dict[float, tuple[float, float]]) – Nutation correction coefficients, mapping from harmonic number to (cos coefficient, sin coefficient) pairs.
mean_motion_time_dependent_phase_nutation_corrections (list[dict[float, tuple[float, float]]]) – Mean motion time-dependent phase nutation corrections.
rotation_rate_corrections (dict[float, tuple[float, float]]) – Rotation rate correction coefficients, mapping from harmonic number to (cos coefficient, sin coefficient) pairs.
x_polar_motion_coefficients (dict[float, tuple[float, float]]) – X-polar motion coefficients, mapping from harmonic number to (cos coefficient, sin coefficient) pairs.
y_polar_motion_coefficients (dict[float, tuple[float, float]]) – Y-polar motion coefficients, mapping from harmonic number to (cos coefficient, sin coefficient) pairs.

Returns:

Instance of the RotationModelSettings derived PlanetaryRotationModelSettings class.

Return type:

RotationModelSettings

Examples

In this example, we create rotation model settings for Mars using the high-accuracy model with fully custom parameters:

import numpy as np
from collections import defaultdict

# Define basic parameters
base_frame = "J2000"
target_frame = "Mars_Fixed_Custom"
angle_n = np.radians(3.37919183)
angle_j = np.radians(24.67682669)
angle_psi_at_epoch = np.radians(81.9683988)
angle_psi_rate_at_epoch = -7608.3 * np.pi/(180.0*1000.0*3600.0) / 31557600.0

# Define correction coefficients
milliarcsec_to_rad = np.pi / (180.0 * 1000.0 * 3600.0)

# Create nutation correction settings
nutation_corrections = {
    0.0: (-1.4 * milliarcsec_to_rad, 0.0),
    1.0: (-0.4 * milliarcsec_to_rad, -632.6 * milliarcsec_to_rad),
    2.0: (0.0, -44.2 * milliarcsec_to_rad),
    3.0: (0.0, -4.0 * milliarcsec_to_rad)
}

# Create mean motion time-dependent phase nutation corrections
mean_motion_corrections = [{
    1.0: (-49.1 * milliarcsec_to_rad, -104.5 * milliarcsec_to_rad),
    2.0: (515.7 * milliarcsec_to_rad, 1097.0 * milliarcsec_to_rad),
    3.0: (112.8 * milliarcsec_to_rad, 240.1 * milliarcsec_to_rad),
    4.0: (19.2 * milliarcsec_to_rad, 40.9 * milliarcsec_to_rad),
    5.0: (3.0 * milliarcsec_to_rad, 6.5 * milliarcsec_to_rad),
    6.0: (0.4 * milliarcsec_to_rad, 1.0 * milliarcsec_to_rad)
}]

# Create rotation rate corrections
rotation_rate_corrections = {
    1.0: (481.0 * milliarcsec_to_rad, -331.0 * milliarcsec_to_rad),
    2.0: (-103.0 * milliarcsec_to_rad, -101.0 * milliarcsec_to_rad),
    3.0: (-35.0 * milliarcsec_to_rad, -4.0 * milliarcsec_to_rad),
    4.0: (-10.0 * milliarcsec_to_rad, -8.0 * milliarcsec_to_rad)
}

# Create polar motion coefficients
x_polar_motion = {
    1.0: (2.8 * milliarcsec_to_rad * np.sin(np.radians(46.5)),
          2.8 * milliarcsec_to_rad * np.cos(np.radians(46.5))),
    2.0: (8.9 * milliarcsec_to_rad * np.sin(np.radians(-150.1)),
          8.9 * milliarcsec_to_rad * np.cos(np.radians(-150.1))),
    3.0: (0.0, 0.0),
    4.0: (0.0, 0.0),
    3.34: (0.0, 50.0 * milliarcsec_to_rad)
}

y_polar_motion = {
    1.0: (11.7 * milliarcsec_to_rad * np.sin(np.radians(118.7)),
          11.7 * milliarcsec_to_rad * np.cos(np.radians(118.7))),
    2.0: (3.9 * milliarcsec_to_rad * np.sin(np.radians(172.5)),
          3.9 * milliarcsec_to_rad * np.cos(np.radians(118.7))),
    3.0: (0.0, 0.0),
    4.0: (0.0, 0.0),
    3.34: (0.0, 50.0 * milliarcsec_to_rad)
}

# Create fully customized rotation model settings
mars_rotation_settings = environment_setup.rotation_model.mars_high_accuracy_full_custom(
    base_frame, target_frame, angle_n, angle_j, angle_psi_at_epoch, angle_psi_rate_at_epoch,
    nutation_corrections, mean_motion_corrections, rotation_rate_corrections,
    x_polar_motion, y_polar_motion)

iau_rotation_model(base_frame: str, target_frame: str, nominal_meridian: float | SupportsIndex, nominal_pole: numpy.ndarray[numpy.float64[2, 1]], rotation_rate: float | SupportsIndex, pole_precession: numpy.ndarray[numpy.float64[2, 1]], merdian_periodic_terms: dict[float | SupportsIndex, tuple[float | SupportsIndex, float | SupportsIndex]], pole_periodic_terms: dict[float | SupportsIndex, tuple[numpy.ndarray[numpy.float64[2, 1]], float | SupportsIndex]], reference_epoch_j2000: float | SupportsIndex = 0.0, angle_base_frame: str = '') → tudatpy.kernel.dynamics.environment_setup.rotation_model.IAURotationModelSettings¶

Function for creating a body rotation model using the typical formulation used by the IAU

Function for creating a body rotation model using the typical formulation used by the International Astronomical Union (IAU), such as those in :[4]. It uses the following formulation \(\mathbf{R}^{(B/I)}(t)\) for the body-fixed to inertial rotation, defined by the rotation pole right ascension and declination (\(\alpha\) and \(\delta\)), and the prime meridian angle \(W\):

\[\mathbf{R}^{(B/I)}(t)=\mathbf{R}_{z}(W(t))\mathbf{R}_{x}(\pi/2-\delta(t))\mathbf{R}_{z}(\pi/2+\alpha(t))\]

Unlike the simple() rotation model, which has a similar formulation, the rotation angles \(W\), \(\alpha\) and \(\delta\) are functions of time:

\[\begin{split}W(t)=W_{0}+\dot{W}(t-t_{0})+\sum_{i}W_{i}\sin(\omega_{W_i}(t-t_{0})+\phi_{W_i})\\ \alpha(t)=\alpha_{0}+\dot{\alpha}(t-t_{0})+\sum_{i}\alpha_{i}\sin(\omega_{N_i}t(t-t_{0})+\phi_{N_i})\\ \delta(t)=\delta_{0}+\dot{\delta}(t-t_{0})+\sum_{i}\delta_{i}\cos(\omega_{N_i}t(t-t_{0})+\phi_{N_i})\\\end{split}\]

so that the angles are a combination of a linear term (rotation rate for \(W\); precession for \(\alpha\) and \(\delta\)) and a series of periodic terms (typically termed librations for \(W\) and nutation for \(\alpha\) and \(\delta\)).

Parameters:

base_frame (str) – Name of the base frame of rotation model (typically “J2000” or “ECLIPJ2000”).
target_frame (str) – Name of the target (body-fixed) frame of rotation model.
nominal_meridian (float) – Value of \(W_{0}\)
nominal_pole (numpy.ndarray[numpy.float64[2, 1]]) – Values of \([\alpha_{0},\delta_{0}]\)
rotation_rate (float) – Value of \(\dot{W}\)
pole_precession (numpy.ndarray[numpy.float64[2, 1]]) – Values of \([\dot{\alpha},\dot{\delta}]\)
merdian_periodic_terms (dict[float, tuple[float, float]]) – Libration terms in \(W\) that are to be used. Dictionary key is value of \(\omega_{W_i}\). Value is a pair consisting of [\(W_{i}\),:math:phi_{W_{i}}]
pole_periodic_terms (list[dict[float, tuple[numpy.ndarray[numpy.float64[2, 1]], float]]]) – Nutation terms for \(\alpha,\delta\) that are to be used. Dictionary key is value of \(\omega_{N_{i}}\). Value is a pair consisting of [[\(\alpha_{i},\delta_{i}\)],:math:phi_{N_{i}}]
angle_base_frame (str) – Optional argument to be used when the angles \(W,\alpha,\delta\) do not define the rotation between target_frame and base_frame, but between target_frame and angle_base_frame (this input). The additional required rotation between angle_base_frame and base_frame is then added to the computation of the rotation matrix (presently only J2000 and ECLIPJ2000 are supported for this input).

Returns:

Instance of the RotationModelSettings class

Return type:

RotationModelSettings

Enumerations¶

`RotationModelType`	Enumeration of rotation model types.
`IAUConventions`	Enumeration of IAU conventions for Earth rotation.

class RotationModelType¶

Bases: pybind11_object

Enumeration of rotation model types.

Enumeration of rotation model types supported by tudat.

Members:

simple_rotational_model : No documentation found.

spice_rotation_model :

gcrs_to_itrs_rotation_model :

synchronous_rotation_model :

planetary_rotation_model :

RotationModelType.name -> str

class IAUConventions¶

Bases: pybind11_object

Enumeration of IAU conventions for Earth rotation.

Enumeration of IAU conventions for Earth rotation supported by tudat.

Members:

iau_2000_a :

iau_2000_b :

iau_2006 :

IAUConventions.name -> str

Classes¶

RotationModelSettings

Base class for providing settings for automatic rotation model creation.

class RotationModelSettings¶

Bases: pybind11_object

Base class for providing settings for automatic rotation model creation.

This class is a functional base class for settings of rotation models that require no information in addition to their type. Basic rotation model has constant orientation of the rotation axis (body-fixed z-axis) and constant rotation rate about this axis. Rotation models requiring additional information must be created using the functions which create the specific object derived from this base class.

property base_frame¶

Name of the base frame of rotation model.

Type:: str

property rotation_type¶

read-only

Type of rotation model that is to be created.

Type:: RotationModelType

property target_frame¶

read-only

Name of the target frame of rotation model.

Type:: str

rotation_model¶

Functions¶

Enumerations¶

Classes¶

`rotation_model`¶