[#1325] Added relative velocity atmo and density correction in facetDragDynEff

[carlo98]

• Tickets addressed: Issue Add atmosphere-relative velocity and density correction support to Drag effectors #1325
• Review: By commit
• Merge strategy: Merge (no squash)

Description

Adds optional atmosphere-relative velocity support and optional multiplicative density correction to facetDragDynamicEffector, bringing it to feature parity with dragDynamicEffector.

Key implementation details reviewers should be aware of:

• Default behavior is unchanged: Both new features are opt-in. Existing users keep the current inertial-velocity, uncorrected-density behavior by default.

• Relative-velocity formulation: When enabled, the module computes v_rel = v_sc - (planetOmega_N x r_sc) before transforming into body coordinates and evaluating per-facet drag.

• Earth default, configurable for other bodies: planetOmega_N defaults to [0, 0, OMEGA_EARTH], so Earth cases work without extra configuration. Non-Earth cases can override this vector from Python via setPlanetOmega_N.

• Conditional state dependency: The spacecraft position state is linked only when atmosphere-relative velocity is enabled, so no new mandatory dependency is introduced for existing facet drag setups.

• Reset guard: If useAtmosphereRelativeVelocity is enabled but the hub position state is unavailable, Reset() emits a BSK_ERROR immediately.

• Near-zero relative velocity handling: If the relative velocity magnitude falls below threshold, the module returns zero drag force and torque instead of normalizing a near-zero vector.

• Density correction state: When densityCorrectionStateName is set, the effective density is scaled as rho_eff = rho_in * (1 + delta), where delta is a scalar state read from the dynamic state manager (e.g. driven by MeanRevertingNoiseStateEffector). Getter and setter methods are provided so the state name is accessible from Python.

Verification

• Added a test confirming drag is unchanged when useAtmosphereRelativeVelocity = False.

• Added a unit test confirming the computed force matches a reference when useAtmosphereRelativeVelocity = True.

• Added a near-zero-relative-velocity test confirming the drag output remains finite and effectively zero.

• Added a reset-guard test confirming initialization fails when atmosphere-relative velocity is enabled without a valid position state.

• Added a test confirming drag force is unchanged when no density correction state is configured.

Documentation

• Updated facetDragDynamicEffector.rst with a new Density Correction State section including the scaling equation, default behavior, and a Python usage example.

• Updated facetDragDynamicEffector.rst with a new Atmosphere Relative Velocity section including the formulation, Earth default, non-Earth configuration note, and a Python usage example.

Future work

• Source planetOmega_N automatically from Spice kernels.
• Extend UnitTests to cover also densityCorrection. This is missing also for dragDynamicEffector.

[carlo98]

This may create problems with PR 1289. Should probably wait for it to be merged?

[schaubh]

@leahkiner , does this PR impact any of your ongoing work?