diff --git a/differt/src/differt/scene/sionna.py b/differt/src/differt/scene/sionna.py index 39962de1..ae6bb14b 100644 --- a/differt/src/differt/scene/sionna.py +++ b/differt/src/differt/scene/sionna.py @@ -1,5 +1,5 @@ """ -Provide a compatibility layer with Sionna's scenes. +Provide a compatibility layer with Sionna's scenes :cite:`sionna`. Sionna uses the simple XML-based format from Mitsuba 3. """ diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst new file mode 100644 index 00000000..890447b4 --- /dev/null +++ b/docs/source/api_reference.rst @@ -0,0 +1,8 @@ +API Reference +============= + +.. toctree:: + :maxdepth: 1 + + reference/differt + reference/differt_core diff --git a/docs/source/guides.rst b/docs/source/guides.rst new file mode 100644 index 00000000..94a39b4e --- /dev/null +++ b/docs/source/guides.rst @@ -0,0 +1,11 @@ +Guides +====== + +.. toctree:: + :maxdepth: 1 + + numpy_vs_jax.md + batch_axes.md + notebooks/type_checking + notebooks/performance_tips + notebooks/path_candidates diff --git a/docs/source/index.rst b/docs/source/index.rst index b24de685..88cd6217 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,27 +1,47 @@ DiffeRT: Differentiable Ray Tracing Toolbox for Radio Propagation ================================================================= +DiffeRT is a Python module that aims to make *Differentiable Ray Tracing* accessible +to researchers in radio propagation! + +It is currently developed as part of a PhD, but a lot of work is put into documentating and +testing the tool, so any researcher should be able to understand how to use this tool for +their own research. + +As mentioned on the GitHub page, the current state of the project is still considered to +be under *high-development*, and we welcome any contribution! + +Contents +-------- + .. toctree:: + :caption: Getting Started + :maxdepth: 1 + + installation + +.. toctree:: + :caption: Basic Tutorials :maxdepth: 1 - :caption: Tutorials notebooks/quickstart notebooks/advanced_path_tracing notebooks/plotting_backend notebooks/diffraction notebooks/ray_tracing_at_city_scale - notebooks/multipath .. toctree:: + :caption: Advanced Tutorials :maxdepth: 1 + + notebooks/multipath + +.. toctree:: :caption: Reference + :maxdepth: 2 - reference/differt - reference/differt_core - numpy_vs_jax.md - batch_axes.md - notebooks/type_checking - notebooks/performance_tips - notebooks/path_candidates + API + guides citing references + Report an issue diff --git a/docs/source/installation.md b/docs/source/installation.md new file mode 100644 index 00000000..c2fea3aa --- /dev/null +++ b/docs/source/installation.md @@ -0,0 +1,60 @@ +# Installation + +DiffeRT consists of two Python modules, {mod}`differt` and {mod}`differt_core`, +where the latter is direct dependency of the former, and both share the *exact same version*. + +The main package, {mod}`differt`, uses Python-only code. The core package, {mod}`differt_core`, +even though only containing a very limited set of utitilies, is written in Rust to offer good performances, +especially when reading large files or generating path candidates (see {ref}`path_candidates`). + +Pre-built binaries are available for most platforms, and we recommend users to install DiffeRT with pip. + +## Pip Install + +The recommended installation procedure is with pip: + +```bash +pip install differt +``` + +:::{important} +If you encounter an error with installing from pip, e.g., +because it is missing pre-built binaries for your platform, +please report it as +[an issue in GitHub](https://github.com/jeertmans/DiffeRT/issues)! +::: + +### About JAX + +If you want to leverage the power of your GPU(s) or TPU(s), you may want +to look at [JAX's installation guide](https://jax.readthedocs.io/en/latest/installation.html), +as they provide the necessary information about how to install JAX with support for your target device. + +DiffeRT works seamlessly with JAX regardless of the active devices (i.e, CPU, GPU, or TPU). + +### Optional dependencies + +By default, DiffeRT will only install a limited set of dependencies, and will not include +any plotting backend, for example. + +You may want to install those optional features by using *extras*[^1]: + +- **Plotting backends:** + - `matplotlib`: provide Matplotlib plotting backend; + - `plotly`: provide Plotly plotting backend; + - `vispy`: provide VisPy plotting backend; +- **VisPy-specific:** + - `vispy-backend`: provide a default [backend toolkit for VisPy](https://vispy.org/installation.html); +- **Jupyter support:** + - `jupyter`: provide support for Matplotlib and VisPy interactive plot inside notebooks; +- **Aliases:** + - `all`: alias to `jupyter,matplotlib,plotly,vispy,vispy-backend`; + +[^1]: Extras are installed with `pip install "differt[extra_1,extra_2,...]`. + +## Install from source + +If you consider contributing to DiffeRT (*thanks!*), or you want to on your own +local version, you will probably need to build the project from source. + +TODO. diff --git a/docs/source/notebooks/multipath.ipynb b/docs/source/notebooks/multipath.ipynb index a594f0ba..8d9ed3dd 100644 --- a/docs/source/notebooks/multipath.ipynb +++ b/docs/source/notebooks/multipath.ipynb @@ -102,7 +102,8 @@ "Street canyons are probably one of the most common types of scenarios studied in RT,\n", "due to their simplicity to model, but also important presence in big cities.\n", "\n", - "As we provide a compatibility layer with Sionna scenes, we will simply load the `'simple_street_canyon'` scene.\n", + "As we provide a compatibility layer with Sionna scenes {cite}`sionna`,\n", + "we will simply load the `'simple_street_canyon'` scene.\n", "\n", "You can download all the scenes from the Sionna repository with\n", "{func}`download_sionna_scenes`.\n", diff --git a/docs/source/references.bib b/docs/source/references.bib index 83cced95..cfe97ec7 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -76,6 +76,15 @@ @inproceedings{mpt-eucap2023 doi = {10.23919/EuCAP57121.2023.10132934}, } +@article{sionna, + author = {Hoydis, Jakob and Cammerer, Sebastian and {Ait Aoudia}, Fayçal and Vem, Avinash and Binder, Nikolaus and Marcus, Guillermo and Keller, Alexander}, + title = {Sionna: An Open-Source Library for Next-Generation Physical Layer Research}, + year = {2022}, + month = {mar}, + journal = {arXiv preprint}, + online = {https://arxiv.org/abs/2203.11854}, +} + @book{utd-mcnamara, author = {McNamara, D. and Pistorius, C. and Malherbe, J.}, title = {Introduction to the {{Uniform Geometrical Theory}} of {{Diffraction}}}, diff --git a/pyproject.toml b/pyproject.toml index 78f5399b..6b120625 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,7 +20,7 @@ docs = [ "myst-nb>=0.17.2", "pillow>=10.1.0", "sphinx-autodoc-typehints>=1.23", - "sphinx-book-theme>=1.0.1", + "sphinx-book-theme>=1.1.3", "sphinx-copybutton>=0.5.2", "sphinx-design>=0.5.0", "sphinx-remove-toctrees>=0.0.3", diff --git a/uv.lock b/uv.lock index be562e7b..2ebdb7b2 100644 --- a/uv.lock +++ b/uv.lock @@ -589,18 +589,18 @@ name = "dash" version = "2.18.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "dash-core-components" }, - { name = "dash-html-components" }, - { name = "dash-table" }, - { name = "flask" }, - { name = "importlib-metadata" }, - { name = "nest-asyncio" }, - { name = "plotly" }, - { name = "requests" }, - { name = "retrying" }, - { name = "setuptools" }, - { name = "typing-extensions" }, - { name = "werkzeug" }, + { name = "dash-core-components", marker = "python_full_version < '3.12'" }, + { name = "dash-html-components", marker = "python_full_version < '3.12'" }, + { name = "dash-table", marker = "python_full_version < '3.12'" }, + { name = "flask", marker = "python_full_version < '3.12'" }, + { name = "importlib-metadata", marker = "python_full_version < '3.12'" }, + { name = "nest-asyncio", marker = "python_full_version < '3.12'" }, + { name = "plotly", marker = "python_full_version < '3.12'" }, + { name = "requests", marker = "python_full_version < '3.12'" }, + { name = "retrying", marker = "python_full_version < '3.12'" }, + { name = "setuptools", marker = "python_full_version < '3.12'" }, + { name = "typing-extensions", marker = "python_full_version < '3.12'" }, + { name = "werkzeug", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/79/95/1a276cad4271a1068fc6193553b2e0f44f29115ee4148cc4d189fd640817/dash-2.18.1.tar.gz", hash = "sha256:ffdf89690d734f6851ef1cb344222826ffb11ad2214ab9172668bf8aadd75d12", size = 7155536 } wheels = [ @@ -679,7 +679,7 @@ wheels = [ [[package]] name = "differt" -version = "0.0.21" +version = "0.0.23" source = { editable = "differt" } dependencies = [ { name = "beartype" }, @@ -760,7 +760,7 @@ requires-dist = [ [[package]] name = "differt-core" -version = "0.0.21" +version = "0.0.23" source = { editable = "differt-core" } dependencies = [ { name = "numpy" }, @@ -860,7 +860,7 @@ requires-dist = [ { name = "scipy", marker = "extra == 'tests'", specifier = ">=1.12.0" }, { name = "sphinx", specifier = ">=6,<8" }, { name = "sphinx-autodoc-typehints", marker = "extra == 'docs'", specifier = ">=1.23" }, - { name = "sphinx-book-theme", marker = "extra == 'docs'", specifier = ">=1.0.1" }, + { name = "sphinx-book-theme", marker = "extra == 'docs'", specifier = ">=1.1.3" }, { name = "sphinx-copybutton", marker = "extra == 'docs'", specifier = ">=0.5.2" }, { name = "sphinx-design", marker = "extra == 'docs'", specifier = ">=0.5.0" }, { name = "sphinx-plotly-directive", marker = "extra == 'docs'", specifier = ">=0.1.3" }, @@ -973,11 +973,11 @@ name = "flask" version = "3.0.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "blinker" }, - { name = "click" }, - { name = "itsdangerous" }, - { name = "jinja2" }, - { name = "werkzeug" }, + { name = "blinker", marker = "python_full_version < '3.12'" }, + { name = "click", marker = "python_full_version < '3.12'" }, + { name = "itsdangerous", marker = "python_full_version < '3.12'" }, + { name = "jinja2", marker = "python_full_version < '3.12'" }, + { name = "werkzeug", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/41/e1/d104c83026f8d35dfd2c261df7d64738341067526406b40190bc063e829a/flask-3.0.3.tar.gz", hash = "sha256:ceb27b0af3823ea2737928a4d99d125a06175b8512c445cbd9a9ce200ef76842", size = 676315 } wheels = [ @@ -2325,20 +2325,20 @@ name = "open3d-cpu" version = "0.18.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "addict" }, - { name = "configargparse" }, - { name = "dash" }, - { name = "ipywidgets" }, - { name = "matplotlib" }, - { name = "nbformat" }, - { name = "numpy" }, - { name = "pandas" }, - { name = "pillow" }, - { name = "pyquaternion" }, - { name = "pyyaml" }, - { name = "scikit-learn" }, - { name = "tqdm" }, - { name = "werkzeug" }, + { name = "addict", marker = "python_full_version < '3.12'" }, + { name = "configargparse", marker = "python_full_version < '3.12'" }, + { name = "dash", marker = "python_full_version < '3.12'" }, + { name = "ipywidgets", marker = "python_full_version < '3.12'" }, + { name = "matplotlib", marker = "python_full_version < '3.12'" }, + { name = "nbformat", marker = "python_full_version < '3.12'" }, + { name = "numpy", marker = "python_full_version < '3.12'" }, + { name = "pandas", marker = "python_full_version < '3.12'" }, + { name = "pillow", marker = "python_full_version < '3.12'" }, + { name = "pyquaternion", marker = "python_full_version < '3.12'" }, + { name = "pyyaml", marker = "python_full_version < '3.12'" }, + { name = "scikit-learn", marker = "python_full_version < '3.12'" }, + { name = "tqdm", marker = "python_full_version < '3.12'" }, + { name = "werkzeug", marker = "python_full_version < '3.12'" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/b9/10/7b2a70830b1bd3c57637181e78a7f37a9cfa191a6066e578cf9cf7b0eacd/open3d_cpu-0.18.0-cp310-cp310-manylinux_2_27_x86_64.whl", hash = "sha256:656ed68b4799787dddc61ee555e1c131cf13a17d4bce07244bef16b52b5ee055", size = 102381476 }, @@ -2886,7 +2886,7 @@ name = "pyquaternion" version = "0.9.9" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "numpy" }, + { name = "numpy", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/3d092aa20efaedacb89c3221a92c6491be5b28f618a2c36b52b53e7446c2/pyquaternion-0.9.9.tar.gz", hash = "sha256:b1f61af219cb2fe966b5fb79a192124f2e63a3f7a777ac3cadf2957b1a81bea8", size = 15530 } wheels = [ @@ -3221,7 +3221,7 @@ name = "retrying" version = "1.3.4" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "six" }, + { name = "six", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/ce/70/15ce8551d65b324e18c5aa6ef6998880f21ead51ebe5ed743c0950d7d9dd/retrying-1.3.4.tar.gz", hash = "sha256:345da8c5765bd982b1d1915deb9102fd3d1f7ad16bd84a9700b85f64d24e8f3e", size = 10929 } wheels = [ @@ -3354,10 +3354,10 @@ name = "scikit-learn" version = "1.5.2" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "joblib" }, - { name = "numpy" }, - { name = "scipy" }, - { name = "threadpoolctl" }, + { name = "joblib", marker = "python_full_version < '3.12'" }, + { name = "numpy", marker = "python_full_version < '3.12'" }, + { name = "scipy", marker = "python_full_version < '3.12'" }, + { name = "threadpoolctl", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/37/59/44985a2bdc95c74e34fef3d10cb5d93ce13b0e2a7baefffe1b53853b502d/scikit_learn-1.5.2.tar.gz", hash = "sha256:b4237ed7b3fdd0a4882792e68ef2545d5baa50aca3bb45aa7df468138ad8f94d", size = 7001680 } wheels = [ @@ -3994,7 +3994,7 @@ name = "werkzeug" version = "3.0.4" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "markupsafe" }, + { name = "markupsafe", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/0f/e2/6dbcaab07560909ff8f654d3a2e5a60552d937c909455211b1b36d7101dc/werkzeug-3.0.4.tar.gz", hash = "sha256:34f2371506b250df4d4f84bfe7b0921e4762525762bbd936614909fe25cd7306", size = 803966 } wheels = [