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:
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
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
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
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
encode()
for encoding blocks during transmissiondecode()
for decoding blocks during receptionbit_block_size()
reporting the input bit block lengthcode_block_size()
reporting the output bit block length
- 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
- 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 equalbit_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 equalcode_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\) andcode_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
- 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.
- 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\) andcode_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