Rename shadow factor to illumination factor

examples/BskSim/scenarios/scenario_AttEclipse.py

@@ -98,7 +98,7 @@
 This plot illustrates the shadow fraction calculated by the CSS as the spacecraft orbits Earth and passes through
 the Earth's shadow. 0.0 corresponds with total eclipse and 1.0 corresponds with direct sunlight.
 
-.. image:: /_images/Scenarios/scenario_AttEclipse_shadowFraction.svg
+.. image:: /_images/Scenarios/scenario_AttEclipse_illuminationFraction.svg
    :align: center
 
 The :ref:`CSSWlsEst` module calculates the position of the sun based on input from the CSS.
@@ -217,7 +217,7 @@ def pull_outputs(self, showPlots):
         num_RW = 4  # number of wheels used in the scenario
 
         # Dynamics process outputs: pull log messages below if any
-        shadowFactor = np.delete(self.shadowRec.shadowFactor, 0, 0)
+        illuminationFactor = np.delete(self.shadowRec.illuminationFactor, 0, 0)
 
         # FSW process outputs
         dataUsReq = np.delete(self.rwMotorRec.motorTorque[:, range(num_RW)], 0, 0)
@@ -235,15 +235,15 @@ def pull_outputs(self, showPlots):
         BSK_plt.plot_rate_error(timeData, omega_BR_B)
         BSK_plt.plot_rw_speeds(timeData, RW_speeds, num_RW)
 
-        BSK_plt.plot_shadow_fraction(timeData, shadowFactor)
+        BSK_plt.plot_shadow_fraction(timeData, illuminationFactor)
         BSK_plt.plot_sun_point(timeData, sunPoint)
 
         figureList = {}
         if showPlots:
             BSK_plt.show_all_plots()
         else:
             fileName = os.path.basename(os.path.splitext(__file__)[0])
-            figureNames = ["attitudeErrorNorm", "rwMotorTorque", "rateError", "rwSpeed", "shadowFraction", "sunDirectionVector"]
+            figureNames = ["attitudeErrorNorm", "rwMotorTorque", "rateError", "rwSpeed", "illuminationFraction", "sunDirectionVector"]
             figureList = BSK_plt.save_all_plots(fileName, figureNames)
 
         return figureList

examples/scenarioCSS.py

@@ -246,7 +246,7 @@ def run(show_plots, useCSSConstellation, usePlatform, useEclipse, useKelly):
     sunPositionMsg = messaging.SpicePlanetStateMsg().write(sunPositionMsgData)
 
     if useEclipse:
-        eclipseMsgData = messaging.EclipseMsgPayload(shadowFactor=0.5)
+        eclipseMsgData = messaging.EclipseMsgPayload(illuminationFactor=0.5)
         eclipseMsg = messaging.EclipseMsg().write(eclipseMsgData)
 
     def setupCSS(CSS):
@@ -418,6 +418,6 @@ def setupCSS(CSS):
          True,        # show_plots
          False,       # useCSSConstellation
          False,       # usePlatform
-         False,       # useEclipse
+         True,       # useEclipse
          False        # useKelly
        )

src/architecture/messaging/msgAutoSource/msgInterfacePy.i.in

@@ -54,3 +54,50 @@ INSTANTIATE_TEMPLATES({type}, {type}Payload, {baseDir})
 %template({type}OutMsgsVector) std::vector<Message<{type}Payload>, std::allocator<Message<{type}Payload>> >;
 %template({type}OutMsgsPtrVector) std::vector<Message<{type}Payload>*, std::allocator<Message<{type}Payload>*> >;
 %template({type}InMsgsVector) std::vector<ReadFunctor<{type}Payload>, std::allocator<ReadFunctor<{type}Payload>> >;
