Update docs

Author: grigory

Changelog.md

@@ -1,14 +1,4 @@
-## 0.2.1
-
-Fix issues with decoding tree of `FastSSCDecoder` and `GeneralizedFastSSCDecoder`
-
-## 0.2.0
-
-Add implementation of [Generalized Fast SSC Decoding](https://arxiv.org/pdf/1804.09508.pdf).
-
-## 0.1.1
-
-Improve the structure of Fast SSC polar code
+# Changelog
 
 ## 0.1.0
 

README.md

@@ -1,29 +1,80 @@
 # Python-polar-coding
-A package for modelling Polar codes.
+
+A package for Polar codes simulation.
 
 ## Installation
 
-`pip install git+git://github.com/fr0mhell/python-polar-coding.git#egg=python_polar_coding`
+```bash
+pip install git+git://github.com/fr0mhell/python-polar-coding.git#egg=python_polar_coding
+```
+
+## Example
+
+Here is a simple example of simulation using `python_polar_coding`.
+
+Binary messages encoded with Polar code, modulated using BPSK, transmitted over
+channel with AWGN and decoded using [Fast SSC](https://arxiv.org/abs/1307.7154) algorithm.
+
+```python
+from python_polar_coding.channels import SimpleBPSKModulationAWGN
+from python_polar_coding.polar_codes import FastSSCPolarCodec
+from python_polar_coding.simulation.functions import (
+    compute_fails,
+    generate_binary_message,
+)
+
+N = 128
+K = 64
+design_snr = 2.0
+messages = 10000
+# SNR in [.0, .5, ..., 4.5, 5]
+snr_range = [i / 2 for i in range(11)]
+
+codec = FastSSCPolarCodec(N=N, K=K, design_snr=design_snr)
+bpsk = SimpleBPSKModulationAWGN(fec_rate=K/N)
+
+result_ber = dict()
+result_fer = dict()
+
+for snr in snr_range:
+    ber = 0
+    fer = 0
+
+    for _ in range(messages):
+        msg = generate_binary_message(size=K)
+        encoded = codec.encode(msg)
+        transmitted = bpsk.transmit(message=msg, snr_db=snr)
+        decoded = codec.decode(transmitted)
+
+        bit_errors, frame_error = compute_fails(msg, decoded)
+        ber += bit_errors
+        fer += frame_error
+
+    result_ber[snr] = ber
+    result_fer[snr] = fer
+```
 
 ## Current progress
 
-**Polar code construction:**
+### Polar code construction
+
+- [x] Arikan's Bhattacharyya bounds [Section V.A](https://arxiv.org/pdf/1501.02473.pdf)
+
+### Decoding
+- [x] SC Decoding
+- [x] [SC LIST Decoding](https://arxiv.org/abs/1206.0050)
+- [x] [Fast SSC Decoding](https://arxiv.org/abs/1307.7154)
+- [x] [RC SCAN Decoding]()
+- [x] [Generalized Fast SSC Decoding](https://arxiv.org/pdf/1804.09508.pdf)
+
+### Modulation
+
+- [x] BPSK
 
-- [x] Arikan's Bhattacharyya bounds [Section V.A](https://arxiv.org/pdf/1501.02473.pdf);
-- [ ] Arikan’s Monte-Carlo estimation [Section V.B](https://arxiv.org/pdf/1501.02473.pdf);
-- [ ] Trifonov’s Gaussian approximation [Section V.D](https://arxiv.org/pdf/1501.02473.pdf);
+## TODO
 
-**Decoding:**
-- [x] SC Decoding;
-- [x] [SC LIST Decoding](https://arxiv.org/abs/1206.0050);
-- [ ] [SC STACK Decoding](https://ieeexplore.ieee.org/document/6215306/?denied=);
-- [x] [Fast SSC Decoding](https://arxiv.org/abs/1307.7154);
-- [x] [RC SCAN Decoding]();
-- [x] [Generalized Fast SSC Decoding](https://arxiv.org/pdf/1804.09508.pdf);
-- [ ] [Generalized Fast SSC LIST Decoding](https://arxiv.org/pdf/1804.09508.pdf);
+[TODO List](TODO.md)
 
-**Modulation:**
+## License
 
-- [x] BPSK;
-- [ ] M-PSK;
-- [ ] M-QAM;
+[MIT License](LICENSE.MD)

TODO.md

@@ -0,0 +1,21 @@
+# TODO List
+
+### Polar code construction
+
+- [ ] Arikan’s Monte-Carlo estimation [Section V.B](https://arxiv.org/pdf/1501.02473.pdf)
+- [ ] Trifonov’s Gaussian approximation [Section V.D](https://arxiv.org/pdf/1501.02473.pdf)
+
+### Decoding
+- [ ] [SC STACK Decoding](https://ieeexplore.ieee.org/document/6215306)
+- [ ] [Fast SSC List Decoding](https://arxiv.org/pdf/1703.08208.pdf)
+- [ ] [Generalized Fast SSC LIST Decoding](https://arxiv.org/pdf/1804.09508.pdf)
+
+### Modulation
+
+- [ ] Q-PSK
+- [ ] 4-QAM
+
+### General
+
+- [ ] Add tests for CRC
+- [ ] Fix CRC-aided SC List decoder

examples/simple_simulation.py

@@ -1,12 +1,12 @@
 from datetime import datetime
 
 from python_polar_coding.channels.simple import SimpleBPSKModulationAWGN
-from python_polar_coding.polar_codes.fast_ssc import FastSSCPolarCode
+from python_polar_coding.polar_codes import FastSSCPolarCodec
 from python_polar_coding.simulation import simulation_task
 
 
 def fast_ssc_simulation():
-    code = FastSSCPolarCode(N=4096, K=1024, design_snr=2.0)
+    code = FastSSCPolarCodec(N=4096, K=1024, design_snr=2.0)
     channel = SimpleBPSKModulationAWGN(fec_rate=code.K/code.N)
     snr_range = [1.0, 1.5, 2.0, 2.5, 3.0]
 

python_polar_coding/channels/__init__.py

@@ -1 +1 @@
-from .simple import SimpleAWGNChannel
+from .simple import SimpleAWGNChannel, SimpleBPSKModulationAWGN

python_polar_coding/polar_codes/__init__.py

@@ -0,0 +1,5 @@
+from .fast_ssc import FastSSCPolarCodec
+from .g_fast_ssc import GeneralizedFastSSCPolarCodec
+from .rc_scan import RCSCANPolarCodec
+from .sc import SCPolarCodec
+from .sc_list import SCListPolarCodec

python_polar_coding/polar_codes/crc.py

@@ -36,6 +36,8 @@ def _compute_crc(self, message: np.array) -> int:
     def check_crc(self, message: np.array) -> bool:
         """Check if message has errors or not using CRC."""
         received_crc = int(
-            ''.join([str(m) for m in message[-self.crc_size::]]), 2)
+            ''.join([str(m) for m in message[-self.crc_size::]]),
+            2
+        )
         check_crc = self._compute_crc(message[:-self.crc_size])
         return received_crc == check_crc

python_polar_coding/simulation/simulation.py

@@ -5,9 +5,9 @@
 from ..channels import SimpleAWGNChannel
 from ..modems import SimpleBPSKModem
 from ..polar_codes import (
-    FastSSCPolarCode,
-    GeneralizedFastSSCPolarCode,
-    RCSCANPolarCode,
+    FastSSCPolarCodec,
+    GeneralizedFastSSCPolarCodec,
+    RCSCANPolarCodec,
 )
 from . import functions, http
 
@@ -25,9 +25,9 @@ class ChannelTypes:
 
 
 CODE_MAP = {
-    CodeTypes.FAST_SSC: FastSSCPolarCode,
-    CodeTypes.RC_SCAN: RCSCANPolarCode,
-    CodeTypes.G_FAST_SSC: GeneralizedFastSSCPolarCode,
+    CodeTypes.FAST_SSC: FastSSCPolarCodec,
+    CodeTypes.RC_SCAN: RCSCANPolarCodec,
+    CodeTypes.G_FAST_SSC: GeneralizedFastSSCPolarCodec,
 }
 
 

setup.py

@@ -12,7 +12,7 @@
 
 setuptools.setup(
     name='python-polar-coding',
-    version='0.2.1',
+    version='0.1.0',
     author='Grigory Timofeev',
     author_email='[email protected]',
     description='Polar coding implementation in Python',