Metadata-Version: 2.4
Name: pyldpcpp
Version: 0.1.0
Summary: C++/Armadillo rewrite of pyldpc's make_ldpc, encode and decode functions
Author: dlex
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Dlex925/pyldpCpp
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: licenses/LICENSE.armadillo-Apache-2.0
License-File: licenses/LICENSE.pyldpc-BSD-3-Clause
Requires-Dist: numpy
Dynamic: license-file

# pyldpCpp

C++/Armadillo rewrite of the 3 main functions from the
[pyldpc](https://github.com/hichamjanati/pyldpc) library.

## Install

```
pip install pyldpcpp
```

## API

```python
make_ldpc(n_code, d_v, d_c, systematic=False, sparse=True, seed=None)  ->  (H, tG)
encode(tG, v, snr, seed=None)                                         ->  y
decode(H, y, snr, maxiter=1000)                                       ->  x
```

The signatures are identical to pyldpc's, so `import pyldpcpp as pyldpc` is enough to switch.

```python
import numpy as np
import pyldpcpp as pyldpc

H, tG = pyldpc.make_ldpc(600, 3, 6, systematic=True, sparse=True, seed=0)
v = np.arange(tG.shape[1]) % 2
y = pyldpc.encode(tG, v, snr=4)
x = pyldpc.decode(H, y, snr=4)
```

# Differences from pyldpc

The image/sound examples have been omitted, along with some flags:

- `sparse` is always false, because of the way encode/decode are implemented. The flag is
  still accepted and **ignored** — in pyldpc it only changes the speed, never the returned values.
- `systematic` **must be `True`**, for efficiency. `systematic=False` raises `NotImplementedError`.
- `H` and `tG` are handles to the C++ code, not numpy arrays, so `encode` and `decode` never copy
  them. `.shape`, indexing and `np.asarray(H)` work; for anything else, convert with
  `np.asarray` first.
- pyldpc rebuilds its O(n²) edge lists from `H` on every `decode` call, while this rewrite
  builds them once, in `make_ldpc`.

Because of the seeding differences between Armadillo and numpy, the same seed builds a different
(but equally valid) code than pyldpc's, so when decoding fails the BERs might be different, and the
`H` and `tG` matrices have to come from the same library.

## Benchmark

Around **1.5-2x faster end to end**.

Times in ms, pyldpcpp / pyldpc, at `d_v`=3, `d_c`=6, SNR=4 dB, four codes per row:

| n | make_ldpc | encode | decode | total | ratio |
|---|---|---|---|---|---|
| 600 | 6.5 / 30.4 | 0.08 / 0.13 | 0.35 / 2.82 | 6.9 / 33.3 | 4.8x |
| 1200 | 28.4 / 126.2 | 0.50 / 0.62 | 0.71 / 7.89 | 29.6 / 134.7 | 4.6x |
| 2400 | 210.5 / 633.8 | 3.28 / 3.59 | 1.87 / 28.5 | 215.6 / 665.9 | 3.1x |
| 4800 | 2620 / 4393 | 18.6 / 18.6 | 3.69 / 119.9 | 2642 / 4532 | 1.7x |
| 9600 | 22157 / 28437 | 146 / 165 | 7.36 / 557 | 22311 / 29158 | 1.3x |

Reproduce with:

```
python testing/bench.py
python testing/bench.py 1200 3 6 4   #single test: n d_v d_c snr [msgs] [blocks]
```