+%pythoncode %{{
+if "{type}" == "EclipseMsg":
+    from . import _{type}Payload as _m
+    from Basilisk.utilities import deprecated
+
+    # ----- Payload aliasing -----
+    def _get_illum(self):
+        return _m.{type}Payload_shadowFactor_get(self)
+
+    def _set_illum(self, v):
+        _m.{type}Payload_shadowFactor_set(self, v)
+
+    {type}Payload.illuminationFactor = property(_get_illum, _set_illum)
+
+    # Deprecate the old shadowFactor name
+    def _warn_get_shadow(self):
+        deprecated.deprecationWarn(
+            "EclipseMsgPayload.shadowFactor",
+            "2026/12/31",
+            "Use EclipseMsgPayload.illuminationFactor instead (0=fully eclipsed, 1=fully sunlit)."
+        )
+        return _m.{type}Payload_shadowFactor_get(self)
+
+    def _warn_set_shadow(self, v):
+        deprecated.deprecationWarn(
+            "EclipseMsgPayload.shadowFactor",
+            "2026/12/31",
+            "Use EclipseMsgPayload.illuminationFactor instead (0=fully eclipsed, 1=fully sunlit)."
+        )
+        _m.{type}Payload_shadowFactor_set(self, v)
+
+    {type}Payload.shadowFactor = property(_warn_get_shadow, _warn_set_shadow)
+
+    # ----- Recorder aliasing so logs can use illuminationFactor -----
+    try:
+        _orig_rec_getattr = EclipseMsgRecorder.__getattr__
+
+        def _rec_getattr_with_alias(self, name):
+            if name == "illuminationFactor":
+                # Delegate to the original implementation but ask for shadowFactor
+                return _orig_rec_getattr(self, "shadowFactor")
+            return _orig_rec_getattr(self, name)
+
+        EclipseMsgRecorder.__getattr__ = _rec_getattr_with_alias
+    except Exception:
+        pass
+%}}

src/architecture/msgPayloadDefC/EclipseMsgPayload.h

@@ -21,10 +21,15 @@
 #define eclipseSimMsg_h
 
 
-//!@brief Eclipse shadow factor message definition.
+//! @brief Eclipse illumination message definition.
 typedef struct {
-    double shadowFactor;       //!< Proportion of illumination due to eclipse. 0 = fully shadowed, 1 = fully illuminated.
-}EclipseMsgPayload;
-
+    //! Fraction of illumination due to eclipse. 0 = fully shadowed, 1 = fully illuminated.
+    double shadowFactor;
+} EclipseMsgPayload;
+
+//! illuminationFactor alias to be used instead of shadowFactor. shadowFactor will be deprecarted by
+#ifndef BSK_DISABLE_ILLUMINATIONFACTOR_ALIAS
+#define illuminationFactor shadowFactor
+#endif
 
 #endif /* eclipseSimMsg_h */

src/simulation/dynamics/RadiationPressure/_Documentation/secUserGuide.tex

@@ -12,13 +12,13 @@ \subsection{Variable Definition and Code Description}
 \begin{table}[H]
 	\caption{Definition and Explanation of Variables Used.}
 	\centering \fontsize{10}{10}\selectfont
-	\begin{tabular}{ | m{5cm}| m{2cm} | m{1.5cm} | m{6cm} |} % Column formatting, 
+	\begin{tabular}{ | m{5cm}| m{2cm} | m{1.5cm} | m{6cm} |} % Column formatting,
 		\hline
 		\textbf{Variable}   		& \textbf{LaTeX Equivalent} 	                  &		\textbf{Variable Type}   & \textbf{Notes} \\ \hline
 		area 						  	  & $A_{\odot}$							  & double 								& [m2] Default setting: 0.0f. Required input for cannonball method to get any real output. This is the area to use when approximating the surface area of the spacecraft.\\ \hline
 		coefficientReflection 	  & $c_{R}$ 								& double 								& Default setting: 1.2. This is a factor applied to the radiation pressure based on spacecraft surface properties.\\ \hline
 		sunEclipseMsgData		& N/A										& string									& No default. If creating a "fake" eclipse message, set to radiation\_pressure.EclipseSimMsg() \\ \hline
-		sunEclipseMsgData.shadowFactor & $F_{\mathrm{s}}$& double								& Default setting: 1.0. i.e. there is no shadow by default. \\ \hline
+		sunEclipseMsgData.illuminationFactor & $F_{\mathrm{s}}$& double								& Default setting: 1.0. i.e. there is no shadow by default. \\ \hline
 	\end{tabular}
 	\label{tabular:vars}
 \end{table}
@@ -36,4 +36,4 @@ \subsection{Code Diagram}
 
 After the inputs are given, radiation\_pressure.cpp calculates the effects of radiation pressure via one of the two methods. At the end, the eclipse factor scales the output forces and torques.
 
-The spacecraft position and orientation states are obtained through the `spacecraft` state engine variables {\tt hubPosition} and {\tt hubSigma}. There is no longer a need to provide spacecraft states through an input message.
+The spacecraft position and orientation states are obtained through the `spacecraft` state engine variables {\tt hubPosition} and {\tt hubSigma}. There is no longer a need to provide spacecraft states through an input message.

src/simulation/dynamics/RadiationPressure/_UnitTest/test_radiationPressure.py

