Merge branch 'feature/improve-codec-structure'

Author: grigory

.isort.cfg

@@ -0,0 +1,5 @@
+[settings]
+line_length=79
+length_sort_stdlib=1
+multi_line_output=3
+include_trailing_comma=True

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/modelling/functions.py

@@ -1,6 +1,6 @@
-from datetime import datetime
 from math import ceil
 from random import shuffle
+from datetime import datetime
 
 import numpy as np
 from pymongo import MongoClient

examples/modelling/runner.py

@@ -1,10 +1,12 @@
 import multiprocessing
-from concurrent import futures
 from datetime import datetime
 from functools import partial
+from concurrent import futures
 
-from examples.modelling.functions import (generate_simulation_parameters,
-                                          simulation_task)
+from examples.modelling.functions import (
+    generate_simulation_parameters,
+    simulation_task,
+)
 from examples.modelling.mongo import DB_NAME
 from python_polar_coding.channels.simple import SimpleBPSKModulationAWGN
 

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

@@ -1,5 +1,5 @@
-from .fast_ssc import FastSSCPolarCode
-from .g_fast_ssc import GeneralizedFastSSCPolarCode
-from .rc_scan import RCSCANPolarCode
-from .sc import SCPolarCode
-from .sc_list import SCListPolarCode
+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/base/__init__.py

@@ -0,0 +1,4 @@
+from .codec import BaseCRCPolarCodec, BasePolarCodec
+from .decoder import BaseDecoder
+from .decoding_path import DecodingPathMixin
+from .functions import *