Release v0.10.0

Signed-off-by: The Sionna Team <sionna@nvidia.com>

.gitignore

@@ -11,3 +11,4 @@ __pycache__
 dev
 _build
 doc/build
+projects/

.gitlab-ci.yml

@@ -0,0 +1,96 @@
+##
+## Copyright (c) 2021, NVIDIA CORPORATION.  All rights reserved.
+##
+## NVIDIA CORPORATION and its licensors retain all intellectual property
+## and proprietary rights in and to this software, related documentation
+## and any modifications thereto.  Any use, reproduction, disclosure or
+## distribution of this software and related documentation without an express
+## license agreement from NVIDIA CORPORATION is strictly prohibited.
+##
+stages:
+  - build
+  - test
+documentation:
+  image: gitlab-master.nvidia.com:5005/nvresearch-gcml/sionna/python-doc:latest
+  stage: build
+  before_script:
+  - echo 'Cleanup environment...'
+  - git branch -D $CI_DOCUMENTATION_BRANCH || IGNORE_FAILURE=true
+  - git remote remove origin-rw || IGNORE_FAILURE=true
+  - git config --local --replace-all user.name "${CI_GIT_USER_NAME}" || IGNORE_FAILURE=true
+  - git config --local --replace-all user.email "${CI_GIT_USER_EMAIL}" || IGNORE_FAILURE=true
+  script:
+  - echo 'Building documentation...'
+  - make doc
+  - echo 'Fetch current state of documentation branch...'
+  - REPO_URL=`echo $CI_REPOSITORY_URL | cut -d'@' -f 2`
+  - git remote add origin-rw https://$CI_GIT_RW_NAME:$CI_GIT_RW_TOKEN@$REPO_URL 
+  - git remote -v
+  - git fetch origin-rw $CI_DOCUMENTATION_BRANCH
+  - git checkout -b $CI_DOCUMENTATION_BRANCH --track origin-rw/${CI_DOCUMENTATION_BRANCH}
+  - echo 'Replace website folders with updated version...'
+  - rm -rf docs
+  - mv doc/build/html docs
+  - echo 'Commit changes to git'
+  - git add docs
+  - git status
+  - |
+    if git diff --cached --quiet
+    then
+      echo 'No changes detected.'
+    else
+      git commit -m "update Documentation from commit ${CI_COMMIT_SHORT_SHA}"
+      git log -n 1
+      git push origin-rw $CI_DOCUMENTATION_BRANCH
+    fi
+  - echo 'Done.'
+  tags:
+  artifacts:
+    name: "$CI_PROJECT_NAME-docs-$CI_COMMIT_SHORT_SHA"
+    paths:
+    - docs
+  only:
+  - main
+all-tests:
+  image: gitlab-master.nvidia.com:5005/nvresearch-gcml/sionna/test-sionna-tensorflow:2.8.0-gpu-jupyter
+  stage: test
+  script:
+  - nvidia-smi
+  - cd test
+  - pytest --junitxml=report.xml
+  tags: 
+  - test
+  artifacts:
+    when: always
+    reports:
+      junit: test/report.xml
+  only:
+  - main
+all-tests-tf-2.8.2:
+  image: gitlab-master.nvidia.com:5005/nvresearch-gcml/sionna/test-sionna-tensorflow:2.8.2-gpu-jupyter
+  stage: test
+  script:
+  - nvidia-smi
+  - cd test
+  - pytest --junitxml=report-tf-2.8.2.xml
+  tags: 
+  - test
+  artifacts:
+    when: always
+    reports:
+      junit: test/report-tf-2.8.2.xml
+  when: manual
+all-tests-tf-2.9.1:
+  image: gitlab-master.nvidia.com:5005/nvresearch-gcml/sionna/test-sionna-tensorflow:2.9.1-gpu-jupyter
+  stage: test
+  script:
+  - nvidia-smi
+  - cd test
+  - pytest --junitxml=report-tf-2.9.1.xml
+  tags: 
+  - test
+  artifacts:
+    when: always
+    reports:
+      junit: test/report-tf-2.9.1.xml
+  when: manual

DOCKERFILE

@@ -1,4 +1,4 @@
-FROM tensorflow/tensorflow:2.8.0-gpu-jupyter
+FROM tensorflow/tensorflow:2.9.1-gpu-jupyter
 EXPOSE 8888
 COPY . /tmp/
 WORKDIR /tmp/

README.md

