C++ Module: solarFlux

Executive Summary

Takes in a spacecraft position message and sun position message and calculates the solar \(\text{W/m}^2\) at the spacecraft location. It also allows for an optional eclipse message to be considered in the solar flux calculation.

Module Assumptions and Limitations

This model uses the solar flux value, SOLAR_FLUX_EARTH, and astronomical unit, AU, values from astroConstants.h
This model assumes constant solar flux and a perfect inverse square fall-off of flux as one moves further from the sun.
This model can take in one spacecraft position message and one sun position message. The eclipse message must correspond to the right spacecraft/planet pair.

Message Connection Descriptions

The following table lists all the module input and output messages. The module msg variable name 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.

Module I/O Messages
Msg Variable Name	Msg Type	Description
sunPositionInMsg	SpicePlanetStateMsgPayload	sun state input message.
spacecraftStateInMsg	SCStatesMsgPayload	spacecraft state input message.
eclipseInMsg	EclipseMsgPayload	(optional) eclipse input message.
solarFluxOutMsg	SolarFluxMsgPayload	solar flux output message.

Detailed Module Description

Many physical effects from sun sensor outputs to spacecraft heating depend on the solar flux incident on a spacecraft. This module provides that flux given the sun and spacecraft positions.

From the user perspective, this module should be instantiated when there is a desire to provide the solar flux at a spacecraft location.

From the developer perspective, the use of this module in conjunction with the developer’s other modules should be preferred over individual modules calculating the solar flux internally and applying it. Especially if eclipsing effects on the solar flux are desired, this module should be used rather than other modules implementing this calculation and applying eclipse themselves. This does a few things. First, it prevents code repetition. Second, it ensures consistency how solar flux values are calculated, avoiding multiple sources and hard-coding numbers. Third, it prevents other modules from needing to apply eclipse individually.

Design Philosophy

Overall, this module was created because many other modules need this information. The eclipse message is included as an optional message. It was decided to do this rather than have a separate module to apply the eclipse in order to reduce module count and maintain similar design philosophy throughout the framework.

Equations

The flux is calculated by scaling the flux at 1 AU and applying the EclipseMsgPayload illuminationFactor:

\[F_{\mathrm{out}} = F_{\mathrm{Earth}} * \frac{\mathrm{AU}^2}{r_{\mathrm{Sun}}^2} * f_s\]

where \(r_{\mathrm{Sun}}\) is the distance between the spacecraft and the sun and \(f_s\) is the illumination factor.

User Guide

The user can only instantiate this module, change the i/o names, and add it to a task. The names below are only special in that they are useful defaults and are actually the defaults, with the exception of the eclipse message which is defaulted to an empty string

from Basilisk.simulation import solarFlux
from Basilisk.utilities import SimulationBaseClass()

sim = SimulationBaseClass.SimBaseClass()
proc = sim.CreateNewProcess("proc")
task = sim.CreateNewTask("task", int(1e9))
proc.addTask(task)

sf = solarFlux.SolarFlux()
sf.sunPositionInMsg.subscribeTo(sunMsg)
sf.spacecraftStateInMsg.subscribeTo(scMsg)
sf.eclipseInMsg.subscribeTo(eclMsg)
sim.AddModelToTask(task.Name, sf)

dataLog = sf.solarFluxOutMsg.recorder()

Warning

shadowFactor is deprecated in favor of illuminationFactor. In C/C++ both names work until Dec 31, 2026. After that date, code must use illuminationFactor exclusively.

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. A warning is logged once when the 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 sun 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. Other time-dependent inputs, such as the epoch used for solar time or a space weather sample, are not shifted and are evaluated at the current time. 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.

class SolarFlux : public SysModel 

#include <solarFlux.h>

solar flux class

Public Functions

inline SolarFlux()

inline ~SolarFlux()

void Reset(uint64_t CurrentSimNanos) override: This method is used to reset the module. Currently no tasks are required.

void UpdateState(uint64_t CurrentSimNanos) override: Read Messages and scale the solar flux then write it out

void writeMessages(uint64_t CurrentSimNanos): This method is used to write the output flux message

void readMessages(uint64_t CurrentSimNanos)

This method is used to read messages and save values to member attributes. If enabled with setExtrapolateScStateToStepMidpoint(), the spacecraft position is extrapolated to the middle of the interval the next spacecraft update integrates, see extrapolateScStateToStepMidpoint().

Parameters:: CurrentSimNanos – [ns] current simulation time

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

ReadFunctor<SpicePlanetStateMsgPayload> sunPositionInMsg: sun state input message

ReadFunctor<SCStatesMsgPayload> spacecraftStateInMsg: spacecraft state input message

Message<SolarFluxMsgPayload> solarFluxOutMsg: solar flux output message

ReadFunctor<EclipseMsgPayload> eclipseInMsg: (optional) eclipse input message

BSKLogger bskLogger: — BSK Logging

Private Members

double fluxAtSpacecraft: [W/m2]

double eclipseFactor = 1.0: [] 1.0 is full sun, 0.0 is full eclipse

Eigen::Vector3d r_SN_N: [m] sun position

Eigen::Vector3d r_ScN_N: [m] s/c position

uint64_t previousUpdateNanos = 0: [ns] time of the previous module update, used to detect stale spacecraft messages

ScStateExtrapolation scStateExtrapolation: opt-in extrapolation of the spacecraft state to the step midpoint