C++ Module: hingedRigidBodyStateEffector

Executive Summary

The hinged rigid body class is an instantiation of the state effector abstract class. The integrated test is validating the interaction between the hinged rigid body module and the rigid body hub that it is attached to. In this case, a hinged rigid body has an inertia tensor and is attached to the hub by a single degree of freedom torsional hinged with a linear spring constant and linear damping term.

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
hingedRigidBodyInMsg	HingedRigidBodyMsgPayload	(Optional) Input message of the reference angle and angle rate.
motorTorqueInMsg	ArrayMotorTorqueMsgPayload	(Optional) Input message of the hinge motor torque value.
hingedRigidBodyOutMsg	HingedRigidBodyMsgPayload	Output message containing the panel hinge state angle and angle rate.
hingedRigidBodyConfigLogOutMsg	SCStatesMsgPayload	Output message containing the panel inertial position and attitude states.

Initialization and Reset

mass must be finite and non-negative. A zero-mass body remains supported when its configured rotational inertia permits nonsingular hinge dynamics. dcm_HB must be a finite, orthogonal, right-handed rotation matrix; scaled axes and reflections are rejected.

These checks run before state registration during spacecraft initialization, including when the effector is attached without being added to a task. Reset() performs the same checks without accessing parent states or changing integrated hinge states, motor commands, or reference values. Invalid configurations raise BasiliskError. See Initialization and Configuration Validation.

Detailed Module Description

Mathematical Modeling

See Allard, Schaub, and Piggott paper: General Hinged Solar Panel Dynamics Approximating First-Order Spacecraft Flexing for a detailed description of this model. A hinged rigid body has 2 states: theta and thetaDot.

For additional information about connecting a reference, see Bascom and Schaub paper: Modular Dynamic Modeling of Hinged Solar Panel Deployments

The module PDF Description contains further information on this module’s function, how to run it, as well as testing.

Note

In contrast to C++ Module: spinningBodyOneDOFStateEffector, this module assumes:

rigid body inertia matrix is diagonal as seen in the hinged body \(\cal S\) frame
the center of mass lies on the \(\hat{\bf s}_1\) axis

Module Testing

Seven dynamics scenarios use the regular C++ Module: spacecraft module with two hinged panels. The five cases in test_hingedRigidBodyDynamics cover conservation and analytical response calculations:

Gravity without damping: orbital energy, orbital angular momentum, rotational energy, and rotational angular momentum remain constant.
Free flight without damping: the same four quantities remain constant.
Free flight with damping: orbital energy and both angular momenta remain constant. Rotational energy decreases, and its loss agrees with the integrated hinge damping power.
Steady-state deflection: under constant force, both damped hinge angles approach the nonlinear static torque-balance solution. Angles and rates are checked throughout the final settling window.
Frequency and amplitude: a constant force is applied and then removed. Periods and peak deflections are measured directly from both Basilisk hinge output messages during the forced and free phases and compared with an independent small-angle solution. Every maximum and minimum is checked, and the required number of extrema follows from the phase duration and analytical period. Full angle and rate histories are also compared, including the final partial cycle, to detect fading or stalled motion.

These tests reject incomplete recordings and non-finite hinge states. Conservation is checked over the full recorded histories with errors normalized by the initial magnitude and a tolerance of 1e-10. The damped energy loss agrees with the integrated damping power to a relative tolerance of 1e-6. Steady-state angles and rates use absolute tolerances of 1e-6 rad and 1e-6 rad/s, respectively. Frequency and amplitude comparisons allow a relative error of 0.5% for the small-angle approximation and sampled peak times. Full-history angle and rate errors are bounded by 0.5% of the analytical amplitude and peak rate, respectively, so the tolerance remains meaningful at zero crossings.

For the symmetric planar force-response cases, the total spacecraft mass is \(M\), each panel has mass \(m\), hinge-to-center-of-mass distance \(d\), center-of-mass inertia \(I_{yy}\) about an axis parallel to the hinge axis, and spring constant \(k\). The static balance is

\[k\theta_{\mathrm{ss}} + m d \frac{F}{M}\cos\theta_{\mathrm{ss}} = 0.\]

