Frames in the Environment
In any state propagation tool, the careful use of reference frames is essential: small mistakes in definitions and conventions
are a notorious source of errors in simulations. The environment and state propagation framework in Tudat handles all the
relevant state translations/rotations/transformations. On this page, we describe various manners in which reference frames
are used in the environment Tudat, in particular in the Body objects (which
constitute the environment). In addition, we highlight what the differences are when extracting a state from different places in Tudat.
This page is limited mainly in the manner that Tudat automatically deals with various different frames. A comprehensive list of
all available frames that are available to the user can be found here.
Content of this page
Translational states
The translational state of a body is a critical piece of information for numerous calculations in the Tudat propagation framework. For instance, (almost) any acceleration acting on a body \(A\) will require the Cartesian state of this body as input.
In Tudat, we use the terms frame and element to describe the following disinct concepts:
Frame orientation: Defines the orientation in inertial space of the set of unit vectors the \(x\), \(y\) and \(z\) axes. These orientations may be constant in time, in which case the frame is said to have an inertial orientation (for instance the J2000 frame orientation), or a time-dependent orientation (for instance an Earth-fixed frame orientation).
Frame origin: Defines the point in inertial space that defines the \(\mathbf{0}\) position (\(x=y=z=0\)). This point may be constant in time, in which case the frame is said to have an inertial origin (for instance: the solar system barycentric origin), or a time-dependent orientation (for instance an Earth-centered origin).
Elements: The physical meaning of the values of a state vector that represent a (translational) state. Examples are Cartesian, Keplerian and Modified Equinoctial. With the exception of possible singularities, these different element types can use six (or more) values to defines the same physical state, but using a very different set of numbers.
The frame itself does not define anything concerning the (state) vector, instead it defines how a specific set of elements represents a specific physical state. In Tudat, a state vector is represented as a vector (numpy in Python; Eigen in C++). The state vector itself cannot store the element set or frame orientation in which it is defined. This information is tracked by Tudat (for internal compuations) or should be tracked by a user (for any user-defined state vector).
In the rest of this section, we will present how Tudat deals with the calculation and transformation of frame origins and orientations. Through out, we will assume that all translational state vectors are represented in Cartesian coordinates.
When running a state propagation, one of the first steps that is performed when evaluating the state derivative function \(\mathbf{f}(\mathbf{x},t)\) (see A single function evaluation) is to update the full environment to the current time \(t\) and state \(\mathbf{x}\). Note that in a basic simulation, \(\mathbf{x}\) is the translational state of a single body. See Interacting with the environment during propagation for details on how to access the current properties of the environment during a propagation.
Even when propagating the dynamics using a non-Cartesian propagator, for instance Keplerian elements,
(see TranslationalPropagatorType
for full list of options), the translational state of a body is always set as its Cartesian state,
with any relevant element conversions performed automatically. The Cartesian state may extracted from one
of two places when the body is updated:
State vector: if the translational state of body \(A\) is among the states that is numerically propagated, these elements will be extracted from the full state, and any relevant frame and elements conversions performed to define the current state of the body \(A\)
Ephemeris of a body: if the translational state of a body is required for a simulation, and this body is not numerically propagated, its state is retrieved from this body’s ephemeris (see
Ephemeris).
Frame origin
Due to the above setup, three different definitions of states are used, where each may have its own distinct origin.
State vector - the variables for which the differential equations are solved numerically during the propagation
Ephemeris - a function of time that is fully defined before the state propagationm
Body - defined from propagated state vector and/or ephemeris at the start of each state derivative evaluation
Tudat allows the flexibility to define a different origin for each one, with relevant translations automatically performed. Below, we summarize each one:
The propagation origin - the propagated state
When define translational propagator settings (see Translational Dynamics), the propagation origin defines the origin w.r.t. which the state vector is defined. For instance if the propagated body is ‘spacecraft’ and the propagation origin (or synonymously, the central body) is ‘Earth’, the state vector will be relative position/velocity of spacecraft w.r.t. Earth.
When defining the initial state of a body: this must be w.r.t. the propagation origin
When retrieving the numerical propagation results, these are always w.r.t. the propagation origin
The ephemeris origin - the states computed by an ephemeris
Each body that is not numerically propagated is typically (but not necessarily) endowed with an ephemeris, which contains a pre-defined function of the body’s translational state as a function of time. Unlike the global origin, the ephemeris origin of each body may be different. In the context of a numerical simulation, users do not often interrogate the ephemeris directly. However, it can be useful to do so outside of a numerical propagation, for instance to analyze the predefined trajectory of a body outside of the propagation framework
When directly retrieving the state from an ephemeris object.
The global origin - the current states in the bodies
When creating a set of body objects, you define a global frame origin, and a global frame orientation.
When a body’s state gets updated (see propagation architecture page, regardless of whether it is retrieved
from the propagated state vector, or an ephemeris, it is always
converted to this global frame origin/orientation before being assigned to a body object.
Consequently, any time that a state is retrieved directly from a body object during the propagation using the state
function (as described here), it will always be defined in this global frame.
The global frame is the same for each body in a simulation. All used for calculations of the state derivative are in this global frame.
Consequently, an (in)judicious choice of global frame origin may have an impact on the numerical noise in a simulation.
For instance, when calculating the dynamics of a spacecraft w.r.t. the Earth, the relative position of the spacecraft w.r.t. the
Earth is computed by extracting the position \(\mathbf{r}\) from the body object representing Earth, and from the body representing the spacecraft.
If the global frame origin is Earth, we will have \(\mathbf{r}=\mathbf{0}\), by definition. However, if the global frame origin set to SSB, the relative position of spacecraft w.r.t. Earth will be calculated by subtracting the barycentric positions of the spacecraft and Earth (of order \(10^{11}\) m) to compute the relative position (or order \(10^{7}\) m for low-to-medium altitude orbits). As a result, 4 orders of magnitude of numerical precision may be lost in the calulcation of the spacecraft position that is used in the calculation of the accelerations.
Any time the state (or position or velocity) are retrieved directly from a body. This will, for instance, be done in custom guidance models.
When high numerical precision is relevant, the global frame origin should be set such that numerical error in evaluating the strongest acceleration(s) is minimized
Frame orientation
Presently, Tudat does not support the automatic rotation of states between the state vector, ephemeris, or body objects (as it does
for the frame origin). Consequently, the frame orientation of each must be equal, as well as inertial. Currently, the frame orientations
J2000 and ECLIPJ2000 are supported (see here). A large number of additional frame orientations can be
used (either by the user or built-in functionality), a comprehensive list of which is provided here
Rotational states
The handling of rotational states in the environment and propagation framework follows that of the translational states to a large degree. However, there is one fewer complication for rotational states: no frame ‘origin’ has to be defined, which simplifies the overall book-keeping of the states. A rotation may be extracted from/defined in one of three places:
During the propagation: directly from a Body object (see Rotational state)
Rotational ephemeris
State vector (if a rotational state is propagated, see Rotational Dynamics)
Since Tudat presently requires all translational state vectors to be defined w.r.t. the same inertial orientation (J2000 or ECLIPJ2000, selected by the user), all rotational states in Tudat that are will always be from this inertial frame to the body-fixed frame (of the body associated with it).
Definition of rotational state
The basic definition of a rotational states in Tudat uses quaternions, which is a typical non-singular choice of elements.
However, the exact definition of the quaternion entries \(q_{0},q_{1},q_{2},q_{3}\) is non-unique, with several conventions
in use. Our quaternion definition is that used in the Eigen library.
Instead of having to manually determine each of the quaternion entries for a given rotation, we provide a function which converts
a rotation matrix to the corresponding quaternion rotation_matrix_to_quaternion_entries(),
and the inverse quaternion_entries_to_rotation_matrix(). Here, we stress that, in
the context of these functions, we are not dealing with actual quaternions (in the sense of mathematical operators that can
rotate a vector), but merely with 4x1 arrays which store the four quaternion elements, using the correct conventions.