# 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

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.

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.

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