Release v0.13.0

Co-authored-by: Jakob Hoydis <[email protected]> Co-authored-by: Fayçal Ait-Aoudia <[email protected]> Co-authored-by: Sebastian Cammerer <[email protected]> Co-authored-by: Guillermo Marcus <[email protected]> Co-authored-by: Sebastian Jung <[email protected]> Co-authored-by: Reinhard Wiesmayr <[email protected]> Co-authored-by: Tim Alexander Uhlemann <[email protected]> Merged-by: Guillermo Marcus <[email protected]> Signed-off-by: The Sionna Team <[email protected]>
NVlabs · Feb 24, 2023 · 037be52 · 037be52
1 parent 9e5074a
commit 037be52
Show file tree

Hide file tree

Showing 392 changed files with 13,052 additions and 897 deletions.
diff --git a/.github/ISSUE_TEMPLATE/10-bug_report.md b/.github/ISSUE_TEMPLATE/10-bug_report.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: Bug report
 about: Create a report to help us make this project better

diff --git a/.github/ISSUE_TEMPLATE/20-feature_request.md b/.github/ISSUE_TEMPLATE/20-feature_request.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: Feature request
 about: Suggest an idea for this project

diff --git a/.github/ISSUE_TEMPLATE/90-blank.md b/.github/ISSUE_TEMPLATE/90-blank.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: Blank
 about: Empty issue that is not one of the categories above

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 
 ## Description
 

diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -1,3 +1,8 @@
+##
+## SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+## SPDX-License-Identifier: Apache-2.0
+##
+
 # For most projects, this workflow file will not need changing; you simply need
 # to commit it to your repository.
 #

diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 .vscode/
 build/
 sionna.egg-info/
+.gitlab/
 __pycache__
 .ipynb_checkpoints
 .pytest_cache

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 # Code of Conduct
 
 ## Our Pledge

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: Copyright (c) 2021-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 SPDX-License-Identifier: Apache-2.0
 -->
 # Contributing to Sionna

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: Copyright (c) 2021-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 SPDX-License-Identifier: Apache-2.0
 -->
 # Sionna: An Open-Source Library for Next-Generation Physical Layer Research
