correction 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- correction-0.2.0/LICENSE +26 -0
- correction-0.2.0/MANIFEST.in +2 -0
- correction-0.2.0/PKG-INFO +229 -0
- correction-0.2.0/README.rst +191 -0
- correction-0.2.0/correct.c +621 -0
- correction-0.2.0/correction.egg-info/PKG-INFO +229 -0
- correction-0.2.0/correction.egg-info/SOURCES.txt +38 -0
- correction-0.2.0/correction.egg-info/dependency_links.txt +1 -0
- correction-0.2.0/correction.egg-info/requires.txt +1 -0
- correction-0.2.0/correction.egg-info/top_level.txt +2 -0
- correction-0.2.0/libcorrect/LICENSE +12 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/bit.h +44 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/convolutional.h +40 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/error_buffer.h +15 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/history_buffer.h +59 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/lookup.h +27 -0
- correction-0.2.0/libcorrect/include/correct/convolutional/metric.h +20 -0
- correction-0.2.0/libcorrect/include/correct/convolutional.h +28 -0
- correction-0.2.0/libcorrect/include/correct/portable.h +20 -0
- correction-0.2.0/libcorrect/include/correct/reed-solomon/encode.h +3 -0
- correction-0.2.0/libcorrect/include/correct/reed-solomon/field.h +167 -0
- correction-0.2.0/libcorrect/include/correct/reed-solomon/polynomial.h +14 -0
- correction-0.2.0/libcorrect/include/correct/reed-solomon/reed-solomon.h +3 -0
- correction-0.2.0/libcorrect/include/correct/reed-solomon.h +76 -0
- correction-0.2.0/libcorrect/include/correct.h +277 -0
- correction-0.2.0/libcorrect/src/convolutional/bit.c +232 -0
- correction-0.2.0/libcorrect/src/convolutional/convolutional.c +59 -0
- correction-0.2.0/libcorrect/src/convolutional/decode.c +321 -0
- correction-0.2.0/libcorrect/src/convolutional/encode.c +61 -0
- correction-0.2.0/libcorrect/src/convolutional/error_buffer.c +43 -0
- correction-0.2.0/libcorrect/src/convolutional/history_buffer.c +158 -0
- correction-0.2.0/libcorrect/src/convolutional/lookup.c +74 -0
- correction-0.2.0/libcorrect/src/convolutional/metric.c +17 -0
- correction-0.2.0/libcorrect/src/reed-solomon/decode.c +508 -0
- correction-0.2.0/libcorrect/src/reed-solomon/encode.c +34 -0
- correction-0.2.0/libcorrect/src/reed-solomon/polynomial.c +255 -0
- correction-0.2.0/libcorrect/src/reed-solomon/reed-solomon.c +187 -0
- correction-0.2.0/setup.cfg +4 -0
- correction-0.2.0/setup.py +55 -0
- correction-0.2.0/test_correct.py +165 -0
correction-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
Copyright (c) 2026, Ilan Schnell
|
|
2
|
+
All rights reserved.
|
|
3
|
+
|
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
|
5
|
+
modification, are permitted provided that the following conditions are met:
|
|
6
|
+
|
|
7
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
8
|
+
list of conditions and the following disclaimer.
|
|
9
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
10
|
+
this list of conditions and the following disclaimer in the documentation
|
|
11
|
+
and/or other materials provided with the distribution.
|
|
12
|
+
|
|
13
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
14
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
15
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
16
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
|
|
17
|
+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
18
|
+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
19
|
+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
20
|
+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
21
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
22
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
23
|
+
|
|
24
|
+
The views and conclusions contained in the software and documentation are those
|
|
25
|
+
of the authors and should not be interpreted as representing official policies,
|
|
26
|
+
either expressed or implied, of the (Python) correct project.
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: correction
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Forward Error Correction - bindings for libcorrect
|
|
5
|
+
Home-page: https://github.com/ilanschnell/correct
|
|
6
|
+
Author: Ilan Schnell
|
|
7
|
+
Author-email: ilanschnell@gmail.com
|
|
8
|
+
License: BSD
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: C
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Topic :: Utilities
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/x-rst
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
License-File: libcorrect/LICENSE
|
|
26
|
+
Requires-Dist: bitarray>=3.4
|
|
27
|
+
Dynamic: author
|
|
28
|
+
Dynamic: author-email
|
|
29
|
+
Dynamic: classifier
|
|
30
|
+
Dynamic: description
|
|
31
|
+
Dynamic: description-content-type
|
|
32
|
+
Dynamic: home-page
|
|
33
|
+
Dynamic: license
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
Dynamic: requires-dist
|
|
36
|
+
Dynamic: requires-python
|
|
37
|
+
Dynamic: summary
|
|
38
|
+
|
|
39
|
+
correct
|
|
40
|
+
=======
|
|
41
|
+
|
|
42
|
+
``correct`` provides Python bindings for the convolutional and Reed-Solomon
|
|
43
|
+
forward error correction algorithms from `libcorrect`_. Convolutional codes
|
|
44
|
+
use bitarrays for encoded data, while Reed-Solomon codes operate on bytes.
|
|
45
|
+
|
|
46
|
+
The package requires Python 3.9 or later and bitarray 3.4 or later.
|
|
47
|
+
|
|
48
|
+
Installation
|
|
49
|
+
------------
|
|
50
|
+
|
|
51
|
+
Install the package from PyPI::
|
|
52
|
+
|
|
53
|
+
python -m pip install libcorrect
|
|
54
|
+
|
|
55
|
+
Run the self-tests::
|
|
56
|
+
|
|
57
|
+
python -m test_correct
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
Convolutional codes
|
|
61
|
+
-------------------
|
|
62
|
+
|
|
63
|
+
A convolutional encoder turns each input bit into several output bits. The
|
|
64
|
+
``inv_rate`` argument is the number of output bits per input bit: ``2`` gives
|
|
65
|
+
a rate 1/2 code, and ``3`` gives a rate 1/3 code. A lower rate adds more
|
|
66
|
+
redundancy.
|
|
67
|
+
|
|
68
|
+
The ``order`` is the width, in bits, of the encoder's shift register. It
|
|
69
|
+
controls how much preceding input affects each output. Larger orders can
|
|
70
|
+
provide stronger codes, but decoding cost and memory use increase rapidly.
|
|
71
|
+
|
|
72
|
+
The generator ``polynomials`` are bit masks which select the shift-register
|
|
73
|
+
bits XORed to produce each output bit. There must be exactly ``inv_rate``
|
|
74
|
+
polynomials. They are conventionally written in octal. For example::
|
|
75
|
+
|
|
76
|
+
conv = correct.Convolutional(2, 7, (0o161, 0o127))
|
|
77
|
+
|
|
78
|
+
This creates a rate 1/2, order 7 code: each input bit produces two output bits,
|
|
79
|
+
using the generator polynomials ``161`` and ``127`` (octal).
|
|
80
|
+
|
|
81
|
+
The following configurations are defined by libcorrect and exercised by the
|
|
82
|
+
test suite:
|
|
83
|
+
|
|
84
|
+
====== ===== ==========================
|
|
85
|
+
Rate Order Polynomials (octal)
|
|
86
|
+
====== ===== ==========================
|
|
87
|
+
1/2 6 ``(0o73, 0o61)``
|
|
88
|
+
1/2 7 ``(0o161, 0o127)``
|
|
89
|
+
1/2 8 ``(0o225, 0o373)``
|
|
90
|
+
1/2 9 ``(0o767, 0o545)``
|
|
91
|
+
1/3 6 ``(0o53, 0o75, 0o47)``
|
|
92
|
+
1/3 7 ``(0o137, 0o153, 0o121)``
|
|
93
|
+
1/3 8 ``(0o333, 0o257, 0o351)``
|
|
94
|
+
1/3 9 ``(0o417, 0o627, 0o675)``
|
|
95
|
+
====== ===== ==========================
|
|
96
|
+
|
|
97
|
+
``Convolutional.encode(data)``
|
|
98
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
99
|
+
|
|
100
|
+
Encode a bytes-like object and return a big-endian ``bitarray.bitarray``. The
|
|
101
|
+
encoder appends ``order + 1`` zero steps to terminate the code. The exact
|
|
102
|
+
encoded length is therefore::
|
|
103
|
+
|
|
104
|
+
inv_rate * (8 * len(data) + order + 1)
|
|
105
|
+
|
|
106
|
+
The result may contain a number of bits which is not divisible by eight;
|
|
107
|
+
bitarray preserves that length without exposing byte-padding details.
|
|
108
|
+
|
|
109
|
+
The following example encodes a message, damages three bits, and recovers the
|
|
110
|
+
original data::
|
|
111
|
+
|
|
112
|
+
>>> import correct
|
|
113
|
+
>>> conv = correct.Convolutional(2, 7, (0o161, 0o127))
|
|
114
|
+
>>> encoded = conv.encode(b"Hello world!")
|
|
115
|
+
>>> encoded.endian
|
|
116
|
+
'big'
|
|
117
|
+
>>> len(encoded)
|
|
118
|
+
208
|
|
119
|
+
>>> for i in 97, 123, 198:
|
|
120
|
+
... encoded.invert(i)
|
|
121
|
+
>>> conv.decode(encoded)
|
|
122
|
+
b'Hello world!'
|
|
123
|
+
|
|
124
|
+
``encoded`` is a big-endian ``bitarray.bitarray`` and can be stored,
|
|
125
|
+
transmitted, or modified using the normal bitarray operations.
|
|
126
|
+
|
|
127
|
+
``Convolutional.decode(codeword)``
|
|
128
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
129
|
+
|
|
130
|
+
Decode a big-endian bitarray produced by a compatible convolutional code and
|
|
131
|
+
return ``bytes``. A little-endian bitarray is rejected because its bit order
|
|
132
|
+
would give the codeword a different meaning.
|
|
133
|
+
|
|
134
|
+
Convolutional decoding cannot reliably detect when corruption exceeds the
|
|
135
|
+
code's ability to recover the original message. Protect the decoded data with
|
|
136
|
+
a checksum or CRC when silent corruption matters.
|
|
137
|
+
|
|
138
|
+
``Convolutional.decode_soft(values)``
|
|
139
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
140
|
+
|
|
141
|
+
Soft decoding accepts one unsigned byte for every encoded bit. Each value
|
|
142
|
+
expresses confidence in the received bit:
|
|
143
|
+
|
|
144
|
+
* ``0`` means a definite zero;
|
|
145
|
+
* ``255`` means a definite one;
|
|
146
|
+
* ``128`` means an unknown or erased bit;
|
|
147
|
+
* intermediate values express intermediate confidence.
|
|
148
|
+
|
|
149
|
+
The argument may be any contiguous bytes-like object with one-byte elements.
|
|
150
|
+
For example, convert a hard codeword to soft symbols and erase one symbol::
|
|
151
|
+
|
|
152
|
+
>>> encoded = conv.encode(b"soft decisions")
|
|
153
|
+
>>> soft = bytearray(255 if bit else 0 for bit in encoded)
|
|
154
|
+
>>> soft[len(soft) // 2] = 128
|
|
155
|
+
>>> conv.decode_soft(soft)
|
|
156
|
+
b'soft decisions'
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
Reed-Solomon codes
|
|
160
|
+
------------------
|
|
161
|
+
|
|
162
|
+
``correct.ReedSolomon(num_roots, primitive_polynomial=0x11d,
|
|
163
|
+
first_root=1, root_gap=1)`` creates a Reed-Solomon code over 8-bit symbols. A
|
|
164
|
+
full encoded block contains at most 255 bytes.
|
|
165
|
+
|
|
166
|
+
``num_roots`` is the number of parity bytes added to every message and must be
|
|
167
|
+
between 1 and 254. A block can therefore contain at most
|
|
168
|
+
``255 - num_roots`` message bytes. With no erasure information, up to
|
|
169
|
+
``num_roots // 2`` corrupted bytes can be corrected.
|
|
170
|
+
|
|
171
|
+
The other constructor arguments define the finite field and generator roots.
|
|
172
|
+
The defaults use the primitive polynomial
|
|
173
|
+
``x^8 + x^4 + x^3 + x^2 + 1``. Change these advanced parameters only when
|
|
174
|
+
interoperating with a protocol or implementation that specifies different
|
|
175
|
+
values; not every combination produces a useful code.
|
|
176
|
+
|
|
177
|
+
``ReedSolomon.encode(data)``
|
|
178
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
179
|
+
|
|
180
|
+
Encode a bytes-like object and return ``bytes`` containing the original data
|
|
181
|
+
followed by ``num_roots`` parity bytes. Short messages use virtual leading
|
|
182
|
+
padding, which is not included in the result::
|
|
183
|
+
|
|
184
|
+
>>> rs = correct.ReedSolomon(32)
|
|
185
|
+
>>> encoded = rs.encode(b"Reed-Solomon")
|
|
186
|
+
>>> len(encoded)
|
|
187
|
+
44
|
|
188
|
+
>>> encoded[:12]
|
|
189
|
+
b'Reed-Solomon'
|
|
190
|
+
>>> rs.decode(encoded)
|
|
191
|
+
b'Reed-Solomon'
|
|
192
|
+
|
|
193
|
+
``ReedSolomon.decode(encoded, erasures=None)``
|
|
194
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
195
|
+
|
|
196
|
+
Decode an encoded bytes-like object and return the original message as
|
|
197
|
+
``bytes``. The optional ``erasures`` argument is a sequence of byte positions
|
|
198
|
+
known to be unreliable. A known erasure consumes one parity byte of the
|
|
199
|
+
correction capacity, while an error at an unknown position consumes two. In
|
|
200
|
+
general, recovery is possible when::
|
|
201
|
+
|
|
202
|
+
2 * unknown_errors + erasures <= num_roots
|
|
203
|
+
|
|
204
|
+
For example, mark several corrupted bytes as erasures::
|
|
205
|
+
|
|
206
|
+
>>> encoded = bytearray(rs.encode(b"known erasures"))
|
|
207
|
+
>>> erasures = [0, 4, 8]
|
|
208
|
+
>>> for i in erasures:
|
|
209
|
+
... encoded[i] ^= 0xff
|
|
210
|
+
>>> rs.decode(encoded, erasures=erasures)
|
|
211
|
+
b'known erasures'
|
|
212
|
+
|
|
213
|
+
As with convolutional decoding, sufficiently severe corruption is not always
|
|
214
|
+
detectable. Use a checksum or CRC when the decoded message must be verified.
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
Version
|
|
218
|
+
-------
|
|
219
|
+
|
|
220
|
+
The installed version is available as::
|
|
221
|
+
|
|
222
|
+
>>> correct.__version__
|
|
223
|
+
'0.2.0'
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
The Python binding and the vendored libcorrect sources are distributed under
|
|
227
|
+
BSD licenses. See ``LICENSE`` and ``libcorrect/LICENSE`` for details.
|
|
228
|
+
|
|
229
|
+
.. _libcorrect: https://github.com/quiet/libcorrect
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
correct
|
|
2
|
+
=======
|
|
3
|
+
|
|
4
|
+
``correct`` provides Python bindings for the convolutional and Reed-Solomon
|
|
5
|
+
forward error correction algorithms from `libcorrect`_. Convolutional codes
|
|
6
|
+
use bitarrays for encoded data, while Reed-Solomon codes operate on bytes.
|
|
7
|
+
|
|
8
|
+
The package requires Python 3.9 or later and bitarray 3.4 or later.
|
|
9
|
+
|
|
10
|
+
Installation
|
|
11
|
+
------------
|
|
12
|
+
|
|
13
|
+
Install the package from PyPI::
|
|
14
|
+
|
|
15
|
+
python -m pip install libcorrect
|
|
16
|
+
|
|
17
|
+
Run the self-tests::
|
|
18
|
+
|
|
19
|
+
python -m test_correct
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
Convolutional codes
|
|
23
|
+
-------------------
|
|
24
|
+
|
|
25
|
+
A convolutional encoder turns each input bit into several output bits. The
|
|
26
|
+
``inv_rate`` argument is the number of output bits per input bit: ``2`` gives
|
|
27
|
+
a rate 1/2 code, and ``3`` gives a rate 1/3 code. A lower rate adds more
|
|
28
|
+
redundancy.
|
|
29
|
+
|
|
30
|
+
The ``order`` is the width, in bits, of the encoder's shift register. It
|
|
31
|
+
controls how much preceding input affects each output. Larger orders can
|
|
32
|
+
provide stronger codes, but decoding cost and memory use increase rapidly.
|
|
33
|
+
|
|
34
|
+
The generator ``polynomials`` are bit masks which select the shift-register
|
|
35
|
+
bits XORed to produce each output bit. There must be exactly ``inv_rate``
|
|
36
|
+
polynomials. They are conventionally written in octal. For example::
|
|
37
|
+
|
|
38
|
+
conv = correct.Convolutional(2, 7, (0o161, 0o127))
|
|
39
|
+
|
|
40
|
+
This creates a rate 1/2, order 7 code: each input bit produces two output bits,
|
|
41
|
+
using the generator polynomials ``161`` and ``127`` (octal).
|
|
42
|
+
|
|
43
|
+
The following configurations are defined by libcorrect and exercised by the
|
|
44
|
+
test suite:
|
|
45
|
+
|
|
46
|
+
====== ===== ==========================
|
|
47
|
+
Rate Order Polynomials (octal)
|
|
48
|
+
====== ===== ==========================
|
|
49
|
+
1/2 6 ``(0o73, 0o61)``
|
|
50
|
+
1/2 7 ``(0o161, 0o127)``
|
|
51
|
+
1/2 8 ``(0o225, 0o373)``
|
|
52
|
+
1/2 9 ``(0o767, 0o545)``
|
|
53
|
+
1/3 6 ``(0o53, 0o75, 0o47)``
|
|
54
|
+
1/3 7 ``(0o137, 0o153, 0o121)``
|
|
55
|
+
1/3 8 ``(0o333, 0o257, 0o351)``
|
|
56
|
+
1/3 9 ``(0o417, 0o627, 0o675)``
|
|
57
|
+
====== ===== ==========================
|
|
58
|
+
|
|
59
|
+
``Convolutional.encode(data)``
|
|
60
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
61
|
+
|
|
62
|
+
Encode a bytes-like object and return a big-endian ``bitarray.bitarray``. The
|
|
63
|
+
encoder appends ``order + 1`` zero steps to terminate the code. The exact
|
|
64
|
+
encoded length is therefore::
|
|
65
|
+
|
|
66
|
+
inv_rate * (8 * len(data) + order + 1)
|
|
67
|
+
|
|
68
|
+
The result may contain a number of bits which is not divisible by eight;
|
|
69
|
+
bitarray preserves that length without exposing byte-padding details.
|
|
70
|
+
|
|
71
|
+
The following example encodes a message, damages three bits, and recovers the
|
|
72
|
+
original data::
|
|
73
|
+
|
|
74
|
+
>>> import correct
|
|
75
|
+
>>> conv = correct.Convolutional(2, 7, (0o161, 0o127))
|
|
76
|
+
>>> encoded = conv.encode(b"Hello world!")
|
|
77
|
+
>>> encoded.endian
|
|
78
|
+
'big'
|
|
79
|
+
>>> len(encoded)
|
|
80
|
+
208
|
|
81
|
+
>>> for i in 97, 123, 198:
|
|
82
|
+
... encoded.invert(i)
|
|
83
|
+
>>> conv.decode(encoded)
|
|
84
|
+
b'Hello world!'
|
|
85
|
+
|
|
86
|
+
``encoded`` is a big-endian ``bitarray.bitarray`` and can be stored,
|
|
87
|
+
transmitted, or modified using the normal bitarray operations.
|
|
88
|
+
|
|
89
|
+
``Convolutional.decode(codeword)``
|
|
90
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
91
|
+
|
|
92
|
+
Decode a big-endian bitarray produced by a compatible convolutional code and
|
|
93
|
+
return ``bytes``. A little-endian bitarray is rejected because its bit order
|
|
94
|
+
would give the codeword a different meaning.
|
|
95
|
+
|
|
96
|
+
Convolutional decoding cannot reliably detect when corruption exceeds the
|
|
97
|
+
code's ability to recover the original message. Protect the decoded data with
|
|
98
|
+
a checksum or CRC when silent corruption matters.
|
|
99
|
+
|
|
100
|
+
``Convolutional.decode_soft(values)``
|
|
101
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
102
|
+
|
|
103
|
+
Soft decoding accepts one unsigned byte for every encoded bit. Each value
|
|
104
|
+
expresses confidence in the received bit:
|
|
105
|
+
|
|
106
|
+
* ``0`` means a definite zero;
|
|
107
|
+
* ``255`` means a definite one;
|
|
108
|
+
* ``128`` means an unknown or erased bit;
|
|
109
|
+
* intermediate values express intermediate confidence.
|
|
110
|
+
|
|
111
|
+
The argument may be any contiguous bytes-like object with one-byte elements.
|
|
112
|
+
For example, convert a hard codeword to soft symbols and erase one symbol::
|
|
113
|
+
|
|
114
|
+
>>> encoded = conv.encode(b"soft decisions")
|
|
115
|
+
>>> soft = bytearray(255 if bit else 0 for bit in encoded)
|
|
116
|
+
>>> soft[len(soft) // 2] = 128
|
|
117
|
+
>>> conv.decode_soft(soft)
|
|
118
|
+
b'soft decisions'
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
Reed-Solomon codes
|
|
122
|
+
------------------
|
|
123
|
+
|
|
124
|
+
``correct.ReedSolomon(num_roots, primitive_polynomial=0x11d,
|
|
125
|
+
first_root=1, root_gap=1)`` creates a Reed-Solomon code over 8-bit symbols. A
|
|
126
|
+
full encoded block contains at most 255 bytes.
|
|
127
|
+
|
|
128
|
+
``num_roots`` is the number of parity bytes added to every message and must be
|
|
129
|
+
between 1 and 254. A block can therefore contain at most
|
|
130
|
+
``255 - num_roots`` message bytes. With no erasure information, up to
|
|
131
|
+
``num_roots // 2`` corrupted bytes can be corrected.
|
|
132
|
+
|
|
133
|
+
The other constructor arguments define the finite field and generator roots.
|
|
134
|
+
The defaults use the primitive polynomial
|
|
135
|
+
``x^8 + x^4 + x^3 + x^2 + 1``. Change these advanced parameters only when
|
|
136
|
+
interoperating with a protocol or implementation that specifies different
|
|
137
|
+
values; not every combination produces a useful code.
|
|
138
|
+
|
|
139
|
+
``ReedSolomon.encode(data)``
|
|
140
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
141
|
+
|
|
142
|
+
Encode a bytes-like object and return ``bytes`` containing the original data
|
|
143
|
+
followed by ``num_roots`` parity bytes. Short messages use virtual leading
|
|
144
|
+
padding, which is not included in the result::
|
|
145
|
+
|
|
146
|
+
>>> rs = correct.ReedSolomon(32)
|
|
147
|
+
>>> encoded = rs.encode(b"Reed-Solomon")
|
|
148
|
+
>>> len(encoded)
|
|
149
|
+
44
|
|
150
|
+
>>> encoded[:12]
|
|
151
|
+
b'Reed-Solomon'
|
|
152
|
+
>>> rs.decode(encoded)
|
|
153
|
+
b'Reed-Solomon'
|
|
154
|
+
|
|
155
|
+
``ReedSolomon.decode(encoded, erasures=None)``
|
|
156
|
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
157
|
+
|
|
158
|
+
Decode an encoded bytes-like object and return the original message as
|
|
159
|
+
``bytes``. The optional ``erasures`` argument is a sequence of byte positions
|
|
160
|
+
known to be unreliable. A known erasure consumes one parity byte of the
|
|
161
|
+
correction capacity, while an error at an unknown position consumes two. In
|
|
162
|
+
general, recovery is possible when::
|
|
163
|
+
|
|
164
|
+
2 * unknown_errors + erasures <= num_roots
|
|
165
|
+
|
|
166
|
+
For example, mark several corrupted bytes as erasures::
|
|
167
|
+
|
|
168
|
+
>>> encoded = bytearray(rs.encode(b"known erasures"))
|
|
169
|
+
>>> erasures = [0, 4, 8]
|
|
170
|
+
>>> for i in erasures:
|
|
171
|
+
... encoded[i] ^= 0xff
|
|
172
|
+
>>> rs.decode(encoded, erasures=erasures)
|
|
173
|
+
b'known erasures'
|
|
174
|
+
|
|
175
|
+
As with convolutional decoding, sufficiently severe corruption is not always
|
|
176
|
+
detectable. Use a checksum or CRC when the decoded message must be verified.
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
Version
|
|
180
|
+
-------
|
|
181
|
+
|
|
182
|
+
The installed version is available as::
|
|
183
|
+
|
|
184
|
+
>>> correct.__version__
|
|
185
|
+
'0.2.0'
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
The Python binding and the vendored libcorrect sources are distributed under
|
|
189
|
+
BSD licenses. See ``LICENSE`` and ``libcorrect/LICENSE`` for details.
|
|
190
|
+
|
|
191
|
+
.. _libcorrect: https://github.com/quiet/libcorrect
|