Eliminating hub translation from the linearized equations gives

\[J_{\mathrm{eff}} = I_{yy} + m d^2 - \frac{2 (m d)^2}{M}, \qquad \omega = \sqrt{\frac{k}{J_{\mathrm{eff}}}}.\]

Starting from rest, the forced response is \(\theta(t) = \theta_{\mathrm{ss,lin}}(1-\cos\omega t)\), where \(\theta_{\mathrm{ss,lin}} = -m d F/(M k)\). After thrust ends at \(t_{\mathrm{off}}\), the predicted free amplitude is \(\sqrt{\theta(t_{\mathrm{off}})^2 + (\dot\theta(t_{\mathrm{off}})/\omega)^2}\). The reference values come from these equations and the prescribed force duration; the measured periods and amplitudes come from Basilisk, not the independent Lagrangian trajectory.

The remaining two cases are in test_hingedRigidBodyStateEffector:

Motor torque: applies a hinge motor torque and checks system rotational angular momentum, stationary center-of-mass position, and the initial panel configuration messages.
Lagrangian comparison: compares spacecraft translation, attitude, and both hinge angles at selected checkpoints against an independently integrated planar model, using an absolute tolerance of 1e-10 in meters or radians as applicable.

The separate test_hingedRigidBodyDefaultConfig test checks the default identity inertia tensor and hinge-frame rotation matrix. The PDF Description provides additional analytical background; the executable tests above define the current coverage.

User Guide

This section is to outline the steps needed to setup a Hinged Rigid Body State Effector in python using Basilisk.

Import the hingedRigidBodyStateEffector class:

from Basilisk.simulation import hingedRigidBodyStateEffector

Create an instantiation of a Hinged Rigid body:

panel1 = hingedRigidBodyStateEffector.HingedRigidBodyStateEffector()

Define all physical parameters for a Hinged Rigid Body. For example:
```
IPntS_S = [[100.0, 0.0, 0.0], [0.0, 50.0, 0.0], [0.0, 0.0, 50.0]]
```
Do this for all of the parameters for a Hinged Rigid Body seen in the Hinged Rigid Body 1 Parameters Table.
(Optional) Define a unique name for each state. If you have multiple panels, they each must have a unique name. If these names are not specified, then the default names are used which are incremented by the effector number:
```
panel1.thetaInit = 5*numpy.pi/180.0
panel1.thetaDotInit = 0.0
```

Define a unique name for each state:

panel1.nameOfThetaState = "hingedRigidBodyTheta1"
panel1.nameOfThetaDotState = "hingedRigidBodyThetaDot1"

Define an optional motor torque input message:
```
panel1.motorTorqueInMsg.subscribeTo(msg)
```
The angular states of the panel are created using an output message hingedRigidBodyOutMsg.
The panel config log state output message is hingedRigidBodyConfigLogOutMsg.
Add the panel to your spacecraft:
```
scObject.addStateEffector(panel1)
```
See C++ Module: spacecraft documentation on how to set up a spacecraft object.

Add the module to the task list:

unitTestSim.AddModelToTask(unitTaskName, panel1)

Hosting a Dynamic Effector

This effector supports the branching described in Advanced: Effector Module Branching, so a compatible dynamic effector can be carried by the panel rather than by the hub:

panel1.addDynamicEffector(childEffector)

This effector then makes its inertial position, velocity, attitude, and angular velocity available in place of the hub’s, and the child reads whichever of the four its model needs. Any geometry given to the child is expressed in that panel’s frame rather than the hub body frame. Both this effector and the child are still added to the task in the usual way.

class HingedRigidBodyStateEffector : public StateEffector, public SysModel 

#include <hingedRigidBodyStateEffector.h>

hinged rigid body state effector class

Public Functions

HingedRigidBodyStateEffector()

Constructor.

This is the constructor, setting variables to default values

~HingedRigidBodyStateEffector()

Destructor.

This is the destructor, nothing to report here

void Reset(uint64_t CurrentSimNanos) override

Validate configuration without changing integrated states or commands.

