Merge pull request #8 from roflmaostc/improve_docs [skip ci]

Update documentation of loss

Author: roflmaostc

docs/src/plugin_doc.rst

@@ -1,6 +1,6 @@
 .. _plugin_doc:
 
-Plugin documentation
+Documentation
 ====================
 
 Dr.TVAM extends the Mitsuba 3 framework with a few *plugins* that are specific

docs/src/plugin_reference/loss.rst

@@ -1,9 +1,9 @@
 .. _loss:
 
-Objective functions
+Loss function
 ===================
 
-Objective functions are a central element of any inverse problem formulation. We
+Loss functions are a central element of any inverse problem formulation. We
 define ours as children of the base ``Loss`` class, which provides a common
 interface to evaluate the loss. The ``Loss`` class overrides the ``__call__``
 method, which allows to call it as if it were a regular function:
@@ -52,7 +52,8 @@ L2 Loss (``L2Loss``)
 
 This loss function computes the squared error between the predicted and target
 values.
-It requires no additional parameter.
+It requires no additional parameter. We do not recommend using this loss as 
+the ThresholdedLoss provides a better results and control.
 
 Thresholded loss (``ThresholdedLoss``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -66,13 +67,18 @@ predicted volume:
   tl`` are penalized. 
 * Finally, object voxels whose recorded dose is *higher* than ``1.0`` are also
   penalized, to avoid some regions being overexposed. 
+* Additionally, a sparsity loss can be added to increase the overall energy 
+  efficiency of the patterns. We prefer homogenous patterns without 
+  spiking values since those reduce the overall energy of the patterns.
 
 With ``'sum'`` reduction, its full expression is:
 
-.. math::
 
-   L = \sum_{i\in\text{Object}} \operatorname{ReLU}\left(t_u - v_i\right)^K + \sum_{i\notin\text{Object}} \operatorname{ReLU}\left(v_i - t_l\right)^K + \sum_{i\in\text{Object}} \operatorname{ReLU}\left(v_i - 1\right)^K
+.. math::
 
+   L = w_{\text{object}} \cdot \sum_{i\in\text{Object}} \operatorname{ReLU}\left(t_u - v_i\right)^K + w_{\text{void}} \cdot \sum_{i\notin\text{Object}} \operatorname{ReLU}\left(v_i - t_l\right)^K\\ + w_{\text{limit}}\cdot \sum_{i\in\text{Object}} \operatorname{ReLU}\left(v_i - 1\right)^K + w_{\text{sparsity}} \cdot \sum_{p \in \text{patterns}} p^M
+   
+where $v_i$ is the intensity value at voxel $i$.
 This objective function was introduced by Wechsler et al. `[2024]
 <https://opg.optica.org/oe/fulltext.cfm?uri=oe-32-8-14705&id=548744>`_.
 
@@ -89,6 +95,10 @@ It requires the following additional parameters:
     * - ``K``
       - ``int``
       - The power to which to raise the error. Defaults to ``2``.
+    
+    * - ``M``
+      - ``int``
+      - The power to which to raise the pattern values. Defaults to ``4``.
 
     * - ``tl``
       - ``float``
@@ -98,3 +108,19 @@ It requires the following additional parameters:
       - ``float``
       - The upper threshold, in ``[0, 1]``. Defaults to ``0.95``.
 
+    * - ``weight_object``
+      - ``float``
+      - Weight of the object term. Defaults to ``1``.
+
+    * - ``weight_void``
+      - ``float``
+      - Weight of the void term. Defaults to ``1``.
+
+    * - ``weight_limit``
+      - ``float``
+      - Weight of the overpolymerization term. Defaults to ``1``.
+
+    * - ``weight_sparsity``
+      - ``float``
+      - Weight of the sparsity term. Defaults to ``0``.
+