prescribedMotionStateEffector#

Executive Summary#

The prescribed motion class is an instantiation of the state effector abstract class. This module describes the dynamics of a rigid sub-component whose three-dimensional motion can be kinematically prescribed relative to a central rigid spacecraft hub whose body frame is denoted as the frame \(\mathcal{B}\). The body frame for the prescribed body is designated by the frame \(\mathcal{F}\). The prescribed body must be commanded to translate and rotate in three-dimensional space relative to a hub-fixed interface designated as the mount frame \(\mathcal{M}\). Accordingly, the prescribed states for the sub-component are written with respect to the mount frame \(\mathcal{M}\): 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 or integrated in this module. No equations of motion exist that need to be integrated for this type of state effector. Therefore, separate kinematic profiler modules must be connected to this module’s prescribed motion PrescribedTranslationMsgPayload and PrescribedRotationMsgPayload input messages to profile the prescribed sub-component’s states as a function of time. These message connections are required to provide the sub-component’s states to this dynamics module. Note that either a single profiler can be connected to both of these input messages, or two separate profiler modules can be used; where one profiles the sub-component’s translational states and the other profiles the sub-component’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 motion spacecraft 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#

There are two integrated unit test scripts written for this module.

The first integrated test uses the prescribedRotation1DOF kinematic profiler module to prescribe a 1-degree-of-freedom (1-DOF) rotation for the prescribed state effector relative to the spacecraft hub. The second integrated test uses the prescribedLinearTranslation kinematic profiler module to prescribe linear translational motion for the prescribed state effector relative to the spacecraft hub.

Both integrated test scripts verify the prescribed motion state effector dynamics by checking to ensure that the orbital angular momentum, orbital energy, and spacecraft rotational angular momentum quantities are reasonably conserved.

User Guide#

This section outlines the steps needed to set up the prescribed motion state effector module in python using Basilisk.

Import the prescribedMotionStateEffector class:

from Basilisk.simulation import prescribedMotionStateEffector

Create the prescribed motion state effector:

prescribed_motion_body = prescribedMotionStateEffector.PrescribedMotionStateEffector()

Define the prescribed motion state effector module parameters:

prescribed_motion_body.setMass(10.0)  # [kg]
prescribed_motion_body.setIPntFc_F([[50.0, 0.0, 0.0], [0.0, 50.0, 0.0], [0.0, 0.0, 50.0]])  # [kg-m^2]
prescribed_motion_body.setR_MB_B([1.0, 0.0, 0.0])  # [m]
prescribed_motion_body.setR_FcF_F([0.1, 0.0, -0.5])  # [m]
prescribed_motion_body.setR_FM_M([0.0, 0.0, 0.0])  # [m]
prescribed_motion_body.setRPrime_FM_M([0.0, 0.0, 0.0])  # [m/s]
prescribed_motion_body.setRPrimePrime_FM_M([0.0, 0.0, 0.0])  # [m/s^2]
prescribed_motion_body.setOmega_FM_F([0.0, 0.0, 0.0])  # [rad/s]
prescribed_motion_body.setOmegaPrime_FM_F([0.0, 0.0, 0.0])   # [rad/s^2]
prescribed_motion_body.setSigma_FM([0.0, 0.0, 0.0])
prescribed_motion_body.setOmega_MB_M([0.0, 0.0, 0.0])  # [rad/s]
prescribed_motion_body.setOmegaPrime_MB_B([0.0, 0.0, 0.0])  # [rad/s^2]
prescribed_motion_body.setSigma_MB([0.0, 0.0, 0.0])
prescribed_motion_body.modelTag = "prescribedMotionBody"

Note that if these parameters are not set by the user, the vector quantities are set to zero and the matrix and scalar quantities are set to identity by default.

Add the prescribed state effector to the spacecraft object:
```
scObject.addStateEffector(prescribed_motion_body)
```

Add the module to the task list:

unitTestSim.AddModelToTask(unitTaskName, prescribed_motion_body)

Make sure to connect the required messages for this module using the kinematic profiler modules if the prescribed motion body is to be actuated relative to the spacecraft hub. 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#

class PrescribedMotionStateEffector : public StateEffector, public SysModel#

Prescribed motion state effector class.

Public Functions

PrescribedMotionStateEffector()#

Constructor.

The constructor sets the module variables to default values.

~PrescribedMotionStateEffector()#

Destructor.

This is the destructor.

void setMass(const double mass)#

Setter method for the effector mass.

Parameters:: mass – [kg] Effector mass
Returns:: void

void setIPntFc_F(const Eigen::Matrix3d IPntFc_F)#

Setter method for IPntFc_F.

Parameters:: IPntFc_F – [kg-m^2] Effector’s inertia matrix about its center of mass point Fc expressed in F frame components
Returns:: void

void setR_FcF_F(const Eigen::Vector3d r_FcF_F)#

Setter method for r_FcF_F.

Parameters:: r_FcF_F – [m] Position vector of the effector’s center of mass point Fc relative to the effector’s body frame origin point F expressed in F frame components
Returns:: void

void setR_FM_M(const Eigen::Vector3d r_FM_M)#

Setter method for r_FM_M.

Parameters:: r_FM_M – [m] Position vector of the effector’s body frame origin point F relative to the hub-fixed mount frame origin point M expressed in M frame components
Returns:: void

void setRPrime_FM_M(const Eigen::Vector3d rPrime_FM_M)#

Setter method for rPrime_FM_M.

Parameters:: rPrime_FM_M – [m/s] B frame time derivative of r_FM_M expressed in M frame components
Returns:: void

void setRPrimePrime_FM_M(const Eigen::Vector3d rPrimePrime_FM_M)#

Setter method for rPrimePrime_FM_M.

Parameters:: rPrimePrime_FM_M – [m/s^2] B frame time derivative of rPrime_FM_M expressed in M frame components
Returns:: void

void setOmega_FM_F(const Eigen::Vector3d omega_FM_F)#

Setter method for omega_FM_F.

Parameters:: omega_FM_F – [rad/s] Angular velocity of the effector body frame F relative to the hub-fixed mount frame M expressed in F frame components
Returns:: void

void setOmegaPrime_FM_F(const Eigen::Vector3d omegaPrime_FM_F)#

Setter method for omegaPrime_FM_F.

Parameters:: omegaPrime_FM_F – [rad/s^2] Angular acceleration of the effector body frame F relative to the hub-fixed mount frame M expressed in F frame components
Returns:: void

void setSigma_FM(const Eigen::MRPd sigma_FM)#

Setter method for sigma_FM.

Parameters:: sigma_FM – MRP attitude of the effector’s body frame F relative to the hub-fixed mount frame M
Returns:: void

void setR_MB_B(const Eigen::Vector3d r_MB_B)#

Setter method for r_MB_B.

Parameters:: r_MB_B – [m] Position vector describing the hub-fixed mount frame origin point M location relative to the hub frame origin point B expressed in B frame components
Returns:: void

void setOmega_MB_M(const Eigen::Vector3d omega_MB_M)#

Setter method omega_MB_M.

Setter method for omega_MB_M.

Parameters:: omega_MB_M – [rad/s] Angular velocity of the hub-fixed mount frame M relative to the hub frame B expressed in M frame components
Returns:: void

void setOmegaPrime_MB_B(const Eigen::Vector3d omegaPrime_MB_B)#

Setter method for omegaPrime_MB_B.

Parameters:: omegaPrime_MB_B – [rad/s^2] Angular acceleration of the hub-fixed mount frame M relative to the hub frame B expressed in B frame components
Returns:: void

void setSigma_MB(const Eigen::MRPd sigma_MB)#

Setter method for sigma_MB.

Parameters:: sigma_MB – MRP attitude of the hub-fixed frame M relative to the hub body frame B
Returns:: void

double getMass() const#

Getter method for the effector mass.

Returns:: double

const Eigen::Matrix3d getIPntFc_F() const#

Getter method for IPntFc_F.

Returns:: const Eigen::Matrix3d

const Eigen::Vector3d getR_FcF_F() const#

Getter method for r_FcF_F.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getR_FM_M() const#

Getter method for r_FM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getRPrime_FM_M() const#

Getter method for rPrime_FM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getRPrimePrime_FM_M() const#

Getter method for rPrimePrime_FM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmega_FM_F() const#

Getter method for omega_FM_F.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmegaPrime_FM_F() const#

Getter method for omegaPrime_FM_F.

Returns:: const Eigen::Vector3d

const Eigen::MRPd getSigma_FM() const#

Getter method for sigma_FM.

Returns:: const Eigen::MRPd

const Eigen::Vector3d getR_MB_B() const#

Getter method for r_MB_B.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmega_MB_M() const#

Getter method omega_MB_M.

Getter method for omega_MB_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmegaPrime_MB_B() const#

Getter method for omegaPrime_MB_B.

Returns:: const Eigen::Vector3d

const Eigen::MRPd getSigma_MB() const#

Getter method for sigma_MB.

Returns:: const Eigen::MRPd

void reset(uint64_t callTime) override#

Reset method.

This method is used to reset the module.

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

void updateState(uint64_t callTime) override#

Method for updating the effector’s states.

This method updates the effector’s states at the dynamics frequency.

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

void computeDerivatives(double callTime, Eigen::Vector3d rDDot_BN_N, Eigen::Vector3d omegaDot_BN_B, Eigen::Vector3d sigma_BN) override#

Method for computing the effector’s MRP attitude state derivative.

This method defines the state effector’s MRP attitude state derivative

Parameters:

callTime – [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 computePrescribedMotionInertialStates()#

Method for computing the effector’s inertial states.

This method computes the prescribed motion state effector states relative to the inertial frame.

Returns:: void

void linkInStates(DynParamManager &states) override#

Method for giving the effector access to hub states.

This method gives the prescribed motion effector access the hub inertial states.

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

void registerStates(DynParamManager &statesIn) override#

Method for registering the effector’s states.

This method registers the prescribed motion effector hub-relative attitude with the dynamic parameter manager.

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

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

Method for computing the effector’s backsubstitution contributions.

This method provides the effector’s backsubstitution contributions. method

Parameters:

callTime – [s] Time the method is called
backSubContr – State effector contribution matrices for backsubstitution
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 updateEffectorMassProps(double callTime) override#

Method for providing the effector’s contributions to the mass properties and mass property rates of the spacecraft.

This method provides the effector contributions to the mass props and mass prop rates of the spacecraft.

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

void updateEnergyMomContributions(double callTime, Eigen::Vector3d &rotAngMomPntCContr_B, double &rotEnergyContr, Eigen::Vector3d omega_BN_B) override#

Method for computing the effector’s contributions to the energy and momentum of the spacecraft.

This method calculates the effector’s contributions to the energy and momentum of the spacecraft.

Parameters:

callTime – [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 writeOutputStateMessages(uint64_t callTime) override#

Method for writing the module’s output messages.

This method writes the module output messages to the messaging system.

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

Public Members

ReadFunctor<PrescribedRotationMsgPayload> prescribedRotationInMsg#: Input message for the effector’s hub-relative rotational prescribed states.

ReadFunctor<PrescribedTranslationMsgPayload> prescribedTranslationInMsg#: Input message for the effector’s hub-relative translational prescribed states.

Message<PrescribedRotationMsgPayload> prescribedRotationOutMsg#: Output message for the effector’s hub-relative rotational prescribed states.

Message<PrescribedTranslationMsgPayload> prescribedTranslationOutMsg#: Output message for the effector’s hub-relative translational prescribed states.

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

prescribedMotionStateEffector#

Executive Summary#

Message Connection Descriptions#

Detailed Module Description#

Mathematical Modeling#

Module Testing#

User Guide#

Class PrescribedMotionStateEffector#

This Page