spectrum: Refine 3GPP channel consistency procedure, tests, and documentation

This commit refines the 3GPP TR 38.901 channel consistency implementation
(Procedure A, Sec. 7.6.3.2) to better align with the specification and to
clarify behavior across different scenarios (including mobility).

The changes include:

Correct handling of cluster-level correlation terms (e.g., shadowing) and
cached per-link randomness needed for cluster generation (incl. NLOS Xn signs)

Updates to ray/cluster evolution during channel updates and removal of random
coupling between update steps

Clear distinction between channel re-generation vs cached-channel update
behavior, controlled by UpdatePeriod

Consistent displacement computation across code and correct TX/RX speed mapping

Fix channel-consistency triggering for moving endpoints and handle NLOSv cases

Enforce canonical ordering for link direction, make updates order-independent,
and tighten assertions

Ensure per-cluster state vectors are consistently sized to the reduced cluster
number, with consistent trim/add logic across generation and update paths.

Add test, example and plot script for spatial consistency feature.

Add documentation for spatial consistency feature (spectrum.rst,
CHANGES.md, RELEASE_NOTES.md) clarifying that TR 38.901 Sec. 7.6.3.1 correlation
across multiple initial locations is not implemented.

Extend/fix test cases for realistic channel updates and improve robustness of
the 3GPP channel tests.

Refactoring and cleanup of ThreeGppChannelModel and related examples/test; run/update
relevant example coverage (incl. V2V)

Clarify Procedure A vs map/field-based approaches.

Address comments by Tom Henderson, Tommaso Pecorella, Peter Barnes and Eduardo Almeida.

Co-authored-by: Sandra Lagen sandra.lagen@cttc.cat

Author: biljkus

CHANGES.md

@@ -52,6 +52,17 @@ fixes, use `./ns3 run "clang-tidy -fix"`.
 
 * (wifi) `CcaEdThreshold` can be changed at run-time.
 * (internet): Updated `TcpLedbat::CongestionAvoidance()` to compute `max_cwnd` as `flightsize + AllowedIncrease × MSS` by adding `m_allowedIncrease * tcb->m_segmentSize`, in accordance with RFC 6817.
+* (spectrum): Added a spatial-consistency update technique aligned with 3GPP TR 38.901 Procedure A
+  (Sec. 7.6.3.2) to the 3GPP channel model. When the `UpdatePeriod` attribute of `ThreeGppChannelModel`
+  is set to a non-zero value, the model evolves channel parameters using Procedure A update equations
+  to preserve correlation across consecutive channel evaluations, with ns-3-specific update triggering
+  suited to discrete-event simulation. In prior ns-3 releases (before ns-3.47), `UpdatePeriod` caused
+  independent (i.i.d.) re-generation of channel realizations. With the updated behavior, an update is
+  attempted when the channel is evaluated and `UpdatePeriod` has elapsed since the last parameter
+  generation/update. If the maximum endpoint displacement between evaluations is within 1 m,
+  Procedure A updates are applied; if it exceeds 1 m, channel parameters are re-generated (new realization).
+  For stationary links, the channel remains unchanged. See `spectrum.rst` for ns-3 update triggering and
+  1 m step-size handling.
 
 ## Changes from ns-3.46 to ns-3.46.1
 

RELEASE_NOTES.md

@@ -45,6 +45,14 @@ been tested on Linux. As of this release, the latest known version to work with
 - (internet) !2405 Added support for TCP FACK (Forward Acknowledgement).
 - (lr-wpan) !2592 Added PHY preamble and RSSI support.
 - (visualizer) Add Lr-Wpan NetDevices support to the Pyviz visualizer.
