spectrum: Remove CalcRxPowerSpectralDensity() overload reading array state

Assisted-by: Claude Fable 5

Author: tomhenderson

CHANGES.md

@@ -41,6 +41,7 @@ This file is a best-effort approach to solving this issue; we will do our best b
 * (network) `Buffer::Deserialize`, `ByteTagList::Deserialize`, `PacketMetadata::Deserialize`, `PacketTagList::Deserialize` and `Packet::Deserialize` functions return now the number of deserialized bytes instead of just `1` for a successful deserialization.
 * (sixlowpan) The `SixLowPanNetDevice` attributes `MeshUnderJitter` and `MeshCacheLength` moved to the mesh-under forwarding policy: use `SixLowPanSimpleFlooding::MeshUnderJitter` and `SixLowPanMeshUnderRouting::MeshCacheLength`, reachable through the device's `MeshUnderRouting` attribute (e.g., `MeshUnderRouting/MeshUnderJitter` in a `Config` path). The old device attributes are deprecated and forward to the current policy.
 * (internet) the `Ipv4InterfaceAddress` functions related to the setup of a secondary address have been removed. This includes `SetPrimary`, `SetSecondary`, and `IsSecondary`. If users have a need for this feature in the future, please document the need by opening a Work Item on ns-3-dev tracker.
+* (spectrum) The `PhasedArraySpectrumPropagationLossModel::CalcRxPowerSpectralDensity()` now requires the beamforming vectors of the two phased arrays to be passed as parameters (pass the vectors in effect when the signal was transmitted and received, respectively); the variant that read them from the arrays was removed without deprecation.
 * (spectrum) The private virtual `PhasedArraySpectrumPropagationLossModel::DoCalcRxPowerSpectralDensity()` and, in `ThreeGppSpectrumPropagationLossModel`, `SionnaRtSpectrumPropagationLossModel` and `TwoRaySpectrumPropagationLossModel`, the protected `GetLongTerm()`, `CalcLongTerm()`, `CalculateLongTermComponent()` and `CalcBeamformingGain()` methods now require the beamforming vectors as parameters. Subclasses must update their overrides; no deprecation is provided.
 
 ### Changes to build system

examples/channel-models/three-gpp-v2v-channel-example.cc

@@ -94,11 +94,14 @@ ComputeSnr(const ComputeSnrParams& params)
     double propagationGainLinear = std::pow(10.0, (propagationGainDb) / 10.0);
     *(params.txParams->psd) *= propagationGainLinear;
     // apply the fast fading and the beamforming gain
