Module: windBase

Executive Summary

Abstract base class for atmospheric wind models. WindBase reads spacecraft state input messages and writes wind velocity output messages in the inertial frame. Concrete subclasses implement evaluateWindModel() to fill the WindMsgPayload for each tracked spacecraft. The module supports multiple spacecraft through the addSpacecraftToModel() method.

Module Description

Multi-spacecraft support. WindBase supports multiple spacecraft through the addSpacecraftToModel() method. Each call to this method subscribes to a spacecraft’s state message and creates a corresponding wind output message. The module processes all connected spacecraft in each update cycle, computing wind velocities for each spacecraft’s position.

Planet-relative position. At every time step, WindBase computes r_BP_N as each spacecraft’s position relative to the planet center in the inertial frame. r_BN_N is read from SCStatesMsgPayload and r_PN_N (stored as PositionVector) is read from SpicePlanetStateMsgPayload:

\[\mathbf{r}_{BP,N} = \mathbf{r}_{BN,N} - \mathbf{r}_{PN,N}\]

This correctly handles simulations where the planet is not at the inertial origin (e.g., heliocentric simulations).

Planet angular velocity. WindBase provides two modes for the planet angular velocity used in co-rotation calculations, selected via setUseSpiceOmegaFlag():

• SPICE mode (default, True): angular velocity is derived from J20002Pfix_dot each time step. Falls back to the manually set value only when planetPosInMsg has not been written to.

• Manual mode (False): the value set via setPlanetOmega_N() is always used (default: Earth rotation rate).

Epoch handling. For time-dependent empirical wind models, WindBase maintains an epochDateTime structure (struct tm) initialised to the Basilisk standard epoch (2019-01-01 00:00:00). During Reset():

• If epochInMsg is linked, the epoch is read from that message.

• Otherwise, customSetEpochFromVariable() is called, giving subclasses the opportunity to set the epoch from a module-level variable.

Message Connection Descriptions

The following table lists all the module input and output messages.

Module I/O Messages

Msg Variable Name	Msg Type	Description
scStateInMsgs	SCStatesMsgPayload	Spacecraft state input messages (vector). Use addSpacecraftToModel() to add spacecraft and automatically create corresponding output messages.
envOutMsgs	WindMsgPayload	Atmospheric wind velocity output messages (vector). Automatically created when spacecraft are added via addSpacecraftToModel(). Each message contains: v_air_N (full air velocity in inertial frame) and v_wind_N (wind perturbation velocity), both expressed in inertial frame N
planetPosInMsg	SpicePlanetStateMsgPayload	Planet SPICE state input message. Provides PositionVector used to compute r_BP_N. Must be connected before InitializeSimulation().
epochInMsg	EpochMsgPayload	(Optional) Epoch date/time message. When connected, overrides the default Basilisk epoch stored in epochDateTime. Required by empirical wind models that depend on calendar date.

---

class WindBase : public SysModel

#include <windBase.h>

Abstract base class for atmospheric wind models.

WindBase reads spacecraft state input messages and writes wind velocity output messages. Concrete subclasses implement evaluateWindModel() to fill the WindMsgPayload for each tracked spacecraft. The module supports multiple spacecraft through the addSpacecraftToModel() method.

Public Functions

WindBase()

This method initializes some basic parameters for the module.

~WindBase()

Destructor.

void Reset(uint64_t CurrentSimNanos) override

Reset: resolves the epoch and calls customReset() for subclass-specific initialization.

Parameters:

CurrentSimNanos – Current simulation time (ns).

void UpdateState(uint64_t CurrentSimNanos) override

Main update method: reads messages, evaluates wind model, writes output.

Parameters:

CurrentSimNanos – Current simulation time (ns).

void addSpacecraftToModel(Message<SCStatesMsgPayload> *tmpScMsg)

Adds a spacecraft to the model by subscribing to its state message and creating an output message.

Parameters:

tmpScMsg – Spacecraft state message to subscribe to.

Eigen::Vector3d getPlanetOmega_N() const

Returns the planet angular velocity vector in the inertial frame.

Returns:

Planet angular velocity [rad/s] in N frame.

void setPlanetOmega_N(const Eigen::Vector3d &omega)

Sets the planet angular velocity vector in the inertial frame.

This method sets the manual planet angular velocity and disables SPICE-derived omega. To re-enable SPICE-derived omega, call setUseSpiceOmegaFlag(true).

Parameters:

omega – Planet angular velocity [rad/s] in N frame.

