Module: prescribedMotionStateEffector

Executive Summary

The prescribed motion class is an instantiation of the state effector abstract class. This module describes the dynamics of a six-degree of freedom (6 DOF) prescribed rigid body connected to a central rigid spacecraft hub. The body frame for the prescribed body is designated by the frame \(\mathcal{F}\). The prescribed body is mounted onto a hub-fixed interface described by a mount frame \(\mathcal{M}\). The prescribed body may be commanded to translate and rotate in three-dimensional space with respect to the interface it is mounted on. Accordingly, the prescribed states for the secondary body are written with respect to the mount frame, \(\mathcal{M}\). The prescribed states are: r_FM_M, rPrime_FM_M, rPrimePrime_FM_M, omega_FM_F, omegaPrime_FM_F, and sigma_FM.

The states of the prescribed body are not defined in this module. Therefore, separate kinematic profiler modules must be connected to this module’s PrescribedTranslationMsgPayload and PrescribedRotationMsgPayload input messages to profile the prescribed body’s states as a function of time. These message connections are required to provide the prescribed body’s states to this dynamics module. Note that either a single profiler can be connected to these input messages or two separate profiler modules can be used; where one profiles the prescribed body’s translational states and the other profiles the prescribed body’s rotational states. See the example script scenarioDeployingSolarArrays for more information about how to set up hub-relative multi-body prescribed motion using this state effector module and the associated kinematic profiler modules.

Message Connection Descriptions

The following table lists all the module input and output messages. The module msg variable name is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.

Module I/O Messages
Msg Variable Name	Msg Type	Description
prescribedTranslationInMsg	PrescribedTranslationMsgPayload	Input message for the effector’s translational prescribed states
prescribedRotationInMsg	PrescribedRotationMsgPayload	Input message for the effector’s rotational prescribed states
prescribedTranslationOutMsg	PrescribedTranslationMsgPayload	Output message for the effector’s translational prescribed states
prescribedRotationOutMsg	PrescribedRotationMsgPayload	Output message for the effector’s rotational prescribed states
prescribedMotionConfigLogOutMsg	SCStatesMsgPayload	Output message containing the effector’s inertial position and attitude states

Detailed Module Description

Mathematical Modeling

See Kiner et al.’s paper: Spacecraft Simulation Software Implementation of General Prescribed Motion Dynamics of Two Connected Rigid Bodies for a detailed description of the derived prescribed dynamics.

The translational equations of motion are:

\[m_{\text{sc}} \left [ \ddot{\boldsymbol{r}}_{B/N} + \boldsymbol{c}^{''} + 2 \left ( \boldsymbol{\omega}_{\mathcal{B}/\mathcal{N}} \times \boldsymbol{c}^{'} \right ) + \left ( \dot{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}} \times \boldsymbol{c} \right ) + \boldsymbol{\omega}_{\mathcal{B}/\mathcal{N}} \times \left ( \boldsymbol{\omega}_{\mathcal{B}/\mathcal{N}} \times \boldsymbol{c} \right ) \right ] = \sum \boldsymbol{F}_{\text{ext}}\]

The rotational equations of motion are:

\[\begin{split}m_{\text{sc}} [\tilde{\boldsymbol{c}}] \ddot{\boldsymbol{r}}_{B/N} + [I_{\text{sc},B}] \dot{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}} = \boldsymbol{L}_B - m_{\text{P}} [\tilde{\boldsymbol{r}}_{F_c/B}] \boldsymbol{r}^{''}_{F_c/B} - \left ( [I^{'}_{\text{sc},B}] + [\tilde{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}}][I_{\text{sc},B}] \right ) \boldsymbol{\omega}_{\mathcal{B}/\mathcal{N}} \\ - \left ( [I^{'}_{\text{P},F_c}] + [\tilde{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}}] [I_{\text{P},F_c}] \right ) \boldsymbol{\omega}_{\mathcal{F}/\mathcal{B}} \ - \ [I_{\text{P},F_c}] \boldsymbol{\omega}^{'}_{\mathcal{F}/\mathcal{B}} \ - \ m_{\text{P}} [\tilde{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}}] [\tilde{\boldsymbol{r}}_{F_c/B}] \boldsymbol{r}^{'}_{F_c/B}\end{split}\]

Module Testing

The unit test for this module is an integrated test with two kinematic profiler modules. This is required because the dynamics module must be connected to kinematic profiler modules to define the states of the prescribed secondary body that is connected to the rigid spacecraft hub. The integrated test for this module has two simple scenarios it is testing. The first scenario prescribes a 1 DOF rotation for the prescribed body using the Module: prescribedRotation1DOF profiler module. The second scenario prescribes a 1 DOF linear translation for the prescribed body using the Module: prescribedLinearTranslation profiler module.

The unit test ensures that the profiled 1 DOF rotation is properly computed for a series of initial and reference PRV angles and maximum angular accelerations. The final prescribed angle theta_FM_Final and angular velocity magnitude thetaDot_Final are compared with the reference values theta_Ref and thetaDot_Ref, respectively. The unit test also ensures that the profiled translation is properly computed for a series of initial and reference positions and maximum accelerations. The final prescribed position magnitude r_FM_M_Final and velocity magnitude rPrime_FM_M_Final are compared with the reference values r_FM_M_Ref and rPrime_FM_M_Ref, respectively. Additionally for each scenario, the conservation quantities of orbital angular momentum, rotational angular momentum, and orbital energy are checked to verify the module dynamics.

User Guide

This section is to outline the steps needed to setup a Prescribed Motion State Effector in python using Basilisk.

Import the prescribedMotionStateEffector class:

from Basilisk.simulation import prescribedMotionStateEffector

Create the prescribed body state effector:

platform = prescribedMotionStateEffector.PrescribedMotionStateEffector()

Define the state effector module parameters:

platform.mass = 100.0
platform.IPntFc_F = [[50.0, 0.0, 0.0], [0.0, 50.0, 0.0], [0.0, 0.0, 50.0]]
platform.r_MB_B = np.array([0.0, 0.0, 0.0])
platform.r_FcF_F = np.array([0.0, 0.0, 0.0])
platform.r_FM_M = np.array([1.0, 0.0, 0.0])
platform.rPrime_FM_M = np.array([0.0, 0.0, 0.0])
platform.rPrimePrime_FM_M = np.array([0.0, 0.0, 0.0])
platform.omega_FM_F = np.array([0.0, 0.0, 0.0])
platform.omegaPrime_FM_F = np.array([0.0, 0.0, 0.0])
platform.sigma_FM = np.array([0.0, 0.0, 0.0])
platform.omega_MB_B = np.array([0.0, 0.0, 0.0])
platform.omegaPrime_MB_B = np.array([0.0, 0.0, 0.0])
platform.sigma_MB = np.array([0.0, 0.0, 0.0])
platform.ModelTag = "Platform"

Do this for all of the public parameters in the prescribed motion state effector module. Note that if these parameters are not set by the user, all scalar and vector quantities are set to zero and all matrices are set to identity by default.

Add the prescribed state effector to your spacecraft:
```
scObject.addStateEffector(platform)
```
See Module: spacecraft documentation on how to set up a spacecraft object.
Make sure to connect the required messages for this module.

Add the module to the task list:

unitTestSim.AddModelToTask(unitTaskName, platform)

See the example script scenarioDeployingSolarArrays for more information about how to set up hub-relative multi-body prescribed motion using this state effector module and the associated kinematic profiler modules.

class PrescribedMotionStateEffector : public StateEffector, public SysModel 

#include <prescribedMotionStateEffector.h>

prescribed motion state effector class

Public Functions

PrescribedMotionStateEffector(): This is the constructor, setting variables to default values.

~PrescribedMotionStateEffector(): This is the destructor.

void Reset(uint64_t currentClock) override

Method for reset.

This method is used to reset the module.

Parameters:: currentClock – [ns] Time the method is called
Returns:: void

void writeOutputStateMessages(uint64_t currentClock) override

Method for writing the output messages.

This method takes the computed states and outputs them to the messaging system.

Parameters:: currentClock – [ns] Time the method is called
Returns:: void

void UpdateState(uint64_t currentSimNanos) override

Method for updating the effector states.

This method updates the effector state at the dynamics frequency.

Parameters:: currentSimNanos – [ns] Time the method is called
Returns:: void

void registerStates(DynParamManager &statesIn) override

Method for registering the effector’s states.

This method allows the state effector to register its states with the dynamic parameter manager.

Parameters:: states – Pointer to give the state effector access the hub states
Returns:: void

void linkInStates(DynParamManager &states) override

Method for giving the effector access to hub states.

This method allows the effector to have access to the hub states.

Parameters:: statesIn – Pointer to give the state effector access the hub states
Returns:: void

void updateContributions(double integTime, BackSubMatrices &backSubContr, Eigen::Vector3d sigma_BN, Eigen::Vector3d omega_BN_B, Eigen::Vector3d g_N) override

Method for computing the effector’s back-substitution contributions.

This method allows the state effector to give its contributions to the matrices needed for the back-sub. method

Parameters:

integTime – [s] Time the method is called
backSubContr – State effector contribution matrices for back-substitution
sigma_BN – Current B frame attitude with respect to the inertial frame
omega_BN_B – [rad/s] Angular velocity of the B frame with respect to the inertial frame, expressed in B frame components
g_N – [m/s^2] Gravitational acceleration in N frame components

Returns:

void

void computeDerivatives(double integTime, Eigen::Vector3d rDDot_BN_N, Eigen::Vector3d omegaDot_BN_B, Eigen::Vector3d sigma_BN) override

Method for effector to compute its state derivatives.

This method is for defining the state effector’s MRP state derivative

Parameters:

integTime – [s] Time the method is called
rDDot_BN_N – [m/s^2] Acceleration of the vector pointing from the inertial frame origin to the B frame origin, expressed in inertial frame components
omegaDot_BN_B – [rad/s^2] Inertial time derivative of the angular velocity of the B frame with respect to the inertial frame, expressed in B frame components
sigma_BN – Current B frame attitude with respect to the inertial frame

Returns:

void

void updateEffectorMassProps(double integTime) override

Method for calculating the effector mass props and prop rates.

This method allows the state effector to provide its contributions to the mass props and mass prop rates of the spacecraft.

Parameters:: integTime – [s] Time the method is called
Returns:: void

void updateEnergyMomContributions(double integTime, Eigen::Vector3d &rotAngMomPntCContr_B, double &rotEnergyContr, Eigen::Vector3d omega_BN_B) override

Method for computing the energy and momentum of the effector.

This method is for calculating the contributions of the effector to the energy and momentum of the spacecraft.

Parameters:

integTime – [s] Time the method is called
rotAngMomPntCContr_B – [kg m^2/s] Contribution of stateEffector to total rotational angular mom
rotEnergyContr – [J] Contribution of stateEffector to total rotational energy
omega_BN_B – [rad/s] Angular velocity of the B frame with respect to the inertial frame, expressed in B frame components

Returns:

void

void computePrescribedMotionInertialStates()

Method for computing the effector’s states relative to the inertial frame.

This method computes the effector states relative to the inertial frame.

Returns:: void

Public Members

double currentSimTimeSec: [s] Current simulation time, updated at the dynamics frequency

double mass: [kg] Effector mass

Eigen::Matrix3d IPntFc_F: [kg-m^2] Inertia of the effector about its center of mass in F frame components

Eigen::Vector3d r_MB_B: [m] Position of point M relative to point B in B frame components

Eigen::Vector3d r_FcF_F: [m] Position of the effector center of mass relative to point F in F frame components

Eigen::Vector3d omega_MB_B: [rad/s] Angular velocity of frame M with respect to frame B in B frame components

Eigen::Vector3d omegaPrime_MB_B: [rad/s^2] B frame time derivative of omega_MB_B in B frame components

Eigen::MRPd sigma_MB: MRP attitude of frame M relative to frame B.

Eigen::Vector3d r_FM_M: [m] Position of point F relative to point M in M frame components

Eigen::Vector3d rPrime_FM_M: [m/s] B frame time derivative of r_FM_M in M frame components

Eigen::Vector3d rPrimePrime_FM_M: [m/s^2] B frame time derivative of rPrime_FM_M in M frame components

Eigen::Vector3d omega_FM_F: [rad/s] Angular velocity of frame F relative to frame M in F frame components

Eigen::Vector3d omegaPrime_FM_F: [rad/s^2] B frame time derivative of omega_FM_F in F frame components

Eigen::MRPd sigma_FM: MRP attitude of frame F relative to frame M.

std::string nameOfsigma_FMState: Identifier for the sigma_FM state data container.

ReadFunctor<PrescribedTranslationMsgPayload> prescribedTranslationInMsg: Input message for the effector’s translational prescribed states.

ReadFunctor<PrescribedRotationMsgPayload> prescribedRotationInMsg: Input message for the effector’s rotational prescribed states.

Message<PrescribedTranslationMsgPayload> prescribedTranslationOutMsg: Output message for the effector’s translational prescribed states.

Message<PrescribedRotationMsgPayload> prescribedRotationOutMsg: Output message for the effector’s rotational prescribed states.

Message<SCStatesMsgPayload> prescribedMotionConfigLogOutMsg: Output config log message for the effector’s states.

Private Members

Eigen::Matrix3d IPntFc_B: [kg-m^2] Inertia of the effector about its center of mass in B frame components

Eigen::Vector3d r_FB_B: [m] Position of point F relative to point B in B frame components

Eigen::Vector3d r_FcF_B: [m] Position of the effector center of mass relative to point F in B frame components

Eigen::Vector3d r_FM_B: [m] Position of point F relative to point M in B frame components

Eigen::Vector3d rPrime_FM_B: [m/s] B frame time derivative of position r_FM_B in B frame components

Eigen::Vector3d rPrimePrime_FM_B: [m/s^2] B frame time derivative of rPrime_FM_B in B frame components

Eigen::Vector3d omega_FM_B: [rad/s] Angular velocity of F frame relative to the M frame in B frame components

Eigen::Vector3d omegaPrime_FM_B: [rad/s^2] B frame time derivative of omega_FB_B in B frame components

Eigen::Vector3d omega_FB_B: [rad/s] Angular velocity of frame F relative to frame B in B frame components

Eigen::Vector3d omegaPrime_FB_B: [rad/s^2] B frame time derivative of omega_FB_B in B frame components

Eigen::Vector3d r_FcM_B: [m] Position of frame F center of mass relative to point M in B frame components

Eigen::Vector3d r_FcB_B: [m] Position of frame F center of mass relative to point B in B frame components

Eigen::Vector3d rPrime_FcM_B: [m/s] B frame time derivative of r_FcM_B in B frame components

Eigen::Vector3d rPrime_FcB_B: [m/s] B frame time derivative of r_FcB_B in B frame components

Eigen::Vector3d rPrimePrime_FcB_B: [m/s^2] B frame time derivative of rPrime_FcB_B in B frame components

Eigen::Vector3d omega_BN_B: [rad/s] Angular velocity of frame B relative to the inertial frame in B frame components

Eigen::Vector3d omega_FN_B: [rad/s] Angular velocity of frame F relative to the inertial frame in B frame components

Eigen::Vector3d rDot_FcB_B: [m/s] Inertial time derivative of r_FcB_B in B frame components

Eigen::MRPd sigma_BN: MRP attitude of frame B relative to the inertial frame.

Eigen::Matrix3d dcm_BN: DCM from inertial frame to frame B.

Eigen::Matrix3d dcm_BM: DCM from frame M to frame B.

Eigen::Matrix3d dcm_FM: DCM from frame M to frame F.

Eigen::Matrix3d dcm_BF: DCM from frame F to frame B.

Eigen::Matrix3d rTilde_FcB_B: [m] Tilde cross product matrix of r_FcB_B

Eigen::Matrix3d omegaTilde_BN_B: [rad/s] Tilde cross product matrix of omega_BN_B

Eigen::Matrix3d omegaTilde_FB_B: [rad/s] Tilde cross product matrix of omega_FB_B

Eigen::Vector3d r_FcN_N: [m] Position of frame F center of mass relative to the inertial frame in inertial frame components

Eigen::Vector3d v_FcN_N: [m/s] Inertial velocity of frame F center of mass relative to the inertial frame in inertial frame components

Eigen::Vector3d sigma_FN: MRP attitude of frame F relative to the inertial frame.

Eigen::Vector3d omega_FN_F: [rad/s] Angular velocity of frame F relative to the inertial frame in F frame components

Eigen::MatrixXd *inertialPositionProperty: [m] r_N Inertial position relative to system spice zeroBase/refBase

Eigen::MatrixXd *inertialVelocityProperty: [m] v_N Inertial velocity relative to system spice zeroBase/refBase

Eigen::Vector3d rEpoch_FM_M: [m] Position of point F relative to point M in M frame components

Eigen::Vector3d rPrimeEpoch_FM_M: [m/s] B frame time derivative of r_FM_M in M frame components

Eigen::Vector3d omegaEpoch_FM_F: [rad/s] Angular velocity of frame F relative to frame M in F frame components

StateData *sigma_FMState: MRP attitude of frame F relative to frame M.

Private Static Attributes

static uint64_t effectorID = 1: ID number of this panel.