Include Cython-AFF3CT example documentation. #83
Conversation
|
Thank you for this complete PR. I have to take the time to check the code. I will do that in the next days. |
doc/source/user/library/examples.rst
Outdated
| @@ -966,3 +966,318 @@ modules while in ``u.modules_stats`` the two dimension are switched. | |||
|
|
|||
| .. note:: The full source code is available here: | |||
| https://github.com/aff3ct/my_project_with_aff3ct/blob/master/examples/openmp/src/main.cpp. | |||
|
|
|||
|
|
|||
| Cython-AFF3CT | |||
| This example serves as a template framework on how to use AFF3CT in Python. | ||
| This example is based on the `Cython`_, and steps of compiling this example | ||
| is included in the `README` file. | ||
|
|
There was a problem hiding this comment.
The main purpose of the cython_polar example is to wrap |AFF3CT| polar code features (frozen bits generation, polar encoding process and polar decoding process) in Python.
This example is based on Cython_ and can be used as a template to bind C++ |AFF3CT| features to Python.
Specific compilation steps are given in the corresponding repository.
| vector[vector[int]] polar_decode_multiple(const int, const int, const vector[bool] &, const vector[vector[float]] &) | ||
|
|
||
| Lines ``7-9`` support 2-D [ndarray](https://numpy.org/doc/stable/reference/arrays.ndarray.html) arguments, and return 2-D lists. | ||
|
|
doc/source/user/library/examples.rst
Outdated
| The polar encoded bits | ||
| """ | ||
| assert info_bits.shape[1] > 0 | ||
| return polar_encode_multiple(k, n, frozen_bits, info_bits) |
There was a problem hiding this comment.
I think we should avoid to mention the py_polar_encode_multiple function.
There was a problem hiding this comment.
I do not agree. Though this function is simple, but it provides a lot of performance gain, especially when user is trying to encode/decode multiple frames in Python. As you know, Python's for-loops are very expensive, not to mention we need to instantiate an encoder/decoder object every time we call it.
There was a problem hiding this comment.
Ok, I see your point so perhaps you can tell in the text the purpose of the multiple function?
doc/source/user/library/examples.rst
Outdated
| The polar decoded bits | ||
| """ | ||
| assert received.shape[1] > 0 | ||
| return polar_decode_multiple(k, n, frozen_bits, received) |
There was a problem hiding this comment.
I think we should avoid to mention the py_polar_decode_multiple function.
doc/source/user/library/examples.rst
Outdated
| .. code-block:: python | ||
| :caption: Setup function | ||
| :name: setup_py | ||
| :emphasize-lines: | ||
| :linenos: | ||
|
|
||
| from distutils.core import setup | ||
| from distutils.extension import Extension | ||
| from Cython.Build import cythonize | ||
|
|
||
| codec = Extension( | ||
| name="codec", | ||
| sources=["codec.pyx"], | ||
| libraries=["aff3ct-2.3.5-384-gec40f26"], | ||
| library_dirs=["../../lib/aff3ct/build/lib"], | ||
| include_dirs=["../../lib/aff3ct/include", "../../lib/aff3ct/lib/cli/src", "../../lib/aff3ct/lib/MIPP/src", "../../lib/aff3ct/lib/MIPP/src", "../../lib/aff3ct/lib/rang/include"], | ||
| language="c++", | ||
| extra_compile_args=["-std=c++14"], | ||
| extra_link_args=["-std=c++14"] | ||
| ) | ||
| setup( | ||
| name="codec", | ||
| ext_modules=cythonize([codec]) | ||
| ) |
There was a problem hiding this comment.
I think that we can remove this code, this is a configuration code.
| /** | ||
| * @brief Polar encoder for multiple frames | ||
| * | ||
| * @param k The number of information bits | ||
| * @param n The codeword length | ||
| * @param frozen_bits std::vector<bool>, frozen bits (length k) | ||
| * @param info_bits std::vector<int>, information bits (length k) | ||
| * @return auto Encoded codewords, std::vector<int> of length n | ||
| */ | ||
| auto polar_encode_multiple(const int k, const int n, | ||
| const std::vector<bool> &frozen_bits, | ||
| const std::vector<std::vector<int>> &info_bits) { | ||
| // populate vector | ||
| std::vector<std::vector<int>> encoded_bits; | ||
|
|
||
| // encode | ||
| module::Encoder_polar<int> polar_encoder(k, n, frozen_bits); | ||
| for (auto frame : info_bits) { | ||
| std::vector<int> encoded(n); | ||
| polar_encoder.encode(frame, encoded); | ||
| encoded_bits.push_back(encoded); | ||
| } | ||
| return encoded_bits; | ||
| } |
There was a problem hiding this comment.
I think we can remove this code.
There was a problem hiding this comment.
I think there is too many blocks of code and not so many explanations. If the code is given with no comments, you can simply add a link to the file in the my_project_with_aff3ct repo. The other solution is to keep this code here but to split it in smaller blocks and to explain what you are doing in the text.
There was a problem hiding this comment.
Done. Please refer to the newest commit.
| /** | ||
| * @brief Polar decoder for multiframe | ||
| * | ||
| * @param k The number of information bits | ||
| * @param n The codeword length | ||
| * @param frozen_bits std::vector<bool>, frozen bits (length k) | ||
| * @param received std::vector<float> soft symbols, BPSK, n_frame rows, n | ||
| * columns | ||
| * @return auto Decoded information bits, std::vector<std::vector<int>> of | ||
| * n_frame rows, k columns | ||
| */ | ||
| auto polar_decode_multiple(const int k, const int n, | ||
| const std::vector<bool> &frozen_bits, | ||
| const std::vector<std::vector<float>> &received) { | ||
| // populate vectors | ||
| std::vector<std::vector<int>> decoded_bits; | ||
|
|
||
| // encode | ||
| module::Decoder_polar_SC_naive<int> polar_decoder(k, n, frozen_bits); | ||
| for (auto frame : received) { | ||
| std::vector<int> decoded(k); | ||
| polar_decoder.decode_siho(frame, decoded); | ||
| decoded_bits.push_back(decoded); | ||
| } | ||
| return decoded_bits; | ||
| } |
There was a problem hiding this comment.
I think we can remove this code too.
|
Hey @kouchy , shall we wrap this up? Please let me know what else you would like to include! |
|
Hi @SubtleMuffin, Sry, we had a new lock-down in my country, I did not have the time to focus on this yet, but I do not forget you :-). Regards. |
|
Hey @kouchy : nothing is paramount than health. Please stay safe! |
This PR introduces the accompanying documentation of
Cython-AFF3CTexample.