Module: cmdForceInertialToForceAtSite

Executive Summary

The CmdForceInertialToForceAtSite module converts a commanded force vector expressed in the inertial frame into an equivalent force vector expressed in a site-fixed frame. The resulting site-frame force is published as a ForceAtSiteMsgPayload for use by downstream force application modules.

Module Description

The module reads a commanded inertial force \(\mathbf{F}_N\) from cmdForceInertialInMsg and obtains site attitude \(\sigma_{SN}\) from one of two sources:

  • siteAttInMsg (preferred when linked)

  • siteFrameStateInMsg (fallback when siteAttInMsg is not linked)

From \(\sigma_{SN}\), the direction cosine matrix \(\mathbf{C}_{SN}\) is formed and used to rotate the force:

\[\mathbf{F}_S = \mathbf{C}_{SN}\mathbf{F}_N\]

The output vector \(\mathbf{F}_S\) is written to forceOutMsg.force_S.

Message Interfaces

Module I/O Messages

Msg Variable Name

Msg Type

Description

cmdForceInertialInMsg

CmdForceInertialMsgPayload

Input commanded force vector in inertial frame, read from forceRequestInertial.

siteAttInMsg

NavAttMsgPayload

Optional/primary input attitude source. If linked, sigma_BN from this message is used to build the inertial-to-site rotation.

siteFrameStateInMsg

SCStatesMsgPayload

Optional/fallback input attitude source. Used only when siteAttInMsg is not linked.

forceOutMsg

ForceAtSiteMsgPayload

Output site-frame force vector, written to force_S.

Detailed Behavior

At each update step, the module performs the following operations:

  1. Reads the input inertial force from cmdForceInertialInMsg.

  2. Selects the attitude source: - If siteAttInMsg is linked, use its sigma_BN. - Otherwise use siteFrameStateInMsg.sigma_BN.

  3. Builds \(\mathbf{C}_{SN}\) from the selected MRP attitude.

  4. Rotates the force from inertial to site frame to compute \(\mathbf{F}_S\).

  5. Writes forceOutMsg.force_S.

During Reset(), the module validates connectivity and logs errors if:

  • cmdForceInertialInMsg is not linked, or

  • both siteAttInMsg and siteFrameStateInMsg are unlinked.

Verification and Testing

The module is verified by automated unit tests in src/simulation/mujocoDynamics/cmdForceInertialToForceAtSite/_UnitTest/test_cmdForceInertialToForceAtSite.py.

Two test cases validate both attitude-source paths:

  • test_cmdForceInertialToForceAtSiteSCStates: links siteFrameStateInMsg and verifies \(\mathbf{F}_S = \mathbf{C}_{SN}\mathbf{F}_N\) against an independent MRP-to-DCM reference implementation.

  • test_cmdForceInertialToForceAtSiteNavAtt: links both attitude messages and verifies that siteAttInMsg takes precedence over siteFrameStateInMsg by matching output to the NavAtt-based reference rotation.

Both tests check agreement to tight numerical tolerance.

class CmdForceInertialToForceAtSite : public SysModel
#include <cmdForceInertialToForceAtSite.h>

Convert a commanded force in the inertial frame into a force at a site frame.

Computes a force vector expressed in the site frame S from an input force expressed in the inertial frame N. Uses either the site attitude message (preferred) or the site state message to obtain orientation S relative to N. The output message contains the force expressed in S.

Public Functions

void UpdateState(uint64_t CurrentSimNanos) override

Advance the model and publish outputs. Reads forceRequestInertial in N, builds C_SN from sigma_BN, computes F_S, and writes forceOutMsg.

Parameters:

CurrentSimNanos – Current simulation time in nanoseconds.

void Reset(uint64_t CurrentSimNanos) override

Validate input links.

Parameters:

CurrentSimNanos – Current simulation time in nanoseconds.

Public Members

ReadFunctor<CmdForceInertialMsgPayload> cmdForceInertialInMsg

Commanded force in N.

ReadFunctor<SCStatesMsgPayload> siteFrameStateInMsg

Site state providing sigma_BN as a fallback orientation source.

ReadFunctor<NavAttMsgPayload> siteAttInMsg

Site attitude providing sigma_BN as the primary orientation source.

Message<ForceAtSiteMsgPayload> forceOutMsg

Output force expressed in S.

BSKLogger bskLogger

Logger.