Interleaving

The interleaver module allows to permute tensors with either pseudo-random permutations or by row/column swapping.

To simplify distributed graph execution (e.g., by running interleaver and deinterleaver in a different sub-graph/device), the interleavers are implemented stateless. Thus, the internal seed cannot be updated on runtime and does not change after the initialization. However, if required, an explicit random seed can be passed as additional input to the interleaver/deinterleaver pair when calling the layer.

The following code snippet shows how to setup and use an instance of the interleaver:

# set-up system
interleaver = RandomInterleaver(seed=1234, # an explicit seed can be provided
                                keep_batch_constant=False, # if True, all samples in the batch are permuted with the same pattern
                                axis=-1) # axis which shall be permuted

deinterleaver = Deinterleaver(interleaver=interleaver) # connect interleaver and deinterleaver

# --- simplified usage with fixed seed ---
# c has arbitrary shape (rank>=2)
c_int = interleaver(c)
# call deinterleaver to reconstruct the original order
c_deint = deinterleaver(c_int)

# --- advanced usage ---
# provide explicit seed if a new random seed should be used for each call
s = tf.random.uniform((), minval=0, maxval=12345678, dtype=tf.int32)

c_int = interleaver([c, s])
c_deint = deinterleaver([c_int, s])
class sionna.phy.fec.interleaving.RowColumnInterleaver(row_depth, axis=-1, inverse=False, precision=None, **kwargs)[source]

Interleaves a sequence of inputs via row/column swapping.

Parameters:

  • row_depth (int) – The row depth, i.e., how many values per row can be stored.

  • axis (int) – The dimension that should be interleaved.

  • inverse (bool, (default False)) – If True, the inverse permutation is performed.

  • precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

x (tf.DType) – Tensor of arbitrary shape and arbitrary dtype.

Output:

tf.DType – Tensor of same shape and dtype as inputs.

Note

If the sequence length is not a multiple of row_depth, additional filler bits are used for the last row that will be removed internally. However, for the last positions the interleaving distance may be slightly degraded.

property axis

Axis to be permuted

property keep_state

Row-column interleaver always uses same internal state.

property perm_seq

Permutation sequence

property perm_seq_inv

Inverse permutation sequence

property row_depth

Row depth of the row-column interleaver

class sionna.phy.fec.interleaving.RandomInterleaver(seed=None, keep_batch_constant=True, inverse=False, keep_state=True, axis=-1, precision=None, **kwargs)[source]

Random interleaver permuting a sequence of input symbols.

Parameters:

  • seed (int) – Integer defining the random seed used if option keep_state is True.

  • keep_batch_constant (bool, (default True)) – If set to True each sample in the batch uses the same permutation. Otherwise, unique permutations per batch sample are generate (slower).

  • inverse (bool, (default False)) – If True, the inverse permutation is performed.

  • keep_state (bool, (default True)) – If True, the permutation is fixed for multiple calls (defined by seed attribute).

  • axis (int, (default -1)) – The dimension that should be interleaved. First dimension (axis=0) is not allowed.

  • precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

  • x (tf.DType) – Tensor of arbitrary shape and dtype.

  • seed (int) – An integer defining the state of the random number generator. If explicitly given, the global internal seed is replaced by this seed. Can be used to realize random interleaver/deinterleaver pairs (call with same random seed).

Output:

tf.DType – Tensor of same shape and dtype as the input x.

Note

The interleaver block is stateless, i.e., the seed is either random during each call or must be explicitly provided during init/call. This simplifies XLA/graph execution.

This is NOT the 5G interleaver sequence.

property axis

Axis to be permuted

find_s_min(seed, seq_length, s_min_stop=0)[source]

Find S parameter such that π(i)−π(j)>S for all i−j<S. This can be used to find optimized interleaver patterns.

s_min_stop is an additional stopping condition, i.e., stop if current S is already smaller than s_min_stop.

Please note that this is a Numpy utility function and usually not part of the graph.

Input:

  • seed (int) – seed to draw random permutation that shall be analyzed.

  • seq_length (int) – length of permutation sequence to be analyzed.

  • s_min_stop (int, (default 0)) – Enables early stop if already current s_min< s_min_stop .

Output:

float – The S-parameter for the given seed.

property keep_state

Generate new random seed per call

property seed

Seed to generate random sequence

class sionna.phy.fec.interleaving.Turbo3GPPInterleaver(inverse=False, axis=-1, precision=None, **kwargs)[source]

Interleaver for 3GPP Turbo codes

Interleaver as used in the 3GPP Turbo codes [3GPPTS36212_I] and, thus, the maximum length is given as 6144 elements (only for the dimension as specific by axis).

Parameters:

  • inverse (bool, (default False)) – If True, the inverse permutation is performed.

  • axis (int, (default -1)) – The dimension that should be interleaved. First dimension (axis=0) is not allowed.

  • precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

x (tf.DType) – 2+D tensor of arbitrary shape and dtype.

Output:

tf.DType – 2+D tensor of same shape and dtype as the input x.

Note

Note that this implementation slightly deviates from the 3GPP standard [3GPPTS36212_I] in a sense that zero-padding is introduced for cases when the exact interleaver length is not supported by the standard.

property axis

Axis to be permuted

class sionna.phy.fec.interleaving.Deinterleaver(interleaver, precision=None, **kwargs)[source]

Deinterleaver that reverts the interleaver for a given input sequence.

Parameters:

  • interleaver (Interleaver) – Associated Interleaver which shall be deinterleaved by this block. Can be either RandomInterleaver or RowColumnInterleaver.

  • precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs. If set to None, precision is used.

Input:

  • x (tf.DType) – 2+D tensor of arbitrary shape.

  • seed (int) – An integer defining the state of the random number generator. If explicitly given, the global internal seed is replaced by this seed. Can be used to realize random interleaver/deinterleaver pairs (call with same random seed).

Output:

tf.DType – 2+D tensor of same shape and dtype as the input x.

Note

This block provides a wrapper of the inverse interleaver function.

property interleaver

Associated interleaver instance

References:

[3GPPTS36212_I] (1,2)

ETSI 3GPP TS 36.212 “Evolved Universal Terrestrial Radio Access (EUTRA); Multiplexing and channel coding”, v.15.3.0, 2018-09.