@@ -125,7 +125,7 @@ def unitRadiationPressure(show_plots, modelType, eclipseOn):
 
     if eclipseOn:
         sunEclipseMsgData = messaging.EclipseMsgPayload()
-        sunEclipseMsgData.shadowFactor = 0.5
+        sunEclipseMsgData.illuminationFactor = 0.5
         sunEclMsg = messaging.EclipseMsg().write(sunEclipseMsgData)
         srpDynEffector.sunEclipseInMsg.subscribeTo(sunEclMsg)
         srpDynEffector2.sunEclipseInMsg.subscribeTo(sunEclMsg)
@@ -196,8 +196,8 @@ def unitRadiationPressure(show_plots, modelType, eclipseOn):
         truthForceExternal_N = [0, 0, 0]
         truthTorqueExternalPntB_B = [-0.80492463017846114E-12, 0.50888380426172319E-12, 0.10249431804585393E-11]
         if eclipseOn:
-            truthForceExternal_B = sunEclipseMsgData.shadowFactor*np.array(truthForceExternal_B)
-            truthTorqueExternalPntB_B = sunEclipseMsgData.shadowFactor * np.array(truthTorqueExternalPntB_B)
+            truthForceExternal_B = sunEclipseMsgData.illuminationFactor * np.array(truthForceExternal_B)
+            truthTorqueExternalPntB_B = sunEclipseMsgData.illuminationFactor * np.array(truthTorqueExternalPntB_B)
         testFailCount, testMessages = unitTestSupport.compareVector(truthForceExternal_B,
                                                                     srpDataForce_B[1, 1:],
                                                                     errTol,

src/simulation/dynamics/RadiationPressure/radiationPressure.cpp

@@ -31,7 +31,7 @@ RadiationPressure::RadiationPressure()
     ,srpModel(SRP_CANNONBALL_MODEL)
     ,stateRead(false)
 {
-    this->sunVisibilityFactor.shadowFactor = 1.0;
+    this->sunVisibilityFactor.illuminationFactor = 1.0;
     this->forceExternal_N.setZero();
     this->forceExternal_B.setZero();
     this->torqueExternalPntB_B.setZero();
@@ -106,16 +106,16 @@ void RadiationPressure::computeForceTorque(double integTime, double timeStep)
 
     if (this->srpModel == SRP_CANNONBALL_MODEL) {
         this->computeCannonballModel(s_N);
-        this->forceExternal_N = this->forceExternal_N * this->sunVisibilityFactor.shadowFactor;
+        this->forceExternal_N = this->forceExternal_N * this->sunVisibilityFactor.illuminationFactor;
     }
     else if (this->srpModel == SRP_FACETED_CPU_MODEL) {
         Eigen::MRPd sigmaLocal_NB;
         sigmaLocal_NB = (Eigen::Vector3d)this->hubSigma->getState();
         Eigen::Matrix3d dcmLocal_BN = sigmaLocal_NB.toRotationMatrix().transpose();
         Eigen::Vector3d s_B = dcmLocal_BN*(sun_r_N - r_N);
         this->computeLookupModel(s_B);
-        this->forceExternal_B = this->forceExternal_B * this->sunVisibilityFactor.shadowFactor;
-        this->torqueExternalPntB_B = this->torqueExternalPntB_B * this->sunVisibilityFactor.shadowFactor;
+        this->forceExternal_B = this->forceExternal_B * this->sunVisibilityFactor.illuminationFactor;
+        this->torqueExternalPntB_B = this->torqueExternalPntB_B * this->sunVisibilityFactor.illuminationFactor;
     } else {
         bskLogger.bskLog(BSK_ERROR,"Requested SRF Model not implemented.\n");
     }

src/simulation/environment/albedo/albedo.cpp

@@ -55,7 +55,7 @@ Albedo::Albedo()
     this->nHat_B_default = { 1.0, 0.0, 0.0 };
     this->fov_default = 90. * D2R;
     this->eclipseCase = false;
-    this->shadowFactorAtdA = 1.0;
+    this->illuminationFactorAtdA = 1.0;
     this->altitudeRateLimit = -1.0;
     return;
 }
@@ -527,7 +527,7 @@ void Albedo::computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload plan
     this->rHat_PI_N = -r_IP_N / r_IP_N.norm();        //! - [-] direction vector from instrument to planet (inertial)
     auto r_SI_N = r_SP_N - r_IP_N;                    //! - [m] sun's position wrt instrument (inertial)
     //! - Calculate the authalic radius, if the polar radius available
-    double t[3], t_aut[3], e, RA_planet, shadowFactorAtdA;
+    double t[3], t_aut[3], e, RA_planet, illuminationFactorAtdA;
     if (this->RP_planets.at(idx) > 0.0) {
         e = sqrt(1 - pow(this->RP_planets.at(idx), 2) / pow(this->REQ_planets.at(idx), 2));
         t[0] = pow(this->REQ_planets.at(idx), 2) * 0.5;
@@ -595,9 +595,9 @@ void Albedo::computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload plan
                 //! - Detect the sunlit region of the planet seen by the instrument
                 if (f1 > 0 && f2 > 0) {
                     //! - Sunlit portion of the planet seen by the instrument's position (max)
-                    //! - Shadow factor at dA (optional)
-                    shadowFactorAtdA = this->shadowFactorAtdA;
-                    if (this->eclipseCase) { shadowFactorAtdA = computeEclipseAtdA(RA_planet, r_dAP_N, r_SP_N); }
+                    //! - illumination factor at dA (optional)
+                    illuminationFactorAtdA = this->illuminationFactorAtdA;
+                    if (this->eclipseCase) { illuminationFactorAtdA = computeEclipseAtdA(RA_planet, r_dAP_N, r_SP_N); }
                     //! - Area of the incremental area
                     dArea = (fabs(lon1 - lon2) * fabs(sin(lat1) - sin(lat2)) * pow(r_dAP_N.norm(), 2));
                     //! - Maximum albedo flux ratio at instrument's position [-]
@@ -609,7 +609,7 @@ void Albedo::computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload plan
                     else {
                         tempmax = this->ALB[idx][ilat][ilon] * tempmax;
                     }
-                    alb_Imax = alb_Imax + tempmax * shadowFactorAtdA;
+                    alb_Imax = alb_Imax + tempmax * illuminationFactorAtdA;
 
                     if (f3 >= cos(fov)) {
                         //! - Sunlit portion of the planet seen by the instrument (fov)
@@ -621,7 +621,7 @@ void Albedo::computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload plan
                         else {
                             tempfov = this->ALB[idx][ilat][ilon] * tempfov;
                         }
-                        alb_I = alb_I + tempfov * shadowFactorAtdA;
+                        alb_I = alb_I + tempfov * illuminationFactorAtdA;
                         albLon1.push_back(this->gdlon[idx][ilon] * 180 / M_PI);
                         albLat1.push_back(this->gdlat[idx][ilat] * 180 / M_PI);
                         IIdx++;
@@ -659,8 +659,8 @@ void Albedo::computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload plan
  */
 double Albedo::computeEclipseAtdA(double Rplanet, Eigen::Vector3d r_dAP_N, Eigen::Vector3d r_SP_N)
 {
-    //! - Compute the shadow factor at incremental area
-    //! - Note that the eclipse module computes the shadow factor at the spacecraft position
+    //! - Compute the illumination factor at incremental area
+    //! - Note that the eclipse module computes the illumination factor at the spacecraft position
     auto r_SdA_N = r_SP_N - r_dAP_N; //! - [m] position vector from dA to Sun (inertial)
     auto s = r_dAP_N.norm();
     auto f_1 = safeAsin((REQ_SUN * 1000 + Rplanet) / r_SP_N.norm());
@@ -672,7 +672,7 @@ double Albedo::computeEclipseAtdA(double Rplanet, Eigen::Vector3d r_dAP_N, Eigen
     auto l_1 = c_1 * tan(f_1);
     auto l_2 = c_2 * tan(f_2);
     double area = 0.0;
-    double shadowFactorAtdA = 1.0; //! - Initialise the value for no eclipse
+    double illuminationFactorAtdA = 1.0; //! - Initialise the value for no eclipse
     double a = safeAsin(REQ_SUN * 1000 / r_SdA_N.norm());   //! - Apparent radius of sun
     double b = safeAsin(Rplanet / r_dAP_N.norm()); //! - Apparent radius of occulting body
     double c = safeAcos((-r_dAP_N.dot(r_SdA_N)) / (r_dAP_N.norm() * r_SdA_N.norm()));
@@ -682,26 +682,26 @@ double Albedo::computeEclipseAtdA(double Rplanet, Eigen::Vector3d r_dAP_N, Eigen
         // In particular (c < a + b) must check last to avoid testing
         // with implausible a, b and c values
         if (c < b - a) { // total eclipse, implying a < b
-            shadowFactorAtdA = 0.0;
+            illuminationFactorAtdA = 0.0;
         }
         else if (c < a - b) { // partial maximum eclipse, implying a > b
             double areaSun = M_PI * a * a;
             double areaBody = M_PI * b * b;
             area = areaSun - areaBody;
-            shadowFactorAtdA = 1 - area / (M_PI * a * a);
+            illuminationFactorAtdA = 1 - area / (M_PI * a * a);
         }
         else if (c < a + b) { // partial eclipse
             double x = (c * c + a * a - b * b) / (2 * c);
             double y = sqrt(a * a - x * x);
             area = a * a * safeAcos(x / a) + b * b * safeAcos((c - x) / b) - c * y;
-            shadowFactorAtdA = 1 - area / (M_PI * a * a);
+            illuminationFactorAtdA = 1 - area / (M_PI * a * a);
         }
     }
-    if (shadowFactorAtdA < 0.0) {
-        shadowFactorAtdA = 0.0;
+    if (illuminationFactorAtdA < 0.0) {
+        illuminationFactorAtdA = 0.0;
     }
-    else if (shadowFactorAtdA > 1.0) {
-        shadowFactorAtdA = 1.0;
+    else if (illuminationFactorAtdA > 1.0) {
+        illuminationFactorAtdA = 1.0;
     }
-    return shadowFactorAtdA;
+    return illuminationFactorAtdA;
 }

src/simulation/environment/albedo/albedo.h

@@ -76,21 +76,21 @@ class Albedo : public SysModel {
     void getPlanetRadius(std::string planetSpiceName);        //!< gets the planet's radius
     void evaluateAlbedoModel(int idx);                        //!< evaluates the ALB model
     void computeAlbedo(int idx, int instIdx, SpicePlanetStateMsgPayload planetMsg, bool AlbArray, double outData[]); //!< computes the albedo at instrument's location
-    double computeEclipseAtdA(double Rplanet, Eigen::Vector3d r_dAP_N, Eigen::Vector3d r_SP_N); //!< computes the shadow factor at dA
+    double computeEclipseAtdA(double Rplanet, Eigen::Vector3d r_dAP_N, Eigen::Vector3d r_SP_N); //!< computes the illumination factor at dA
 
 public:
     std::vector<Message<AlbedoMsgPayload>*> albOutMsgs;         //!< vector of output messages for albedo data
     ReadFunctor<SpicePlanetStateMsgPayload> sunPositionInMsg;   //!< input message name for sun data
     ReadFunctor<SCStatesMsgPayload> spacecraftStateInMsg;   //!< input message name for spacecraft data
     std::vector<ReadFunctor<SpicePlanetStateMsgPayload>> planetInMsgs; //!< vector of planet data input data
 
-    BSKLogger bskLogger;                        //!< BSK Logging    
+    BSKLogger bskLogger;                        //!< BSK Logging
     int defaultNumLat;                                 //!< [-] default number of latitude grid points
     int defaultNumLon;                                 //!< [-] default number of longitude grid points
     Eigen::Vector3d nHat_B_default;             //!< [-] default value for unit normal of the instrument (spacecraft body)
     double fov_default;                         //!< [rad] default value for instrument's field of view half angle
     bool eclipseCase;                           //!< consider eclipse at dA, if true
-    double shadowFactorAtdA;                    //!< [-] shadow factor at incremental area
+    double illuminationFactorAtdA;                    //!< [-] illumination factor at incremental area
     double altitudeRateLimit;                   //!< [-] rate limit of the instrument's altitude to the planet's radius for albedo calculations
 
 private:

src/simulation/environment/albedo/albedo.rst

@@ -126,9 +126,9 @@ conditions.
 The Mars' albedo data is obtained from `TES instrument <http://www.mars.asu.edu/data/tes_albedo/>`__ as VICAR format
 and converted to .csv format for consistency with 1x1, 5x5, and 10x10 degree resolutions.
 
-``shadowFactorAtdA`` is optional to be calculated with eclipseCase being True or can be assigned
+``illuminationFactorAtdA`` is optional to be calculated with eclipseCase being True or can be assigned
 directly by the user with eclipseCase False. It is used as a multiplication term in Eq. :eq:`eq:albedo:10`, if defined.
-Therefore, when using albedo output on an instrument, it should be used after the shadow factor multiplication of the
+Therefore, when using albedo output on an instrument, it should be used after the illumination factor multiplication of the
 instrument, if exists.
 
 A limit can be set in order not to compute the albedo for planets too far by :math:`altitudeRateLimit` which is the
@@ -202,3 +202,8 @@ The model can  be added to a task like other simModels.
 .. code-block:: python
 
       unitTestSim.AddModelToTask(simTaskName, albModule)
+
+.. 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.