Testing documentation for SINR calculation in downlink/uplink and Adaptive Modulation and Coding tests

doc/manual/source/lte-testing.rst

@@ -21,7 +21,7 @@ You can get a more detailed report in HTML format in this way::
 
     ./test.py -w results.html
 
-After the above command has run, you can view the detailed result for each test by opebning the file ``results.html`` with a web browser.
+After the above command has run, you can view the detailed result for each test by opening the file ``results.html`` with a web browser.
 
 
 
@@ -35,9 +35,41 @@ Unit Tests
 SINR calculation in the Downlink
 --------------------------------
 
-SINR calculation in the uplink
+This unit test program checks that the SINR calculation in downlink is performed correctly. The SINR in the downlink is calculated for each Resource Block assigned to data transmissions by dividing the power of the intended signal from the considered eNB by the sum of the noise power plus all the transmissions on the same RB coming from other eNBs (the interference signals).
+
+.. math::
+
+  \mathrm{SINR} = \frac{ P_\mathrm{signal} }{ P_\mathrm{noise} + \sum P_\mathrm{interference} }
+
+The unit test program includes two test cases with random transmited signals and random interference signals. The signals are active during different periods of time. A chunk of time is a period of time during which :math:`n` signals are active (:math:`T_i`). A different SINR is calculated (:math:`\mathrm{SINR_i}`) for each chunk. The expected :math:`\mathrm{SINR}` is
+
+.. math::
+
+  {\mathrm{SINR}}_{total} = \frac{ \displaystyle\sum_{\forall\mathrm{chunks}} {\mathrm{SINR}}_i * T_i }{ T_{total} }
+
+The test vectors are obtained by an Octave script that applies the described algorithm. The unit test program checks that the SINR calculation in downlink is performed correctly in the :cpp:class:`ns3::LtePhy` interface. It implements this interface in the :cpp:class:`ns3::LteTestUePhy` test class.
+
+
+
+
+SINR calculation in the Uplink
 ------------------------------
 
+This unit test program checks that the SINR calculation in uplink is performed correctly. The SINR in the uplink is calculated for each Resource Block assigned to data transmissions by dividing the power of the intended signal from the considered UE by the sum of the noise power plus all the transmissions on the same RB coming from other UEs (the interference signals).
+
+.. math::
+
+  \mathrm{SINR} = \frac{ P_\mathrm{signal} }{ P_\mathrm{noise} + \sum P_\mathrm{interference} }
+
+The unit test program includes two test cases with random transmited signals and random interference signals. The signals are active during different periods of time. A chunk of time is a period of time during which :math:`n` signals are active (:math:`T_i`). A different SINR is calculated (:math:`\mathrm{SINR_i}`) for each chunk. The expected :math:`\mathrm{SINR}` is
+
+.. math::
+
+  {\mathrm{SINR}}_{total} = \frac{ \displaystyle\sum_{\forall\mathrm{chunks}} {\mathrm{SINR}}_i * T_i }{ T_{total} }
+
+The test vectors are obtained by an Octave script that applies the described algorithm. The unit test program checks that the SINR calculation in uplink is performed correctly in the :cpp:class:`ns3::LtePhy` interface. It implements this interface in the :cpp:class:`ns3::LteTestUePhy` test class.
+
+
 
 System Tests
 ~~~~~~~~~~~~
@@ -45,6 +77,28 @@ System Tests
 Adaptive Modulation and Coding
 ------------------------------
 
+This system test is run consisting of a single eNB and a single UE, with different test cases corresponding to different SINR values perceived by the UE; the test checks that in each test case the chosen MCS corresponds to the values in a known test vector.
+
+The test vector is obtained with the model described in [Piro2011]_ which cites [Seo2004]_. Here we described how this model works. We get the spectral efficiency :math:`\eta_i` for each value of the SNR in dB using Shannon's theorem:
+
+.. math::
+
+  \mathrm{BER} = 0.00005
+
+.. math::
+
+  \Gamma = \frac{ -\ln{ (5 * \mathrm{BER}) } }{ 1.5 }
+
+.. math::
+
+  \eta_i = \log_2 { \left( 1 + \frac{ {\mathrm{SINR}}_i }{ \Gamma } \right) }
+
+Then, 3GPP [R1-081483]_ document (its XLS sheet annexed file) is used to get the corresponding MCS scheme. The spectral efficiency is quantized based on the CQI (rounding to the lowest value) and is mapped to the corresponding MCS scheme (i.e. the MCS index that appears on the same line looking at the MCS table on the right). Note that the quantization of the CQI is coarser than the spectral efficiency reported in the CQI table.
+
+Finally, note that there are some discrepancies between the MCS index in [R1-081483]_ and that indicated by the standard: [TS36.213]_ Table 7.1.7.1-1 says that the MCS index goes from 0 to 31, and 0 appears to be a valid MCS scheme (TB size is not 0) but in [R1-081483]_ the first useful MCS index is 1. Hence to get the value as intended by the standard we need to subtract 1 from the index reported in [R1-081483]_.
+
+
+
 Round Robin scheduler performance
 ---------------------------------
 
@@ -75,7 +129,7 @@ In the first category of test cases, the UEs are all placed at the same distance
 
    T = \frac{S(M,B)}{\tau N}
 
-The second category of tests is aimed at verify the fairness behavior in presence of UEs with different SINRs (and therefore different estimated throughput from PFS). The test consists of checking whether the throughput obtained by each UE over the whole simulation matches with the steady-state throughput expected by the PF scheduler according to the theory (see for instance [Kushner2004cpfsa]_). 
+The second category of tests is aimed at verify the fairness behavior in presence of UEs with different SINRs (and therefore different estimated throughput from PFS). The test consists of checking whether the throughput obtained by each UE over the whole simulation matches with the steady-state throughput expected by the PF scheduler according to the theory (see for instance [Kushner2004]_).
 Let :math:`Ri` the estimation done by PFS of the throughput of the :math:`i` UE for the next TTI according to the CQIs received and :math:`Ti` the throughput preceived by the :math:`i` UE . The test verifies that the ratio of the obtained throughput value respect to the global one (i.e. the sum of the ones of all users) is equal to the steady-state throughput of the PFS, that is
 
 .. math::
@@ -89,4 +143,12 @@ References
 
 .. [TS36.213] 3GPP TS 36.213 "LTE Physical layer procedures"
 
-.. [Kushner2004cpfsa] H.J. Kushner and P.A. Whiting, "Convergence of proportional-fair sharing algorithms under general conditions", IEEE Trans. on Wireless Communications, July 2004 
+.. [Kushner2004] H.J. Kushner and P.A. Whiting, "Convergence of proportional-fair sharing algorithms under general conditions", IEEE Trans. on Wireless Communications, July 2004
+
+.. [Piro2011] G. Piro, N. Baldo. M. Miozzo, "An LTE module for the ns-3 network simulator", Wns3 2011
+              (in conjunction with SimuTOOLS 2011), March 2011, Barcelona (Spain)
+
+.. [Seo2004] H. Seo, B. G. Lee. "A proportional-fair power allocation scheme for fair and efficient multiuser
+             OFDM systems", In Proc. of IEEE GLOBECOM, December 2004. Dallas (USA)
+
+.. [R1-081483] 3GPP R1-081483 "Conveying MCS and TB size via PDCCH"