Throws:

BSK_ERROR – if input contains NaN or infinite values.

bool getUseSpiceOmegaFlag() const

Gets the current useSpiceOmega flag.

Returns:

true if SPICE-derived omega is being used when available.

void setUseSpiceOmegaFlag(bool useSpice)

Sets the useSpiceOmega flag.

Parameters:

useSpice – If true, use SPICE-derived omega when available, fallback to manual otherwise.

Public Members

std::vector<ReadFunctor<SCStatesMsgPayload>> scStateInMsgs = {}

Spacecraft state input messages.

std::vector<Message<WindMsgPayload>*> envOutMsgs = {}

Wind velocity output messages.

ReadFunctor<SpicePlanetStateMsgPayload> planetPosInMsg = {}

Planet SPICE state input message.

ReadFunctor<EpochMsgPayload> epochInMsg = {}

(optional) epoch date/time input message

BSKLogger bskLogger = {}

&#8212; BSK Logging

Protected Functions

void writeMessages(uint64_t CurrentClock)

Writes the wind output messages for each spacecraft.

Parameters:

CurrentClock – Current simulation time (ns).

bool readMessages()

Reads the spacecraft and planet state messages.

Returns:

true if all required messages were successfully read.

Eigen::Vector3d computeRelativePos(const SpicePlanetStateMsgPayload &planetState, const SCStatesMsgPayload &scState) const

Computes r_BP_N from spacecraft and planet positions.

Parameters:

• planetState – Planet state message.

• scState – Spacecraft state message.

Returns:

Spacecraft position relative to planet in inertial frame [m].

void updateLocalWind(double currentTime)

Computes r_BP_N, then calls evaluateWindModel() for each spacecraft.

Parameters:

currentTime – Current simulation time (s).

virtual void evaluateWindModel(WindMsgPayload *msg, const Eigen::Vector3d &r_BP_N, const Eigen::Vector3d &v_corotatingAir_N, double currentTime) = 0

Pure-virtual method that each concrete wind model must implement.

Parameters:

• msg – Output wind message to fill.

• r_BP_N – Spacecraft position relative to planet in inertial frame [m].

• v_corotatingAir_N – Co-rotating atmosphere velocity [m/s] in N frame.

• currentTime – Current simulation time (s).

virtual void customReset(uint64_t CurrentClock)

Optional subclass reset hook.

Parameters:

CurrentClock – Current simulation time (ns).

virtual void customWriteMessages(uint64_t CurrentClock)

Optional subclass write hook.

Parameters:

CurrentClock – Current simulation time (ns).

virtual bool customReadMessages()

Optional subclass read hook.

Returns:

true if successful.

virtual void customSetEpochFromVariable()

Optional hook called from Reset() when epochInMsg is not linked. Subclasses can override this to set epochDateTime from a module variable.

void updatePlanetOmegaFromSpice()

Updates spiceOmega_N from J20002Pfix_dot when SPICE provides it.

With C = J20002Pfix (maps inertial N to planet-fixed P), the kinematic equation gives skew_PN_P = -C_dot * C^T. spiceOmega_N is extracted from that skew-symmetric matrix and rotated to the inertial frame: spiceOmega_N = C^T * omega_PN_P. The update is skipped when J20002Pfix_dot is zero (SPICE did not compute orientation derivatives), preserving the manually set value.

Eigen::Vector3d getSelectedOmega()

Returns the selected planet angular velocity to use in wind calculations. Either planetOmega_N set by the user or spiceOmega_N computed from SPICE.

Returns:

Selected planet angular velocity [rad/s] in N frame.

Protected Attributes

std::vector<WindMsgPayload> envOutBuffer = {}

Message write buffer for each spacecraft.

std::vector<SCStatesMsgPayload> scStates = {}

Cached spacecraft state messages.

SpicePlanetStateMsgPayload planetState = {}

Cached planet state message.

Private Members

bool useSpiceOmega = true

[bool] If true, use SPICE-derived omega; if false, use manually set value

Eigen::Vector3d planetOmega_N = {0.0, 0.0, OMEGA_EARTH}

[rad/s] Planet angular velocity in inertial frame (default: Earth rotation rate)

Eigen::Vector3d spiceOmega_N = {0.0, 0.0, 0.0}

[rad/s] Planet angular velocity derived from SPICE DCM derivatives

struct epochDateTime

#include <windBase.h>

Epoch date/time (Gregorian) for time-dependent models.