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{P}\). 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_PM_M, rPrime_PM_M, rPrimePrime_PM_M, omega_PM_P, omegaPrime_PM_P, and sigma_PM.

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}}_{P_c/B}] \boldsymbol{r}^{''}_{P_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},P_c}] + [\tilde{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}}] [I_{\text{P},P_c}] \right ) \boldsymbol{\omega}_{\mathcal{P}/\mathcal{B}} \ - \ [I_{\text{P},P_c}] \boldsymbol{\omega}^{'}_{\mathcal{P}/\mathcal{B}} \ - \ m_{\text{P}} [\tilde{\boldsymbol{\omega}}_{\mathcal{B}/\mathcal{N}}] [\tilde{\boldsymbol{r}}_{P_c/B}] \boldsymbol{r}^{'}_{P_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_PM_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_PM_M_Final and velocity magnitude rPrime_PM_M_Final are compared with the reference values r_PM_M_Ref and rPrime_PM_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.IPntPc_P = [[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_PcP_P = np.array([0.0, 0.0, 0.0])
platform.r_PM_M = np.array([1.0, 0.0, 0.0])
platform.rPrime_PM_M = np.array([0.0, 0.0, 0.0])
platform.rPrimePrime_PM_M = np.array([0.0, 0.0, 0.0])
platform.omega_PM_P = np.array([0.0, 0.0, 0.0])
platform.omegaPrime_PM_P = np.array([0.0, 0.0, 0.0])
platform.sigma_PM = 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

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

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

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

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

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

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

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

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

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.

Public Members

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

double mass: [kg] Effector mass

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

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

Eigen::Vector3d r_PcP_P: [m] Position of the effector center of mass relative to point P in P 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_PM_M: [m] Position of point P relative to point M in M frame components

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

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

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

Eigen::Vector3d omegaPrime_PM_P: [rad/s^2] B frame time derivative of omega_PM_P in P frame components

Eigen::MRPd sigma_PM: MRP attitude of frame P relative to frame M.

std::string nameOfsigma_PMState: Identifier for the sigma_PM 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 IPntPc_B: [kg-m^2] Inertia of the effector about its center of mass in B frame components

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

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

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

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

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

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

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

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

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

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

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

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

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

Eigen::Vector3d rPrimePrime_PcB_B: [m/s^2] B frame time derivative of rPrime_PcB_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_PN_B: [rad/s] Angular velocity of frame P relative to the inertial frame in B frame components

Eigen::Vector3d rDot_PcB_B: [m/s] Inertial time derivative of r_PcB_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_PM: DCM from frame M to frame P.

Eigen::Matrix3d dcm_BP: DCM from frame P to frame B.

Eigen::Matrix3d rTilde_PcB_B: [m] Tilde cross product matrix of r_PcB_B

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

Eigen::Matrix3d omegaTilde_PB_B: [rad/s] Tilde cross product matrix of omega_PB_B

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

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

Eigen::Vector3d sigma_PN: MRP attitude of frame P relative to the inertial frame.

Eigen::Vector3d omega_PN_P: [rad/s] Angular velocity of frame P relative to the inertial frame in P 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_PM_M: [m] Position of point P relative to point M in M frame components

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

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

StateData *sigma_PMState: MRP attitude of frame P relative to frame M.

Private Static Attributes

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