+- (spectrum) The ns-3 3GPP channel model supports a spatial-consistency update technique
+  aligned with TR 38.901 Procedure A (Sec. 7.6.3.2), enabled via the `UpdatePeriod`
+  attribute of `ThreeGppChannelModel` (see `spectrum.rst` for ns-3 update triggering and
+  1 m step-size handling). Default per-cluster shadowing correlation distances are
+  provided for terrestrial cellular scenarios (UMa/UMi/RMa/Indoor). For V2V and NTN,
+  the corresponding 3GPP reports do not provide standardized per-cluster correlation
+  distances; users should configure appropriate values in the parameter tables (the
+  default is 1 m, yielding weak correlation unless adjusted).
 
 ### Bugs fixed
 

examples/channel-models/examples-to-run.py

@@ -8,6 +8,11 @@
 # See test.py for more information.
 cpp_examples = [
     ("three-gpp-v2v-channel-example", "True", "True"),
+    (
+        "three-gpp-v2v-channel-example --updatePeriodMs=1",
+        "True",
+        "True",
+    ),
 ]
 
 # A list of Python examples to run in order to ensure that they remain

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

@@ -6,20 +6,21 @@
  */
 
 /*
- * This is an example on how to configure the channel model classes to simulate
+ * @file
+ * This is an example of how to configure the channel model classes to simulate
  * a vehicular environment.
  * The channel condition is determined using the model specified in [1], Table 6.2-1.
  * The pathloss is determined using the model specified in [1], Table 6.2.1-1.
  * The model for the fast fading is the one described in 3GPP TR 38.901 v15.0.0,
  * the model parameters are those specified in [1], Table 6.2.3-1.
  *
- * This example generates the output file 'example-output.txt'. Each row of the
- * file is organized as follows:
- * Time[s] TxPosX[m] TxPosY[m] RxPosX[m] RxPosY[m] ChannelState SNR[dB] Pathloss[dB]
- * We also provide a bash script which reads the output file and generates two
+ * This example generates the output file 'three-gpp-v2v-channel-example-output.txt'. Each row of
+ * the file is organized as follows: Time[s] TxPosX[m] TxPosY[m] RxPosX[m] RxPosY[m] ChannelState
+ * SNR[dB] Pathloss[dB] We also provide a bash script which reads the output file and generates two
  * figures:
- * (i) map.gif, a GIF representing the simulation scenario and vehicle mobility;
- * (ii) snr.png, which represents the behavior of the SNR.
+ * (i) three-gpp-v2v-channel-example-map.gif, a GIF representing the simulation scenario and vehicle
+ * mobility;
+ * (ii) three-gpp-v2v-channel-example-snr.png, which represents the behavior of the SNR.
  *
  * [1] 3GPP TR 37.885, v15.3.0
  */
@@ -64,45 +65,34 @@ struct ComputeSnrParams
 
 /**
  * Perform the beamforming using the DFT beamforming method
- * @param thisDevice the device performing the beamforming
+ * @param txMob the mobility model of the node performing the beamforming
  * @param thisAntenna the antenna object associated to thisDevice
- * @param otherDevice the device towards which point the beam
+ * @param rxMob the mobility model of the node towards which will point the beam
  */
 static void
-DoBeamforming(Ptr<NetDevice> thisDevice,
-              Ptr<PhasedArrayModel> thisAntenna,
-              Ptr<NetDevice> otherDevice)
+DoBeamforming(Ptr<MobilityModel> txMob, Ptr<PhasedArrayModel> thisAntenna, Ptr<MobilityModel> rxMob)
 {
-    PhasedArrayModel::ComplexVector antennaWeights;
-
-    // retrieve the position of the two devices
-    Vector aPos = thisDevice->GetNode()->GetObject<MobilityModel>()->GetPosition();
-    Vector bPos = otherDevice->GetNode()->GetObject<MobilityModel>()->GetPosition();
-
     // compute the azimuth and the elevation angles
-    Angles completeAngle(bPos, aPos);
-
+    Angles completeAngle(rxMob->GetPosition(), txMob->GetPosition());
     PhasedArrayModel::ComplexVector bf = thisAntenna->GetBeamformingVector(completeAngle);
     thisAntenna->SetBeamformingVector(bf);
 }
 
 /**
  * Compute the average SNR
- * @param params A structure that holds a bunch of parameters needed by ComputSnr function to
+ * @param params A structure that holds a bunch of parameters needed by ComputeSnr function to
  * calculate the average SNR
  */
 static void
 ComputeSnr(const ComputeSnrParams& params)
 {
     // check the channel condition
     Ptr<ChannelCondition> cond = m_condModel->GetChannelCondition(params.txMob, params.rxMob);
-
     // apply the pathloss
     double propagationGainDb = m_propagationLossModel->CalcRxPower(0, params.txMob, params.rxMob);
     NS_LOG_DEBUG("Pathloss " << -propagationGainDb << " dB");
     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,
@@ -120,13 +110,11 @@ ComputeSnr(const ComputeSnrParams& params)
     double noisePowerSpectralDensity = kT_W_Hz * noiseFigureLinear;
     Ptr<SpectrumValue> noisePsd = Create<SpectrumValue>(params.txParams->psd->GetSpectrumModel());
     (*noisePsd) = noisePowerSpectralDensity;
-
-    // compute the SNR
+    // log the average SNR
     NS_LOG_DEBUG("Average SNR " << 10 * log10(Sum(*rxPsd) / Sum(*noisePsd)) << " dB");
-
-    // print the SNR and pathloss values in the snr-trace.txt file
+    // print the SNR and pathloss values in the three-gpp-v2v-channel-example-output.txt file
     std::ofstream f;
-    f.open("example-output.txt", std::ios::out | std::ios::app);
+    f.open("three-gpp-v2v-channel-example-output.txt", std::ios::out | std::ios::app);
     f << Simulator::Now().GetSeconds() << " " // time [s]
       << params.txMob->GetPosition().x << " " << params.txMob->GetPosition().y << " "
       << params.rxMob->GetPosition().x << " " << params.rxMob->GetPosition().y << " "
@@ -170,28 +158,20 @@ main(int argc, char* argv[])
     double vScatt = 0;                  // maximum speed of the vehicles in the scenario [m/s]
     double subCarrierSpacing = 60e3;    // subcarrier spacing in kHz
     uint32_t numRb = 275;               // number of resource blocks
+    uint32_t updatePeriodMs = 0;
 
     CommandLine cmd(__FILE__);
     cmd.AddValue("frequency", "operating frequency in Hz", frequency);
     cmd.AddValue("txPow", "tx power in dBm", txPow_dbm);
     cmd.AddValue("noiseFigure", "noise figure in dB", noiseFigure);
     cmd.AddValue("scenario", "3GPP propagation scenario, V2V-Urban or V2V-Highway", scenario);
+    cmd.AddValue("updatePeriodMs", "the channel update period", updatePeriodMs);
     cmd.Parse(argc, argv);
 
     // create the nodes
     NodeContainer nodes;
     nodes.Create(2);
 
-    // create the tx and rx devices
-    Ptr<SimpleNetDevice> txDev = CreateObject<SimpleNetDevice>();
-    Ptr<SimpleNetDevice> rxDev = CreateObject<SimpleNetDevice>();
-
-    // associate the nodes and the devices
-    nodes.Get(0)->AddDevice(txDev);
-    txDev->SetNode(nodes.Get(0));
-    nodes.Get(1)->AddDevice(rxDev);
-    rxDev->SetNode(nodes.Get(1));
-
     // create the antenna objects and set their dimensions
     Ptr<PhasedArrayModel> txAntenna =
         CreateObjectWithAttributes<UniformPlanarArray>("NumColumns",
@@ -321,6 +301,7 @@ main(int argc, char* argv[])
     channelModel->SetAttribute("Frequency", DoubleValue(frequency));
     channelModel->SetAttribute("ChannelConditionModel", PointerValue(m_condModel));
     channelModel->SetAttribute("vScatt", DoubleValue(vScatt));
+    channelModel->SetAttribute("UpdatePeriod", TimeValue(MilliSeconds(updatePeriodMs)));
 
     // create the spectrum propagation loss model
     m_spectrumLossModel = CreateObjectWithAttributes<ThreeGppSpectrumPropagationLossModel>(
@@ -330,8 +311,8 @@ main(int argc, char* argv[])
     BuildingsHelper::Install(nodes);
 
     // set the beamforming vectors
-    DoBeamforming(txDev, txAntenna, rxDev);
-    DoBeamforming(rxDev, rxAntenna, txDev);
+    DoBeamforming(txMob, txAntenna, rxMob);
+    DoBeamforming(rxMob, rxAntenna, txMob);
 
     // create the tx power spectral density
     Bands rbs;
@@ -340,17 +321,17 @@ main(int argc, char* argv[])
     {
         BandInfo rb;
         rb.fl = freqSubBand;
-        freqSubBand += subCarrierSpacing / 2;
+        freqSubBand += (subCarrierSpacing * 12) / 2;
         rb.fc = freqSubBand;
-        freqSubBand += subCarrierSpacing / 2;
+        freqSubBand += (subCarrierSpacing * 12) / 2;
         rb.fh = freqSubBand;
         rbs.push_back(rb);
     }
     Ptr<SpectrumModel> spectrumModel = Create<SpectrumModel>(rbs);
     Ptr<SpectrumValue> txPsd = Create<SpectrumValue>(spectrumModel);
     Ptr<SpectrumSignalParameters> txParams = Create<SpectrumSignalParameters>();
     double txPow_w = std::pow(10., (txPow_dbm - 30) / 10);
-    double txPowDens = (txPow_w / (numRb * subCarrierSpacing));
+    double txPowDens = (txPow_w / (numRb * subCarrierSpacing * 12));
     (*txPsd) = txPowDens;
     txParams->psd = txPsd->Copy();
 
@@ -362,13 +343,13 @@ main(int argc, char* argv[])
 
     // initialize the output file
     std::ofstream f;
-    f.open("example-output.txt", std::ios::out);
+    f.open("three-gpp-v2v-channel-example-output.txt", std::ios::out);
     f << "Time[s] TxPosX[m] TxPosY[m] RxPosX[m] RxPosY[m] ChannelState SNR[dB] Pathloss[dB]"
       << std::endl;
     f.close();
 
     // print the list of buildings to file
-    PrintGnuplottableBuildingListToFile("buildings.txt");
+    PrintGnuplottableBuildingListToFile("three-gpp-v2v-channel-example-buildings.txt");
 
     Simulator::Run();
     Simulator::Destroy();

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

@@ -15,7 +15,7 @@
 import pandas as pd
 
 # Load the data
-df = pd.read_csv("example-output.txt", sep=r"\s+", comment="#")
+df = pd.read_csv("three-gpp-v2v-channel-example-output.txt", sep=r"\s+", comment="#")
 df = df.iloc[::10, :]
 
 # Column indices (adjust if needed)
@@ -48,7 +48,9 @@
 ax_snr.grid(True)
 (snr_line,) = ax_snr.plot([], [], "k-")
 
-buildings = pd.read_csv("buildings.txt", sep=r"\s+", comment="#", header=None)
+buildings = pd.read_csv(
+    "three-gpp-v2v-channel-example-buildings.txt", sep=r"\s+", comment="#", header=None
+)
 building_patches = []
 for idx, row in buildings.iterrows():
     x0, y0, x1, y1 = row
@@ -73,7 +75,7 @@ def update(frame):
 ani = animation.FuncAnimation(fig, update, frames=len(df), interval=0.001, blit=False)
 
 # Save animation
-ani.save("map.gif", writer="pillow")
+ani.save("three-gpp-v2v-channel-example-map.gif", writer="pillow")
 
 # Save final SNR plot separately
 plt.figure()
@@ -83,4 +85,4 @@ def update(frame):
 plt.grid(True)
 plt.xlim(0, 40)
 plt.ylim(-20, 100)
-plt.savefig("snr.png")
+plt.savefig("three-gpp-v2v-channel-example-snr.png")