Release v0.12.0

Signed-off-by: The Sionna Team <[email protected]>
NVlabs · Dec 7, 2022 · b2878ed · b2878ed
1 parent e8f921a
commit b2878ed
Show file tree

Hide file tree

Showing 99 changed files with 13,375 additions and 2,202 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,110 +0,0 @@
-##
-## 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
-all-tests-tf-2.10.0:
-  image: gitlab-master.nvidia.com:5005/nvresearch-gcml/sionna/test-sionna-tensorflow:2.10.0-gpu-jupyter
-  stage: test
-  script:
-  - nvidia-smi
-  - cd test
-  - pytest --junitxml=report-tf-2.10.0.xml
-  tags: 
-  - test
-  artifacts:
-    when: always
-    reports:
-      junit: test/report-tf-2.10.0.xml
-  when: manual

diff --git a/README.md b/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.10](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04.
+Sionna requires [TensorFlow 2.7-2.10](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.
 
 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.11.0
+    0.12.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.11.0
+    0.12.0
 ```
 
 ## License and Citation

diff --git a/doc/source/api/channel.wireless.rst b/doc/source/api/channel.wireless.rst
@@ -580,7 +580,11 @@ one_ring_corr_mat
 
 References:
    .. [TR38901] 3GPP TR 38.901,
-      “Study on channel model for frequencies from 0.5 to 100 GHz“, Release 16.1
+      "Study on channel model for frequencies from 0.5 to 100 GHz", Release 16.1
+
+   .. [TS38141-1] 3GPP TS 38.141-1
+      "Base Station (BS) conformance testing Part 1: Conducted conformance testing",
+      Release 17
 
    .. [Tse] D. Tse and P. Viswanath, “Fundamentals of wireless communication“,
       Cambridge university press, 2005.

diff --git a/doc/source/api/fec.conv.rst b/doc/source/api/fec.conv.rst
@@ -3,7 +3,7 @@ Convolutional Codes
 
 This module supports encoding of convolutional codes and provides layers for Viterbi [Viterbi]_ and BCJR [BCJR]_ decoding.
 
-While the :class:`~sionna.fec.conv.decoding.ViterbiDecoder` decoding algorithm produces maximum likelihood *sequence* estimations, the :class:`~sionna.fec.conv.decoding.BCJRDecoder` produces the a posterior probability (APP) bit-estimates.
+While the :class:`~sionna.fec.conv.decoding.ViterbiDecoder` decoding algorithm produces maximum likelihood *sequence* estimates, the :class:`~sionna.fec.conv.decoding.BCJRDecoder` produces the maximum a posterior (MAP) bit-estimates.
 
 The following code snippet shows how to set up a rate-1/2, constraint-length-3 :class:`~sionna.fec.conv.encoding.ConvEncoder` in two alternate ways and a corresponding :class:`~sionna.fec.conv.decoding.ViterbiDecoder` or :class:`~sionna.fec.conv.decoding.BCJRDecoder`. You can find further examples in the `Channel Coding Tutorial Notebook <../examples/5G_Channel_Coding_Polar_vs_LDPC_Codes.html>`_.
 
@@ -16,11 +16,16 @@ Setting-up:
    # or
    encoder = ConvEncoder(gen_poly=['101', '111']) # or polynomial can be used as input directly
 
-   # Viterbi decoding
+   # --- Viterbi decoding ---
    decoder = ViterbiDecoder(gen_poly=encoder.gen_poly) # polynomial used in encoder
+   # or just reference to the encoder
+   decoder = ViterbiDecoder(encoder=encoder) # the code parameters are infered from the encoder
 
-   # or BCJR decoding
-   decoder = BCJRDecoder(gen_poly=encoder.gen_poly) # polynomial used in encoder
+   # --- or BCJR decoding ---
+   decoder = BCJRDecoder(gen_poly=encoder.gen_poly, algorithm="map") # polynomial used in encoder
+
+   # or just reference to the encoder
+   decoder = BCJRDecoder(encoder=encoder, algorithm="map") # the code parameters are infered from the encoder
 
 
 Running the encoder / decoder:
@@ -75,12 +80,13 @@ polynomial_selector
 .. autofunction:: sionna.fec.conv.utils.polynomial_selector
 
 
+
 References:
-   .. [Viterbi] A. Viterbi "Error bounds for convolutional codes and an
-      asymptotically optimum decoding algorithm", IEEE Trans Inf Theory, 1967.
+   .. [Viterbi] A. Viterbi, "Error bounds for convolutional codes and an
+      asymptotically optimum decoding algorithm", IEEE Trans. Inf. Theory, 1967.
 
-   .. [BCJR]  L. Bahl, J. Cocke, F. Jelinek, und J. Raviv "Optimal Decoding
-      of Linear Codes for Minimizing Symbol Error Rate", IEEE Trans Inf
+   .. [BCJR]  L. Bahl, J. Cocke, F. Jelinek, und J. Raviv, "Optimal Decoding
+      of Linear Codes for Minimizing Symbol Error Rate", IEEE Trans. Inf.
       Theory, March 1974.
 
    .. [Moon] Todd. K. Moon, "Error Correction Coding: Mathematical

diff --git a/doc/source/api/fec.ldpc.rst b/doc/source/api/fec.ldpc.rst
@@ -32,8 +32,8 @@ Now, the encoder and decoder can be used by:
    # u_hat contains the estimated information bits and has shape [...,k].
    u_hat = decoder(llr)
 
-Encoder
-*******
+LDPC Encoder
+************
 
 LDPC5GEncoder
 -------------
@@ -42,15 +42,8 @@ LDPC5GEncoder
    :members:
    :exclude-members: call, build
 
-AllZeroEncoder
---------------
-
-.. autoclass:: sionna.fec.ldpc.encoding.AllZeroEncoder
-   :members:
-   :exclude-members: call, build
-
-Decoder
-*******
+LDPC Decoder
+************
 
 LDPCBPDecoder
 -------------

diff --git a/doc/source/api/fec.linear.rst b/doc/source/api/fec.linear.rst
@@ -0,0 +1,80 @@
+Linear Codes
+############
+
+This package provides generic support for binary linear block codes.
+
+For encoding, a universal :class:`~sionna.fec.linear.LinearEncoder` is available and can be initialized with either a generator or parity-check matrix. The matrix must be binary and of full rank.
+
+For decoding, :class:`~sionna.fec.linear.OSDecoder` implements the
+ordered-statistics decoding (OSD) algorithm [Fossorier]_ which provides close to
+maximum-likelihood (ML) estimates for a sufficiently large order of the decoder.
+Please note that OSD is highly complex and not feasible for all code lengths.
+
+*Remark:* As this package provides support for generic encoding and decoding
+(including Polar and LDPC codes), it cannot rely on code specific
+optimizations. To benefit from an optimized decoder and keep the complexity as low as possible, please use the code specific enc-/decoders whenever available.
+
+The encoder and decoder can be set up as follows:
+
+.. code-block:: Python
+
+   pcm, k, n, coderate = load_parity_check_examples(pcm_id=1) # load example code
+
+   # or directly import an external parity-check matrix in alist format
+   al = load_alist(path=filename)
+   pcm, k, n, coderate = alist2mat(al)
+
+   # encoder can be directly initialized with the parity-check matrix
+   encoder = LinearEncoder(enc_mat=pcm, is_pcm=True)
+
+   # decoder can be initialized with generator or parity-check matrix
+   decoder = OSDecoder(pcm, t=4, is_pcm=True) # t is the OSD order
+
+   # or instantiated from a specific encoder
+   decoder = OSDecoder(encoder=encoder, t=4) # t is the OSD order
+
+We can now run the encoder and decoder:
+
+.. code-block:: Python
+
+   # u contains the information bits to be encoded and has shape [...,k].
+   # c contains codeword bits and has shape [...,n]
+   c = encoder(u)
+
+   # after transmission LLRs must be calculated with a demapper
+   # let's assume the resulting llr_ch has shape [...,n]
+   c_hat = decoder(llr_ch)
+
+
+Encoder
+*******
+
+LinearEncoder
+-------------
+.. autoclass:: sionna.fec.linear.LinearEncoder
+   :members:
+   :exclude-members: call, build
+
+AllZeroEncoder
+--------------
+.. autoclass:: sionna.fec.linear.AllZeroEncoder
+   :members:
+   :exclude-members: call, build
+
+Decoder
+*******
+
+OSDecoder
+---------
+.. autoclass:: sionna.fec.linear.OSDecoder
+   :members:
+   :exclude-members: call, build
+
+References:
+   .. [Fossorier] M. Fossorier, S. Lin, "Soft-Decision Decoding of Linear
+                  Block Codes Based on Ordered Statistics", IEEE Trans. Inf.
+                  Theory, vol. 41, no.5, 1995.
+
+   .. [Stimming_LLR_OSD] A.Balatsoukas-Stimming, M. Parizi, A. Burg,
+                         "LLR-Based Successive Cancellation List Decoding
+                         of Polar Codes." IEEE Trans Signal Processing, 2015.
diff --git a/doc/source/api/fec.rst b/doc/source/api/fec.rst
@@ -41,6 +41,7 @@ All this--and much more--can be explored within the Sionna FEC module.
 .. toctree::
    :maxdepth: 3
 
+   fec.linear
    fec.ldpc
    fec.polar
    fec.conv

diff --git a/doc/source/api/fec.turbo.rst b/doc/source/api/fec.turbo.rst
@@ -9,7 +9,7 @@ decoders are composed of the :class:`~sionna.fec.conv.encoding.ConvEncoder` and
 Please note that various notations are used in literature to represent the
 generator polynomials for the underlying convolutional codes. For simplicity,
 :class:`~sionna.fec.turbo.encoding.TurboEncoder` only accepts the binary
-format, i.e., `10011` for the generator polynomial which corresponds to the
+format, i.e., `10011`, for the generator polynomial which corresponds to the
 polynomial :math:`1 + D^3 + D^4`.
 
 The following code snippet shows how to set-up a rate-1/3, constraint-length-4 :class:`~sionna.fec.turbo.encoding.TurboEncoder` and the corresponding :class:`~sionna.fec.turbo.decoding.TurboDecoder`.
@@ -27,11 +27,12 @@ Setting-up:
                           rate=1/3, # Rate of the desired Turbo code
                           terminate=False) # Do not terminate the constituent convolutional encoders
 
+   # the decoder can be initialized with a reference to the encoder
    decoder = TurboDecoder(encoder,
                           num_iter=6, # Number of iterations between component BCJR decoders
+                          algorithm="map", # can be also "maxlog"
                           hard_out=True) # hard_decide output
 
-
 Running the encoder / decoder:
 
 .. code-block:: Python

diff --git a/doc/source/api/fec.utils.rst b/doc/source/api/fec.utils.rst
@@ -4,19 +4,15 @@ 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
@@ -25,7 +21,7 @@ Note that many research projects provide their parity-check matrices in the  `al
    al = load_alist(path=filename)
    pcm, k, n, coderate = alist2mat(al)
 
-   # the encoder can be directly initialized with a parity-check matrix
+   # the linear 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
@@ -48,12 +44,6 @@ Note that many research projects provide their parity-check matrices in the  `al
    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
@@ -183,6 +173,10 @@ int2bin_tf
 ----------
 .. autofunction:: sionna.fec.utils.int2bin_tf
 
+int_mod_2
+---------
+.. autofunction:: sionna.fec.utils.int_mod_2
+
 llr2mi
 ------
 .. autofunction:: sionna.fec.utils.llr2mi