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, optional) – 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 (np.ndarray) – A numpy vector of \(L_n\) code bits, representing a single code block to be decoded.
Returns:: A numpy vector of \(K_n\) bits, representing a single data block.
Return type:: np.ndarray
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 (np.ndarray) – A numpy vector of \(K_n\) bits, representing a single bit block to be encoded.
Returns:: A numpy vector of \(L_n\) bits, representing a single code block.
Return type:: np.ndarray
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.

Returns: Number of bits \(K_n\).

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.

Returns: Number of bits \(L_n\).

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\).

Returns:: The code rate \(R_n\)
Return type:: float

yaml_tag: Optional[str] = 'Encoder'#: YAML serialization tag.

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

Bases: RandomNode, Serializable

Configuration managing a channel coding pipeline.

Parameters:

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

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 (np.ndarray) – Numpy vector of code bits to be decoded to data bits.
num_data_bits (int, optional) – The expected number of resulting data bits.

Returns:

Numpy vector of the resulting data bit stream after decoding.

Return type:

np.ndarray

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 (np.ndarray) – Numpy vector of data bits to be encoded.
num_code_bits (int, optional) – The expected resulting number of code bits.

Returns:

Numpy vector of encoded bits.

Return type:

np.ndarray

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.
Returns:: The required number of input bits.
Return type:: int

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.

Returns:: Number of bits \(K\).
Return type:: int

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.

Returns:: Number of bits \(L\).
Return type:: int

property encoders: List[Encoder]#

List of encoders registered within this pipeline.

Returns:: 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.
Return type:: List[Encoder]

property modem: BaseModem#

Communication modem instance this coding pipeline configuration is attached to.

Returns:: Handle to the modem instance.
Return type:: Modem
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\).

Returns:: The code rate \(R\).
Return type:: float