Module: prescribedMotionStateEffector

Executive Summary

The prescribed motion state effector class is an instantiation of the state effector abstract class. This module is used to connect a prescribed motion component to the spacecraft hub. The states of the prescribed component are purely prescribed, meaning there are no free degrees of freedom associated with its motion and hence there are no states integrated in this module. Instead, the states of the prescribed component are externally profiled using a kinematic profiler module and are provided as input messages to the prescribed state effector class.

The body frame for the prescribed body is designated by the frame \(\mathcal{P}\). The prescribed body is attached to the hub through a hub-fixed mount interface described by the mount frame \(\mathcal{M}\). The prescribed body hub-relative motion is profiled 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. If neither message is connected to the module, the prescribed body will not move with respect to the hub. If the prescribed body should only rotate, then only the rotational message needs to be subscribed to the module and the translational message can be ignored. Similarly, if the prescribed component should only translate, the rotational message can be ignored. Note that either a single profiler module can be used to connect both messages to this module, or two separate profiler modules can be used; where one profiles the translational states and the other profiles the 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

Module Overview

Module Basic Capability

The basic capability of this module is to connect a prescribed motion component to the spacecraft hub. An in-depth discussion of the functionality of this module and the dynamics derivation required to simulate this type of component motion is provided in the following journal paper

Note

“Spacecraft Backsubstitution Dynamics with General Multibody Prescribed Subcomponents”, Leah Kiner, Hanspeter Schaub, and Cody Allard Journal of Aerospace Information Systems 2025 22:8, 703-715

Branching Capability

An additional feature of this module is the ability to attach other state effectors to the prescribed motion component. Doing so creates a chain, where the prescribed component is wedged between the hub and its attached state effector. This capability enables select component branching relative to the spacecraft hub. A detailed discussion of this capability is provided in the following conference paper

Note

L. Kiner, and H. Schaub, “Backsubstitution Method For Prescribed Motion Actuators With Attached Dynamic Sub-Components”, AAS Astrodynamics Specialist Conference, Boston, Massachusetts, August 10–14, 2025

Currently, this branching capability has only been configured for the spinningBodyOneDOF, spinningBodyTwoDOF, and linearTranslationOneDOF state effectors. See the User Guide section for how to connect these effectors to the prescribed motion effector. The scenario scripts scenarioPrescribedMotionWithRotationBranching and scenarioPrescribedMotionWithTranslationBranching are more complex examples demonstrating how to connect multiple state effectors to the prescribed motion effector.

Module Testing

There are two unit test scripts for this module. The first tests the basic functionality of the module, while the second test checks the branching capability of the module. Both tests are integrated tests with the Module: prescribedRotation1DOF and Module: prescribedLinearTranslation profiler modules.

Basic Test

The basic test script for this module profiles simultaneous translation and rotation for the prescribed body relative to the hub using the Module: prescribedRotation1DOF and Module: prescribedLinearTranslation profiler modules. The initial and reference attitude and displacement of the prescribed body relative to the hub are varied in the test. The test checks that the quantities of spacecraft orbital angular momentum, rotational angular momentum, and orbital energy are conserved for the duration of the simulation to verify the module dynamics.

Branching Test

The branching test script for this module has three separate test functions. All tests configure an identical spacecraft hub an actuating prescribed motion component. The first test connects a free Module: spinningBodyOneDOFStateEffector to the prescribed component. The second test connects a free Module: spinningBodyTwoDOFStateEffector to the prescribed component. The third test connects a free Module: linearTranslationOneDOFStateEffector to the prescribed component. All tests check that the quantities of spacecraft orbital energy, orbital angular momentum, rotational angular momentum are conserved for the duration of the simulation.

User Guide

This section outlines how to set up the prescribed motion module in python using Basilisk.

Import the prescribedMotionStateEffector class:

from Basilisk.simulation import prescribedMotionStateEffector

Create the prescribed motion state effector:

prescribed_body = prescribedMotionStateEffector.PrescribedMotionStateEffector()

Set the prescribed motion module parameters:

prescribed_body.setMass(100.0)
prescribed_body.setIPntPc_P([[50.0, 0.0, 0.0], [0.0, 50.0, 0.0], [0.0, 0.0, 50.0]])
prescribed_body.setR_MB_B(np.array([0.0, 0.0, 0.0]))
prescribed_body.setR_PcP_P(np.array([0.0, 0.0, 0.0]))
prescribed_body.setR_PM_M(np.array([1.0, 0.0, 0.0]))
prescribed_body.setRPrime_PM_M(np.array([0.0, 0.0, 0.0]))
prescribed_body.setRPrimePrime_PM_M(np.array([0.0, 0.0, 0.0]))
prescribed_body.setOmega_PM_P(np.array([0.0, 0.0, 0.0]))
prescribed_body.setOmegaPrime_PM_P(np.array([0.0, 0.0, 0.0]))
prescribed_body.setSigma_PM(np.array([0.0, 0.0, 0.0]))
prescribed_body.setSigma_MB(np.array([0.0, 0.0, 0.0]))
prescribed_body.ModelTag = "prescribedBody"

Add the prescribed state effector to your spacecraft:
```
scObject.addStateEffector(prescribed_body)
```
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, prescribed_body)

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.

If you’d like to connect a state effector to the prescribed state effector instead of the spacecraft hub, the states of the attached effector must be written with respect to the prescribed body frame instead of the hub body frame. After creating the attached state effector, make sure to connect it to the prescribed motion effector rather than the hub:

prescribed_body.addStateEffector(attached_state_effector)

See the example scripts scenarioPrescribedMotionWithRotationBranching and scenarioPrescribedMotionWithTranslationBranching for more information about how to connect multiple state effectors to the prescribed motion effector.

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 setMass(const double mass)

Setter method for the effector mass.

Parameters:: mass – [kg] Effector mass

void setIPntPc_P(const Eigen::Matrix3d IPntPc_P)

Setter method for IPntPc_P.

Parameters:: IPntPc_P – [kg-m^2] Effector’s inertia matrix about its center of mass point Pc expressed in P frame components

void setR_PcP_P(const Eigen::Vector3d r_PcP_P)

Setter method for r_PcP_P.

Parameters:: r_PcP_P – [m] Position vector of the effector’s center of mass point Pc relative to the effector’s body frame origin point P expressed in P frame components

void setR_PM_M(const Eigen::Vector3d r_PM_M)

Setter method for r_PM_M.

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

void setRPrime_PM_M(const Eigen::Vector3d rPrime_PM_M)

Setter method for rPrime_PM_M.

Parameters:: rPrime_PM_M – [m/s] B frame time derivative of r_PM_M expressed in M frame components

void setRPrimePrime_PM_M(const Eigen::Vector3d rPrimePrime_PM_M)

Setter method for rPrimePrime_PM_M.

Parameters:: rPrimePrime_PM_M – [m/s^2] B frame time derivative of rPrime_PM_M expressed in M frame components

void setOmega_PM_P(const Eigen::Vector3d omega_PM_P)

Setter method for omega_PM_P.

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

void setOmegaPrime_PM_P(const Eigen::Vector3d omegaPrime_PM_P)

Setter method for omegaPrime_PM_P.

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

void setSigma_PM(const Eigen::MRPd sigma_PM)

Setter method for sigma_PM.

Parameters:: sigma_PM – MRP attitude of the effector’s body frame P relative to the hub-fixed mount frame M

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

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

double getMass() const

Getter method for the effector mass.

Returns:: double

const Eigen::Matrix3d getIPntPc_P() const

Getter method for IPntPc_P.

Returns:: const Eigen::Matrix3d

const Eigen::Vector3d getR_PcP_P() const

Getter method for r_PcP_P.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getR_PM_M() const

Getter method for r_PM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getRPrime_PM_M() const

Getter method for rPrime_PM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getRPrimePrime_PM_M() const

Getter method for rPrimePrime_PM_M.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmega_PM_P() const

Getter method for omega_PM_P.

Returns:: const Eigen::Vector3d

const Eigen::Vector3d getOmegaPrime_PM_P() const

Getter method for omegaPrime_PM_P.

Returns:: const Eigen::Vector3d

const Eigen::MRPd getSigma_PM() const

Getter method for sigma_PM.

Returns:: const Eigen::MRPd

const Eigen::Vector3d getR_MB_B() const

Getter method for r_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 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 registerProperties(DynParamManager &states) override

Method for registering the prescribed motion properties.

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

Parameters:: states – 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.

void addStateEffector(StateEffector *newStateEffector)

Method to attach a state effector to prescribed motion.

This method attaches a stateEffector to the prescribedMotionStateEffector

Public Members

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 Functions

template<typename Type> inline void assignStateParamNames(Type effector): Assign the state engine parameter names to attached effectors

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

Eigen::Matrix3d IPntPc_B: [kg-m^2] Inertia of the effector about its center of mass 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::MatrixXd *r_PN_N: [m] Position of frame P relative to the inertial frame in inertial frame components

Eigen::MatrixXd *v_PN_N: [m/s] Inertial velocity of frame P relative to the inertial frame in inertial frame components

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

Eigen::MatrixXd *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.

std::string spacecraftName: Name of prescribed object used for effector branching.

std::vector<StateEffector*> stateEffectors: Vector of attached state effectors.

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

Eigen::MatrixXd *rPrime_PB_B: [m/s] B frame time derivative of r_PB_B in B frame components

Eigen::MatrixXd *rPrimePrime_PB_B: [m/s^2] B frame time derivative of rPrime_PB_B in B frame components

Eigen::MatrixXd *sigma_PB: MRP attitude of frame P relative to frame B.

Eigen::MatrixXd *omega_PB_P: [rad/s] Angular velocity of frame P relative to frame B in P frame components

Eigen::MatrixXd *omegaPrime_PB_P: [rad/s] B frame time derivative of omega_PB_P in P frame components

std::string nameOfPrescribedPositionProperty: Identifier for prescribed position r_PB_B.

std::string nameOfPrescribedVelocityProperty: Identifier for prescribed velocity rPrime_PB_B.

std::string nameOfPrescribedAccelerationProperty: Identifier for prescribed acceleration rPrimePrime_PB_B.

std::string nameOfPrescribedAttitudeProperty: Identifier for prescribed attitude sigma_PB.

std::string nameOfPrescribedAngVelocityProperty: Identifier for prescribed angular velocity omega_PB_P.

std::string nameOfPrescribedAngAccelerationProperty: Identifier for prescribed angular acceleration omegaPrime_PB_P.

std::string nameOfInertialPositionProperty: Identifier for prescribed motion inertial position r_PN_N.

std::string nameOfInertialVelocityProperty: Identifier for prescribed motion inertial velocity property v_PN_N.

std::string nameOfInertialAttitudeProperty: Identifier for the prescribed motion inertial attitude property sigma_PN.

std::string nameOfInertialAngVelocityProperty: Identifier for the prescribed motion inertial angular velocity property omega_PN_P.

Private Static Attributes

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