Module: dragDynamicEffector
Executive Summary
Drag dynamics class used to compute drag effects on spacecraft bodies. This class is used to implement drag dynamic effects on spacecraft using a variety of simple or complex models, which will include cannonball (attitude-independent) drag, single flat-plate drag, faceted drag models, and an interface to full-CAD GPU-accelerated drag models.
Density Correction State
The module supports an optional density correction state that scales the incoming atmospheric density.
If densityCorrectionStateName is set, the drag model uses
where \(\rho_{\text{in}}\) is read from atmoDensInMsg and \(\delta_\rho\) is the scalar
state referenced by densityCorrectionStateName.
If densityCorrectionStateName is left empty (default), no correction is applied and
atmoDensInMsg.neutralDensity is used directly.
Example setup:
# Drag model
drag = dragDynamicEffector.DragDynamicEffector()
drag.coreParams.dragCoeff = 2.2
drag.coreParams.projectedArea = 10.0
drag.atmoDensInMsg.subscribeTo(atmo.envOutMsgs[0])
# Optional: apply multiplicative density correction from a scalar state
stochasticAtmo = meanRevertingNoiseStateEffector.MeanRevertingNoiseStateEffector()
# ... Configure stochasticAtmo here
scObject.addStateEffector(stochasticAtmo)
drag.densityCorrectionStateName = stochasticAtmo.getStateName()
scObject.addDynamicEffector(drag)
Atmosphere Relative Velocity
The drag computation can optionally use the spacecraft velocity relative to a rotating atmosphere instead of the inertial spacecraft velocity. This is useful for modeling atmospheric drag in Low Earth Orbit, where the atmosphere approximately co-rotates with the Earth.
If useAtmosphereRelativeVelocity is enabled, the drag model computes
where
\(\mathbf{v}_{sc}\) is the spacecraft inertial velocity
\(\mathbf{r}_{sc}\) is the spacecraft inertial position
\(\boldsymbol{\omega}_{planet}\) is the planetary rotation vector
For Earth simulations, the planetary rotation rate is automatically taken from OMEGA_EARTH in astroConstants.h.
For other bodies it can be configured through planetOmega_N.
If useAtmosphereRelativeVelocity is left disabled (default), the drag model uses the spacecraft inertial velocity directly.
Example setup:
drag = dragDynamicEffector.DragDynamicEffector()
drag.coreParams.dragCoeff = 2.2
drag.coreParams.projectedArea = 10.0
drag.atmoDensInMsg.subscribeTo(atmo.envOutMsgs[0])
# Enable atmosphere-relative velocity
drag.setUseAtmosphereRelativeVelocity(True)
drag.setPlanetOmega_N([0.0, 0.0, 7.2921159e-5])
scObject.addDynamicEffector(drag)
Message Connection Descriptions
The following table lists all the module input and output messages. The module msg connection 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.
Msg Variable Name |
Msg Type |
Description |
|---|---|---|
atmoDensInMsg |
atmospheric density input message |
-
struct DragBaseData
- #include <dragDynamicEffector.h>
Container for basic drag parameters - the spacecraft’s atmosphere-relative velocity, its projected area, and its drag coefficient.
-
class DragDynamicEffector : public SysModel, public DynamicEffector
- #include <dragDynamicEffector.h>
drag dynamic effector
Public Functions
-
DragDynamicEffector()
-
~DragDynamicEffector()
The destructor.
-
void linkInStates(DynParamManager &states)
class method
This method is used to link the dragEffector to the hub attitude and velocity, which are required for calculating drag forces and torques.
- Parameters:
states – simulation states
-
void computeForceTorque(double integTime, double timeStep)
This method computes the body forces and torques for the dragEffector in a simulation loop, selecting the model type based on the settable attribute “modelType.”
-
void Reset(uint64_t CurrentSimNanos)
This method is used to reset the module.
-
void UpdateState(uint64_t CurrentSimNanos)
This method is called to update the local atmospheric conditions at each timestep. Naturally, this means that conditions are held piecewise-constant over an integration step.
- Parameters:
CurrentSimNanos – The current simulation time in nanoseconds
-
void WriteOutputMessages(uint64_t CurrentClock)
The DragEffector does not write output messages to the rest of the sim.
-
bool ReadInputs()
This method is used to read the incoming density message and update the internal density/ atmospheric data.
-
void cannonballDrag()
This method implements a simple “cannnonball” (attitude-independent) drag model.
-
void updateDragDir()
This method updates the internal drag direction based on the spacecraft velocity vector.
-
double getDensity()
This method obtains the density from the input data and applies a correction based on the density correction state (if it was configured)
-
void setUseAtmosphereRelativeVelocity(bool useRelVel)
Enables or disables the use of atmosphere-relative velocity for drag computation. When enabled, the drag force is computed using v_rel = v_sc - (omega_planet x r_sc). Requires hub position state to be available.
- Parameters:
useRelVel – true to use atmosphere-relative velocity, false to use inertial velocity
-
bool getUseAtmosphereRelativeVelocity() const
Returns whether atmosphere-relative velocity is used in drag computation.
- Returns:
true if atmosphere-relative velocity is enabled
-
void setPlanetOmega_N(const Eigen::Vector3d &omega)
Sets the planetary rotation vector expressed in the inertial frame. Used to compute the atmosphere velocity when useAtmosphereRelativeVelocity is enabled. For Earth, the default is taken from OMEGA_EARTH in astroConstants.h: [0, 0, 7.2921159e-5] rad/s.
- Parameters:
omega – Planetary rotation vector [rad/s] in inertial frame N
Public Members
-
DragBaseData coreParams
— Struct used to hold drag parameters
-
ReadFunctor<AtmoPropsMsgPayload> atmoDensInMsg
— message used to read density inputs
-
std::string modelType
— String used to set the type of model used to compute drag
-
std::string densityCorrectionStateName = ""
— If not ‘’, finds a state with this name to get
densityCorrection
-
StateData *densityCorrection
— Used density is
(1 + densityCorrection) * atmoInData.neutralDensity
-
BSKLogger bskLogger
— BSK Logging
-
DragDynamicEffector()