@@ -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.6-2.8](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04.
+Sionna requires [TensorFlow 2.6-2.9](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04.
 
 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.9.2
+    0.10.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.8.0
+    0.10.0
 ```
 
 ## License and Citation

doc/source/api/fec.ldpc.rst

@@ -2,7 +2,7 @@ Low-Density Parity-Check (LDPC)
 ===============================
 
 The low-density parity-check (LDPC) code module supports 5G compliant LDPC codes and allows iterative belief propagation (BP) decoding.
-Further, the module supports rate-matching for 5G.
+Further, the module supports rate-matching for 5G and provides a generic linear encoder.
 
 The following code snippets show how to setup and run a rate-matched 5G compliant LDPC encoder and a corresponding belief propagation (BP) decoder.
 

doc/source/api/fec.polar.rst

@@ -94,6 +94,10 @@ generate_rm_code
 ----------------
 .. autofunction:: sionna.fec.polar.utils.generate_rm_code
 
+generate_dense_polar
+--------------------
+.. autofunction:: sionna.fec.polar.utils.generate_dense_polar
+
 References:
    .. [3GPPTS38212] ETSI 3GPP TS 38.212 "5G NR Multiplexing and channel
       coding", v.16.5.0, 2021-03.
@@ -142,3 +146,6 @@ References:
    .. [Ebada_Design] M. Ebada, S. Cammerer, A. Elkelesh and S. ten Brink,
       “Deep Learning-based Polar Code Design”, Annual Allerton
       Conference on Communication, Control, and Computing, 2019.
+
+   .. [Goala_LP] N. Goela, S. Korada, M. Gastpar, "On LP decoding of Polar
+        Codes," IEEE ITW 2010.

doc/source/api/fec.utils.rst

@@ -3,6 +3,86 @@ FEC Utility Functions
 
 This module provides utility functions for the FEC package. It also provides serval functions to simplify EXIT analysis of iterative receivers.
 
+(Binary) Linear Codes
+**************************
+
+Several functions are provided to convert parity-check matrices into generator matrices and vice versa. Please note that currently only binary codes are supported.
+Further, a universal linear encoder is available and can be initialized either with a generator or with a parity-check matrix, respectively.
+
+.. code-block:: Python
+
+   # load example parity-check matrix
+   pcm, k, n, coderate = load_parity_check_examples(pcm_id=3)
+
+   # the encoder can be directly initialized with a parity-check matrix
+   encoder = LinearEncoder(pcm, is_pcm=True)
+
+Note that many research projects provide their parity-check matrices in the  `alist` format [MacKay]_ (e.g., see [UniKL]_). The follwing code snippet provides an example of how to import an external LDPC parity-check matrix from an `alist` file and how to set-up an encoder/decoder.
+
+.. code-block:: Python
+
+   # load external example parity-check matrix in alist format
+   al = load_alist(path=filename)
+   pcm, k, n, coderate = alist2mat(al)
+
+   # the encoder can be directly initialized with a parity-check matrix
+   encoder = LinearEncoder(pcm, is_pcm=True)
+
+   # initalize BP decoder for the given parity-check matrix
+   decoder = LDPCBPDecoder(pcm, num_iter=20)
+
+   # and run simulation with random information bits
+   no = 1.
+   batch_size = 10
+   num_bits_per_symbol = 2
+
+   source = BinarySource()
+   mapper = Mapper("qam", num_bits_per_symbol)
+   channel = AWGN()
+   demapper = Demapper("app", "qam", num_bits_per_symbol)
+
+   u = source([batch_size, k])
+   c = encoder(u)
+   x = mapper(c)
+   y = channel([x, no])
+   llr = demapper([y, no])
+   c_hat = decoder(llr)
+
+LinearEncoder
+-------------
+.. autoclass:: sionna.fec.utils.LinearEncoder
+   :members:
+   :exclude-members: call, build
+
+load_parity_check_examples
+--------------------------
+.. autofunction:: sionna.fec.utils.load_parity_check_examples
+
+alist2mat
+---------
+.. autofunction:: sionna.fec.utils.alist2mat
+
+load_alist
+----------
+.. autofunction:: sionna.fec.utils.load_alist
+
+make_systematic
+---------------
+.. autofunction:: sionna.fec.utils.make_systematic
+
+gm2pcm
+------
+.. autofunction:: sionna.fec.utils.gm2pcm
+
+pcm2gm
+------
+.. autofunction:: sionna.fec.utils.pcm2gm
+
+verify_gm_pcm
+-------------
+.. autofunction:: sionna.fec.utils.verify_gm_pcm
+
+
 EXIT Analysis
 *************
 
@@ -79,18 +159,6 @@ GaussianPriorSource
 -------------------
 .. autoclass:: sionna.fec.utils.GaussianPriorSource
 
-load_parity_check_examples
---------------------------
-.. autofunction:: sionna.fec.utils.load_parity_check_examples
-
-alist2mat
----------
-.. autofunction:: sionna.fec.utils.alist2mat
-
-load_alist
-----------
-.. autofunction:: sionna.fec.utils.load_alist
-
 bin2int
 -------
 .. autofunction:: sionna.fec.utils.bin2int
@@ -128,7 +196,6 @@ j_fun_inv_tf
 .. autofunction:: sionna.fec.utils.j_fun_inv_tf
 
 
-
 References:
    .. [tenBrinkEXIT] S. ten Brink, “Convergence Behavior of Iteratively
       Decoded Parallel Concatenated Codes,” IEEE Transactions on

doc/source/api/mapping.rst

@@ -62,6 +62,24 @@ SymbolDemapperWithPrior
    :exclude-members: call, build
    :members:
 
+SymbolLogits2LLRs
+------------------
+.. autoclass:: sionna.mapping.SymbolLogits2LLRs
+   :exclude-members: call, build
+   :members:
+
+SymbolLogits2LLRsWithPrior
+---------------------------
+.. autoclass:: sionna.mapping.SymbolLogits2LLRsWithPrior
+   :exclude-members: call, build
+   :members:
+
+SymbolLogits2Moments
+----------------------
+.. autoclass:: sionna.mapping.SymbolLogits2Moments
+   :exclude-members: call, build
+   :members:
+
 References:
    .. [3GPPTS38211] ETSI TS 138 211 "5G NR Physical channels and modulation", V16.2.0, Jul. 2020
       https://www.3gpp.org/ftp/Specs/archive/38_series/38.211/38211-h00.zip

doc/source/api/mimo.rst

@@ -60,6 +60,14 @@ lmmse_equalizer
 ---------------
 .. autofunction:: sionna.mimo.lmmse_equalizer
 
+Detection
+**********
+
+MaximumLikelihoodDetector
+---------------------------------
+.. autoclass:: sionna.mimo.MaximumLikelihoodDetector
+   :exclude-members: call, build
+   :members:
 
 References:
         .. [BHS2017] Emil Björnson, Jakob Hoydis and Luca Sanguinetti (2017),

doc/source/api/ofdm.rst

@@ -188,6 +188,11 @@ NearestNeighborInterpolator
 .. autoclass:: sionna.ofdm.NearestNeighborInterpolator
    :members:
 
+LinearInterpolator
+---------------------------
+.. autoclass:: sionna.ofdm.LinearInterpolator
+   :members:
+
 
 Precoding
 *********
@@ -207,3 +212,12 @@ LMMSEEqualizer
 .. autoclass:: sionna.ofdm.LMMSEEqualizer
    :exclude-members: call, build
    :members:
+
+Detection
+**********
+
+MaximumLikelihoodDetector
+----------------------------
+.. autoclass:: sionna.ofdm.MaximumLikelihoodDetector
+   :exclude-members: call, build
+   :members:

doc/source/api/utils.rst

@@ -83,10 +83,18 @@ BinarySource
 ------------
 .. autoclass:: sionna.utils.BinarySource
 
+SymbolSource
+------------
+.. autoclass:: sionna.utils.SymbolSource
+
 QAMSource
 ---------
 .. autoclass:: sionna.utils.QAMSource
 
+PAMSource
+---------
+.. autoclass:: sionna.utils.PAMSource
+
 PlotBER
 -------
 .. autoclass:: sionna.utils.plotting.PlotBER

doc/source/installation.rst

@@ -7,7 +7,7 @@ You can alternatively test them on `Google Colab <https://colab.research.google.
 Although not necessary, we recommend running Sionna in a `Docker container <https://www.docker.com>`_.
 
 .. note::
-    Sionna requires `TensorFlow 2.5 or higher <https://www.tensorflow.org/install>`_ and Python 3.6-3.9.
+    Sionna requires `TensorFlow 2.6-2.9 <https://www.tensorflow.org/install>`_ and Python 3.6-3.9.
     We recommend Ubuntu 20.04.
 
     We refer to the `TensorFlow GPU support tutorial <https://www.tensorflow.org/install/gpu>`_ for GPU support and the required driver setup.
@@ -37,7 +37,7 @@ e.g., using `conda <https://docs.conda.io>`_. On macOS, you need to install `ten
 
     >>> import sionna
     >>> print(sionna.__version__)
-    0.9.2
+    0.10.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>`_.
 
@@ -109,4 +109,4 @@ e.g., using `conda <https://docs.conda.io>`_.
 
     >>> import sionna
     >>> print(sionna.__version__)
-    0.9.2
+    0.10.0