Spacecraft

SWITCH TO API

Description

The spacecraft module is a special implementation of the core DynamicBody class, which is an abstract class that handles the modular integration of 6 degrees of freedom (6dof) equations of motion using a back substitution method. The spacecraft module is designed to act as a container and manager for Components, which includes both physical and virtual (software) components. When created, it will automatically search for and connect to an available Universe system, which provides the default communications bus between the spacecraft and other modules as illustrated in the diagram below.

NOTE

The spacecraft and other modules can publish/subscribe to messages generated by other modules directly without using the Universe as the common data bus but this would impact the ability of other modules to access this data. The advantages/disadvantages of this are very case-dependent.

The following description of the module implementation provides a general breakdown of core spacecraft behaviors. The provided pseudo-code is simplified for clarity of explanation. It does not include additional optimizations or error catches and is used solely for the purpose of explaining the systems.

---

Example Use Cases

• Any Satellite Simulation: The spacecraft object provides the baseline container for modelling spacecraft dynamics. Special instances that use lookup tables or only propagate 3 degrees of freedom orbits are discussed elsewhere.

---

Module Implementation

OnBegin

At the beginning of every simulation, the spacecraft will run the following procedure:

1. Create a new integrator

   Initializes the local integrator that the spacecraft will use to propagate StateProperties and VectorProperties. This integrator is specified by the user which is the RK4 integrator by default. Components may initialize their own internal integrators (e.g. a local Euler model) or connect to the spacecraft integrator. To connect to the spacecraft integrator, they must use the Register States override on the component class. Below is a simplified example from the reaction wheel array module:

public override void RegisterStates(StateProperties properties)
{
  base.RegisterStates(properties);
 
  // Loop through an array of RWs and set container object
 
  // Create the RW wheel state integrator
  OmegasState = properties.Get("reactionWheelOmegas", (uint)NumRW);
  ThetasState = properties.Get("reactionWheelThetas", (uint)NumRW);
 
  // Set the inital values
  OmegasState.SetValue(omegasForInit);
  ThetasState.SetValue(thetasForInit);
}

2. Ensure this body is attached to the Universe Checks to make sure that the spacecraft has been attached to the Universe. If not, it creates a new attachment.

3. Create the Gravity Effector class Initializes a GravityEffector module and attaches it to the spacecraft. This is required because the DynamicBody does not, by default have to represent an orbiting object. The gravity effector component will evaluate gravitation contributions to the spacecraft’s EOMs.

   This does not evaluate gravity gradient contributions caused by non-uniform mass distributions, this is done by the `GravityGradientEffector` module and must be manually added.

4. Attach the Body Effector class The BodyEffector class is a general container for kinematic data (position, velocity, attitude, rotation). The Spacecraft / Dynamic Body does not store these by default.

5. Initialise the Dynamics The final step to begin is to pre-initialize the dynamic information of the simulation prior to the first tick call. As shown in the below pseudo-code this is essential to ensure correct cross-initialization of all child components and pre-condition the simulation with correct state information prior to the first integration step. It also ensures that the spacecraft all components have correctly published output message data.

void InitialiseDynamics(double time)
{
  // Update the Component list of all objects attached
      
  // Initialise effectors components
 
  // Update the Mass Properties at the time
 
  // Update the position and velocity with respect to the centre of mass differences
 
  // Call the equations of motion at the initial time
  UpdateEquationsOfMotion(time, 0)			
 
  // Compute Energy and Momentum at the initial time
 
  // Write output messages for spacecraft and all child components
}

OnUpdate

The DynamicBody’s OnUpdate function is relatively trivial:

1. Triggers a domain-specific integration function.
2. Triggers the parent object and all child components to update their messages.

   NOTE

   It’s important that the parent object triggers child components to write out their messages unless there is a specific reason to trigger this writing step early. This is to ensure that components do not provide out-of-sync data to dependent modules.

These can be further broken down as follows:

1. This step triggers the integrator attached to the spacecraft, where registered variables are propagated forward. As a simple example, the below code block shows the Euler method’s integrator. It’s here that the equations of motion (EOM) of the object are integrated. The implementation of the spacecraft EOMs is described in the following section.

public override void Integrate (double prev_time, double step)
{
    // Perform an Euler update
    // dy/dt = f(t, y), y(t_0) = y_0
    // t_{i+1} = t_i + h
    // y_{i+1} = y_i + h*f(t_i, y_i)
 
    // Update the state using the current derivative
 
    // Update the derivatives at the new state
    Object.UpdateEquationsOfMotion(prev_time + step, step);
}

