Scrambling

The Scrambler module allows to (pseudo) randomly flip bits in a binary sequence or the signs of a real-valued sequence, respectively. The Descrambler implement the corresponding descrambling operation.

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

Further, the TB5GScrambler enables 5G NR compliant scrambling as specified in [3GPPTS38211_scr].

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

# set-up system
scrambler = Scrambler(seed=1234, # an explicit seed can be provided
                     binary=True) # indicate if bits shall be flipped

descrambler = Descrambler(scrambler=scrambler) # connect scrambler and descrambler

# --- simplified usage with fixed seed ---
# c has arbitrary shape and contains 0s and 1s (otherwise set binary=False)
c_scr = scrambler(c)
# descramble to reconstruct the original order
c_descr = descrambler(c_scr)

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

c_scr = scrambler([c, s])
c_descr = descrambler([c_scr, s])
class sionna.phy.fec.scrambling.Scrambler(seed=None, keep_batch_constant=False, binary=True, sequence=None, keep_state=True, precision=None, **kwargs)[source]

Randomly flips the state/sign of a sequence of bits or LLRs, respectively.

Parameters:

  • seed (None (default) | int) – Defaults to None. Defines the initial state of the pseudo random generator to generate the scrambling sequence. If None, a random integer will be generated. Only used when called with keep_state is True.

  • keep_batch_constant (bool, (default False)) – If True, all samples in the batch are scrambled with the same scrambling sequence. Otherwise, per sample a random sequence is generated.

  • sequence (None | Array of 0s and 1s) – If provided, the seed will be ignored and the explicit scrambling sequence is used. Shape must be broadcastable to x.

  • binary (bool, (default True)) – Indicates whether bit-sequence should be flipped (i.e., binary operations are performed) or the signs should be flipped (i.e., soft-value/LLR domain-based).

  • keep_state (bool, (default True)) – Indicates whether the scrambling sequence should be kept constant.

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

Input:

  • x (tf.float) – Tensor of arbitrary shape.

  • seed (None (default) | 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 scrambler/descrambler pairs (call with same random seed).

  • binary (None (default) | bool) – Overrules the init parameter binary iff explicitly given. Indicates whether bit-sequence should be flipped (i.e., binary operations are performed) or the signs should be flipped (i.e., soft-value/LLR domain-based).

Output:

tf.float – Tensor of same shape as x.

Note

For inverse scrambling, the same scrambler can be re-used (as the values are flipped again, i.e., result in the original state). However, keep_state must be set to True as a new sequence would be generated otherwise.

The scrambler 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. If the seed is provided in the init() function, this fixed seed is used for all calls. However, an explicit seed can be provided during the call function to realize true random states.

Scrambling is typically used to ensure equal likely 0 and 1 for sources with unequal bit probabilities. As we have a perfect source in the simulations, this is not required. However, for all-zero codeword simulations and higher-order modulation, so-called “channel-adaptation” [Pfister03] is required.

property keep_state

Indicates if new random sequences are used per call

property seed

Seed used to generate random sequence

property sequence

Explicit scrambling sequence if provided

class sionna.phy.fec.scrambling.TB5GScrambler(n_rnti=1, n_id=1, binary=True, channel_type='PUSCH', codeword_index=0, precision=None, **kwargs)[source]

5G NR Scrambler for PUSCH and PDSCH channel.

Implements the pseudo-random bit scrambling as defined in [3GPPTS38211_scr] Sec. 6.3.1.1 for the “PUSCH” channel and in Sec. 7.3.1.1 for the “PDSCH” channel.

Only for the “PDSCH” channel, the scrambler can be configured for two codeword transmission mode. Hereby, codeword_index corresponds to the index of the codeword to be scrambled.

If n_rnti are a list of ints, the scrambler assumes that the second last axis contains len( n_rnti ) elements. This allows independent scrambling for multiple independent streams.

Parameters:

  • n_rnti (int | list of ints) – RNTI identifier provided by higher layer. Defaults to 1 and must be in range [0, 65335]. If a list is provided, every list element defines a scrambling sequence for multiple independent streams.

  • n_id (int | list of ints) – Scrambling ID related to cell id and provided by higher layer. Defaults to 1 and must be in range [0, 1023]. If a list is provided, every list element defines a scrambling sequence for multiple independent streams.

  • binary (bool, (default True)) – Indicates whether bit-sequence should be flipped (i.e., binary operations are performed) or the signs should be flipped (i.e., soft-value/LLR domain-based).

  • channel_type (str, 'PUSCH' | 'PDSCH') – Can be either ‘PUSCH’ or ‘PDSCH’.

  • codeword_index (int, 0 | 1) – Scrambler can be configured for two codeword transmission. codeword_index can be either 0 or 1.

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

Input:

  • x (tf.float) – Tensor of arbitrary shape. If n_rnti and n_id are a list, it is assumed that x has shape […,num_streams, n] where num_streams=len( n_rnti ).

  • binary (None (default) | bool) – Overrules the init parameter binary iff explicitly given. Indicates whether bit-sequence should be flipped (i.e., binary operations are performed) or the signs should be flipped (i.e., soft-value/LLR domain-based).

Output:

tf.float – Tensor of same shape as x.

Note

The parameters radio network temporary identifier (RNTI) n_rnti and the datascrambling ID n_id are usually provided be the higher layer protocols.

For inverse scrambling, the same scrambler can be re-used (as the values are flipped again, i.e., result in the original state).

property keep_state

Required for descrambler, is always True for the TB5GScrambler.

class sionna.phy.fec.scrambling.Descrambler(scrambler, binary=True, precision=None, **kwargs)[source]

Descrambler for a given scrambler.

Parameters:

  • scrambler (Scrambler, TB5GScrambler) – Associated Scrambler or TB5GScrambler instance which should be descrambled.

  • binary (bool, (default True)) – Indicates whether bit-sequence should be flipped (i.e., binary operations are performed) or the signs should be flipped (i.e., soft-value/LLR domain-based).

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

Input:

  • x (tf.float) – 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 scrambler/descrambler pairs (call with same random seed).

Output:

tf.float – Tensor of same shape as x.

property scrambler

Associated scrambler instance

References:
[Pfister03]

J. Hou, P. Siegel, L. Milstein, and H. Pfister, “Capacity approaching bandwidth-efficient coded modulation schemes based on low-density parity-check codes,” IEEE Trans. Inf. Theory, Sep. 2003.

[3GPPTS38211_scr] (1,2)

ETSI 3GPP TS 38.211 “Physical channels and modulation”, v.16.2.0, 2020-07.