[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status - GitHub](https://github.com/YairMZ/LDPC/actions/workflows/python-app.yml/badge.svg)](https://github.com/YairMZ/LDPC/actions/workflows/python-app.yml/badge.svg)
[![codecov](https://codecov.io/gh/YairMZ/LDPC/branch/main/graph/badge.svg?token=2RR3afDfeD)](https://codecov.io/gh/YairMZ/LDPC)
[![Sourcery](https://img.shields.io/badge/Sourcery-enabled-brightgreen)](https://sourcery.ai)
# LDPC
My implementation of LDPC codes.
My notes regarding theory and implementation appears on GitHub Pages: https://yairmz.github.io/LDPC/
To install:
```shell
pip install sim-ldpc
```
To run tests simply clone, cd into the cloned repo, and run:
```shell
python -m pytest
```
or
```shell
python -m pytest --cov-report=html
```
to run also coverage tests, or
```shell
python -m pytest -n auto --cov-report=html
```
to run tests in parallel (with number of CPU's dictated by machine) to speed up tests.
Verify static typing with
```shell
mypy --strict --config-file .mypy.ini .
```
-----
## Included modules
- [Utilities](ldpc/utils/README.md): implementing various utility operations to assist with encoding, decoding and
simulations.
- [Encoder](ldpc/encoder/README.md): implementing a generator based encoder, and encoders for IEEE802.11 (WiFi) LDPC codes.
- [Decoder](ldpc/decoder/README.md): implementing several decoders
- Log-SPA based BP decoder
- MS decodcer
- Gallager bit filpping decoder
- Weighted bit flipping decoders, several variants
- Parallel probabilistic bit flipping decoder (PPBF)
-----
## Basic Example
```python
import numpy as np
from bitstring import BitArray, Bits
from ldpc.decoder import DecoderWiFi, bsc_llr
from ldpc.encoder import EncoderWiFi
from ldpc.wifi_spec_codes import WiFiSpecCode
from ldpc.utils import QCFile
# create information bearing bits
rng = np.random.default_rng()
info_bits = np.array(Bits(bytes=rng.bytes(41))[:648//2], dtype=np.int_)
# create encoder with frame of 648 bits, and rate 1/2. Possible rates and frame sizes are per the ieee802.11n spec.
enc = EncoderWiFi(WiFiSpecCode.N648_R12)
# encode bits
encoded = enc.encode(info_bits)
# verify validity of codeword
h = enc.h
np.dot(h, np.array(encoded)) % 2 # creates an all zero vector as required.
# create a decoder which assumes a probability of p=0.05 for bit flips by the channel
# allow up to 20 iterations for the bp decoder.
p = 0.05
decoder = DecoderWiFi(spec=WiFiSpecCode.N648_R12, max_iter=20, channel_model=bsc_llr(p=p))
# create a corrupted version of encoded codeword with error rate p
corrupted = BitArray(encoded)
no_errors = int(len(corrupted)*p)
error_idx = rng.choice(len(corrupted), size=no_errors, replace=False)
for idx in error_idx:
corrupted[idx] = not corrupted[idx]
decoded, llr, decode_success, num_of_iterations, syndrome, vnode_validity = decoder.decode(corrupted)
# Verify correct decoding
print(Bits(decoded) == Bits(encoded)) # true
info = decoder.info_bits(decoded)
# a decoder can also be instantiated without a channel model, in which case llr is expected to be sent for decoding instead of
# hard channel outputs.
channel = bsc_llr(p=p)
channel_llr = channel(np.array(corrupted, dtype=np.int_))
decoder = DecoderWiFi(spec=WiFiSpecCode.N648_R12, max_iter=20)
decoded, llr2, decode_success, num_of_iterations, syndrome, vnode_validity = decoder.decode(channel_llr)
print(Bits(decoded) == Bits(encoded)) # true
info = decoder.info_bits(decoded)
```
The example is also included as a jupyter notebook. Note however, that you need to launch the notebook from the correct
path for it to be able to access installed packages. To run the notebook:
1. create a new virtualenv
```shell
python3 -m venv ~/.virtualenv/LDPC_env
```
2. activate it and install `sim-ldpc`, and `notebook`:
```shell
source ~/.virtualenv/LDPC_env/bin/activate
pip install sim-ldpc
pip install notebook
```
3. run jupyter from within the virtual env for it to have access to all requirements:
```shell
~/.virtualenv/LDPC_env/bin/jupyter-notebook
```
5. run the notebook
__________
## Sources
- Cai Z., Hao J., Tan P.H., Sun S., Chin P.S., Efficient encoding of IEEE 802.11n LDPC codes. Electronics Letters 25,
1471--1472 (2006).
- IEEE802.11 encoder tested against the implementation in https://github.com/tavildar/LDPC
- [Channel codes : classical and modern](https://www.cambridge.org/il/academic/subjects/engineering/communications-and-signal-processing/channel-codes-classical-and-modern)
by William E. Ryan, 2009.
Raw data
{
"_id": null,
"home_page": "https://github.com/YairMZ/LDPC",
"name": "sim-ldpc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "LDPC,Belief Propagation,SPA,Tanner Graph,IEEE 802.11",
"author": "Yair Mazal",
"author_email": "yairmazal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/55/76/9ecd17f85274d5673bf44cc4ad47f3da59c3a8af8887fd5edfdaabfc98a2/sim-ldpc-0.3.5.tar.gz",
"platform": null,
"description": "[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status - GitHub](https://github.com/YairMZ/LDPC/actions/workflows/python-app.yml/badge.svg)](https://github.com/YairMZ/LDPC/actions/workflows/python-app.yml/badge.svg)\n[![codecov](https://codecov.io/gh/YairMZ/LDPC/branch/main/graph/badge.svg?token=2RR3afDfeD)](https://codecov.io/gh/YairMZ/LDPC)\n[![Sourcery](https://img.shields.io/badge/Sourcery-enabled-brightgreen)](https://sourcery.ai)\n# LDPC\nMy implementation of LDPC codes.\nMy notes regarding theory and implementation appears on GitHub Pages: https://yairmz.github.io/LDPC/ \nTo install:\n```shell\npip install sim-ldpc\n```\nTo run tests simply clone, cd into the cloned repo, and run:\n```shell\npython -m pytest\n```\nor\n```shell\npython -m pytest --cov-report=html\n```\nto run also coverage tests, or\n```shell\npython -m pytest -n auto --cov-report=html\n```\nto run tests in parallel (with number of CPU's dictated by machine) to speed up tests.\n\nVerify static typing with\n```shell\nmypy --strict --config-file .mypy.ini .\n```\n\n-----\n## Included modules\n - [Utilities](ldpc/utils/README.md): implementing various utility operations to assist with encoding, decoding and \nsimulations.\n - [Encoder](ldpc/encoder/README.md): implementing a generator based encoder, and encoders for IEEE802.11 (WiFi) LDPC codes.\n - [Decoder](ldpc/decoder/README.md): implementing several decoders\n - Log-SPA based BP decoder\n - MS decodcer\n - Gallager bit filpping decoder\n - Weighted bit flipping decoders, several variants\n - Parallel probabilistic bit flipping decoder (PPBF)\n-----\n\n## Basic Example\n```python\nimport numpy as np\nfrom bitstring import BitArray, Bits\nfrom ldpc.decoder import DecoderWiFi, bsc_llr\nfrom ldpc.encoder import EncoderWiFi\nfrom ldpc.wifi_spec_codes import WiFiSpecCode\nfrom ldpc.utils import QCFile\n\n# create information bearing bits\nrng = np.random.default_rng()\ninfo_bits = np.array(Bits(bytes=rng.bytes(41))[:648//2], dtype=np.int_)\n# create encoder with frame of 648 bits, and rate 1/2. Possible rates and frame sizes are per the ieee802.11n spec.\nenc = EncoderWiFi(WiFiSpecCode.N648_R12)\n# encode bits\nencoded = enc.encode(info_bits)\n\n# verify validity of codeword\nh = enc.h\nnp.dot(h, np.array(encoded)) % 2 # creates an all zero vector as required.\n\n# create a decoder which assumes a probability of p=0.05 for bit flips by the channel\n# allow up to 20 iterations for the bp decoder.\np = 0.05\ndecoder = DecoderWiFi(spec=WiFiSpecCode.N648_R12, max_iter=20, channel_model=bsc_llr(p=p))\n\n# create a corrupted version of encoded codeword with error rate p\ncorrupted = BitArray(encoded)\nno_errors = int(len(corrupted)*p)\nerror_idx = rng.choice(len(corrupted), size=no_errors, replace=False)\nfor idx in error_idx:\n corrupted[idx] = not corrupted[idx]\ndecoded, llr, decode_success, num_of_iterations, syndrome, vnode_validity = decoder.decode(corrupted)\n# Verify correct decoding\nprint(Bits(decoded) == Bits(encoded)) # true\ninfo = decoder.info_bits(decoded)\n\n# a decoder can also be instantiated without a channel model, in which case llr is expected to be sent for decoding instead of\n# hard channel outputs.\nchannel = bsc_llr(p=p)\nchannel_llr = channel(np.array(corrupted, dtype=np.int_))\ndecoder = DecoderWiFi(spec=WiFiSpecCode.N648_R12, max_iter=20)\ndecoded, llr2, decode_success, num_of_iterations, syndrome, vnode_validity = decoder.decode(channel_llr)\nprint(Bits(decoded) == Bits(encoded)) # true\ninfo = decoder.info_bits(decoded)\n```\nThe example is also included as a jupyter notebook. Note however, that you need to launch the notebook from the correct \npath for it to be able to access installed packages. To run the notebook:\n1. create a new virtualenv\n```shell\npython3 -m venv ~/.virtualenv/LDPC_env\n```\n2. activate it and install `sim-ldpc`, and `notebook`:\n```shell\nsource ~/.virtualenv/LDPC_env/bin/activate\npip install sim-ldpc\npip install notebook\n```\n3. run jupyter from within the virtual env for it to have access to all requirements:\n```shell\n~/.virtualenv/LDPC_env/bin/jupyter-notebook\n```\n5. run the notebook\n__________\n## Sources\n - Cai Z., Hao J., Tan P.H., Sun S., Chin P.S., Efficient encoding of IEEE 802.11n LDPC codes. Electronics Letters 25, \n1471--1472 (2006).\n - IEEE802.11 encoder tested against the implementation in https://github.com/tavildar/LDPC\n - [Channel codes : classical and modern](https://www.cambridge.org/il/academic/subjects/engineering/communications-and-signal-processing/channel-codes-classical-and-modern)\nby William E. Ryan, 2009.\n \n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simulate LDPC codes, both encoding and decoding",
"version": "0.3.5",
"project_urls": {
"Homepage": "https://github.com/YairMZ/LDPC"
},
"split_keywords": [
"ldpc",
"belief propagation",
"spa",
"tanner graph",
"ieee 802.11"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2fd172fcb034b0c268ac70da221b82d10933d9a9fb08ec33189592e215e2878c",
"md5": "64783e7e74c8250da376ee85dfeb7fc7",
"sha256": "4748cf93674d4ffc080bae71ee40cfa3721cf4cba742b38cb68d1bbab2704af0"
},
"downloads": -1,
"filename": "sim_ldpc-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64783e7e74c8250da376ee85dfeb7fc7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 2260047,
"upload_time": "2023-06-29T16:29:38",
"upload_time_iso_8601": "2023-06-29T16:29:38.661355Z",
"url": "https://files.pythonhosted.org/packages/2f/d1/72fcb034b0c268ac70da221b82d10933d9a9fb08ec33189592e215e2878c/sim_ldpc-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55769ecd17f85274d5673bf44cc4ad47f3da59c3a8af8887fd5edfdaabfc98a2",
"md5": "bd291412ed3eea2c63acfd801a941882",
"sha256": "1fbe2fb6ec3fedd696f78c962ef1be4305d3d4e7e4fa040a31cd1bc6284f87db"
},
"downloads": -1,
"filename": "sim-ldpc-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "bd291412ed3eea2c63acfd801a941882",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2120491,
"upload_time": "2023-06-29T16:29:41",
"upload_time_iso_8601": "2023-06-29T16:29:41.738128Z",
"url": "https://files.pythonhosted.org/packages/55/76/9ecd17f85274d5673bf44cc4ad47f3da59c3a8af8887fd5edfdaabfc98a2/sim-ldpc-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-29 16:29:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "YairMZ",
"github_project": "LDPC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "bitstring",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "networkx",
"specs": [
[
"~=",
"2.6.3"
]
]
},
{
"name": "numba",
"specs": []
}
],
"lcname": "sim-ldpc"
}