2. By default, the spacecraft does not own any mass properties. If an OverrideMassProperties flag is set on the spacecraft, this function will be skipped. This means that mass properties will remain fixed and the UpdateMassProperties function on components will not be updated. While this will be more performant, it may cause undesired behavior in state effector modules where their contributions to system mass properties cause internal forces/torques e.g. fuel burn models. Total system mass property calculations are discussed further in the following section.

void UpdateMassProperties(double time, double step)
{
    // 2.1 - Get all components and call update mass properties
    foreach (var component in ChildComponents) 
    {
        // Call mass properties on the physical object
        component.UpdateMassProperties(time, step);
    }
 
    // 2.2 - Updates the output messages from the totals calculated
}

3. By default, the spacecraft also computes other parameters of interest, specifically accumulated $\Delta v$, non-conservative accelerations, and total system energy and momentum. These are useful parameters to support mission analysis and verify simulation behavior e.g. if a method is supposed to be energy/momentum conservation, comparing initial and final energy states is important. Not all modules are energy and/or momentum conserving e.g. Reaction Wheel simple jitter does not conserve momentum, but the fully coupled jitter model does.

UpdateEquationsOfMotion

To integrate the contribution of spacecraft components into the total system dynamics in a modular way, the spacecraft uses the back substitution method described here [1], where the goal is to structure the equations of motion (EOM) of the spacecraft and the contribution of components into the following matrix form,

$$\left[\begin{array}{cc}[A]& [B]\\ [C]& [D]\end{array}\right]\left[\begin{array}{c}{\ddot{\mathbf{r}}}_{B/N}\\ {\dot{\omega }}_{\mathcal{B}/\mathcal{N}}\end{array}\right]=\left[\begin{array}{c}{\mathbf{v}}_{\text{trans}}\\ {\mathbf{v}}_{\text{rot}}\end{array}\right]$$

This allows the modular contribution of components to the total system dynamics to be super-imposed through their contributions to $[A]$, $[B]$, $[C]$, $[D]$, $v_{trans}$, $v_{rot}$, without a priori knowledge on the form of these contributions. This system of equations can then be solved as follows [1]:

$${\dot{\omega }}_{\mathcal{B}/\mathcal{N}}=([D]-[C][A{]}^{-1}[B]{)}^{-1}({\mathbf{v}}_{\text{rot}}-[C][A{]}^{-1}{\mathbf{v}}_{\text{trans}})$$ $${\ddot{\mathbf{r}}}_{B/N}=[A{]}^{-1}({\mathbf{v}}_{\text{trans}}-[B]{\dot{\omega }}_{\mathcal{B}/\mathcal{N}})$$

With that goal in mind, the EOMs of the spacecraft can be written as [1],

$$\begin{gathered} (m_{\text{sc}}[I_{3\times 3}]+\sum _{i=1}^N[A_{\mathrm{contr},i}]){\ddot{\mathbf{r}}}_{B/N}+(-m_{\text{sc}}[{\tilde{\mathbf{r}}}_{Cm/B}]+\sum _{i=1}^N[B_{\mathrm{contr},i}]){\dot{\omega }}_{\mathcal{B}/\mathcal{N}} \\ ={\mathbf{F}}_{\mathrm{ext}}-2m_{\text{sc}}[{\tilde{\omega }}_{\mathcal{B}/\mathcal{N}}]{\dot{r}}_{Cm/B}-m_{\text{sc}}[{\tilde{\omega }}_{\mathcal{B}/\mathcal{N}}][{\tilde{\omega }}_{\mathcal{B}/\mathcal{N}}]{\mathbf{r}}_{Cm/B}+\sum _{i=1}^N{\mathbf{v}}_{\mathrm{trans},\mathrm{contr},i} \end{gathered}$$ $$\begin{gathered} [m_{\text{sc}}[{\tilde{\mathbf{r}}}_{Cm/B}]+\sum _{i=1}^N[C_{\mathrm{contr},i}]]{\ddot{\mathbf{r}}}_{B/N}+[[I_{\text{sc},B}]+\sum _{i=1}^N[D_{\mathrm{contr},i}]]{\dot{\omega }}_{\mathcal{B}/\mathcal{N}} \\ =-[{\tilde{\omega }}_{\mathcal{B}/\mathcal{N}}][I_{\text{sc},B}]{\omega }_{\mathcal{B}/\mathcal{N}}-\dot{[I_{\text{sc},B}]}{\omega }_{\mathcal{B}/\mathcal{N}}+{\mathbf{L}}_{ext}+\sum _{i=1}^N{\mathbf{v}}_{\mathrm{rot},\mathrm{contr},i} \end{gathered}$$

where:

• $m_{sc}$ is the total mass of the spacecraft.
• $[I_{3\times 3}]$ is a 3x3 identity matrix.
• $[I_{sc,B}]$ is the spacecraft’s total moment of inertia in the body frame in the body frame $\mathcal{B}$.
• $\dot{[I_{sc,B}]}$ is the rate of change spacecraft’s total moment of inertia in the body frame $\mathcal{B}$.
• ${\ddot{r}}_{B/N}$ is the acceleration of the spacecraft body frame $\mathcal{B}$ with with respect to the inertial frame $\mathcal{N}$.
• $r_{Cm/B}$ is the vector that describes the distance between the body frame $\mathcal{B}$ and the spacecraft’s total center of mass.
• ${\dot{r}}_{Cm/B}$ is the rate of change of the total spacecraft center of mass in the body frame $\mathcal{B}$.
• ${\dot{\omega }}_{B/N}$ is the angular velocity of the spacecraft body frame $\mathcal{B}$ with respect to the inertial frame $\mathcal{N}$.
• ${\omega }_{B/N}$ is the attitude of the spacecraft body frame $\mathcal{B}$ with respect to the inertial frame $\mathcal{N}$.
• ${\mathbf{F}}_{ext}$ are external forces being applied to the body in the body frame $\mathcal{B}$.
• ${\mathbf{L}}_{ext}$ are external torques being applied to the body in the body frame $\mathcal{B}$.

Note: $[\tilde{x}]$ is the matrix representation of a cross-product operation.

As indicated in the below pseudo-code, this is the approach taken here:

void UpdateEquationsOfMotion(double time, double step)
{
    // 1 - Update the Mass Props at the time
    UpdateMassProperties(time, step)			
 
    // 2 - Compute the kinematic properties relative to the 
    //     total system mass properties
 
    // 3 - Compute the Gravity at this location
 
    // 4 - Loop through effectors and collect their contributions to 
    // the back substitution matrix and external forces/torques
    foreach (var component in ChildComponents) 
    {
        // Get all physical components to report their contributions to the EOMs
        component.UpdateContributions(time, step);
    }
 
    // 4 - Compute the Derivatives of the Body
}

NOTE

It is important that the UpdateMassProperties function is called both here and at OnUpdate. The first OnUpdate call makes sure that the UpdateMassProperties function has been correctly called prior to integration. It’s called here is essential to provide correct mass properties information from components at intermediate turns during integration steps. If this is not done correctly, it may result in numerical errors.

1. As in the OnUpdate step, the mass properties of the spacecraft components are updated.
2. The EOMs propagate the inertial state of the body frame $\mathcal{B}$. The reason that the $\mathcal{B}$ frame is used is that the total system mass properties are not assumed to be known by the child components at the point that their contributions are calculated. Nevertheless, forces and torques must strictly be applied relative to total system mass properties. To compute the total system mass properties, all components track both their orientation relative to the body frame $\mathcal{B}$ along with their mass properties in their local component frame $\mathcal{L}$. The spacecraft may then request total mass property information, which triggers a recursive call through child component hierarchies to compute each component’s contributions to the total system mass properties, specifically the total system mass, the total center of mass and the total moment of inertia about the center of mass and their corresponding rates, all in the $\mathcal{B}$ frame. A more detailed breakdown of the mass system is covered in a dedicated technical note.

   As discussed in the OnBegin function, the spacecraft attaches a gravity effector module. A specific call is made here to compute the gravity contribution given ${\mathbf{r}}_{Cm/N}$ and ${\mathbf{v}}_{Cm/N}$.

3. This step loops through all child components and collects their contributions to the EOMs as defined in the back substitution method above.
4. Completes the back substitution method by solving for ${\dot{\omega }}_{\mathcal{B}/\mathcal{N}}$ and ${\ddot{\mathbf{r}}}_{B/N}$ as defined above.

---

Assumptions/Limitations

• By default, the spacecraft object does not have its own mass properties - all mass properties should be calculated from attached physical components. The exception to this is if the override mass properties flag is set to true, in which case the mass properties of the spacecraft must be set by the user.
• Limitations and assumptions are primarily inherited from attached components.
• Simulation accuracy is strongly linked to integrator and integrator step size. It’s up to the user to ensure that numerical errors due to selection or integrators and step size are minimized as this is a function of specific use cases.

---

References

[1] Hanspeter Schaub and John L. Junkins. Analytical Mechanics of Space Systems. AIAA Education Series, Reston, VA, 3rd edition, 2014.