Module: cannonballDrag

Executive Summary

The CannonballDrag module computes quasi-steady aerodynamic drag force and the associated torque acting at a site fixed on a body. It outputs force and torque expressed in a site-fixed reference frame. The model follows the classical cannonball drag formulation and is intended for low-fidelity aerodynamic disturbance modeling.

Module Description

This module evaluates aerodynamic drag with force magnitude computed as

\[F = \tfrac{1}{2} \rho v^2 C_D A\]

where \(\rho\) is the local neutral atmospheric density, \(v\) is the magnitude of the relative flow velocity at the site, \(C_D\) is the drag coefficient, and \(A\) is the projected area. The drag force direction is opposite the relative velocity vector.

The force is applied at a specified center-of-pressure location relative to the site frame origin, producing a torque given by

\[\boldsymbol{\tau} = \mathbf{r}_{CP/S} \times \mathbf{F}\]

Both force and torque are expressed in the site-fixed reference frame.

Message Interfaces

Module I/O Messages
Msg Variable Name	Msg Type	Description
dragGeometryInMsg	DragGeometryMsgPayload	Input message providing the aerodynamic geometry parameters: `dragCoeff` (\(C_D\)), `projectedArea` (\(A\)), and `r_CP_S` (center-of-pressure vector relative to the site frame origin, expressed in the site frame).
atmoDensInMsg	AtmoPropsMsgPayload	Input message providing local atmospheric properties at the site location, including `neutralDensity` (\(\rho\)).
referenceFrameStateInMsg	SCStatesMsgPayload	Input message providing the inertial state of the site reference frame, including `sigma_BN` (MRPs for site frame attitude relative to inertial) and `v_BN_N` (inertial velocity of the site frame origin).
forceOutMsg	ForceAtSiteMsgPayload	Output message containing aerodynamic drag force expressed in the site reference frame.
forceOutMsgC	ForceAtSiteMsgPayload	Output message containing aerodynamic drag force expressed in the site reference frame (C-wrapped output).
torqueOutMsg	TorqueAtSiteMsgPayload	Output message containing aerodynamic torque about the site frame origin, expressed in the site reference frame.
torqueOutMsgC	TorqueAtSiteMsgPayload	Output message containing aerodynamic torque about the site frame origin, expressed in the site reference frame (C-wrapped output).

Detailed Behavior

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

Reads the atmospheric density from atmoDensInMsg.
Reads the drag coefficient, projected area, and center-of-pressure location from dragGeometryInMsg.
Reads the site frame attitude and inertial velocity from referenceFrameStateInMsg.
Transforms the inertial velocity into the site frame using the provided attitude.
Computes the drag force magnitude and direction in the site frame.
Computes the resulting torque about the site frame origin.
Publishes the force and torque through forceOutMsg and torqueOutMsg (and forceOutMsgC and torqueOutMsgC).

The model assumes quasi-steady aerodynamics and does not account for lift, shadowing, free-molecular effects, or flow angular rates.

Verification and Testing

The CannonballDrag module is verified through automated unit and integration tests that exercise both isolated force computation and coupled orbital dynamics behavior.

A unit-level test initializes the module with prescribed atmospheric density, drag geometry, site attitude, and inertial velocity. The resulting force and torque outputs are compared against analytically computed reference values obtained by explicitly rotating the inertial velocity into the site frame and applying the cannonball drag equations. The test passes if the force and torque vectors match the reference solutions within numerical tolerance.

An integration-level test embeds the module in a MuJoCo-based orbital simulation with gravity and an exponential atmosphere model. The spacecraft is propagated over one orbital period, and the drag force output is compared at each time step against an independent reference implementation of the same drag law evaluated using the recorded state and atmospheric density. Successful verification requires agreement between the module output and the reference drag force history to within prescribed tolerances.

class CannonballDrag : public SysModel 

#include <cannonballDrag.h>

Aerodynamic drag model that computes force and torque at a MuJoCo site.

Updates a force and a torque to represent quasi-steady aerodynamic drag acting at a site fixed on a body. The model reads:

Geometry: drag coefficient and projected reference area.
Atmosphere: neutral density.
Reference frame state: position, velocity, and attitude of the site frame.

Force direction is opposite the relative flow. Magnitude follows \( F = \tfrac{1}{2}\rho\,v^2 C_D A \). Torque is \( \tau = r_{CP/S} \times F \) in the site frame.

The force and torque output in forceOutMsg and torqueOutMsg are given in the site reference frame whose state is given in referenceFrameStateInMsg.

Frames and notation:

N: inertial.
S: site-fixed reference frame where outputs are expressed.

Public Functions

void SelfInit() override: Initializes the C output messages.

void UpdateState(uint64_t CurrentSimNanos) override

Advance the model and publish outputs.

Parameters:: CurrentSimNanos – Current simulation time in nanoseconds.

void Reset(uint64_t CurrentSimNanos) override

Validate all input messages are linked.

Parameters:: CurrentSimNanos – Current simulation time in nanoseconds.

Public Members

ReadFunctor<DragGeometryMsgPayload> dragGeometryInMsg: Geometry input.

ReadFunctor<AtmoPropsMsgPayload> atmoDensInMsg: Atmospheric properties input.

ReadFunctor<SCStatesMsgPayload> referenceFrameStateInMsg: State of the reference frame .

Message<ForceAtSiteMsgPayload> forceOutMsg: Output force at the site in the site reference frame.

ForceAtSiteMsg_C forceOutMsgC = {}: Output force at the site in the site reference frame (C message).

Message<TorqueAtSiteMsgPayload> torqueOutMsg: Output torque in the site reference frame.

TorqueAtSiteMsg_C torqueOutMsgC = {}: Output torque in the site reference frame (C message).

BSKLogger bskLogger: Logger.