-    auto rxParams = m_spectrumLossModel->CalcRxPowerSpectralDensity(params.txParams,
-                                                                    params.txMob,
-                                                                    params.rxMob,
-                                                                    params.txAntenna,
-                                                                    params.rxAntenna);
+    auto rxParams =
+        m_spectrumLossModel->CalcRxPowerSpectralDensity(params.txParams,
+                                                        params.txMob,
+                                                        params.rxMob,
+                                                        params.txAntenna,
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
     Ptr<SpectrumValue> rxPsd = rxParams->psd;
     NS_LOG_DEBUG("Average rx power " << 10 * log10(Sum(*rxPsd) * 180e3) << " dB");
 

src/spectrum/doc/spectrum.rst

@@ -771,13 +771,14 @@ received PSD and the frequency domain 3D spectrum channel matrix.
 Procedure used to compute the PSD of the received signal and the frequency domain 3D
 spectrum channel matrix:
 
-1. Retrieve the beamforming vectors
-To account for the beamforming, ``ThreeGppSpectrumPropagationLossModel`` has to
-retrieve the beamforming vectors of the transmitting and receiving antennas.
-The method ``DoCalcRxPowerSpectralDensity`` uses the antenna objects
-that are passed as parameters for both the transmitting and receiving devices,
-and calls the method GetBeamformingVector to retrieve the beamforming vectors
-of these antenna objects.
+1. Obtain the beamforming vectors
+To account for the beamforming, ``ThreeGppSpectrumPropagationLossModel`` needs
+the beamforming vectors of the transmitting and receiving antennas.
+The method ``DoCalcRxPowerSpectralDensity`` receives them as parameters,
+together with the antenna objects of both devices; it does not read the
+vectors from the antenna objects itself, so the caller decides which vectors
+apply (``MultiModelSpectrumChannel`` passes the transmitter's vector captured
+when the transmission started).
 
 2. Retrieve the channel matrix and the channel params
 The ``ThreeGppSpectrumPropagationLossModel`` relies on the ``ThreeGppChannelModel`` class

src/spectrum/examples/sionna-rt-channel-example.cc

@@ -197,11 +197,14 @@ ComputeSnr(const ComputeSnrParams& params)
     NS_ASSERT_MSG(params.rxAntenna, "params.rxAntenna is nullptr!");
 
     // apply the fast fading and the beamforming gain
-    auto rxParams = m_spectrumLossModel->CalcRxPowerSpectralDensity(txParams,
-                                                                    params.txMob,
-                                                                    params.rxMob,
-                                                                    params.txAntenna,
-                                                                    params.rxAntenna);
+    auto rxParams =
+        m_spectrumLossModel->CalcRxPowerSpectralDensity(txParams,
+                                                        params.txMob,
+                                                        params.rxMob,
+                                                        params.txAntenna,
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
     auto rxPsd = rxParams->psd;
     double rxPowDb = 10 * log10(Sum(*rxPsd) * 180e3);
     double snrDb = 10 * log10(Sum(*rxPsd) / Sum(*noisePsd));

src/spectrum/examples/three-gpp-channel-consistency-example.cc

@@ -166,11 +166,14 @@ ComputeSnr(const ComputeSnrParams& params)
     double propagationGainLinear = std::pow(10.0, (propagationGainDb) / 10.0);
     *(params.txParams->psd) *= propagationGainLinear;
     // apply the fast fading and the beamforming gain
-    auto rxParams = m_spectrumLossModel->CalcRxPowerSpectralDensity(params.txParams,
-                                                                    params.txMob,
-                                                                    params.rxMob,
-                                                                    params.txAntenna,
-                                                                    params.rxAntenna);
+    auto rxParams =
+        m_spectrumLossModel->CalcRxPowerSpectralDensity(params.txParams,
+                                                        params.txMob,
+                                                        params.rxMob,
+                                                        params.txAntenna,
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
     Ptr<SpectrumValue> rxPsd = rxParams->psd;
     // create the noise psd
     // taken from lte-spectrum-value-helper

src/spectrum/examples/three-gpp-channel-example.cc

@@ -265,11 +265,14 @@ ComputeSnr(const ComputeSnrParams& params)
     sign = +1.0;
     DoBeamforming(params.rxMob, params.rxAntenna, params.txMob, sign);
     // apply the fast fading and the beamforming gain
-    auto rxParams = m_spectrumLossModel->CalcRxPowerSpectralDensity(txParams,
-                                                                    params.txMob,
-                                                                    params.rxMob,
-                                                                    params.txAntenna,
-                                                                    params.rxAntenna);
+    auto rxParams =
+        m_spectrumLossModel->CalcRxPowerSpectralDensity(txParams,
+                                                        params.txMob,
+                                                        params.rxMob,
+                                                        params.txAntenna,
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
     auto rxPsdSteering = rxParams->psd;
     NS_LOG_DEBUG("Average rx power " << 10 * log10(Sum(*rxPsdSteering) * 180e3) << " dB");
     NS_LOG_DEBUG("Average SNR " << 10 * log10(Sum(*rxPsdSteering) / Sum(*noisePsd)) << " dB");
@@ -289,7 +292,9 @@ ComputeSnr(const ComputeSnrParams& params)
                                                         params.txMob,
                                                         params.rxMob,
                                                         params.txAntenna,
-                                                        params.rxAntenna);
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
 
     auto rxPsdMatchedFilterComb = rxParamsMatchedFilterComb->psd;
     NS_LOG_DEBUG("Average rx power when using matched filter combining "

src/spectrum/examples/three-gpp-ntn-channel-example.cc

@@ -267,11 +267,14 @@ ComputeSnr(ComputeSnrParams& params)
         ConstCast<AntennaModel, const AntennaModel>(params.txAntenna->GetAntennaElement());
 
     // apply the fast fading and the beamforming gain
-    rxSsp = m_spectrumLossModel->CalcRxPowerSpectralDensity(rxSsp,
-                                                            params.txMob,
-                                                            params.rxMob,
-                                                            params.txAntenna,
-                                                            params.rxAntenna);
+    rxSsp =
+        m_spectrumLossModel->CalcRxPowerSpectralDensity(rxSsp,
+                                                        params.txMob,
+                                                        params.rxMob,
+                                                        params.txAntenna,
+                                                        params.rxAntenna,
+                                                        params.txAntenna->GetBeamformingVector(),
+                                                        params.rxAntenna->GetBeamformingVector());
     NS_LOG_DEBUG("Average rx power " << 10 * log10(Sum(*rxSsp->psd) * params.bandwidth) << " dB");
 
     // compute the SNR

src/spectrum/model/phased-array-spectrum-propagation-loss-model.cc

@@ -55,23 +55,6 @@ PhasedArraySpectrumPropagationLossModel::GetNext() const
     return m_next;
 }
 
-Ptr<SpectrumSignalParameters>
-PhasedArraySpectrumPropagationLossModel::CalcRxPowerSpectralDensity(
-    Ptr<const SpectrumSignalParameters> params,
-    Ptr<const MobilityModel> a,
-    Ptr<const MobilityModel> b,
-    Ptr<const PhasedArrayModel> aPhasedArrayModel,
-    Ptr<const PhasedArrayModel> bPhasedArrayModel) const
-{
-    return CalcRxPowerSpectralDensity(params,
-                                      a,
-                                      b,
-                                      aPhasedArrayModel,
-                                      bPhasedArrayModel,
-                                      aPhasedArrayModel->GetBeamformingVector(),
-                                      bPhasedArrayModel->GetBeamformingVector());
-}
-
 Ptr<SpectrumSignalParameters>
 PhasedArraySpectrumPropagationLossModel::CalcRxPowerSpectralDensity(
     Ptr<const SpectrumSignalParameters> params,

src/spectrum/model/phased-array-spectrum-propagation-loss-model.h

@@ -57,28 +57,6 @@ class PhasedArraySpectrumPropagationLossModel : public Object
      */
     Ptr<PhasedArraySpectrumPropagationLossModel> GetNext() const;
 
-    /**
-     * Calculate the received PSD using the beamforming vectors currently set on the
-     * phased antenna arrays of the sender and of the receiver.
-     *
-     * @param txPsd the spectrum signal parameters.
-     * @param a sender mobility
-     * @param b receiver mobility
-     * @param aPhasedArrayModel the instance of the phased antenna array of the sender
-     * @param bPhasedArrayModel the instance of the phased antenna array of the receiver
-     *
-     * @return SpectrumSignalParameters in which is updated the PSD to contain
-     * a set of values Vs frequency representing the received
-     * power in the same units used for the txPower parameter,
-     * and additional chanSpectrumMatrix is computed to support MIMO systems.
-     */
-    Ptr<SpectrumSignalParameters> CalcRxPowerSpectralDensity(
-        Ptr<const SpectrumSignalParameters> txPsd,
-        Ptr<const MobilityModel> a,
-        Ptr<const MobilityModel> b,
-        Ptr<const PhasedArrayModel> aPhasedArrayModel,
-        Ptr<const PhasedArrayModel> bPhasedArrayModel) const;
-
     /**
      * Calculate the received PSD using the given beamforming vectors, which need not be
      * the ones currently set on the phased antenna arrays. The arrays provide the