Parameters:: CurrentSimNanos – [ns] Current simulation time.

void writeOutputStateMessages(uint64_t CurrentClock) override

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

Parameters:: CurrentClock – The current simulation time (used for time stamping)

void UpdateState(uint64_t CurrentSimNanos) override

This method is used so that the simulation will ask HRB to update messages.

Parameters:: CurrentSimNanos – The current simulation time in nanoseconds

void registerStates(DynParamManager &statesIn) override

Method for registering the HRB states.

This method allows the HRB state effector to register its states: theta and thetaDot with the dyn param manager

Parameters:: statesIn – [inout] Dynamic parameter manager used to register states or properties.

void linkInStates(DynParamManager &states) override

Method for getting access to other states.

This method allows the HRB state effector to have access to the hub states and gravity

Parameters:: states – [in] Dynamic parameter manager containing the required states.

void addDynamicEffector(DynamicEffector *newDynamicEffector, int segment = 1) override

Method for adding attached dynamic effector.

This method attaches a dynamicEffector to the specified HRB

Parameters:

newDynamicEffector – the dynamic effector to be attached to the HRB
segment – the integer number segment to be attached to (default segment=1)

void registerProperties(DynParamManager &states) override

Method for registering the HRB inertial properties.

This method registers the HRB inertial properties with the dynamic parameter manager and links them into dependent dynamic effectors

Parameters:: states – [inout] Dynamic parameter manager used to register states or properties.

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

Method for back-sub contributions.

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

Parameters:

integTime – [in] [s] Current integration time.
backSubContr – [inout] Backsubstitution contributions.
sigma_BN – [in] Hub attitude relative to the inertial frame.
omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.
g_N – [in] [m/s^2] Gravitational acceleration expressed in inertial-frame components.

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

Method for HRB to compute its derivatives.

This method is used to find the derivatives for the HRB stateEffector: thetaDDot and the kinematic derivative

Parameters:

integTime – [in] [s] Current integration time.
rDDot_BN_N – [in] [m/s^2] Hub translational acceleration expressed in inertial-frame components.
omegaDot_BN_B – [in] [rad/s^2] Hub angular acceleration expressed in body-frame components.
sigma_BN – [in] Hub attitude relative to the inertial frame.

void updateEffectorMassProps(double integTime) override

Method for giving the s/c the HRB mass props and prop rates.

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

Parameters:: integTime – [in] [s] Current integration time.

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

Computing energy and momentum for HRBs.

This method is for calculating the contributions of the HRB state effector to the energy and momentum of the s/c

Parameters:

integTime – [in] [s] Current integration time.
rotAngMomPntCContr_B – [inout] [kg*m^2/s] Rotational angular momentum contribution.
rotEnergyContr – [inout] [J] Rotational energy contribution.
omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.

void calcForceTorqueOnBody(double integTime, Eigen::Vector3d omega_BN_B) override

Force and torque on s/c due to HRBs.

Calculate the force and torque exerted on the attached body.

Parameters:

integTime – [in] [s] Current integration time.
omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.

Public Members

double mass: [kg] mass of hinged rigid body

double d: [m] distance from hinge point H to hinged rigid body center of mass S

double k: [N-m/rad] torsional spring constant of hinge

double c: [N-m-s/rad] rotational damping coefficient of hinge

double thetaInit: [rad] Initial hinged rigid body angle

double thetaDotInit: [rad/s] Initial hinged rigid body angle rate

double thetaRef: [rad] hinged rigid body reference angle

double thetaDotRef: [rad/s] hinged rigid body reference angle rate

std::string nameOfThetaState: Identifier for the theta state data container.

std::string nameOfThetaDotState: Identifier for the thetaDot state data container.

std::string nameOfInertialPositionProperty: identifier for the inertial position property

std::string nameOfInertialVelocityProperty: identifier for the inertial velocity property

std::string nameOfInertialAttitudeProperty: identifier for the inertial attitude property

std::string nameOfInertialAngVelocityProperty: identifier for the inertial angular velocity property

Eigen::Matrix3d IPntS_S: [kg-m^2] Inertia of hinged rigid body about point S in S frame components

