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}\) that is fixed with respect to the hub. 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, a flight software profiler module must be connected to this module’s PrescribedMotionMsgPayload input message to profile the prescribed body’s states as a function of time. This message connection is required to provide the prescribed body’s states to this dynamics module.

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
prescribedMotionInMsg	PrescribedMotionMsgPayload	Input message for the effector’s prescribed states
prescribedMotionOutMsg	PrescribedMotionMsgPayload	Output message for the effector’s 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 flight software profiler modules. This is required because the dynamics module must be connected to a flight software profiler module 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 rotational attitude maneuver for the prescribed body using the Module: prescribedRot1DOF flight software module. The second scenario prescribes a translational maneuver for the prescribed body using the Module: prescribedTrans flight software module.

The unit test ensures that the profiled 1 DOF rotational attitude maneuver 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 translational maneuver 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 validate 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 an instantiation of a prescribed body:

platform = prescribedMotionStateEffector.PrescribedMotionStateEffector()

Define all physical parameters for the state effector:

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)

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. (unused)

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.

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)¶

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 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.

ReadFunctor<PrescribedMotionMsgPayload> prescribedMotionInMsg¶: Input message for the effector’s prescribed states.

Message<PrescribedMotionMsgPayload> prescribedMotionOutMsg¶: Output message for the effector’s 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

StateData *hubSigma¶: Hub attitude relative to the inertial frame represented by MRP.

StateData *hubOmega¶: [rad/s] Hub angular velocity in B frame components relative to the inertial frame

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

Private Static Attributes

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