@@ -14,7 +14,7 @@ In order to run the tutorial notebooks on your machine, you also need [Jupyter](
 You can alternatively test them on [Google Colab](https://colab.research.google.com/).
 Although not necessary, we recommend running Sionna in a [Docker container](https://www.docker.com).
 
-Sionna requires [TensorFlow 2.7-2.11](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04. TensorFlow 2.6 still works but is not recommended because of known, unpatched CVEs.
+Sionna requires [TensorFlow 2.8-2.11](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04. Earlier versions of TensorFlow (2.7+) still work but are not recommended because of known, unpatched CVEs.
 
 We refer to the [TensorFlow GPU support tutorial](https://www.tensorflow.org/install/gpu) for GPU support and the required driver setup.
 
@@ -35,7 +35,7 @@ On macOS, you need to install [tensorflow-macos](https://github.com/apple/tensor
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.12.1
+    0.13.0
 ```
 
 3.) Once Sionna is installed, you can run the [Sionna "Hello, World!" example](https://nvlabs.github.io/sionna/examples/Hello_World.html), have a look at the [quick start guide](https://nvlabs.github.io/sionna/quickstart.html), or at the [tutorials](https://nvlabs.github.io/sionna/tutorials.html).
@@ -94,7 +94,7 @@ We recommend to do this within a [virtual environment](https://docs.python.org/3
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.12.1
+    0.13.0
 ```
 
 ## License and Citation

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 # Reporting vulnerabilities
 
 Please email reports about any security related issues you find to `[email protected]`.

diff --git a/doc/build_docs.sh b/doc/build_docs.sh
@@ -1,5 +1,5 @@
 ##
-## SPDX-FileCopyrightText: Copyright (c) 2021-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+## SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 ## SPDX-License-Identifier: Apache-2.0
 ##
 set -e

diff --git a/doc/make.bat b/doc/make.bat
@@ -1,3 +1,7 @@
+::
+:: SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+:: SPDX-License-Identifier: Apache-2.0
+::
 @ECHO OFF
 
 pushd %~dp0

diff --git a/doc/source/_ext/made_with_sionna.py b/doc/source/_ext/made_with_sionna.py
@@ -1,5 +1,5 @@
 #
-# SPDX-FileCopyrightText: Copyright (c) 2021-2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
 

diff --git a/doc/source/_static/css/sionna.css b/doc/source/_static/css/sionna.css
@@ -1,3 +1,7 @@
+/*
+SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+*/
 .wy-side-nav-search {
     background-color: #76b900;
 }

diff --git a/doc/source/api/channel.wireless.rst b/doc/source/api/channel.wireless.rst
@@ -326,6 +326,11 @@ cir_to_time_channel
 
 .. autofunction:: sionna.channel.cir_to_time_channel
 
+time_to_ofdm_channel
+--------------------
+
+.. autofunction:: sionna.channel.time_to_ofdm_channel
+
 .. _ofdm-waveform:
 
 Channel with OFDM waveform
@@ -347,7 +352,7 @@ the channel response at the subcarrier frequencies, i.e.,
    \widehat{h}_{u, k, v, l, s, n}
       &= \int_{-\infty}^{+\infty} h_{u, k, v, l}(s,\tau) e^{-j2\pi n \Delta_f \tau} d\tau\\
       &= \sum_{m=0}^{M-1} a_{u, k, v, l, m}(s)
-      e^{j2\pi n \Delta_f \tau_{u, k, v, l, m}}
+      e^{-j2\pi n \Delta_f \tau_{u, k, v, l, m}}
    \end{align}
 
 where :math:`s` is used as time step to indicate that the channel response can

diff --git a/doc/source/api/fec.rst b/doc/source/api/fec.rst
@@ -21,7 +21,7 @@ respectively.
 
 *Remark*: The performance of different coding scheme varies significantly with
 the choice of the exact code and decoding parameters which can be
-found in the notebook `From GSM to 5G - The Evolution of Forward Error Correction <../examples/Evolution_of_FEC.ipynb>`_. Further, the situation also changes for short length codes and results can be found in `5G Channel Coding: Polar vs. LDPC Codes <../examples/5G_Channel_Coding_Polar_vs_LDPC_Codes.ipynb>`_.
+found in the notebook `From GSM to 5G - The Evolution of Forward Error Correction <../examples/Evolution_of_FEC.html>`_. Further, the situation also changes for short length codes and results can be found in `5G Channel Coding: Polar vs. LDPC Codes <../examples/5G_Channel_Coding_Polar_vs_LDPC_Codes.html>`_.
 
 .. figure:: ../figures/FEC_evolution.png
    :align: center

diff --git a/doc/source/api/fec.scrambling.rst b/doc/source/api/fec.scrambling.rst
@@ -1,12 +1,22 @@
 Scrambling
 **********
 
-The scrambler module allows to (pseudo) randomly flip bits in a binary sequence or the signs of a real-valued sequence, respectively.
+The :class:`~sionna.fec.scrambling.Scrambler` module allows to (pseudo)
+randomly flip bits in a binary sequence or the signs of a real-valued sequence,
+respectively. The :class:`~sionna.fec.scrambling.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.
+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.
 
-The following code snippet shows how to setup and use an instance of the scrambler:
+Further, the :class:`~sionna.fec.scrambling.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:
 
 .. code-block:: Python
 
@@ -36,6 +46,12 @@ Scrambler
    :members:
    :exclude-members: call, build
 
+TB5GScrambler
+-------------
+.. autoclass:: sionna.fec.scrambling.TB5GScrambler
+   :members:
+   :exclude-members: call, build
+
 Descrambler
 -----------
 .. autoclass:: sionna.fec.scrambling.Descrambler
@@ -47,3 +63,6 @@ References:
       approaching bandwidth-efficient coded modulation schemes
       based on low-density parity-check codes," IEEE Trans. Inf. Theory,
       Sep. 2003.
+
+   .. [3GPPTS38211_scr] ETSI 3GPP TS 38.211 "Physical channels and modulation",
+      v.16.2.0, 2020-07.
diff --git a/doc/source/api/fec.utils.rst b/doc/source/api/fec.utils.rst
@@ -153,10 +153,6 @@ GaussianPriorSource
 -------------------
 .. autoclass:: sionna.fec.utils.GaussianPriorSource
 
-generate_prng_seq
------------------
-.. autofunction:: sionna.fec.utils.generate_prng_seq
-
 bin2int
 -------
 .. autofunction:: sionna.fec.utils.bin2int
@@ -219,9 +215,3 @@ References:
    .. [MacKay] http://www.inference.org.uk/mackay/codes/alist.html
 
    .. [UniKL] https://www.uni-kl.de/en/channel-codes/
-
-   .. [3GPPTS38211_S] ETSI 3GPP TS 38.211 "Physical channels and modulation",
-      v.16.2.0, 2020-07.
-
-   .. [3GPPTS38212_I] ETSI 3GPP TS 38.212 "5G NR Multiplexing and channel
-      coding", v.16.5.0, 2021-03.
diff --git a/doc/source/api/nr.rst b/doc/source/api/nr.rst
@@ -0,0 +1,155 @@
+5G NR
+#####
+This module provides layers and functions to support simulations of
+5G NR compliant features, in particular, the physical uplink shared channel (PUSCH). It provides implementations of a subset of the physical layer functionalities as described in the 3GPP specifications [3GPP38211]_, [3GPP38212]_, and [3GPP38214]_.
+
+The best way to discover this module's components is by having a look at the `5G NR PUSCH Tutorial <../examples/5G_NR_PUSCH.html>`_.
+
+The following code snippet shows how you can make standard-compliant
+simulations of the 5G NR PUSCH with a few lines of code:
+
+.. code-block:: Python
+
+   # Create a PUSCH configuration with default settings
+   pusch_config = PUSCHConfig()
+
+   # Instantiate a PUSCHTransmitter from the PUSCHConfig
+   pusch_transmitter = PUSCHTransmitter(pusch_config)
+
+   # Create a PUSCHReceiver using the PUSCHTransmitter
+   pusch_receiver = PUSCHReceiver(pusch_transmitter)
+
+   # AWGN channel
+   channel = AWGN()
+
+   # Simulate transmissions over the AWGN channel
+   batch_size = 16
+   no = 0.1 # Noise variance
+
+   x, b = pusch_transmitter(batch_size) # Generate transmit signal and info bits
+
+   y = channel([x, no]) # Simulate channel output
+
+   b_hat = pusch_receiver([x, no]) # Recover the info bits
+
+   # Compute BER
+   print("BER:", compute_ber(b, b_hat).numpy())
+
+The :class:`~sionna.nr.PUSCHTransmitter` and :class:`~sionna.nr.PUSCHReceiver` provide high-level abstractions of all required processing blocks. You can easily modify them according to your needs.
+
+Carrier
+*******
+
+CarrierConfig
+-------------
+.. autoclass:: sionna.nr.CarrierConfig
+   :exclude-members: check_config
+   :members:
+
+Layer Mapping
+*************
+
+LayerMapper
+-----------
+.. autoclass:: sionna.nr.LayerMapper
+   :exclude-members: build, call
+   :members:
+
+LayerDemapper
+-------------
+.. autoclass:: sionna.nr.LayerDemapper
+   :exclude-members: build, call
+   :members:
+
+
+PUSCH
+*****
+
+PUSCHConfig
+-----------
+.. autoclass:: sionna.nr.PUSCHConfig
+   :exclude-members: check_config, l, l_ref, l_0, l_d, l_prime, n
+   :members:
+
+PUSCHDMRSConfig
+---------------
+.. autoclass:: sionna.nr.PUSCHDMRSConfig
+   :exclude-members: check_config
+   :members:
+
+PUSCHLSChannelEstimator
+-----------------------
+.. autoclass:: sionna.nr.PUSCHLSChannelEstimator
+   :exclude-members: estimate_at_pilot_locations
+   :members:
+
+PUSCHPilotPattern
+-----------------
+.. autoclass:: sionna.nr.PUSCHPilotPattern
+   :inherited-members:
+
+PUSCHPrecoder
+-------------
+.. autoclass:: sionna.nr.PUSCHPrecoder
+   :exclude-members: build, call
+   :members:
+
+PUSCHReceiver
+----------------
+.. autoclass:: sionna.nr.PUSCHReceiver
+   :exclude-members: build, call
+   :members:
+
+PUSCHTransmitter
+----------------
+.. autoclass:: sionna.nr.PUSCHTransmitter
+   :exclude-members: build, call
+   :members:
+
+
+Transport Block
+***************
+
+TBConfig
+--------
+.. autoclass:: sionna.nr.TBConfig
+   :exclude-members:
+   :members:
+
+TBEncoder
+---------
+.. autoclass:: sionna.nr.TBEncoder
+   :exclude-members: build, call
+   :members:
+
+TBDecoder
+---------
+.. autoclass:: sionna.nr.TBDecoder
+   :exclude-members: build, call
+   :members:
+
+Utils
+*****
+
+calculate_tb_size
+-----------------
+.. autofunction:: sionna.nr.utils.calculate_tb_size
+
+generate_prng_seq
+-----------------
+.. autofunction:: sionna.nr.utils.generate_prng_seq
+
+select_mcs
+----------
+.. autofunction:: sionna.nr.utils.select_mcs
+
+
+References:
+   .. [3GPP38211] 3GPP TS 38.211. "NR; Physical channels and modulation."
+
+   .. [3GPP38212] 3GPP TS 38.212. "NR; Multiplexing and channel coding"
+
+   .. [3GPP38214] 3GPP TS 38.214. "NR; Physical layer procedures for data."
+
+
+