Eigen::Vector3d r_HB_B: [m] vector pointing from body frame origin to Hinge location

Eigen::Matrix3d dcm_HB: DCM from body frame to hinge frame.

Message<HingedRigidBodyMsgPayload> hingedRigidBodyOutMsg: state output message name

ReadFunctor<ArrayMotorTorqueMsgPayload> motorTorqueInMsg: (optional) motor torque input message name

ReadFunctor<HingedRigidBodyMsgPayload> hingedRigidBodyRefMsg: (optional) rigid body reference input message name

Message<SCStatesMsgPayload> hingedRigidBodyConfigLogOutMsg: panel state config log message name

HingedRigidBodyMsgPayload HRBoutputStates: instance of messaging system message struct

BSKLogger bskLogger: BSK Logging.

std::vector<DynamicEffector*> dynEffectors: Vector of dynamic effectors attached.

Private Functions

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

void validateConfiguration()

Validate mass and the configured hinge-frame DCM.

Validate mass and the fixed hinge orientation without accessing parent states.

void computePanelInertialStates(): This method computes the panel states relative to the inertial frame

Private Members

double u: [N-m] optional motor torque

Eigen::Vector3d aTheta: term needed for Backsubstitution

Eigen::Vector3d bTheta: term needed for Backsubstitution

double cTheta: term needed for Backsubstitution

Eigen::Vector3d omega_PN_S: [rad/s] omega_BN in S frame components

Eigen::Vector3d sHat1_P: unit direction vector for the first axis of the S frame

Eigen::Vector3d sHat2_P: unit direction vector for the second axis of the S frame

Eigen::Vector3d sHat3_P: unit direction vector for the third axis of the S frame

Eigen::Vector3d r_SP_P: Vector pointing from B to CoM of hinged rigid body in B frame components.

Eigen::Vector3d rPrime_SP_P: [m/s] Body time derivative of rSB_B

Eigen::Vector3d omegaLoc_PN_P: [rad/s] local copy of omegaBN

Eigen::Vector3d omega_BN_B = {0.0, 0.0, 0.0}: Hub/Inertial angular velocity vector in B frame components.

Eigen::Matrix3d dcm_SH: DCM from hinge to hinged rigid body frame, S.

Eigen::Matrix3d dcm_SP: DCM from body to S frame.

Eigen::Matrix3d rTilde_HP_P: Tilde matrix of rHB_B.

Eigen::Matrix3d rTilde_SP_P: Tilde matrix of rSB_B.

Eigen::Matrix3d rPrimeTilde_SP_P: Tilde matrix of rPrime_SB_B.

Eigen::Matrix3d ISPrimePntS_P: [kg-m^2/s] time body derivative IPntS in body frame components

Eigen::Matrix3d omegaTildeLoc_PN_P: tilde matrix of omegaBN

Eigen::MRPd sigma_BN = {0.0, 0.0, 0.0}: Hub/Inertial attitude represented by MRP.

Eigen::Vector3d r_SN_N: [m] position vector of hinge CM S relative to inertial frame N

Eigen::Vector3d v_SN_N: [m/s] inertial velocity vector of S relative to inertial frame N

Eigen::MatrixXd *r_HN_N: [m] position vector of hinge point H relative to inertial frame

Eigen::MatrixXd *v_HN_N: [m/s] inertial velocity vector of H relative to inertial frame

Eigen::MatrixXd *sigma_SN: MRP attitude of panel frame S relative to inertial frame.

Eigen::MatrixXd *omega_SN_S: [rad/s] inertial panel frame angular velocity vector

StateData *hubSigmaState = nullptr: hub attitude state, read live for the published kinematics

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::MatrixXd *c_B: [m] Vector from point B to CoM of s/c in B frame components

Eigen::MatrixXd *cPrime_B: [m/s] Body time derivative of vector c_B in B frame components

double theta: [rad] hinged rigid body angle

double thetaDot: [rad/s] hinged rigid body angle rate

StateData *thetaState: state manager of theta for hinged rigid body

StateData *thetaDotState: state manager of thetaDot for hinged rigid body

Private Static Attributes

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