[#1387] Fix linkBudget antenna LOS frame transform

Author: dhutererprats

docs/source/Support/bskKnownIssues.rst

@@ -27,6 +27,9 @@ Version |release|
   for Basilisk and compatible plugins. If source builds fail with SWIG 4.4.0 or emit
   ``builtin type swigvarlink has no __module__ attribute`` warnings, upgrade to SWIG 4.4.1 or a newer
   supported 4.x release.
+- BSK-1387: :ref:`linkBudget` could compute excessive pointing loss for non-identity antenna attitudes
+  because the inertial line-of-sight vector was transformed using the antenna-to-inertial DCM. This is
+  fixed in the current version.
 
 
 Version 2.10.0 (April 2, 2026)

docs/source/Support/bskReleaseNotesSnippets/1387-linkBudget-antenna-sigma-frame.rst

@@ -0,0 +1 @@
+- Fixed :ref:`linkBudget` pointing-loss frame handling so ``AntennaLogMsgPayload.sigma_AN`` antenna orientations are interpreted consistently with :ref:`simpleAntenna`.

src/simulation/communication/linkBudget/_UnitTest/test_linkBudget.py

@@ -1220,6 +1220,51 @@ def test_linkBudget_pointing_loss():
     assert testFailCount == 0, "\n".join(testMessages)
 
 
+def test_linkBudget_pointing_loss_nontrivial_attitude_zero_error():
+    """
+    Verify that a perfectly pointed, non-identity antenna attitude produces
+    negligible pointing loss.
+
+    This catches frame-convention regressions where the inertial LOS vector is
+    transformed with the antenna-to-inertial DCM instead of its transpose.
+    """
+    frequency_Hz = 2.2e9  # [Hz]
+    directivity_dB = 20.0  # [dB]
+    k = 1.0  # [-]
+    pointing_loss_tolerance = 1e-10  # [dB]
+
+    pos1 = [0.0, 0.0, 0.0]  # [m]
+    pos2 = [1000e3, 400e3, 700e3]  # [m]
+
+    ant1_payload, _ = create_antenna_msg_payload(
+        name="Ant1",
+        state=ANTENNA_TX,
+        frequency=frequency_Hz,
+        directivity_dB=directivity_dB,
+        k=k,
+        position=pos1,
+        target_position=pos2,
+    )
+    ant2_payload, _ = create_antenna_msg_payload(
+        name="Ant2",
+        state=ANTENNA_RX,
+        frequency=frequency_Hz,
+        directivity_dB=directivity_dB,
+        k=k,
+        position=pos2,
+        target_position=pos1,
+    )
+
+    unitTestSim, linkBudgetModule, _ = setup_link_budget_sim(ant1_payload, ant2_payload)
+    run_simulation(unitTestSim)
+
+    L_point_sim = linkBudgetModule.getL_point()
+    assert abs(L_point_sim) < pointing_loss_tolerance, (
+        "Perfectly aligned non-identity antenna attitudes should have near-zero "
+        f"pointing loss, got {L_point_sim:.6e} dB"
+    )
+
+
 def test_linkBudget_no_bandwidth_overlap():
     """
     Test behavior when antennas have no overlapping bandwidth.

src/simulation/communication/linkBudget/linkBudget.cpp

@@ -283,8 +283,8 @@ Eigen::Vector2d LinkBudget::getPointingError(Eigen::Vector3d r_A1N_N, Eigen::Vec
         bskLogger.bskLog(BSK_WARNING, "LinkBudget.getPointingError: antenna positions are coincident; returning zero pointing errors.");
         return {0.0, 0.0};
     }
-    // Calculate the unit vector from antenna 1 to antenna 2
-    Eigen::Vector3d n_A2A1_A1 = dcm_NA1 * (r_A2A1_N / deltaNorm);
+    // Calculate the unit vector from antenna 1 to antenna 2, decomposed in antenna 1 frame
+    Eigen::Vector3d n_A2A1_A1 = dcm_NA1.transpose() * (r_A2A1_N / deltaNorm);
     // boresight vector of antenna 1 in {A1} frame
     double boresightComponent = n_A2A1_A1[2];
     double azimuthError       = std::atan2(n_A2A1_A1[0], boresightComponent);  // [rad] Azimuth pointing error

src/simulation/communication/linkBudget/linkBudget.h

@@ -187,7 +187,7 @@ class LinkBudget:  public SysModel {
     double calcCosSlantGround(Eigen::Vector3d r_AN_N, Eigen::Vector3d n_A_N, Eigen::Vector3d r_BN_N);
     void generateLookupTable(LinkBudgetTypes::GasType gasType, LookupTable* lookupTable);
     void precomputeAtmosphericAttenuationAtLayers(AttenuationLookupTable* tableAttenuation, double frequency);
-    Eigen::Vector2d getPointingError(Eigen::Vector3d r_A1N_N, Eigen::Vector3d r_A2N_N, Eigen::MRPd sigma_NA1);
+    Eigen::Vector2d getPointingError(Eigen::Vector3d r_A1N_N, Eigen::Vector3d r_A2N_N, Eigen::MRPd sigma_AN1);
     void calculatePointingLoss();
     void calculateFrequencyOffsetLoss();
     void calculateCNR();

src/simulation/communication/linkBudget/linkBudget.rst

@@ -134,7 +134,7 @@ Pointing Loss
 
    Figure 3: Illustration of pointing loss due to antenna misalignment (pointing error angle in elevation, :math:`\| \theta_\mathrm{el} \| > 0^\circ`)
 
-The pointing error loss accounts for signal degradation when the antennas are not perfectly aligned. This loss is computed assuming a Gaussian antenna radiation pattern (consistent with the :ref:`simpleAntenna` module).
+The pointing error loss accounts for signal degradation when the antennas are not perfectly aligned. This loss is computed assuming a Gaussian antenna radiation pattern (consistent with the :ref:`simpleAntenna` module). The antenna orientation is read from ``AntennaLogMsgPayload.sigma_AN`` and the inertial line-of-sight vector is decomposed in the antenna frame, where the antenna boresight is the local +Z axis.
 
 For each antenna, the pointing error is decomposed into azimuth and elevation components relative to the antenna boresight direction\: