[#1317] Added option to use atmosphere relative velocity in dragDynamicEff

[carlo98]

• Tickets addressed: Issue Atmosphere relative velocity in dragDynamicaEffector #1317
• Review: By commit
• Merge strategy: Merge (no squash)

Description

Adds optional atmosphere-relative velocity support to dragDynamicEffector, allowing drag to be computed from spacecraft velocity relative to a rotating planetary atmosphere instead of inertial velocity alone.

Key implementation details reviewers should be aware of:

• Default behavior is unchanged: The new logic is enabled only when useAtmosphereRelativeVelocity is set to True. Existing users keep the current inertial-velocity 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 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.

• 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 drag setups.

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

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

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 test verifying the position state is only required when atmosphere-relative velocity is enabled.

• 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.

Documentation

• Updated dragDynamicEffector.rst with a new section.

• Added the equation, default Earth behavior, non-Earth configuration note, and a Python usage example.

Future work

• Source planetOmega_N automatically from Spice kernels.

• Extend atmosphere-relative velocity support to non-cannonball drag models.