Documentation

README.md

@@ -4,19 +4,27 @@
 
 # misuka
 
-[1]: https://dl.acm.org/doi/pdf/10.1145/3730900
+|  Documentation  |       PyPI      |
+|      :---:      |      :---:      |
+| [![docs][1]][2] | [![pypi][3]][4] |
+
+[1]: https://readthedocs.org/projects/misuka/badge/?version=latest
 [2]: https://misuka.readthedocs.io/en/latest/
+[3]: https://img.shields.io/pypi/v/misuka.svg?color=orange
+[4]: https://pypi.org/project/misuka/
+[5]: https://dl.acm.org/doi/pdf/10.1145/3730900
 
 ## Introduction
 
 misuka is a research-focused room acoustic renderer for forward and inverse sound transport simulation, developed in collaboration between the [Audio Communication Group](https://www.tu.berlin/en/ak) and the [Computer Graphics Group](https://www.cg.tu-berlin.de/) at [TU Berlin](https://www.tu.berlin/).
 
 It is a fully compatible extension to [Mitsuba 3](https://github.com/mitsuba-renderer/mitsuba3), adding plugins for acoustic simulation.
+The renderer is described in [misuka: An Open-Source Differentiable Room Acoustic Renderer](https://doi.org/10.1121/2.0002193).
 
 
 ## Main Features
 
-- **Differentiation**: misuka is a differentiable renderer, meaning that it can compute derivatives of the entire simulation with respect to input parameters such as material properties, emitter and receiver positions, and scene geometry. It implements [Time-Resolved Path Replay Backpropagation][1] for efficient gradient estimation.
+- **Differentiation**: misuka is a differentiable renderer, meaning that it can compute derivatives of the entire simulation with respect to input parameters such as material properties, emitter and receiver positions, and scene geometry. It implements [Time-Resolved Path Replay Backpropagation][5] for efficient gradient estimation.
 
 - **Cross-platform**: misuka has been tested on Linux (``x86_64``), macOS (``arm64``), and Windows (``x86_64``).
 
@@ -34,15 +42,42 @@ You can find tutorials for forward rendering and gradient-based optimization in
 
 ## Installation
 
-misuka can be compiled analogously to Mitsuba 3.
-Please refer the [Mitsuba 3 documentation](https://mitsuba.readthedocs.io/en/latest/src/developer_guide/compiling.html) for instructions.
+We provide pre-compiled binary wheels via PyPI. Installing misuka this way is as simple as running
+
+```
+pip install misuka
+```
+
+on the command line. The Python package includes the following variants by default:
+
+- `scalar_rgb`
+- `cuda_ad_acoustic`
+- `metal_ad_acoustic`
+- `llvm_ad_acoustic`
+
+Additional variants can be enabled by compiling misuka.
+Please refer to the [Developer's Guide](https://misuka.readthedocs.io/en/latest/src/developer_guide/compiling.html) for instructions.
 
 ### Requirements
 
 - `Python >= 3.9`
 - (optional) For computation on the GPU: `Nvidia driver >= 535`
-- (optional) For vectorized / parallel computation on the CPU: `LLVM >= 11.1`
-- (optional) For computation on Apple Silicon GPUs: macOS with a Metal-capable GPU
+- (optional) For vectorized / parallel computation on the CPU: `LLVM >= 15`
+- (optional) For computation on Apple Silicon GPUs: macOS 15 or newer with a Metal-capable GPU
+
+The optional ones are loaded from your system at runtime rather than shipped with misuka.
+See [Runtime requirements](https://misuka.readthedocs.io/en/latest/src/runtime_requirements.html) for how to install them and, where needed, how to point misuka at them.
+
+## License
+
+misuka is licensed under the [PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0), which permits academic and private use.
+Files inherited from Mitsuba 3 remain under the original BSD-3-Clause license.
+See [LICENSE](LICENSE) for the file-level rules.
+
+If you are interested in using misuka commercially, please contact a.jueterbock@tu-berlin.de.
+
+
+## Citation
 
 When using misuka in academic projects, please cite:
 
@@ -63,7 +98,7 @@ When using misuka in academic projects, please cite:
 }
 ```
 
-When using Time-Resolved Path Replay Backpropagation in academic projects, please cite:
+If your work uses Time-Resolved Path Replay Backpropagation, please also cite:
 
 ```bibtex
 @article{acoustic_prb,

docs/_static/external_links_new_tab.js

@@ -0,0 +1,17 @@
+// Open links that leave the misuka documentation in a new tab.
+//
+// Covers both the page body and furo's sidebar, including toctree entries that
+// point at absolute URLs (the upstream Mitsuba links in key_topics.rst and the
+// Mitsuba how-to guides in the sidebar).
+
+document.addEventListener('DOMContentLoaded', function () {
+    document.querySelectorAll('a[href]').forEach(function (link) {
+        // `link.host` is resolved against the current page, so relative links
+        // and in-page anchors compare equal to the current host and are skipped.
+        if (!/^https?:$/.test(link.protocol) || link.host === window.location.host)
+            return;
+
+        link.setAttribute('target', '_blank');
+        link.setAttribute('rel', 'noopener noreferrer');
+    });
+});

docs/_static/theme_overrides.css

@@ -36,7 +36,7 @@ div.sphinxsidebar h4 {
     font-size: 14px;
     font-weight: bold;
     text-transform: uppercase;
-    color: #606060;
+    color: var(--color-foreground-secondary);
 }
 
 .paramtype {
@@ -57,11 +57,11 @@ div.sidebar-wrapper {
 }
 
 .paramstable {
-    background-color: #f0f0f0;
+    background-color: var(--color-background-hover);
 }
 
 .paramstable .row-even {
-    background-color: #f9f9f9;
+    background-color: var(--color-background-secondary);
 }
 
 abbr[title], abbr[data-original-title] {
@@ -92,16 +92,16 @@ div.body td.align-middle {
     vertical-align: middle;
 }
 table.docutils th {
-	border-bottom: 2px solid #AAA;
-	border-top: 2px solid #AAA;
+	border-bottom: 2px solid var(--color-foreground-border);
+	border-top: 2px solid var(--color-foreground-border);
 }
 table.docutils td {
     border: 0;
     padding: 4px 8px 4px 5px;
     line-height: 130%;
 }
 table.docutils {
-    border-bottom: 2px solid #AAA;
+    border-bottom: 2px solid var(--color-foreground-border);
     margin: 0 0 1em 0;
     padding: 0 -0.5em 0 -0.5em;
 }
@@ -127,21 +127,21 @@ a:hover, div.related ul li a:hover, div.body a:hover {
     color: #0071aa;
 }
 h1, h2 {
-	color: #333;
+	color: var(--color-content-foreground);
 }
 
 /* no background for top bar since it's orange */
 div.related ul {
 	background-image: none;
-	background-color: #fff;
+	background-color: var(--color-background-primary);
 }
 
 /* give figures a nice rounded box style */
 div.figure {
 	margin: 20px 0px;
 	padding: 3px 7px;
 	/* padding-top: 10px; */
-	border: 1px solid #DDD;
+	border: 1px solid var(--color-background-border);
 	-webkit-border-radius: 3px;
 	-moz-border-radius: 3px;
 	border-radius: 3px;
@@ -160,11 +160,11 @@ div.figure:target > p.caption,
 div.subfigure:target > p.caption,
 div.figure:target > center > p.caption,
 div.math:target span.eqno {
-    background-color: #FFA;
+    background-color: var(--color-highlight-on-target);
 }
 div.figure:target,
 div.subfigure:target {
-	border: 1px dashed #333;
+	border: 1px dashed var(--color-foreground-border);
 }
 div.figure.compound {
 	padding: 0;
@@ -216,7 +216,7 @@ span:target + h3
 span:target + h2,
 span:target + h1
 {
-	background-color: #FFA;
+	background-color: var(--color-highlight-on-target);
 }
 
 /* description lists */
@@ -236,7 +236,7 @@ dd {
 }
 
 div#bibliography span.brackets {
-    color: #333;
+    color: var(--color-content-foreground);
 }
 
 /* margins for images */
@@ -247,15 +247,23 @@ img {
 }
 
 .sidebar-logo {
-    max-width: 25%;
+    max-width: 70%;
 }
 
-.card-body.text-center {
-    padding: 0.01rem;
+.sidebar-logo-container {
+    margin-bottom: 0;
 }
 
-.theme-toggle-container {
-    display: none;
+.sidebar-brand {
+    padding-bottom: 0;
+}
+
+.sidebar-search-container {
+    margin-top: 1rem;
+}
+
+.card-body.text-center {
+    padding: 0.01rem;
 }
 
 #plugin-reference .toctree-wrapper { column-count: 2; }
@@ -270,42 +278,6 @@ img {
 }
 
 
-/* Override to disable dark theme support in sphinx_tabs */
-@media (prefers-color-scheme: dark) {
-    body[data-theme="auto"] .page .sphinx-tabs-panel {
-        color: auto;
-        background-color: white;
-    }
-
-    body[data-theme="auto"] .page .sphinx-tabs-tab {
-        color: #1D5C87;
-        background-color: rgba(255, 255, 255, 0);
-    }
-
-    body[data-theme="auto"] .page .sphinx-tabs-tab[aria-selected="true"] {
-        border-bottom: 1px solid white;
-        background-color: white;
-    }
-}
-
-/* Explicit dark theme styling: okay to keep */
-/*
-body[data-theme="dark"] .sphinx-tabs-panel {
-    color: white;
-    background-color: rgb(50, 50, 50);
-  }
-
-  body[data-theme="dark"] .sphinx-tabs-tab {
-    color: white;
-    background-color: rgba(255, 255, 255, 0.05);
-  }
-
-  body[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"] {
-    border-bottom: 2px solid rgb(50, 50, 50);
-    background-color: rgb(50, 50, 50);
-  }
-*/
-
 /* Copybutton: disable on the "prompt numbering" cell in notebooks */
 .nbinput .prompt.highlight-none .copybtn,
 .nboutput .prompt.highlight-none .copybtn {