aff3ct / py_aff3ct

Python wrapper for AFF3CT.

AFF3CT: A Fast Forward Error Correction Toolbox!

AFF3CT is a simulator and a library dedicated to the Forward Error Correction (FEC or channel coding). It is written in C++ and it supports a large range of codes: from the well-spread Turbo codes to the new Polar codes including the Low-Density Parity-Check (LDPC) codes. AFF3CT can be used as a command line program and it simulates communication chains based on a Monte Carlo method.

It is very easy to use, for instance, to estimate the BER/FER decoding performances of the (2048,1723) Polar code from 1.0 to 4.0 dB:

aff3ct -C "POLAR" -K 1723 -N 2048 -m 1.0 -M 4.0 -s 1.0

And the output will be:

# ----------------------------------------------------
# ---- A FAST FORWARD ERROR CORRECTION TOOLBOX >> ----
# ----------------------------------------------------
# Parameters :
# [...]
#
# The simulation is running...
# ---------------------||------------------------------------------------------||---------------------
#  Signal Noise Ratio  ||   Bit Error Rate (BER) and Frame Error Rate (FER)    ||  Global throughput
#         (SNR)        ||                                                      ||  and elapsed time
# ---------------------||------------------------------------------------------||---------------------
# ----------|----------||----------|----------|----------|----------|----------||----------|----------
#     Es/N0 |    Eb/N0 ||      FRA |       BE |       FE |      BER |      FER ||  SIM_THR |    ET/RT
#      (dB) |     (dB) ||          |          |          |          |          ||   (Mb/s) | (hhmmss)
# ----------|----------||----------|----------|----------|----------|----------||----------|----------
       0.25 |     1.00 ||      104 |    16425 |      104 | 9.17e-02 | 1.00e+00 ||    4.995 | 00h00'00
       1.25 |     2.00 ||      104 |    12285 |      104 | 6.86e-02 | 1.00e+00 ||   13.678 | 00h00'00
       2.25 |     3.00 ||      147 |     5600 |      102 | 2.21e-02 | 6.94e-01 ||   14.301 | 00h00'00
       3.25 |     4.00 ||     5055 |     2769 |      100 | 3.18e-04 | 1.98e-02 ||   30.382 | 00h00'00
# End of the simulation.

Features

The simulator targets high speed simulations and extensively uses parallel techniques like SIMD, multi-threading and multi-nodes programming models. Below, a list of the features that motivated the creation of the simulator:

1. reproduce state-of-the-art decoding performances,
2. explore various channel code configurations, find new trade-offs,
3. prototype hardware implementation (fixed-point receivers, hardware in the loop tools),
4. reuse tried and tested modules and add yours,
5. alternative to MATLAB, if you seek to reduce simulations time.

AFF3CT was first intended to be a simulator but as it developed, the need to reuse sub-parts of the code intensified: the library was born. Below is a list of possible applications for the library:

1. build custom communication chains that are not possible with the simulator,
2. facilitate hardware prototyping,
3. enable various modules to be used in SDR contexts.

If you seek for using AFF3CT as a library, please refer to the dedicated documentation page.

Installation

First make sure to have installed a C++11 compiler, CMake and Git. Then install AFF3CT by running:

git clone --recursive https://github.com/aff3ct/aff3ct.git
mkdir aff3ct/build
cd aff3ct/build
cmake .. -DCMAKE_BUILD_TYPE="Release"
make -j4

Contribute

• Source Code
• Contributing guidelines

Support

If you are having issues, please let us know on our issue tracker.

License

The project is licensed under the MIT license.

How to cite AFF3CT

We recommend you to cite the SoftwareX journal article: A. Cassagne et al., “AFF3CT: A Fast Forward Error Correction Toolbox!,“ Elsevier SoftwareX, 2019 [Bibtex Entry].

External Links

• Official website
• Documentation

py_aff3ct's Issues

Issue while compiling

While launching configure.py, I've had this error:

Traceback (most recent call last):
  File "../configure.py", line 11, in <module>
    import xmltodict
ModuleNotFoundError: No module named 'xmltodict'

Error when trying to install Py_aff3ct

