Release v0.19.0

Signed-off-by: The Sionna Team <[email protected]> Merged-by: Guillermo Marcus <[email protected]> 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: Merlin Nimier-David <[email protected]> Co-authored-by: Lorenzo Maggi <[email protected]>
NVlabs · Sep 30, 2024 · 6a85e1c · 6a85e1c
1 parent 0a4a22e
commit 6a85e1c
Show file tree

Hide file tree

Showing 189 changed files with 16,219 additions and 6,792 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@ sionna.egg-info/
 __pycache__
 .ipynb_checkpoints
 .pytest_cache
+.python-version
 .DS_Store
 .buildinfo
 .Trash-1000
@@ -19,3 +20,4 @@ projects/
 nohup.out
 /*.obj
 dist/
+sionna/system/data
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,4 @@
-recursive-include ./sionna *.csv *.npy *.json *.xml *.ply
+recursive-include sionna *.csv *.npy *.json *.xml *.ply
 #include ./sionna *.csv, *.npy
 prune test
 
diff --git a/Makefile b/Makefile
@@ -16,6 +16,10 @@ install: FORCE
 lint:
 	pylint sionna/
 
+notebook:
+	export SIONNA_NO_PREVIEW=1; \
+	jupyter nbconvert --to notebook --execute --inplace $(file)
+
 run-docker:
 	docker run -p 8888:8888 --privileged=true $(GPU) --env NVIDIA_DRIVER_CAPABILITIES=graphics,compute,utility --rm -it sionna
 

diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ Although not necessary, we recommend running Sionna in a [Docker container](http
 
 Sionna requires [TensorFlow 2.13-2.15](https://www.tensorflow.org/install) and Python 3.8-3.11. We recommend Ubuntu 22.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). 
+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/what.html#backends).
 
 We refer to the [TensorFlow GPU support tutorial](https://www.tensorflow.org/install/gpu) for GPU support and the required driver setup.
 
@@ -38,7 +38,7 @@ On macOS, you need to install [tensorflow-macos](https://github.com/apple/tensor
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.18.0
+    0.19.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).
@@ -97,7 +97,7 @@ We recommend to do this within a [virtual environment](https://docs.python.org/3
 ```
     >>> import sionna
     >>> print(sionna.__version__)
-    0.18.0
+    0.19.0
 ```
 
 ## License and Citation

diff --git a/doc/source/_static/css/sionna.css b/doc/source/_static/css/sionna.css
@@ -10,11 +10,11 @@ SPDX-License-Identifier: Apache-2.0
     background-color: #76b900;
 }
 
-html.writer-html4 .rst-content dl:not(.docutils) .property, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .property {
+html.writer-html4 .rst-content dl:not(.docutils) .property, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property {
     display: block;
 }
 
-html.writer-html4 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) > dt {
+html.writer-html4 .rst-content dl:not(.docutils)>dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt {
     display: table;
     margin: 6px 0;
     font-size: 90%;
@@ -23,15 +23,15 @@ html.writer-html4 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-co
     color: #555;
     border-top: 3px solid #76b900;
     padding: 6px;
-    position:relative
+    position: relative;
 }
 
-html.writer-html4 .rst-content dl:not(.docutils) dl:not(.field-list) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list) > dt {
+html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt {
     margin-bottom: 6px;
     border: none;
     border-left: 3px solid #76b900;
     background: #75b90062;
-    color:#555
+    color: #555;
 }
 
 h3 {

diff --git a/doc/source/api/channel.discrete.rst b/doc/source/api/channel.discrete.rst
@@ -64,7 +64,7 @@ BinaryZChannel
 
 
 References:
-   .. [GumbleSoftmax] E. Jang, G. Shixiang, and Ben Poole. `"Categorical reparameterization with gumbel-softmax,"` arXiv preprint arXiv:1611.01144 (2016).
+   .. [GumbleSoftmax] E\. Jang, G\. Shixiang, and B\. 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.
+   .. [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.optical.rst b/doc/source/api/channel.optical.rst
@@ -127,34 +127,34 @@ time_frequency_vector
 
 
 References:
-   .. [HT1973] R. H. Hardin and F. D. Tappert,
+   .. [HT1973] R\. H\. Hardin and F\. D\. Tappert,
          "Applications of the Split-Step Fourier Method to the Numerical Solution of Nonlinear and Variable Coefficient Wave Equations.",
          SIAM Review Chronicles, Vol. 15, No. 2, Part 1, p 423, 1973.
 
-   .. [FMF1976] J. A. Fleck, J. R. Morris, and M. D. Feit,
+   .. [FMF1976] J\. A\. Fleck, J\. R\. Morris, and M\. D\. Feit,
          "Time-dependent Propagation of High Energy Laser Beams Through the Atmosphere",
          Appl. Phys., Vol. 10, pp 129–160, 1976.
 
-   .. [MFFP2009] N. J. Muga, M. C. Fugihara, M. F. S. Ferreira, and A. N. Pinto,
+   .. [MFFP2009] N\. J\. Muga, M\. C\. Fugihara, M\. F\. S\. Ferreira, and A\. N\. Pinto,
          "ASE Noise Simulation in Raman Amplification Systems",
          Conftele, 2009.
 
-   .. [A2012] G. P. Agrawal,
+   .. [A2012] G\. P\. Agrawal,
          "Fiber-optic Communication Systems",
-         4th ed. Wiley series in microwave and optical engineering 222. New York: Wiley, 2010.
+         4th ed. Wiley Series in Microwave and Optical Engineering 222. New York: Wiley, 2010.
 
-   .. [EKWFG2010] R. J. Essiambre, G. Kramer, P. J. Winzer, G. J. Foschini, and B. Goebel,
+   .. [EKWFG2010] R\. J\. Essiambre, G\. Kramer, P\. J\. Winzer, G\. J\. Foschini, and B\. Goebel,
          "Capacity Limits of Optical Fiber Networks",
          Journal of Lightwave Technology 28, No. 4, 2010.
 
-   .. [BGT2000] D. M. Baney, P. Gallion, and R. S. Tucker,
+   .. [BGT2000] D\. M\. Baney, P\. Gallion, and R\. S\. Tucker,
          "Theory and Measurement Techniques for the Noise Figure of Optical Amplifiers",
          Optical Fiber Technology 6, No. 2, 2000.
 
-   .. [GD1991] C.R. Giles, and E. Desurvire,
+   .. [GD1991] C\. R\. Giles, and E\. Desurvire,
          "Modeling Erbium-Doped Fiber Amplifiers",
          Journal of Lightwave Technology 9, No. 2, 1991.
 
-   .. [WMC1991] P. K. A. Wai, C. R. Menyuk, and H. H. Chen,
+   .. [WMC1991] P\. K\. A\. Wai, C\. R\. Menyuk, and H\. H\. Chen,
          "Stability of Solitons in Randomly Varying Birefringent Fibers",
          Optics Letters, No. 16, 1991.
diff --git a/doc/source/api/channel.wireless.rst b/doc/source/api/channel.wireless.rst
@@ -591,17 +591,17 @@ References:
       "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.
+   .. [Tse] D\. Tse and P\. Viswanath, “Fundamentals of wireless communication“,
+      Cambridge University Press, 2005.
 
-   .. [SoS] C. Xiao, Y. R. Zheng and N. C. Beaulieu, "Novel Sum-of-Sinusoids Simulation Models for Rayleigh and Rician Fading Channels," in IEEE Transactions on Wireless Communications, vol. 5, no. 12, pp. 3667-3679, December 2006, doi: 10.1109/TWC.2006.256990.
+   .. [SoS] C\. Xiao, Y\. R\. Zheng and N\. C\. Beaulieu, "Novel Sum-of-Sinusoids Simulation Models for Rayleigh and Rician Fading Channels," in IEEE Transactions on Wireless Communications, vol. 5, no. 12, pp. 3667-3679, December 2006, doi: 10.1109/TWC.2006.256990.
 
-   .. [MAL2018] Ranjan K. Mallik,
+   .. [MAL2018] R\. K\. Mallik,
          "The exponential correlation matrix: Eigen-analysis and
          applications", IEEE Trans. Wireless Commun., vol. 17, no. 7,
          pp. 4690-4705, Jul. 2018.
 
-   .. [BHS2017] Emil Björnson, Jakob Hoydis and Luca Sanguinetti (2017),
+   .. [BHS2017] E\. Björnson, J\. Hoydis, L\. Sanguinetti (2017),
          `“Massive MIMO Networks: Spectral, Energy, and Hardware Efficiency”
          <https://massivemimobook.com>`_,
          Foundations and Trends in Signal Processing:

diff --git a/doc/source/api/config.rst b/doc/source/api/config.rst
@@ -3,5 +3,5 @@ Configuration
 Sionna's configuration API. It can be used to set global variables which can be used
 by all modules and functions.
 
-.. autoclass:: sionna.Config
-   :members:
+.. autoclass:: sionna.config.Config
+   :members:
diff --git a/doc/source/api/fec.conv.rst b/doc/source/api/fec.conv.rst
@@ -82,12 +82,9 @@ 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
-      Methods and Algorithms", John Wiley & Sons, 2020.
+   .. [Moon] T\. K\. Moon, "Error Correction Coding: Mathematical Methods and Algorithms", John Wiley & Sons, 2020.
diff --git a/doc/source/api/fec.scrambling.rst b/doc/source/api/fec.scrambling.rst
@@ -59,7 +59,7 @@ Descrambler
    :exclude-members: call, build
 
 References:
-   .. [Pfister03] J. Hou, P.Siegel, L. Milstein, and H. Pfister, "Capacity
+   .. [Pfister03] J\. Hou, P\. Siegel, L\. Milstein, and H\. Pfister, "Capacity
       approaching bandwidth-efficient coded modulation schemes
       based on low-density parity-check codes," IEEE Trans. Inf. Theory,
       Sep. 2003.

diff --git a/doc/source/api/fec.turbo.rst b/doc/source/api/fec.turbo.rst
@@ -81,7 +81,7 @@ puncture_pattern
 .. autofunction:: sionna.fec.turbo.utils.puncture_pattern
 
 References:
-   .. [Berrou] C. Berrou, A. Glavieux, P. Thitimajshima, "Near Shannon limit error-correcting coding and decoding: Turbo-codes", IEEE ICC, 1993.
+   .. [Berrou] C\. Berrou, A\. Glavieux, P\. Thitimajshima, "Near Shannon limit error-correcting coding and decoding: Turbo-codes", IEEE ICC, 1993.
 
    .. [3GPPTS36212_Turbo] ETSI 3GPP TS 36.212 "Evolved Universal Terrestrial
       Radio Access (EUTRA); Multiplexing and channel coding", v.15.3.0, 2018-09.

diff --git a/doc/source/api/mimo.rst b/doc/source/api/mimo.rst
@@ -52,6 +52,21 @@ zero_forcing_precoder
 ---------------------
 .. autofunction:: sionna.mimo.zero_forcing_precoder
 
+grid_of_beams_dft_ula
+---------------------
+.. autofunction:: sionna.mimo.grid_of_beams_dft_ula
+
+grid_of_beams_dft
+---------------------
+.. autofunction:: sionna.mimo.grid_of_beams_dft
+
+flatten_precoding_mat
+---------------------
+.. autofunction:: sionna.mimo.flatten_precoding_mat
+
+normalize_precoding_power
+-------------------------
+.. autofunction:: sionna.mimo.normalize_precoding_power
 
 Equalization
 ************
@@ -61,7 +76,7 @@ lmmse_equalizer
 .. autofunction:: sionna.mimo.lmmse_equalizer
 
 mf_equalizer
----------------
+------------
 .. autofunction:: sionna.mimo.mf_equalizer
 
 zf_equalizer
@@ -167,17 +182,17 @@ References:
    .. [CovProperRV] `Covariance matrices of real and imaginary parts <https://en.wikipedia.org/wiki/Complex_random_vector#Covariance_matrices_of_real_and_imaginary_parts>`_,
       Wikipedia, accessed 11 September, 2022.
 
-   .. [YH2015] S. Yang and L. Hanzo, `"Fifty Years of MIMO Detection: The Road to Large-Scale MIMOs"
+   .. [YH2015] S\. Yang and L\. Hanzo, `"Fifty Years of MIMO Detection: The Road to Large-Scale MIMOs"
       <https://ieeexplore.ieee.org/abstract/document/7244171>`_,
       IEEE Communications Surveys & Tutorials, vol. 17, no. 4, pp. 1941-1988, 2015.
 
-   .. [FT2015] W. Fu and J. S. Thompson, `"Performance analysis of K-best detection with adaptive modulation"
+   .. [FT2015] W\. Fu and J\. S\. Thompson, `"Performance analysis of K-best detection with adaptive modulation"
       <https://ieeexplore.ieee.org/abstract/document/7454351>`_, IEEE Int. Symp. Wirel. Commun. Sys. (ISWCS), 2015.
 
-   .. [EP2014] J. Céspedes, P. M. Olmos, M. Sánchez-Fernández, and F. Perez-Cruz,
+   .. [EP2014] J\. Céspedes, P\. M\. Olmos, M\. Sánchez-Fernández, and F\. Perez-Cruz,
       `"Expectation Propagation Detection for High-Order High-Dimensional MIMO Systems" <https://ieeexplore.ieee.org/abstract/document/6841617>`_,
       IEEE Trans. Commun., vol. 62, no. 8, pp. 2840-2849, Aug. 2014.
 
-   .. [CST2011] C. Studer, S. Fateh, and D. Seethaler,
+   .. [CST2011] C\. Studer, S\. Fateh, and D\. Seethaler,
       `"ASIC Implementation of Soft-Input Soft-Output MIMO Detection Using MMSE Parallel Interference Cancellation" <https://ieeexplore.ieee.org/abstract/document/5779722>`_,
       IEEE Journal of Solid-State Circuits, vol. 46, no. 7, pp. 1754–1765, July 2011.
diff --git a/doc/source/api/rt.rst b/doc/source/api/rt.rst
@@ -27,7 +27,7 @@ The paper `Sionna RT: Differentiable Ray Tracing for Radio Propagation Modeling
 .. include:: rt_utils.rst.txt
 
 References:
-   .. [Balanis97] A. Balanis, "Antenna Theory: Analysis and Design," 2nd Edition, John Wiley & Sons, 1997.
+   .. [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.
-   .. [Wiffen2018] F. Wiffen et al., "`Comparison of OTFS and OFDM in Ray Launched sub-6 GHz and mmWave Line-of-Sight Mobility Channels <https://ieeexplore.ieee.org/abstract/document/8580850>`_", Proc. IEEE Int. Sym. Personal, Indoor and Mobil Radio Commun. (PIMRC), Bologna, Italy, Sep. 2018.
+   .. [Wiffen2018] F\. Wiffen et al., "`Comparison of OTFS and OFDM in Ray Launched sub-6 GHz and mmWave Line-of-Sight Mobility Channels <https://ieeexplore.ieee.org/abstract/document/8580850>`_", Proc. IEEE Int. Sym. Personal, Indoor and Mobil Radio Commun. (PIMRC), Bologna, Italy, Sep. 2018.
diff --git a/doc/source/api/rt_coverage_map.rst.txt b/doc/source/api/rt_coverage_map.rst.txt
@@ -1,19 +1,22 @@
 Coverage Maps
-***************
-
-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 coverage map describes a metric, such as path gain, received signal strength
+(RSS), or signal-to-interference-plus-noise ratio (SINR) for 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 channel gain, RSS, or SINR, 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
 needs to be quantized into small rectangular bins.
 
-In Sionna, coverage maps are computed with the help of the function :meth:`~sionna.rt.Scene.coverage_map` which returns an instance of
+In Sionna, coverage maps are computed with the help of the function
+:meth:`sionna.rt.Scene.coverage_map` which returns an instance of
 :class:`~sionna.rt.CoverageMap`. They can be visualized by providing them either as arguments to the functions :meth:`~sionna.rt.Scene.render`,
-:meth:`~sionna.rt.Scene.render_to_file`, and :meth:`~sionna.rt.Scene.preview`, or by using the class method :meth:`~sionna.rt.CoverageMap.show`.
+:meth:`~sionna.rt.Scene.render_to_file`, and :meth:`~sionna.rt.Scene.preview`,
+or by using the class method :meth:`~sionna.rt.CoverageMap.show`.
 
 A very useful feature is :meth:`~sionna.rt.CoverageMap.sample_positions` which allows sampling
-of random positions within the scene that have sufficient coverage from a specific transmitter.
+of random positions within the scene that have sufficient path gain, RSS, or SINR from a specific transmitter.
 This feature is used in the `Sionna Ray Tracing Tutorial <../examples/Sionna_Ray_Tracing_Introduction.html>`_ to generate a dataset of channel impulse responses
 for link-level simulations.
 
@@ -22,4 +25,4 @@ CoverageMap
 .. autoclass:: sionna.rt.CoverageMap
    :members:
    :inherited-members:
-   :exclude-members: to_world
+   :exclude-members: to_world, _pos_to_idx_tile