Coding Pipeline¶

This module introduces the concept of bit Encoder steps, which form single chain link within a channel coding processing chain.

Considering an arbitrary coding scheme consisting of multiple steps, the process of encoding bit streams during transmission and decoding them during subsequent reception is modeled by a chain of Encoder instances:

        %%{init: {'theme': 'dark'}}%%
flowchart LR

   input([Input Bits]) --> n_i[...]
   n_i --> n_a[Encoder N-1] --> n_b[Encoder N] --> n_c[Encoder N+1]  --> n_o[...]
   n_o --> output([Coded Bits])

During transmission encoding the processing chain is sequentially executed from left to right, during reception decoding in reverse order.

Within bit streams, Encoder instances sequentially encode block sections of \(K_n\) bits into code sections of \(L_n\) bits. Therefore, the rate of the \(n\)-th Encoder

\[R_n = \frac{K_n}{L_n}\]

is defined as the relation between input and output block length. The pipeline configuration as well as the encoding step execution is managed by the EncoderManager. Provided with a frame of \(K\) input bits, the manager will generate a coded frame of \(L\) bits by sequentially executing all \(N\) configured encoders. Considering a frame of \(K_{\mathrm{Frame}, n}\) input bits to the \(n\)-th encoder within the pipeline, the manager will split the frame into

\[M_n(K_{\mathrm{Frame}, n}) = \left\lceil \frac{K_{\mathrm{Frame}, n}}{K_n} \right\rceil\]

blocks to be encoded independently. The last block will be padded with zeros should it not contain sufficient bits. While this may not be exactly standard-compliant behaviour, it is a necessary simplification to enable arbitrary combinations of encoders. Therefore, the coding rate of the whole pipeline

\[R = \frac{K}{L} = \frac{K}{M_N \cdot R_N}\]

can only be defined recursively considering the number of input blocks \(M_N\) and rate \(R_N\) of the last encoder with in the pipeline, respectively.

class Encoder(manager=None)[source]¶

Bases: ABC, Serializable

Base class of a single coding step within a channel coding pipeline.

Instances of this class represent the \(n\)-th coding step within an EncoderManager configuration, encoding blocks of \(K_n\) bits into blocks of \(L_n\) bits, respectively, therefore achieving a rate of

\[R_n = \frac{K_n}{L_n} \mathrm{.}\]

All inheriting classes represent implementations of coding steps and are required to implement the methods

encode() for encoding blocks during transmission

decode() for decoding blocks during reception

bit_block_size() reporting the input bit block length

code_block_size() reporting the output bit block length

Parameters:: manager (EncoderManager | None) – The coding pipeline configuration this encoder is registered in.

abstract decode(encoded_bits)[source]¶

Decodes a single block of bits.

Bit decoding routine during data reception, decoding a block of \(L_n\) code bits into a block of \(K_n\) data bits.

Parameters:: encoded_bits (ndarray) – A numpy vector of \(L_n\) code bits, representing a single code block to be decoded.
Return type:: ndarray

Returns: A numpy vector of \(K_n\) bits, representing a single data block.

Raises:: ValueError – If the length of encoded_bits does not equal code_block_size().

abstract encode(bits)[source]¶

Encodes a single block of bits.

Bit encoding routine during data transmission, encoding a block of \(K_n\) input bits into a block of \(L_n\) code bits.

Parameters:: bits (ndarray) – A numpy vector of \(K_n\) bits, representing a single bit block to be encoded.
Return type:: ndarray

Returns: A numpy vector of \(L_n\) bits, representing a single code block.

Raises:: ValueError – If the length of bits does not equal bit_block_size().

abstract property bit_block_size: int¶

Data bit block size of a single coding operation.

In other words, the number of input bits within a single code block during transmit encoding, or the number of output bits during receive decoding. Referred to as \(K_n\) within the respective equations.

abstract property code_block_size: int¶

Code bit block size of a single coding operation.

In other words, the number of input bits within a single code block during receive decoding, or the number of output bits during transmit encoding. Referred to as \(L_n\) within the respective equations.

property enabled: bool¶: Is the encoding currently enabled within its chain?

property manager: EncoderManager | None¶

Coding pipeline configuration this encoder is registered in.

Returns: Handle to the coding pipeline.

property rate: float¶

Code rate achieved by this coding step.

Defined as the relation

\[R_n = \frac{K_n}{L_n}\]

between the bit_block_size() \(K_n\) and code_block_size() \(L_n\).

class EncoderManager(modem=None, allow_padding=True, allow_truncating=True)[source]¶

Bases: RandomNode, Serializable

Configuration managing a channel coding pipeline.

Parameters:

modem (BaseModem | None) – Communication modem instance this coding pipeline configuration is attached to. By default, the coding pipeline is considered to be floating.
allow_padding (bool) – Tolerate padding of data bit blocks during encoding. Enabled by default.
allow_truncating (bool) – Tolerate truncating of data code blocks during decoding. Enabled by default.

classmethod Deserialize(process)[source]¶

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:: process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.
Return type:: EncoderManager
Returns:: The deserialized object.

add_encoder(encoder)[source]¶

Parameters:: encoder (Encoder) – The new encoder to be added.
Return type:: None

decode(encoded_bits, num_data_bits=None)[source]¶

Decode a stream of code bits to a stream of plain data bits.

By default, decoding encoded_bits may ignore bits in order to match the next integer multiple of the expected code_block_size.

The resulting data might be cut to match the requested num_data_bits.

Parameters:

encoded_bits (ndarray) – Numpy vector of code bits to be decoded to data bits.
num_data_bits (int | None) – The expected number of resulting data bits.

Return type:

ndarray

Returns: Numpy vector of the resulting data bit stream after decoding.

Raises:

RuntimeError – If num_data_bits is bigger than the resulting data bits after decoding.
RuntimeError – If truncating is required but disabled by allow_truncating.

encode(data_bits, num_code_bits=None)[source]¶

Encode a stream of data bits to a stream of code bits.

By default, the input data_bits will be padded with zeros to match the next integer multiple of the expected Encoder.bit_block_size().

The resulting code will be padded with zeros to match the requested num_code_bits.

Parameters:

data_bits (ndarray) – Numpy vector of data bits to be encoded.
num_code_bits (int | None) – The expected resulting number of code bits.

Return type:

ndarray

Returns: Numpy vector of encoded bits.

Raises:: ValueError – If num_code_bits is smaller than the resulting code bits after encoding.

required_num_data_bits(num_code_bits)[source]¶

Compute the number of input bits required to produce a certain number of output bits.

Parameters:: num_code_bits (int) – The expected number of output bits.
Return type:: int

Returns: The required number of input bits.

serialize(process)[source]¶

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:: process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.
Return type:: None

allow_padding: bool¶: Tolerate padding of data bit blocks during encoding.

allow_truncating: bool¶: Tolerate truncating of data code blocks during decoding.

property bit_block_size: int¶

Data bit block size of a single coding operation.

In other words, the number of input bits within a single code block during transmit encoding, or the number of output bits during receive decoding. Referred to as \(K\) within the respective equations.

property code_block_size: int¶

Code bit block size of a single coding operation.

In other words, the number of input bits within a single code block during receive decoding, or the number of output bits during transmit encoding. Referred to as \(L\) within the respective equations.

property encoders: List[Encoder]¶

List of encoders registered within this pipeline.

List of \(N\) Encoder instances where the \(n\)-th entry represents the \(n\)-th coding operation during transmit encoding, or, inversely, the \(1 + N - n\)-th coding operation during receive decoding.

property modem: BaseModem¶

Communication modem instance this coding pipeline configuration is attached to.

Raises:: RuntimeError – If the encoding configuration is floating, i.e. not attached to a modem.

property rate: float¶

Code rate achieved by this coding pipeline configuration.

Defined as the relation

\[R = \frac{K}{L}\]

between the bit_block_size() \(K\) and code_block_size() \(L\).