When I try to copy the Cmake configuration file using this command:
cp lib/aff3ct/build/lib/cmake/aff3ct-*/* cmake/Modules
I got the error that the directory does not exist, although I finished the Aff3ct installation successfully. How can I fix this?

Detection flag as the output of the decoder

Hi,

First, I wanted to thank you for this great work. I have a question regarding the possible outputs of the provided decoders. Is it possible to receive a flag that the detection has happened besides the decoded code word? In other words, a flag that shows the decoder could detect the error, and the syndrome was nonzero.

Regards

How to place py_aff3ct.so to import without `sys.path.insert`

I have built the .so successfully and sys.path.insert(0, '../../build/lib') is working well.

However, VSCode Intellisense seems not to work if the lib is imported afterwards via sys.path.insert.

So then I tried to place the .so into my $CONDA_PREFIX/lib/ as I'm using conda environment, but py_aff3ct cannot be found when imported directly without sys.path.insert.

I hope that there's a way to realize direct import.

Thanks for your outstanding work!

PyBind Unknown Type

Hi,

I am trying to use the Python bindings for the Interleaver module in aff3ct. However, when I run configure.py, it keeps reporting

(WW) Constructor not be wrapped for class aff3ct::tools::Interleaver_core_column_row -> argument read_order has unknown type 'aff3ct::tools::Interleaver_core_column_row::READ_ORDER'.
(WW) Constructor not be wrapped for class aff3ct::tools::Interleaver_core_row_column -> argument read_order has unknown type 'aff3ct::tools::Interleaver_core_row_column::READ_ORDER'.

This produces an ImportError in Python when py_aff3ct package is import because Interleaver_core_row_column symbol is undefined.

Thanks for creating the Python bindings. This is a very useful package for simulation and modeling of custom waveforms and communications system.

Jeff

How to feed array into multithread sequence?

I have an upstream array which contains thousands of codewords to be decoded.

So I write a feeder like this:

class Feeder(Py_Module):
    def __init__(self, N: int, batch_size: int, dtype):
        Py_Module.__init__(self)
        self.name = "py_Feeder"
        self.N = N
        self.batch_size = batch_size
        self.cnt = 0

        step = self.create_task("step")
        inpt = self.create_socket_in(step, "input", batch_size * N, dtype)
        out = self.create_socket_out(step, "output", N, dtype)
        self.create_codelet(step, lambda slf, lsk, fid: slf.step(lsk[inpt], lsk[out]))

    def step(self, x: ndarray, y: ndarray):
        if self.cnt >= self.batch_size:
            print("Feeder overflow")
            self.toggle_done()
            return 0
        y[:] = x[:, self.cnt * self.N: (self.cnt + 1) * self.N]
        self.cnt += 1
        if self.cnt >= self.batch_size:
            self.toggle_done()
        return 0

It works well when sequence is run with 1 thread, but when it comes to multithreading, the code just keeps
running into overflow.

Mutex lock seems not to be supported either.

Is there a proper way to implement it?

get_trellis method no longer exposed

Hi,

I just did a pull on py_aff3ct and noticed that tt appears that the get_trellis method on the Encoder_RSC_DB class is no longer exposed to Python. For example,

enc = aff3ct.module.encoder.Encoder_RSC_DB(K, N, standard='DVB-RCS2')
trellis = enc.get_trellis()

produces

Traceback (most recent call last):
  File "./test_bfer_rsc_db.py", line 31, in <module>
    trellis = enc.get_trellis()
AttributeError: 'py_aff3ct.module.encoder.Encoder_RSC_DB' object has no attribute 'get_trellis'

Adding this->def("get_trellis", &Encoder_RSC_DB<B>::get_trellis); to the definitions method of Encoder_RSC_DB Pybind wrapper appears to fix it.

template <typename B>
void Wrapper_Encoder_RSC_DB<B>
::definitions()
{
	this->def(py::init<const int &, const int &, const std::string, const bool>(),"K"_a, "N"_a, "standard"_a = "DVB-RCS1", "buffered_encoding"_a = true, py::return_value_policy::reference);
	this->def("get_trellis", &Encoder_RSC_DB<B>::get_trellis);
};

Thanks,
Jeff

How to install py_aff3ct in google colab

use CRC inside py_aff3ct

Thank you so much for this super helpful project.

I am trying to modify from https://github.com/aff3ct/py_aff3ct/blob/master/examples/full_python/bfer_polar.py to use the CA-SCL decoding with some crc polynomial. I rarely worked with c++ and I'm not familiar at all with the binding stuff... I could not find any wrapped module for CRCs, and I'm not sure how to construct a proper aff3ct::module::CRC type argument for the decoder Decoder_polar_SCL_naive_CA. Any hints on this?

Linking AFF3CT with SDRs

Hi again,

I manage to work fluently with your code (the python wrapped version) and in parallel I have a working physical communication channel configured using LimeSDR Tx and Rx. But I have no idea how to link those two together :(

Here is an example to the workflow I am interested to achieve, while using your encode & decode functions:

[vecIn = A packed vector I provide from python]
vecTx = enc(vecIn)
[vecTx => SDR_Tx => the real world]
[the real world => SDR_Rx => vecRx]
vecOut = dec(vecRx)
if vecOut == vecIn: print('Well done Evgy!')

Can you maybe tell me how this can be done?

Thank you

BCH Encoding Issue

Hi,
Thanks for this very nice, well documented project :)

I am trying to modify the example from /examples/notebooks/16QAM_tutorial to some more advanced encoding. I tried the BCH encoding end received errors during the execution of the decoder. Code and error log are found below.

Perhaps you know how can I fix this or maybe you have another encoding-decoding example using something other then the repeater encoding?

Also, I plan to use your code as an encoder-decoder in a combination with an SDR module with its analog layers managed through GNURadio. Do you think those examples would be good for this?

Thanks

The code:

import build.lib.py_aff3ct as py_aff3ct
import numpy as np
import matplotlib.pyplot as plt

K   = 6     # Message size in bits
N   = 31    # Packet length in bits
t   = 7
bps = 4     # Bits per Symbols
Ns  = 16    # Packet size in symbols

src  = py_aff3ct.module.source.Source_random(K)             # Build source
enc_pol = py_aff3ct.tools.BCH_polynomial_generator(N, K)
enc  = py_aff3ct.module.encoder.Encoder_BCH(K, N, enc_pol)
cstl = py_aff3ct.tools.constellation.Constellation_QAM(bps) # Setup constellation tool
mdm  = py_aff3ct.module.modem.Modem_generic(N, cstl)        # Build the modem
chn  = py_aff3ct.module.channel.Channel_AWGN_LLR(Ns)      # Build the channel (Ns complex symbols = 2Ns real dims)
dec  = py_aff3ct.module.decoder.Decoder_BCH(K, N, t)
mnt  = py_aff3ct.module.monitor.Monitor_BFER_AR(K,100)      # Build the monitor (counting errors)

## Bind the tasks
enc[      'encode::U_K' ].bind(src[   'generate::U_K' ]) # Source       -> Encoder
mdm[    'modulate::X_N1'].bind(enc[     'encode::X_N' ]) # Encoder      -> Modulation
chn[   'add_noise::X_N' ].bind(mdm[   'modulate::X_N2']) # Modulation   -> Channel
mdm[  'demodulate::Y_N1'].bind(chn[  'add_noise::Y_N' ]) # Channel      -> Demodulation
dec[ 'decode_siho::Y_N' ].bind(mdm[ 'demodulate::Y_N2']) # Demodulation -> Decoder
mnt['check_errors::U'   ].bind(src[   'generate::U_K' ]) # Source       -> Monitor
mnt['check_errors::V'   ].bind(dec['decode_siho::V_K' ]) # Decoder      -> Monitor

sigma = np.ndarray(shape = (1,1),  dtype = np.float32)
sigma[0] = 0.05

chn[ 'add_noise::CP'].bind(sigma)
mdm['demodulate::CP'].bind(sigma)

## Execute
src('generate'   ).exec()
enc('encode'     ).exec()
mdm('modulate'   ).exec()
chn('add_noise'  ).exec()
mdm('demodulate' ).exec()
dec('decode_siho').exec()

The error:

raceback (most recent call last):
  File "/scratch_1.py", line 41, in <module>
    dec('decode_siho').exec()
RuntimeError: In the '/usr/include/aff3ct-3.0.1/aff3ct/Module/Decoder/Decoder_SIHO.hxx' file at line 228 ('_decode_siho' function): "Unimplemented function or method."

Incompatible Constructor Arguments

I am attempting to use the Python bindings for aaff3ct from py_aff3ct to simulate a DVB RCS2 encoder and decoder in waveform simulation. However, I am getting incompatible constructor arguments when I try to instantiate the Decoder_turbo_DB object. Below is a code snippet:

# Build DVBS-RCS2 Turbo encoder.
enc_n = aff3ct.module.encoder.Encoder_RSC_DB(K, 
                                             2*K, 
                                             standard='DVB-RCS2')

enc_i = aff3ct.module.encoder.Encoder_RSC_DB(K, 
                                             2*K, 
                                             standard='DVB-RCS2')

itl = aff3ct.module.Interleaver(aff3ct.tools.interleaver_core.Interleaver_core_ARP_DVB_RCS2(int(K/2)))

enc = aff3ct.module.encoder.Encoder_turbo_DB(K,
                                             N,
                                             enc_n,
                                             enc_i,
                                             itl)

# Build DVBS-RCS2 Trubo decoder.
trellis_n = enc_n.get_trellis()
dec_n = aff3ct.module.decoder.Decoder_RSC_DB_BCJR_DVB_RCS2(K, 
                                                           trellis_n)

trellis_i = enc_i.get_trellis()
dec_i = aff3ct.module.decoder.Decoder_RSC_DB_BCJR_DVB_RCS2(K, 
                                                           trellis_i)

dec = aff3ct.module.decoder.Decoder_turbo_DB(K,
                                             N,
                                             8,
                                             dec_n,
                                             dec_i,
                                             itl)

However, this produces:

Traceback (most recent call last):
  File "./test_bfer_turbo_db.py", line 45, in <module>
    dec = aff3ct.module.decoder.Decoder_turbo_DB(K,
TypeError: __init__(): incompatible constructor arguments. The following argument types are supported:
    1. py_aff3ct.module.decoder.Decoder_turbo_DB(K: int, N: int, n_ite: int, siso_n: py_aff3ct.module.decoder.Decoder_RSC_DB_BCJR, siso_i: py_aff3ct.module.decoder.Decoder_RSC_DB_BCJR, pi: aff3ct::module::Interleaver<float, unsigned int>)

Invoked with: 304, 912, 8, <py_aff3ct.module.decoder.Decoder_RSC_DB_BCJR_DVB_RCS2 object at 0x7fa10ea8c130>, <py_aff3ct.module.decoder.Decoder_RSC_DB_BCJR_DVB_RCS2 object at 0x7fa126d790f0>, <py_aff3ct.module.Interleaver object at 0x7fa11423df30>

I am unsure what argument to the constructor is invalid. As a test, I modified the Pybind wrapper for Decoder_turbo_DB in Decoder_turbo_DB.cpp from

template <typename B, typename R>
void Wrapper_Decoder_turbo_DB<B, R>
::definitions()
{
	this->def(py::init<const int &, const int &, const int &, const Decoder_RSC_DB_BCJR<B, R> &, const Decoder_RSC_DB_BCJR<B, R> &, const Interleaver<R> &>(),"K"_a, "N"_a, "n_ite"_a, "siso_n"_a, "siso_i"_a, "pi"_a, py::return_value_policy::reference);
};

to

template <typename B, typename R>
void Wrapper_Decoder_turbo_DB<B, R>
::definitions()
{
	this->def(py::init<const int &, const int &, const int &, const Decoder_RSC_DB_BCJR_DVB_RCS2<B, R> &, const Decoder_RSC_DB_BCJR_DVB_RCS2<B, R> &, const Interleaver<R> &>(),"K"_a, "N"_a, "n_ite"_a, "siso_n"_a, "siso_i"_a, "pi"_a, py::return_value_policy::reference);
};

However, this still produced same error.

Do you have any guidance or insight on how to fix or debug this?

Thanks,
Jeff