Scrambling

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

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

Further, theTB5GScrambler enables 5G NR compliantscrambling as specified in[3GPPTS38211_scr].

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

# set-up systemscrambler=Scrambler(seed=1234,# an explicit seed can be providedbinary=True)# indicate if bits shall be flippeddescrambler=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 orderc_descr=descrambler(c_scr)# --- advanced usage ---# provide explicite seed if a new random seed should be used for each calls=tf.random.uniform((),minval=0,maxval=12345678,dtype=tf.int32)c_scr=scrambler([c,s])c_descr=descrambler([c_scr,s])
classsionna.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 thepseudo random generator to generate the scrambling sequence.If None, a random integer will be generated. Only usedwhen called withkeep_state is True.

  • keep_batch_constant (bool, (defaultFalse)) – IfTrue, all samples in the batch are scrambled with the samescrambling sequence. Otherwise, per sample a randomsequence is generated.

  • sequence (None |Array of0s and 1s) – If provided, the seed will be ignored and the explicit scramblingsequence is used. Shape must be broadcastable tox.

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

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

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

Input:

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

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

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

Output:

tf.float – Tensor of same shape asx.

Note

For inverse scrambling, the same scrambler can be re-used (as the valuesare flipped again, i.e., result in the original state). However,keep_state must be set toTrue as a new sequence would be generatedotherwise.

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

Scrambling is typically used to ensure equal likely0 and1 forsources with unequal bit probabilities. As we have a perfect source inthe simulations, this is not required. However, for all-zero codewordsimulations and higher-order modulation, so-called “channel-adaptation”[Pfister03] is required.

propertykeep_state

Indicates if new random sequences are used per call

propertyseed

Seed used to generate random sequence

propertysequence

Explicit scrambling sequence if provided

classsionna.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.1for the “PDSCH” channel.

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

Ifn_rnti are a list of ints, the scrambler assumes that the secondlast axis containslen(n_rnti) elements. This allows independentscrambling for multiple independent streams.

Parameters:

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

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

  • binary (bool, (defaultTrue)) – Indicates whether bit-sequence should be flipped(i.e., binary operations are performed) or the signs should beflipped (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 toNone,precision is used.

Input:

  • x (tf.float) – Tensor of arbitrary shape. Ifn_rnti andn_id are alist, it is assumed thatx has shape[…,num_streams, n] wherenum_streams=len(n_rnti).

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

Output:

tf.float – Tensor of same shape asx.

Note

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

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

propertykeep_state

Required for descrambler, is alwaysTrue for the TB5GScrambler.

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

Descrambler for a given scrambler.

Parameters:

  • scrambler (Scrambler,TB5GScrambler) – AssociatedScrambler orTB5GScrambler instance whichshould be descrambled.

  • binary (bool, (defaultTrue)) – Indicates whether bit-sequence should be flipped (i.e., binaryoperations 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 toNone,precision is used.

Input:

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

Output:

tf.float – Tensor of same shape asx.

propertyscrambler

Associated scrambler instance

References:
[Pfister03]

J. Hou, P. Siegel, L. Milstein, and H. Pfister, “Capacityapproaching bandwidth-efficient coded modulation schemesbased 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.