Merge pull request #81

Add Wifi 802.11 physical simulation

Author: BastienTr

README.md

@@ -37,6 +37,9 @@ Available Features
 - Binary Symmetric Channel (BSC)
 - Binary AWGN Channel (BAWGNC)
 
+[Wifi 802.11 Simulation Class](https://github.com/veeresht/CommPy/blob/master/commpy/wifi80211.py)
+- A class to simulate the transmissions and receiving parameters of physical layer 802.11 (currently till VHT (ac))
+
 [Filters](https://github.com/veeresht/CommPy/blob/master/commpy/filters.py)
 -------
 - Rectangular

THANKS.txt

@@ -2,6 +2,7 @@ Please add names as needed so that we can keep up with all the contributors.
 
 Veeresh Taranalli for initial creation and contribution of CommPy.
 Bastien Trotobas for adding some features, bugfixes, maintenance.
+Eduardo Soares (@eSoares) for several enhancements including WiFi 802.11 class and code speedups.
 Vladimir Fadeev for bugfixes, addition of convolutional code puncturing and readme explanation of codings.
 Youness Akourim for adding features and fixing some bugs.
 Rey Tucker for python3 compatibility fixes.

commpy/channelcoding/convcode.py

@@ -747,7 +747,8 @@ def viterbi_decode(coded_bits, trellis, tb_depth=None, decoding_type='hard'):
 
     return decoded_bits[:L]
 
-def puncturing(message, punct_vec):
+
+def puncturing(message: np.ndarray, punct_vec: np.ndarray) -> np.ndarray:
     """
     Applying of the punctured procedure.
     Parameters
@@ -771,7 +772,8 @@ def puncturing(message, punct_vec):
             shift = shift + 1
     return np.array(punctured)
 
-def depuncturing(punctured, punct_vec, shouldbe):
+
+def depuncturing(punctured: np.ndarray, punct_vec: np.ndarray, shouldbe: int) -> np.ndarray:
     """
     Applying of the inserting zeros procedure.
     Parameters
@@ -797,5 +799,5 @@ def depuncturing(punctured, punct_vec, shouldbe):
         else:
             shift2 = shift2 + 1
         if idx%N == 0:
-            shift = shift + 1;
+            shift = shift + 1
     return depunctured

commpy/examples/wifi80211_conv_encode_decode.py

@@ -0,0 +1,34 @@
+# Authors: CommPy contributors
+# License: BSD 3-Clause
+
+import math
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import commpy.channels as chan
+# ==================================================================================================
+# Complete example using Commpy Wifi 802.11 physical parameters
+# ==================================================================================================
+from commpy.wifi80211 import Wifi80211
+
+# AWGN channel
+channels = chan.SISOFlatChannel(None, (1 + 0j, 0j))
+
+w2 = Wifi80211(mcs=2)
+w3 = Wifi80211(mcs=3)
+
+# SNR range to test
+SNRs2 = np.arange(0, 6) + 10 * math.log10(w2.get_modem().num_bits_symbol)
+SNRs3 = np.arange(0, 6) + 10 * math.log10(w3.get_modem().num_bits_symbol)
+
+BERs_mcs2 = w2.link_performance(channels, SNRs2, 10, 10, 600, stop_on_surpass_error=False)
+BERs_mcs3 = w3.link_performance(channels, SNRs3, 10, 10, 600, stop_on_surpass_error=False)
+
+# Test
+plt.semilogy(SNRs2, BERs_mcs2, 'o-', SNRs3, BERs_mcs3, 'o-')
+plt.grid()
+plt.xlabel('Signal to Noise Ration (dB)')
+plt.ylabel('Bit Error Rate')
+plt.legend(('MCS 2', 'MCS 3'))
+plt.show()

commpy/links.py

@@ -58,7 +58,8 @@ def link_performance(link_model, SNRs, send_max, err_min, send_chunk=None, code_
     BERs : 1d ndarray
            Estimated Bit Error Ratio corresponding to each SNRs
     """
-
+    if not send_chunk:
+        send_chunk = err_min
     return link_model.link_performance(SNRs, send_max, err_min, send_chunk, code_rate)
 
 
@@ -133,7 +134,7 @@ class LinkModel:
         *Default* is 1.
     """
 
-    def __init__(self, modulate, channel, receive, num_bits_symbol, constellation, Es=1, decoder=None, rate=1):
+    def __init__(self, modulate, channel, receive, num_bits_symbol, constellation, Es=1, decoder=None, rate=1.):
         self.modulate = modulate
         self.channel = channel
         self.receive = receive
@@ -146,8 +147,10 @@ def __init__(self, modulate, channel, receive, num_bits_symbol, constellation, E
             self.decoder = lambda msg: msg
         else:
             self.decoder = decoder
+        self.full_simulation_results = None
 
-    def link_performance(self, SNRs, send_max, err_min, send_chunk=None, code_rate=1):
+    def link_performance_full_metrics(self, SNRs, tx_max, err_min, send_chunk=None, code_rate: float = 1.,
+                                      number_chunks_per_send=1, stop_on_surpass_error=True):
         """
         Estimate the BER performance of a link model with Monte Carlo simulation.
 
@@ -157,8 +160,8 @@ def link_performance(self, SNRs, send_max, err_min, send_chunk=None, code_rate=1
                Signal to Noise ratio in dB defined as :math:`SNR_{dB} = (E_b/N_0)_{dB} + 10 \log_{10}(R_cM_c)`
                where :math:`Rc` is the code rate and :math:`Mc` the modulation rate.
 
-        send_max : int
-                   Maximum number of bits send for each SNR.
+        tx_max : int
+                 Maximum number of transmissions for each SNR.
 
         err_min : int
                   link_performance send bits until it reach err_min errors (see also send_max).
@@ -172,6 +175,110 @@ def link_performance(self, SNRs, send_max, err_min, send_chunk=None, code_rate=1
                     Rate of the used code.
                     *Default*: 1 i.e. no code.
 
+        number_chunks_per_send : int
+                                 Number of chunks per transmission
+
+        stop_on_surpass_error : bool
+                                Controls if during simulation of a SNR it should break and move to the next SNR when
+                                the bit error is above the err_min parameter
+
+        Returns
+        -------
+        List[BERs, BEs, CEs, NCs]
+           BERs : 1d ndarray
+                  Estimated Bit Error Ratio corresponding to each SNRs
+           BEs : 2d ndarray
+                 Number of Estimated Bits with Error per transmission corresponding to each SNRs
+           CEs : 2d ndarray
+                 Number of Estimated Chunks with Errors per transmission corresponding to each SNRs
+           NCs : 2d ndarray
+                 Number of Chunks transmitted per transmission corresponding to each SNRs
+        """
+
+        # Initialization
+        BERs = np.zeros_like(SNRs, dtype=float)
+        BEs = np.zeros((len(SNRs), tx_max), dtype=int)  # Bit errors per tx
+        CEs = np.zeros((len(SNRs), tx_max), dtype=int)  # Chunk Errors per tx
+        NCs = np.zeros((len(SNRs), tx_max), dtype=int)  # Number of Chunks per tx
+        # Set chunk size and round it to be a multiple of num_bits_symbol*nb_tx to avoid padding
+        if send_chunk is None:
+            send_chunk = err_min
+        divider = self.num_bits_symbol * self.channel.nb_tx
+        send_chunk = max(divider, send_chunk // divider * divider)
+
+        receive_size = self.channel.nb_tx * self.num_bits_symbol
+        full_args_decoder = len(getfullargspec(self.decoder).args) > 1
+
+        # Computations
+        for id_SNR in range(len(SNRs)):
+            self.channel.set_SNR_dB(SNRs[id_SNR], code_rate, self.Es)
+            total_tx_send = 0
+            bit_err = np.zeros(tx_max, dtype=int)
+            chunk_loss = np.zeros(tx_max, dtype=int)
+            chunk_count = np.zeros(tx_max, dtype=int)
+            for id_tx in range(tx_max):
+                if stop_on_surpass_error and bit_err.sum() > err_min:
+                    break
+                # Propagate some bits
+                msg = np.random.choice((0, 1), send_chunk * number_chunks_per_send)
+                symbs = self.modulate(msg)
+                channel_output = self.channel.propagate(symbs)
+
+                # Deals with MIMO channel
+                if isinstance(self.channel, MIMOFlatChannel):
+                    nb_symb_vector = len(channel_output)
+                    received_msg = np.empty(int(math.ceil(len(msg) / self.rate)), dtype=np.int8)
+                    for i in range(nb_symb_vector):
+                        received_msg[receive_size * i:receive_size * (i + 1)] = \
+                            self.receive(channel_output[i], self.channel.channel_gains[i],
+                                         self.constellation, self.channel.noise_std ** 2)
+                else:
+                    received_msg = self.receive(channel_output, self.channel.channel_gains,
+                                                self.constellation, self.channel.noise_std ** 2)
+                # Count errors
+                if full_args_decoder:
+                    decoded_bits = self.decoder(channel_output, self.channel.channel_gains,
+                                                self.constellation, self.channel.noise_std ** 2,
+                                                received_msg, self.channel.nb_tx * self.num_bits_symbol)
+                else:
+                    decoded_bits = self.decoder(received_msg)
+                # calculate number of error frames
+                for i in range(number_chunks_per_send):
+                    errors = np.bitwise_xor(msg[send_chunk * i:send_chunk * (i + 1)],
+                                            decoded_bits[send_chunk * i:send_chunk * (i + 1)]).sum()
+                    bit_err[id_tx] += errors
+                    chunk_loss[id_tx] += 1 if errors > 0 else 0
+
+                chunk_count[id_tx] += number_chunks_per_send
+                total_tx_send += 1
+            BERs[id_SNR] = bit_err.sum() / (total_tx_send * send_chunk)
+            BEs[id_SNR] = bit_err
+            CEs[id_SNR] = np.where(bit_err > 0, 1, 0)
+            NCs[id_SNR] = chunk_count
+            if BEs[id_SNR].sum() < err_min:
+                break
+        self.full_simulation_results = BERs, BEs, CEs, NCs
+        return BERs, BEs, CEs, NCs
+
+    def link_performance(self, SNRs, send_max, err_min, send_chunk=None, code_rate=1):
+        """
+        Estimate the BER performance of a link model with Monte Carlo simulation.
+        Parameters
+        ----------
+        SNRs : 1D arraylike
+               Signal to Noise ratio in dB defined as :math:`SNR_{dB} = (E_b/N_0)_{dB} + 10 \log_{10}(R_cM_c)`
+               where :math:`Rc` is the code rate and :math:`Mc` the modulation rate.
+        send_max : int
+                   Maximum number of bits send for each SNR.
+        err_min : int
+                  link_performance send bits until it reach err_min errors (see also send_max).
+        send_chunk : int
+                      Number of bits to be send at each iteration. This is also the frame length of the decoder if available
+                      so it should be large enough regarding the code type.
+                      *Default*: send_chunck = err_min
+        code_rate : float in (0,1]
+                    Rate of the used code.
+                    *Default*: 1 i.e. no code.
         Returns
         -------
         BERs : 1d ndarray

commpy/tests/test_links.py

@@ -23,13 +23,17 @@ def test_link_performance():
 
     def receiver(y, h, constellation, noise_var):
         return QPSK.demodulate(y, 'hard')
+
     model = LinkModel(QPSK.modulate, SISOFlatChannel(fading_param=(1 + 0j, 0)), receiver,
                       QPSK.num_bits_symbol, QPSK.constellation, QPSK.Es)
 
     BERs = link_performance(model, range(0, 9, 2), 600e4, 600)
-    desired = erfc(sqrt(10**(arange(0, 9, 2) / 10) / 2)) / 2
+    desired = erfc(sqrt(10 ** (arange(0, 9, 2) / 10) / 2)) / 2
     assert_allclose(BERs, desired, rtol=0.25,
                     err_msg='Wrong performance for SISO QPSK and AWGN channel')
+    full_metrics = model.link_performance_full_metrics(range(0, 9, 2), 1000, 600)
+    assert_allclose(full_metrics[0], desired, rtol=0.25,
+                    err_msg='Wrong performance for SISO QPSK and AWGN channel')
 
     # Apply link_performance to MIMO 16QAM and 4x4 Rayleigh channel
     QAM16 = QAMModem(16)
@@ -38,6 +42,7 @@ def receiver(y, h, constellation, noise_var):
 
     def receiver(y, h, constellation, noise_var):
         return QAM16.demodulate(kbest(y, h, constellation, 16), 'hard')
+
     model = LinkModel(QAM16.modulate, RayleighChannel, receiver,
                       QAM16.num_bits_symbol, QAM16.constellation, QAM16.Es)
     SNRs = arange(0, 21, 5) + 10 * log10(QAM16.num_bits_symbol)
@@ -46,6 +51,9 @@ def receiver(y, h, constellation, noise_var):
     desired = (2e-1, 1e-1, 3e-2, 2e-3, 4e-5)  # From reference
     assert_allclose(BERs, desired, rtol=1.25,
                     err_msg='Wrong performance for MIMO 16QAM and 4x4 Rayleigh channel')
+    full_metrics = model.link_performance_full_metrics(SNRs, 1000, 600)
+    assert_allclose(full_metrics[0], desired, rtol=1.25,
+                    err_msg='Wrong performance for MIMO 16QAM and 4x4 Rayleigh channel')
 
 
 if __name__ == "__main__":

commpy/tests/test_wifi80211.py

@@ -0,0 +1,47 @@
+# Authors: CommPy contributors
+# License: BSD 3-Clause
+
+from __future__ import division  # Python 2 compatibility
+
+from numpy import arange, log10
+from numpy.random import seed
+from numpy.testing import run_module_suite, dec, assert_allclose
+
+from commpy.channels import MIMOFlatChannel, SISOFlatChannel
+from commpy.modulation import kbest
+from commpy.wifi80211 import Wifi80211
+
+
+@dec.slow
+def test_wifi80211_siso_channel():
+    seed(17121996)
+    wifi80211 = Wifi80211(1)
+    BERs = wifi80211.link_performance(SISOFlatChannel(fading_param=(1 + 0j, 0)), range(0, 9, 2), 10 ** 4, 600)[0]
+    desired = (0.489, 0.503, 0.446, 0.31, 0.015)  # From previous tests
+    # for i, val in enumerate(desired):
+    #     print((BERs[i] - val) / val)
+    assert_allclose(BERs, desired, rtol=0.3,
+                    err_msg='Wrong performance for SISO QPSK and AWGN channel')
+
+
+@dec.slow
+def test_wifi80211_mimo_channel():
+    seed(17121996)
+    # Apply link_performance to MIMO 16QAM and 4x4 Rayleigh channel
+    wifi80211 = Wifi80211(3)
+    RayleighChannel = MIMOFlatChannel(4, 4)
+    RayleighChannel.uncorr_rayleigh_fading(complex)
+    modem = wifi80211.get_modem()
+
+    def receiver(y, h, constellation, noise_var):
+        return modem.demodulate(kbest(y, h, constellation, 16), 'hard')
+
+    BERs = wifi80211.link_performance(RayleighChannel, arange(0, 21, 5) + 10 * log10(modem.num_bits_symbol), 10 ** 4,
+                                      600, receiver=receiver)[0]
+    desired = (0.535, 0.508, 0.521, 0.554, 0.475)  # From previous test
+    assert_allclose(BERs, desired, rtol=1.25,
+                    err_msg='Wrong performance for MIMO 16QAM and 4x4 Rayleigh channel')
+
+
+if __name__ == "__main__":
+    run_module_suite()