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 systeminterleaver=RandomInterleaver(seed=1234,# an explicit seed can be providedkeep_batch_constant=False,# if True, all samples in the batch are permuted with the same patternaxis=-1)# axis which shall be permuteddeinterleaver=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 orderc_deint=deinterleaver(c_int)# --- advanced usage ---# provide explicit seed if a new random seed should be used for each calls=tf.random.uniform((),minval=0,maxval=12345678,dtype=tf.int32)c_int=interleaver([c,s])c_deint=deinterleaver([c_int,s])
- classsionna.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, (defaultFalse)) – IfTrue, the inverse permutation is performed.
precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs.If set toNone,
precisionis 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, additionalfiller bits are used for the last row that will be removed internally.However, for the last positions the interleaving distance may beslightly degraded.- propertyaxis
Axis to be permuted
- propertykeep_state
Row-column interleaver always uses same internal state.
- propertyperm_seq
Permutation sequence
- propertyperm_seq_inv
Inverse permutation sequence
- propertyrow_depth
Row depth of the row-column interleaver
- classsionna.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_stateisTrue.keep_batch_constant (bool, (defaultTrue)) – If set to True each sample in the batch uses the same permutation.Otherwise, unique permutations per batch sample are generate (slower).
inverse (bool, (defaultFalse)) – IfTrue, the inverse permutation is performed.
keep_state (bool, (defaultTrue)) – IfTrue, the permutation is fixed for multiple calls (defined by
seedattribute).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 toNone,
precisionis used.
- Input:
x (tf.DType) – Tensor of arbitrary shape and dtype.
seed (int) – An integer defining the state of the random numbergenerator. If explicitly given, the global internal seed isreplaced by this seed. Can be used to realize randominterleaver/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 randomduring each call or must be explicitly provided during init/call.This simplifies XLA/graph execution.
This is NOT the 5G interleaver sequence.
- propertyaxis
Axis to be permuted
- find_s_min(seed,seq_length,s_min_stop=0)[source]
Find\(S\) parameter such that\(\pi(i)-\pi(j)>S\) for all\(i-j<S\). This can be used to find optimized interleaver patterns.
s_min_stopis an additional stopping condition, i.e., stop ifcurrent\(S\) is already smaller thans_min_stop.Please note that this is a Numpy utility function and usually not partof 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.
- propertykeep_state
Generate new random seed per call
- propertyseed
Seed to generate random sequence
- classsionna.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 asspecific by
axis).- Parameters:
inverse (bool, (defaultFalse)) – IfTrue, 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 toNone,
precisionis 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 3GPPstandard[3GPPTS36212_I] in a sense that zero-padding is introducedfor cases when the exact interleaver length is not supported by thestandard.
- propertyaxis
Axis to be permuted
- classsionna.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
RandomInterleaverorRowColumnInterleaver.precision (None (default) | ‘single’ | ‘double’) – Precision used for internal calculations and outputs.If set toNone,
precisionis used.
- Input:
x (tf.DType) – 2+D tensor of arbitrary shape.
seed (int) – An integer defining the state of the random numbergenerator. If explicitly given, the global internal seed isreplaced by this seed. Can be used to realize randominterleaver/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.
- propertyinterleaver
Associated interleaver instance
References: