Release v0.15.0

Signed-off-by: The Sionna Team <[email protected]> Co-authored-by: Jakob Hoydis <[email protected]> Co-authored-by: Fayçal Ait-Aoudi <[email protected]> Co-authored-by: Sebastian Cammerer <[email protected]> Co-authored-by: Guillermo Marcus <[email protected]> Co-authored-by: Merlin Nimier-David <[email protected]> Co-authored-by: Benjamin Menküc<[email protected]> Co-authored-by: Taha Yassine <[email protected]> Co-authored-by: Jérome Eertmans <[email protected]> Co-authored-by: Raghav Subbaraman <[email protected]> Merged-by: Guillermo Marcus <[email protected]>
NVlabs · Jul 11, 2023 · 03ced4c · 03ced4c
1 parent 08b1bd2
commit 03ced4c
Show file tree

Hide file tree

Showing 131 changed files with 17,424 additions and 4,479 deletions.
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -47,7 +47,7 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v2
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -58,7 +58,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      uses: github/codeql-action/autobuild@v2
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -72,4 +72,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2
diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml
@@ -0,0 +1,63 @@
+##
+## SPDX-FileCopyrightText: Copyright (c) 2021-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+## SPDX-License-Identifier: Apache-2.0
+##
+
+name: "Lint check"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+env:
+  DEFAULT_PYTHON: "3.11"
+
+jobs:
+  pylint:
+    name: "Pylint"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read            # for checkout to fetch code
+      security-events: write    # for github/codeql-action/upload-sarif to upload SARIF results
+      actions: read             # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Checkout SARIF converter
+        uses: actions/checkout@v3
+        with:
+          repository: gmarcusm/pylint-sarif.git         # use fork with python 3 fixes in the meantime.
+          ref: master
+          path: pylint-sarif
+
+      - name: Set up Python ${{ env.DEFAULT_PYTHON }}
+        id: python
+        uses: actions/[email protected]
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON }}
+          check-latest: true
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip setuptools wheel
+          pip install -U pylint python_jsonschema_objects
+
+      - name: Run pylint
+        run: pylint --exit-zero testcode/
+
+      - name: Generate SARIF report
+        run: python pylint-sarif/pylint2sarif.py testcode/
+        continue-on-error: true
+
+      - name: Upload pylint results to GitHub
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: pylint.sarif
+          wait-for-processing: true
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,6 @@
 .vscode/
 build/
 sionna.egg-info/
-.gitlab/
 __pycache__
 .ipynb_checkpoints
 .pytest_cache
@@ -19,3 +18,4 @@ doc/source/examples/*.ipynb
 projects/
 nohup.out
 /*.obj
+dist/
diff --git a/README.md b/README.md
@@ -9,13 +9,15 @@ Sionna&trade; is an open-source Python library for link-level simulations of dig
 The official documentation can be found [here](https://nvlabs.github.io/sionna/).
 
 ## Installation
+
 Sionna requires [Python](https://www.python.org/) and [Tensorflow](https://www.tensorflow.org/).
-In order to run the tutorial notebooks on your machine, you also need [Jupyter](https://jupyter.org/).
+In order to run the tutorial notebooks on your machine, you also need [JupyterLab](https://jupyter.org/).
 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.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.
-To run the ray tracer on CPU, [LLVM](https://llvm.org) is required.
+Sionna requires [TensorFlow 2.10 or newer](https://www.tensorflow.org/install) and Python 3.6-3.9. We recommend Ubuntu 20.04. Earlier versions of TensorFlow may still work but are not recommended because of known, unpatched CVEs.
+
+To run the ray tracer on CPU, [LLVM](https://llvm.org) is required by DrJit.  Please check the [installation instructions for the LLVM backend](https://drjit.readthedocs.io/en/latest/firststeps-py.html#llvm-backend). 
 
 We refer to the [TensorFlow GPU support tutorial](https://www.tensorflow.org/install/gpu) for GPU support and the required driver setup.
 
@@ -36,7 +38,7 @@ On macOS, you need to install [tensorflow-macos](https://github.com/apple/tensor
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.14.0
+    0.15.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).
@@ -79,7 +81,7 @@ or without GPU:
     make run-docker
 ```
 
-This will immediately launch a Docker image with Sionna installed, running Jupyter on port 8888.
+This will immediately launch a Docker image with Sionna installed, running JupyterLab on port 8888.
 
 4.) Browse through the example notebooks by connecting to [http://127.0.0.1:8888](http://127.0.0.1:8888) in your browser.
 
@@ -95,7 +97,7 @@ We recommend to do this within a [virtual environment](https://docs.python.org/3
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.14.0
+    0.15.0
 ```
 
 ## License and Citation

diff --git a/doc/source/api/channel.discrete.rst b/doc/source/api/channel.discrete.rst
@@ -0,0 +1,70 @@
+========
+Discrete
+========
+
+This module provides layers and functions that implement channel
+models with discrete input/output alphabets.
+
+All channel models support binary inputs :math:`x \in \{0, 1\}` and `bipolar`
+inputs :math:`x \in \{-1, 1\}`, respectively. In the later case, it is assumed
+that each `0` is mapped to `-1`.
+
+The channels can either return discrete values or log-likelihood ratios (LLRs).
+These LLRs describe the channel transition probabilities
+:math:`L(y|X=1)=L(X=1|y)+L_a(X=1)` where :math:`L_a(X=1)=\operatorname{log} \frac{P(X=1)}{P(X=0)}` depends only on the `a priori` probability of :math:`X=1`. These LLRs equal the `a posteriori` probability if :math:`P(X=1)=P(X=0)=0.5`.
+
+Further, the channel reliability parameter :math:`p_b` can be either a scalar
+value or a tensor of any shape that can be broadcasted to the input. This
+allows for the efficient implementation of
+channels with non-uniform error probabilities.
+
+The channel models are based on the `Gumble-softmax trick` [GumbleSoftmax]_ to
+ensure differentiability of the channel w.r.t. to the channel reliability
+parameter. Please see [LearningShaping]_ for further details.
+
+
+Setting-up:
+
+>>> bsc = BinarySymmetricChannel(return_llrs=False, bipolar_input=False)
+
+Running:
+
+>>> x = tf.zeros((128,)) # x is the channel input
+>>> pb = 0.1 # pb is the bit flipping probability
+>>> y = bsc((x, pb))
+
+
+BinaryMemorylessChannel
+=======================
+
+.. autoclass:: sionna.channel.BinaryMemorylessChannel
+   :members:
+   :exclude-members: call, build
+
+BinarySymmetricChannel
+======================
+
+.. autoclass:: sionna.channel.BinarySymmetricChannel
+   :members:
+   :exclude-members: call, build
+
+BinaryErasureChannel
+====================
+
+.. autoclass:: sionna.channel.BinaryErasureChannel
+   :members:
+   :exclude-members: call, build
+
+BinaryZChannel
+==============
+
+.. autoclass:: sionna.channel.BinaryZChannel
+   :members:
+   :exclude-members: call, build
+
+
+References:
+   .. [GumbleSoftmax] E. Jang, G. Shixiang, and Ben Poole. `"Categorical reparameterization with gumbel-softmax,"` arXiv preprint arXiv:1611.01144 (2016).
+
+   .. [LearningShaping] M. Stark, F. Ait Aoudia, and J. Hoydis. `"Joint learning of geometric and probabilistic constellation shaping,"` 2019 IEEE Globecom Workshops (GC Wkshps). IEEE, 2019.
+
diff --git a/doc/source/api/channel.rst b/doc/source/api/channel.rst
@@ -9,3 +9,4 @@ This module provides layers and functions that implement channel models for `wir
 
    channel.wireless
    channel.optical
+   channel.discrete
diff --git a/doc/source/api/rt.rst b/doc/source/api/rt.rst
@@ -6,17 +6,16 @@ The best way to get started is by having a look at the `Sionna Ray Tracing Tutor
 The `Primer on Electromagnetics <../em_primer.html>`_ provides useful background knowledge and various definitions that are used throughout the API documentation.
 
 The most important component of the ray tracer is the :class:`~sionna.rt.Scene`.
-It has methods for the computation of propagation :class:`~sionna.rt.Paths` (:meth:`~sionna.rt.Scene.compute_path`) and :class:`~sionna.rt.CoverageMap` (:meth:`~sionna.rt.Scene.coverage_map`).
+It has methods for the computation of propagation :class:`~sionna.rt.Paths` (:meth:`~sionna.rt.Scene.compute_paths`) and :class:`~sionna.rt.CoverageMap` (:meth:`~sionna.rt.Scene.coverage_map`).
 Sionna has several integrated `Example Scenes`_ that you can use for your own experiments. In this `video <https://youtu.be/7xHLDxUaQ7c>`_, we explain how you can create your own scenes using `OpenStreetMap  <https://www.openstreetmap.org>`_ and `Blender <https://www.blender.org>`_.
-You can preview a scene within a Jupyter notebook (:meth:`~sionna.rt.Scene.preview`) or render it to a file from the viewpoint of a camera (:meth:`~sionna.rt.Scene.render_to_file`).
+You can preview a scene within a Jupyter notebook (:meth:`~sionna.rt.Scene.preview`) or render it to a file from the viewpoint of a camera (:meth:`~sionna.rt.Scene.render` or :meth:`~sionna.rt.Scene.render_to_file`).
 
-Propagation :class:`~sionna.rt.Paths` can be transformed into time-varying channel impulse responses (CIRs) via :class:`~sionna.rt.Paths2CIR`. The CIRs can then be used for link-level simulations in Sionna via the functions :meth:`~sionna.channel.cir_to_time_channel` or :meth:`~sionna.channel.cir_to_ofdm_channel`. Alternatively, you can create a dataset of CIRs that can be used like a channel model with the help of :class:`~sionna.channel.CIRDataset`.
+Propagation :class:`~sionna.rt.Paths` can be transformed into time-varying channel impulse responses (CIRs) via :meth:`~sionna.rt.Paths.cir`. The CIRs can then be used for link-level simulations in Sionna via the functions :meth:`~sionna.channel.cir_to_time_channel` or :meth:`~sionna.channel.cir_to_ofdm_channel`. Alternatively, you can create a dataset of CIRs that can be used like a channel model with the help of :class:`~sionna.channel.CIRDataset`.
 
 The paper `Sionna RT: Differentiable Ray Tracing for Radio Propagation Modeling <https://nvlabs.github.io/sionna/made_with_sionna.html#sionna-rt-differentiable-ray-tracing-for-radio-propagation-modeling>`_ shows how differentiable ray tracing can be used for various optimization tasks. The related `notebooks <https://nvlabs.github.io/sionna/made_with_sionna.html#sionna-rt-differentiable-ray-tracing-for-radio-propagation-modeling>`_ can be a good starting point for your own experiments.
 
 .. include:: rt_scene.rst.txt
 .. include:: rt_paths.rst.txt
-.. include:: rt_paths_2_cir.rst.txt
 .. include:: rt_coverage_map.rst.txt
 .. include:: rt_camera.rst.txt
 .. include:: rt_scene_object.rst.txt
@@ -29,3 +28,4 @@ The paper `Sionna RT: Differentiable Ray Tracing for Radio Propagation Modeling
 References:
    .. [Balanis97] A. Balanis, "Antenna Theory: Analysis and Design," 2nd Edition, John Wiley & Sons, 1997.
    .. [ITUR_P2040_2] ITU-R, “Effects of building materials and structures on radiowave propagation above about 100 MHz“, Recommendation ITU-R P.2040-2
+   .. [SurfaceIntegral] Wikipedia, "`Surface integral <https://en.wikipedia.org/wiki/Surface_integral>`_", accessed Jun. 22, 2023.
diff --git a/doc/source/api/rt_antenna.rst.txt b/doc/source/api/rt_antenna.rst.txt
@@ -42,3 +42,10 @@ tr38901_pattern
 ---------------
 .. autofunction:: sionna.rt.antenna.tr38901_pattern
 
+polarization_model_1
+--------------------
+.. autofunction:: sionna.rt.antenna.polarization_model_1
+
+polarization_model_2
+--------------------
+.. autofunction:: sionna.rt.antenna.polarization_model_2
diff --git a/doc/source/api/rt_coverage_map.rst.txt b/doc/source/api/rt_coverage_map.rst.txt
@@ -1,9 +1,8 @@
 Coverage Maps
 ***************
 
-A coverage map describes the average received power from a specific transmitter at every point on a plane.
-In other words, for a given transmitter, it associates every point on a surface  with the sum of the
-squared amplitudes of the path coefficients :math:`a_i` :eq:`H_final` that a receiver with
+A coverage map describes the received power from a specific transmitter at every point on a plane.
+In other words, for a given transmitter, it associates every point on a surface  with the power that a receiver with
 a specific orientation would observe at this point. A coverage map is not uniquely defined as it depends on
 the transmit and receive arrays and their respective antenna patterns, the transmitter and receiver orientations, as well as
 transmit precoding and receive combining vectors. Moreover, a coverage map is not continuous but discrete because the plane
@@ -23,7 +22,7 @@ CoverageMap
 .. autoclass:: sionna.rt.CoverageMap
    :members:
    :inherited-members:
-   :exclude-members: as_tensor, sample_positions, show
+   :exclude-members: as_tensor, sample_positions, show, to_world
 
 as_tensor
 ---------

diff --git a/doc/source/api/rt_paths.rst.txt b/doc/source/api/rt_paths.rst.txt
@@ -2,22 +2,21 @@ Paths
 ******
 
 A propagation path :math:`i` starts at a transmit antenna and ends at a receive antenna. It is described by
-its transfer matrix :math:`\mathbf{T}_i` and delay :math:`\tau_i`, as well as the
+its channel coefficient :math:`a_i` and delay :math:`\tau_i`, as well as the
 angles of departure :math:`(\theta_{\text{T},i}, \varphi_{\text{T},i})`
 and arrival :math:`(\theta_{\text{R},i}, \varphi_{\text{R},i})`.
-For more detail, see :eq:`H_final`. Antenna patterns are not applied.
+For more detail, see the `Primer on Electromagnetics <../em_primer.html>`_.
 
 In Sionna, paths are computed with the help of the function :meth:`~sionna.rt.Scene.compute_paths` which returns an instance of
 :class:`~sionna.rt.Paths`. Paths can be visualized by providing them as arguments to the functions :meth:`~sionna.rt.Scene.render`, 
 :meth:`~sionna.rt.Scene.render_to_file`, or :meth:`~sionna.rt.Scene.preview`.
 
-Paths can be transformed to channel impulse responses (CIRs) with :class:`~sionna.rt.Paths2CIR` which can
+Channel impulse responses (CIRs) can be obtained with :meth:`~sionna.rt.Paths.cir` which can
 then be used for link-level simulations. This is for example done in the `Sionna Ray Tracing Tutorial <../examples/Sionna_Ray_Tracing_Introduction.html>`_.
-Transmitter and receiver orientations as well as antenna patterns will be applied during this step.
 
 Paths
 -------
 .. autoclass:: sionna.rt.Paths
    :members:
    :inherited-members:
-   :exclude-members: mask, vertices, normals, objects
+   :exclude-members: mask, vertices, normals, objects, clone, merge, finalize, set_los_path_type
diff --git a/doc/source/api/rt_paths_2_cir.rst.txt b/doc/source/api/rt_paths_2_cir.rst.txt
diff --git a/doc/source/api/rt_radio_material.rst.txt b/doc/source/api/rt_radio_material.rst.txt
@@ -9,6 +9,14 @@ permeability :math:`\mu_r`. For more details, see :eq:`epsilon`, :eq:`mu`, :eq:`
 These quantities can possibly depend on the frequency of the incident radio
 wave. Note that Sionna currently only allows non-magnetic materials with :math:`\mu_r=1`.
 
+Additionally, a :class:`~sionna.rt.RadioMaterial` can have an effective roughness (ER)
+associated with it, leading to diffuse reflections (see, e.g., [Degli-Esposti11]_).
+The ER model requires a scattering coefficient :math:`S\in[0,1]` :eq:`scattering_coefficient`,
+a cross-polarization discrimination coefficient :math:`K_x` :eq:`xpd`, as well as a scattering pattern
+:math:`f_\text{s}(\hat{\mathbf{k}}_\text{i}, \hat{\mathbf{k}}_\text{s})` :eq:`lambertian_model`--:eq:`backscattering_model`, such as the
+:class:`~sionna.rt.LambertianPattern` or :class:`~sionna.rt.DirectivePattern`. The meaning of
+these parameters is explained in `Scattering <../em_primer.rst#scattering>`_.
+
 Similarly to scene objects (:class:`~sionna.rt.SceneObject`), all radio
 materials are uniquely identified by their name.
 For example, specifying that a scene object named `"wall"` is made of the
@@ -48,6 +56,8 @@ The table below provides their values which are used in Sionna
 Note that the relative permittivity :math:`\varepsilon_r` and
 conductivity :math:`\sigma` of all materials are updated automatically when
 the frequency is set through the scene's property :class:`~sionna.rt.Scene.frequency`.
+Moreover, by default, the scattering coefficient, :math:`S`, of these materials is set to
+0, leading to no diffuse reflection.
 
 +---------------------------+------------------------------------+--------------------------+-----------------------+
 | Material name             | Real part of relative permittivity | Conductivity [S/m]       | Frequency range (GHz) |
@@ -96,15 +106,22 @@ the frequency is set through the scene's property :class:`~sionna.rt.Scene.frequ
 
 Custom radio materials can be implemented using the
 :class:`~sionna.rt.RadioMaterial` class by specifying a relative permittivity
-:math:`\varepsilon_r`  and a conductivity
-:math:`\sigma`. Note that only non-magnetic materials with :math:`\mu_r=1` are currently allowed. 
-The following code snippet shows how to create a custom radio material:
+:math:`\varepsilon_r` and conductivity :math:`\sigma`, as well as optional
+parameters related to diffuse scattering, such as the scattering coefficient :math:`S`,
+cross-polarization discrimination coefficient :math:`K_x`, and scattering pattern :math:`f_\text{s}(\hat{\mathbf{k}}_\text{i}, \hat{\mathbf{k}}_\text{s})`.
+Note that only non-magnetic materials with :math:`\mu_r=1` are currently allowed. 
+The following code snippet shows how to create a custom radio material. Note that the creation
+of a :class:`~sionna.rt.RadioMaterial` requires that a scene is loaded.
 
 .. code-block:: Python
    
+   load_scene() # Load empty scene
    custom_material = RadioMaterial("my_material",
                                    relative_permittivity=2.0,
-                                   conductivity=5.0)
+                                   conductivity=5.0,
+                                   scattering_coefficient=0.3,
+                                   xpd_coefficient=0.1,
+                                   scattering_pattern=LambertianPattern())
 
 It is also possible to define the properties of a material through a callback
 function that computes the material properties
@@ -139,4 +156,18 @@ RadioMaterial
 -------------
 .. autoclass:: sionna.rt.RadioMaterial
    :members:
-   :exclude-members: core_material, frequency_update, decrease_use, increase_use, scene, is_placeholder
+   :exclude-members: core_material, frequency_update, decrease_use, increase_use, scene, is_placeholder, discard_object_using, add_object_using
+
+ScatteringPattern
+-----------------
+.. autoclass:: sionna.rt.LambertianPattern
+   :members: visualize
+   :exclude-members:
+
+.. autoclass:: sionna.rt.DirectivePattern
+   :members: visualize, alpha_r
+   :exclude-members:
+
+.. autoclass:: sionna.rt.BackscatteringPattern
+   :members: visualize, alpha_i, alpha_r, lambda_, trainable_lambda_
+   :exclude-members: