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

Factory function for creating simple rotation model settings. 

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

Factory function for creating synchronous rotational ephemeris settings. 

Factory function for creating rotation model settings from the Spice interface. 

Factory function for creating highaccuracy Earth rotation model settings. 

Factory function for creating simple rotation model settings for targetframes with constant orientation. 

Factory function for creating rotation model settings based on custom aerodynamic angles (attack, sideslip, bank). 
Factory function for creating rotation model settings based on an angle of attack calculated from pitchtrim, and custom aerodynamic angles sideslip, bank. 


Factory function for creating rotation model settings where the bodyfixed xaxis is imposed to lie in a userdefined inertial direction 

Factory function for creating rotation model settings where the bodyfixed xaxis is imposed to lie in the direction of a relative position or velocity vector. 
Factory function for creating a highaccuracy Mars rotation model. 
 simple(base_frame: str, target_frame: str, initial_orientation: numpy.ndarray[numpy.float64[3, 3]], initial_time: float, rotation_rate: float) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating simple rotation model settings.
Factory 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 (bodyfixed) frame at some reference time
initial_time
(\(t_{0}\)) is defined by theinitial_orientation
(\(\mathbf{R}^{(B/I)}(t_{0})\)) rotation matrix. Rotation about the bodyfixed zaxis is defined by therotation_rate
(\(\omega\)) float variable (in rad/s). The rotation matrix is computed from:\[\mathbf{R}^{(B/I)}(t)=\mathbf{R}_{z}(\omega(tt_{0}))(t_{0})\mathbf{R}^{(B/I)}(t_{0})\]where \(\mathbf{R}^{(B/I)}\) denotes the rotation matrix from inertial to bodyfixed frame, and \(\mathbf{R}_{z}\) denotes a rotaion matrix about the zaxis.
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 (float) – Initial time (reference epoch for rotation matrices).
rotation_rate (float) – Constant rotation rate [rad/s] about rotational axis.
 Returns:
Instance of the
RotationModelSettings
derivedSimpleRotationModelSettings
class Return type:
SimpleRotationModelSettings
Examples
In this example, we create
RotationModelSettings
for Earth, using a simple rotation model with constant orientation of the rotation axis (bodyfixed zaxis), and constant rotation rate about this axis:# 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 = 2e5 # [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) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating simple rotation model settings using initial orientation and rotation rates from Spice.
Factory 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 byinitial_time
) are extracted from Spice  for the full Spice rotation model seespice()
. Also note the distinction between thetarget_frame
andtarget_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 bodyfixed 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 (float) – Initial time (reference epoch for rotation matrices).
 Returns:
Instance of the
RotationModelSettings
derivedSimpleRotationModelSettings
class Return type:
SimpleRotationModelSettings
Notes
In order to create a
SimpleRotationModelSettings
object which describes a synchronous rotation w.r.t. somecentral_body
, we require anephemeris_settings
attribute to theBodySettings
object of thecentral_body
.Examples
In this example, we create
RotationModelSettings
for Earth, using a simple rotation model with constant orientation of the rotation axis (bodyfixed zaxis), and constant rotation rate about this axis. The initial orientation and rotation rate are extracted from Spice at the time defined byinitial_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.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating synchronous rotational ephemeris settings.
Factory 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 bodyfixed xaxis is always pointing towards the central body  the bodyfixed zaxis is always perpendicular to the orbital plane (along the direction of \(\mathbf{x}\times\mathbf{v}\) )  the bodyfixed yaxis completes the righthanded reference frame
Such a model can be useful for, for instance, approximate rotation of tidally locked natural satellites or nadirpointing spacecraft.
 Parameters:
 Returns:
Instance of the
RotationModelSettings
derivedSynchronousRotationModelSettings
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) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating rotation model settings from the Spice interface.
Factory function for settings object, defining a rotation model directly (and entirely) from Spice interface.
 Parameters:
 Returns:
Instance of
RotationModelSettings
class. Return type:
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.numerical_simulation.environment_setup.rotation_model.IAUConventions = <IAUConventions.iau_2006: 2>, base_frame: str = 'GCRS') tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating highaccuracy Earth rotation model settings.
Factory function for settings object, defining highaccuracy Earth rotation model according to the IERS 2010 Conventions. This settings class has various options to deviate from the default settings, typical applications will use default. 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. bodyfixed frame) name is ITRS. The precessionnutation theory may be any member of
IAUConventions
(iau_2000a
/iau_2000b
oriau_2006
). Alternative options to modify the input (not shown here) include the EOP correction file, input time scale, short period UT1 and polar motion variations. The target frame (e.g. bodyfixed frame) name is ITRS. 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
derivedGcrsToItrsRotationModelSettings
class Return type:
GcrsToItrsRotationModelSettings
Examples
In this example, we create
RotationModelSettings
for Earth, using a highaccuracy Earth rotation model as defined by IERS 2010 conventions:# 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.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating simple rotation model settings for targetframes with constant orientation.
Factory 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 bodyfixed (base to target) frame at initial time (constant throughout).
 Returns:
Instance of the
RotationModelSettings
derivedSimpleRotationModelSettings
class. Return type:
SimpleRotationModelSettings
Examples
In this example, we create
RotationModelSettings
for Earth, using a constant rotation matrix between Earthfixed 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 )
 aerodynamic_angle_based(central_body: str, base_frame: str, target_frame: str, angle_funcion: Callable[[float], numpy.ndarray[numpy.float64[3, 1]]] = None) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating rotation model settings based on custom aerodynamic angles (attack, sideslip, bank).
Factory 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) reentry vehicle. It calculates the rotation matrix from inertial frame to the bodyfixed frame of the current body B (typically a vehicle) w.r.t. the bodyfixed frame of a central body C (e.g., the body at which the reentry 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 bodyfixed 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 bodyfixed frame. This rotation uses the current angle of attack and sideslip angles
In the above algorithm, the latitude, longitude, heading and flightpath angles are computed from the vehicle’s current translational state, in the bodyfixed 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[[float], 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. 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
derivedCustomRotationModelSettings
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], numpy.ndarray[numpy.float64[2, 1]]] = None) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating rotation model settings based on an angle of attack calculated from pitchtrim, and custom aerodynamic angles sideslip, bank.
Factory function for creating rotation model settings based on an angle of attack calculated from pitchtrim, 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[[float], 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. 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
derivedCustomRotationModelSettings
class, which defines the required settings for the rotation model. Return type:
CustomRotationModelSettings
 custom_inertial_direction_based(inertial_body_axis_direction: Callable[[float], numpy.ndarray[numpy.float64[3, 1]]], base_frame: str, target_frame: str, free_rotation_angle_function: Callable[[float], float] = None) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating rotation model settings where the bodyfixed xaxis is imposed to lie in a userdefined inertial direction
Factory function for creating rotation model settings where the bodyfixed xaxis is imposed to lie in a userdefined inertial direction \(\hat{\mathbf{T}}_{I}\). Specifically, it ensures that the rotation matrix from bodyfixed to inertial frame is set up such that \(\hat{\mathbf{T}}_{I}=R^{(I/B)}\hat{\mathbf{i}}\) (where \(\mathbf{i}\) is the unitvector in local xdirection). The complete rotation matrix requires an additional angle \(\phi\) (rotation of the body about its bodyfixed xaxis), which is set to 0 by default.
The full rotation matrix is computed from a 321 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 xdirection of the bodyfixed 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: this function may be extended in the future to allow an arbitrary bodyfixed direction to align with an arbitrary inertial direction. At present, its functionality is limited to imposing the inertial direction of the bodyfixed xaxis.
 Parameters:
inertial_body_axis_direction (Callable[[float], numpy.ndarray[numpy.float64[3, 1]]]) – Custom function defined by the user, which imposes the inertial orientation of the bodyfixed xaxis, 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[[float], float], default = None) – Custom function provided by the user, which returns a value for the free rotation angle \(\phi\) about the bodyfixed xaxis as a function of time. If this input is left empty, this angle is fixed to 0.
 Returns:
Instance of the
RotationModelSettings
derivedBodyFixedDirectionBasedRotationSettings
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], float] = None) tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating rotation model settings where the bodyfixed xaxis is imposed to lie in the direction of a relative position or velocity vector.
Factory function for creating rotation model settings where the bodyfixed xaxis 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[[float], float], default = None) – Custom function provided by the user, which returns a value for the free rotation angle \(\phi\) about the bodyfixed xaxis as a function of time. If this input is left empty, this angle is fixed to 0.
 Returns:
Instance of the
RotationModelSettings
derivedBodyFixedDirectionBasedRotationSettings
class, which defines the required settings for the rotation model. Return type:
BodyFixedDirectionBasedRotationSettings
 mars_high_accuracy() tudatpy.kernel.numerical_simulation.environment_setup.rotation_model.RotationModelSettings #
Factory function for creating a highaccuracy Mars rotation model.
Factory function for creating a highaccuracy Mars rotation model, using the default parameters of Konopliv et al. (2016) and the mathematical model of ` Konopliv et al. (2006) <https://www.sciencedirect.com/science/article/pii/S0019103506000297>`_. The rotation matrix formulation is given in Eq. (13)(19) of that paper. Note that, at the moment, all parameters in this rotation model are hard coded, and cannot be adapted by the user (except by estimating a number of its constituent parameters, see parameter module ) As such, this model is at present applicable to Mars rotation only. If you require more finegrained control of the parameters, please contact the Tudat support team
 Returns:
Instance of the
RotationModelSettings
derivedPlanetaryRotationModelSettings
class, which defines the required settings for the rotation model. Return type:
Enumerations#
Enumeration of rotation model types. 

Enumeration of IAU conventions for Earth rotation. 
 class RotationModelType#
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 :
 property name#
Classes#
Base class for providing settings for automatic rotation model creation. 
 class RotationModelSettings#
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 (bodyfixed zaxis) and constant rotation rate about this axis. Rotation models requiring additional information must be created using the factory functions which create the specific object derived from this base class.
 property rotation_type#
readonly
Type of rotation model that is to be created.
 Type: