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)

Bases: abc.ABC, hermespy.core.factory.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

Parameters

manager (EncoderManager, optional) – The coding pipeline configuration this encoder is registered in.

yaml_tag: Optional[str] = 'Encoder'

YAML serialization tag.

enabled: bool

Enable flag for the encoding within its managed pipeline.

property manager: hermespy.coding.coding.EncoderManager

Coding pipeline configuration this encoder is registered in.

Returns

Handle to the coding pipeline.

Return type

EncoderManager

Raises

RuntimeError – If the encoder is considered floating.

abstract encode(bits)

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 decode(encoded_bits)

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

Return type

int

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

Return type

int

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

class EncoderManager(modem=None, allow_padding=True, allow_truncating=True)

Bases: hermespy.core.factory.Serializable, hermespy.core.random_node.RandomNode

Configuration managing a channel coding pipeline.

Parameters
  • modem (Modem, 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.

yaml_tag: str = 'Encoding'

YAML serialization tag.

allow_padding: bool

Tolerate padding of data bit blocks during encoding.

allow_truncating: bool

Tolerate truncating of data code blocks during decoding.

property modem: hermespy.modem.modem.Modem

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.

add_encoder(encoder)

Register a new encoder instance to this pipeline configuration.

Parameters

encoder (Encoder) – The new encoder to be added.

Return type

None

property encoders: List[hermespy.coding.coding.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]

encode(data_bits, num_code_bits=None)

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.

decode(encoded_bits, num_data_bits=None)

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

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 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

required_num_data_bits(num_code_bits)

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