C++ Module: atmosphereBase
Executive Summary
General atmosphere base class used to calculate neutral density/temperature using arbitrary models
The Atmosphere class is used to calculate the neutral density and temperature above a body using arbitrary models.
Each atmosphere is attached to a specific planet, but provides support for
multiple spacecraft through addSpacecraftToModel().
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 |
|---|---|---|
scStateInMsgs |
vector of spacecraft state input messages. |
|
envOutMsgs |
vector of atmospheric density output messages. |
|
planetPosInMsg |
(optional) planet state input message. If not provided the planet state is zero information. |
|
epochInMsg |
(optional) epoch date/time input message. The date and time are interpreted as UTC, independent of the time zone of the computer. |
Spacecraft State Timing
The module is normally executed before the spacecraft within a task, so the spacecraft state message it reads was written
at the end of the previous step. By default the message is used as written. To avoid an output that lags the interval it is applied
to, the extrapolation can be enabled with setExtrapolateScStateToStepMidpoint(True). The spacecraft position is
then advanced with the message velocity by half of the message age, which is the middle of the interval that the next
spacecraft update integrates. It is skipped for a message that was written at the current time and for a stale
message that was written before the previous update of the module, for example a state written once at the start of
the simulation.
Warning
The extrapolation requires that the module is updated with the same task period as the spacecraft, so that the state message written by the spacecraft at the previous module update is exactly one module interval old. If the task periods differ, whether the spacecraft is faster or slower than the module, half of the message age is not the middle of the module interval. The state is then not extrapolated to the midpoint: the spacecraft stay at the epoch of their messages, and the planets are moved to that epoch if all the spacecraft messages were written at the previous module update (they are left as written otherwise), so that every spacecraft is evaluated against the same planet epoch. A warning is logged once when a spacecraft message is found not to have been written at the previous module update. A task period mismatch is not always detectable this way: a message written at the current module update, for example by a faster spacecraft that runs before the module, is used as written and gives no warning. No message that is not the output of the previous module update is ever extrapolated. A task period that changes during the simulation has the same effect. The extrapolation only starts once two write times of the spacecraft state message have been observed and their interval equals the module update interval, so the first updates are not extrapolated. Until then the spacecraft state is used as written and the planet is moved back to the epoch of that state, so the relative geometry stays consistent. Run the module in the same task as the spacecraft, or at the same period.
When the extrapolation is enabled the position and the orientation of the planet (or of the sun and the planets for the eclipse) are advanced, or moved back, with their message velocity and angular rate to the same middle of the interval as the spacecraft, so that the relative geometry is evaluated at a single epoch. Time-dependent models, such as the local solar time or the decimal year of the epoch, are evaluated at the same epoch as the geometry: the middle of the interval if the extrapolation applies, the epoch of the previous update while the spacecraft state is not yet extrapolated, and the current time otherwise. Inputs read from messages, such as a space weather sample, are not shifted. As in the gravity effector, the planet is advanced by the time since its message was written, whatever the age of the message, so a planet message written once with a non-zero velocity is projected forward over the whole simulation.
Planet Shape
By default the planet is a sphere and the altitude is the distance to the planet center minus planetRadius. If the
planet polar radius is set with setPlanetPolarRadius(), the altitude (and, for models that use it such as
C++ Module: msisAtmosphere, the latitude) is computed above the oblate ellipsoid defined by planetRadius and the polar
radius, and planetPosInMsg must be connected to provide the planet orientation. A planet message that leaves
J20002Pfix at zero, as one that only sets the position and the velocity does, is treated as the identity. For the Earth use the equatorial
radius REQ_EARTH * 1000 and the polar radius RP_EARTH * 1000 from astroConstants:
atmosphere.setPlanetPolarRadius(orbitalMotion.RP_EARTH * 1000.0) # [m]
A negative polar radius, the default, selects the sphere. The difference between the two altitudes is up to about 21 km, which changes the density of an atmosphere model by tens of percent at mid and high latitudes.
-
class AtmosphereBase : public SysModel
- #include <atmosphereBase.h>
atmospheric density base class
Public Functions
-
AtmosphereBase()
This method initializes some basic parameters for the module.
-
~AtmosphereBase()
Destructor.
-
void Reset(uint64_t CurrentSimNanos)
This method is used to reset the module.
-
void addSpacecraftToModel(Message<SCStatesMsgPayload> *tmpScMsg)
Adds the spacecraft message to a vector of sc messages and automatically creates the corresponding output message.
- Parameters:
tmpScMsg – A spacecraft state message name.
-
void UpdateState(uint64_t CurrentSimNanos)
Computes the current local magnetic field for each spacecraft and writes their respective messages.
- Parameters:
CurrentSimNanos – The current simulation time in nanoseconds
-
void setPlanetPolarRadius(double polarRadius)
Sets the polar radius of the planet. If set, the altitude (and the geodetic latitude in models that use it) is computed above the oblate ellipsoid defined by the equatorial radius planetRadius and this polar radius. By default the planet is a sphere of radius planetRadius, and altitude is the distance to the planet center minus planetRadius. The planet orientation message planetPosInMsg is required when the polar radius is set.
- Parameters:
polarRadius – [m] planet polar radius; a negative value selects the spherical planet
-
double getPlanetPolarRadius() const
Returns the polar radius of the planet.
- Returns:
[m] planet polar radius; a negative value means the planet is treated as a sphere
-
void setExtrapolateScStateToStepMidpoint(bool enable)
Enables or disables the extrapolation of the spacecraft state to the middle of the interval the next spacecraft update integrates, see extrapolateScStateToStepMidpoint(). It is disabled by default, in which case the spacecraft state message is used as written. The extrapolation assumes that the module and the spacecraft run at the same task rate with a constant spacecraft step; a warning is logged once if a spacecraft message was not written at the previous module update, which is typically a task rate mismatch. A mismatch is not always detectable, but a message that is not the output of the previous module update is never extrapolated.
- Parameters:
enable – [-] true to extrapolate the spacecraft state to the middle of the step
-
bool getExtrapolateScStateToStepMidpoint() const
Returns whether the spacecraft state extrapolation is enabled.
- Returns:
[-] true if the spacecraft state is extrapolated
Public Members
-
std::vector<ReadFunctor<SCStatesMsgPayload>> scStateInMsgs
Vector of the spacecraft position/velocity input message.
-
std::vector<Message<AtmoPropsMsgPayload>*> envOutMsgs
Vector of message names to be written out by the environment.
-
ReadFunctor<SpicePlanetStateMsgPayload> planetPosInMsg
Message name for the planet’s SPICE position message.
-
ReadFunctor<EpochMsgPayload> epochInMsg
(optional) epoch date/time input message
-
double envMinReach
[m] Minimum planet-relative position needed for the environment to work, default is off (neg. value)
-
double envMaxReach
[m] Maximum distance at which the environment will be calculated, default is off (neg. value)
-
double planetRadius
[m] Radius of the planet
-
BSKLogger bskLogger
— BSK Logging
Protected Functions
-
void writeMessages(uint64_t CurrentClock)
This method is used to write the output magnetic field messages whose names are established in AddSpacecraftToModel.
- Parameters:
CurrentClock – The current time used for time-stamping the message
-
bool readMessages(uint64_t CurrentSimNanos)
This method is used to read the incoming command message and set the associated spacecraft positions for computing the atmosphere. If enabled with setExtrapolateScStateToStepMidpoint(), the spacecraft state is extrapolated to the middle of the interval the next spacecraft update integrates, see extrapolateScStateToStepMidpoint().
- Parameters:
CurrentSimNanos – [ns] current simulation time
- Returns:
true if all required messages were read
-
void updateLocalAtmosphere(double currentTime)
This method is used to update the local magnetic field based on each spacecraft’s position.
-
void updateRelativePos(SpicePlanetStateMsgPayload *planetState, SCStatesMsgPayload *scState)
This method is used to determine the spacecraft position vector relative to the planet.
- Parameters:
planetState – A space planetstate message struct.
scState – A spacecraft states message struct.
-
virtual void evaluateAtmosphereModel(AtmoPropsMsgPayload *msg, double currentTime) = 0
class method
-
virtual void customReset(uint64_t CurrentClock)
Custom Reset() method. This allows a child class to add additional functionality to the Reset() method
-
virtual void customWriteMessages(uint64_t CurrentClock)
Custom output message writing method. This allows a child class to add additional functionality.
-
virtual bool customReadMessages()
Custom output input reading method. This allows a child class to add additional functionality.
-
virtual void customSetEpochFromVariable()
Custom customSetEpochFromVariable() method. This allows a child class to specify how the module epoch information is set by a module variable.
Protected Attributes
-
double orbitRadius
[m] sc orbit radius about planet
-
double orbitAltitude
[m] sc altitude above planetRadius
-
std::vector<AtmoPropsMsgPayload> envOutBuffer
— Message buffer for magnetic field messages
-
std::vector<SCStatesMsgPayload> scStates
vector of the spacecraft state messages
-
SpicePlanetStateMsgPayload planetState
planet state message
-
uint64_t previousUpdateNanos = 0
[ns] time of the previous module update, used to detect stale spacecraft messages
-
struct tm epochDateTime
time/date structure containing the epoch information using a Gregorian calendar
Private Members
-
double planetPolarRadius = -1.0
[m] polar radius of the planet; a negative value selects a spherical planet of radius planetRadius, planetRadius must not change after Reset()
-
ScStateExtrapolation scStateExtrapolation
opt-in extrapolation of the spacecraft state to the step midpoint
-
std::vector<std::unique_ptr<Message<AtmoPropsMsgPayload>>> ownedEnvOutMsgs
Storage for envOutMsgs.
-
AtmosphereBase()