fix rendering part 1

GiovanniCanali · GiovanniCanali · commit e0fbd3dafade · 2025-03-13T22:31:26.000+01:00
diff --git a/pina/domain/difference_domain.py b/pina/domain/difference_domain.py
@@ -23,11 +23,11 @@ def __init__(self, geometries):
         Initialization of the :class:`Difference` class.
 
         :param list[DomainInterface] geometries: A list of instances of the
-            :class:`~pina.domain.DomainInterface` class on which the difference
-            operation is performed. The first domain in the list serves as the
-            base from which points are sampled, while the remaining domains
-            define the regions to be excluded from the base domain to compute
-            the difference.
+            :class:`~pina.domain.domain_interface.DomainInterface` class on
+            which the difference operation is performed. The first domain in the
+            list serves as the base from which points are sampled, while the
+            remaining domains define the regions to be excluded from the base
+            domain to compute the difference.
 
         :Example:
             >>> # Create two ellipsoid domains
diff --git a/pina/domain/ellipsoid.py b/pina/domain/ellipsoid.py
@@ -26,14 +26,14 @@ def __init__(self, ellipsoid_dict, sample_surface=False):
         .. warning::
             Sampling for dimensions greater or equal to 10 could result in a
             shrinkage of the ellipsoid, which degrades the quality of the
-            samples. For dimensions higher than 10, use other sampling
-            algorithms.
-            .. seealso::
-                **Original reference**: Dezert, Jean, and Musso, Christian.
-                *An efficient method for generating points uniformly distributed
-                in hyperellipsoids.*
-                Proceedings of the Workshop on Estimation, Tracking and Fusion:
-                A Tribute to Yaakov Bar-Shalom. 2001.
+            samples. For dimensions higher than 10, see the following reference.
+        
+        .. seealso::
+            **Original reference**: Dezert, Jean, and Musso, Christian.
+            *An efficient method for generating points uniformly distributed
+            in hyperellipsoids.*
+            Proceedings of the Workshop on Estimation, Tracking and Fusion:
+            A Tribute to Yaakov Bar-Shalom. 2001.
 
         :Example:
             >>> spatial_domain = Ellipsoid({'x':[-1, 1], 'y':[-1,1]})
diff --git a/pina/domain/exclusion_domain.py b/pina/domain/exclusion_domain.py
@@ -25,8 +25,8 @@ def __init__(self, geometries):
         Initialization of the :class:`Exclusion` class.
 
         :param list[DomainInterface] geometries: A list of instances of the
-            :class:`~pina.domain.DomainInterface` class on which the exclusion
-            operation is performed.
+            :class:`~pina.domain.domain_interface.DomainInterface` class on
+            which the exclusion operation is performed.
 
         :Example:
             >>> # Create two ellipsoid domains
diff --git a/pina/domain/intersection_domain.py b/pina/domain/intersection_domain.py
@@ -24,8 +24,8 @@ def __init__(self, geometries):
         Initialization of the :class:`Intersection` class.
 
         :param list[DomainInterface] geometries: A list of instances of the
-            :class:`~pina.domain.DomainInterface` class on which the
-            intersection operation is performed.
+            :class:`~pina.domain.domain_interface.DomainInterface` class on
+            which the intersection operation is performed.
 
         :Example:
             >>> # Create two ellipsoid domains
diff --git a/pina/domain/operation_interface.py b/pina/domain/operation_interface.py
@@ -15,8 +15,8 @@ def __init__(self, geometries):
         Initialization of the :class:`OperationInterface` class.
 
         :param list[DomainInterface] geometries: A list of instances of the
-            :class:`~pina.domain.DomainInterface` class on which the set
-            operation is performed.
+            :class:`~pina.domain.domain_interface.DomainInterface` class on
+            which the set operation is performed.
         """
         # check consistency geometries
         check_consistency(geometries, DomainInterface)
diff --git a/pina/domain/union_domain.py b/pina/domain/union_domain.py
@@ -23,8 +23,8 @@ def __init__(self, geometries):
         Initialization of the :class:`Union` class.
 
         :param list[DomainInterface] geometries: A list of instances of the
-            :class:`~pina.domain.DomainInterface` class on which the union
-            operation is performed.
+            :class:`~pina.domain.domain_interface.DomainInterface` class on
+            which the union operation is performed.
 
         :Example:
             >>> # Create two ellipsoid domains
diff --git a/pina/equation/equation.py b/pina/equation/equation.py
@@ -6,8 +6,9 @@
 class Equation(EquationInterface):
     """
     Implementation of the Equation class. Every ``equation`` passed to a
-    :class:`~pina.condition.Condition` object must be either a :class:`Equation`
-    or a :class:`~pina.equation.SystemEquation` instance.
+    :class:`~pina.condition.condition.Condition` object must be either an
+    instance of :class:`Equation` or
+    :class:`~pina.equation.system_equation.SystemEquation`.
     """
 
     def __init__(self, equation):
@@ -32,10 +33,11 @@ def residual(self, input_, output_, params_=None):
 
         :param LabelTensor input_: Input points where the equation is evaluated.
         :param LabelTensor output_: Output tensor, eventually produced by a
-            :class:`~torch.nn.Module` instance.
+            :class:`torch.nn.Module` instance.
         :param dict params_: Dictionary of unknown parameters, associated with a
-            :class:`~pina.problem.InverseProblem` instance. If the equation is
-            not related to a :class:`~pina.problem.InverseProblem` instance, the
+            :class:`~pina.problem.inverse_problem.InverseProblem` instance.
+            If the equation is not related to a 
+            :class:`~pina.problem.inverse_problem.InverseProblem` instance, the
             parameters must be initialized to ``None``. Default is ``None``.
         :return: The computed residual of the equation.
         :rtype: LabelTensor
diff --git a/pina/equation/equation_factory.py b/pina/equation/equation_factory.py
@@ -28,7 +28,7 @@ def equation(input_, output_):
             :param LabelTensor input_: Input points where the equation is
                 evaluated.
             :param LabelTensor output_: Output tensor, eventually produced by a
-                :class:`~torch.nn.Module` instance.
+                :class:`torch.nn.Module` instance.
             :return: The computed residual of the equation.
             :rtype: LabelTensor
             """
@@ -66,7 +66,7 @@ def equation(input_, output_):
             :param LabelTensor input_: Input points where the equation is
                 evaluated.
             :param LabelTensor output_: Output tensor, eventually produced by a
-                :class:`~torch.nn.Module` instance.
+                :class:`torch.nn.Module` instance.
             :return: The computed residual of the equation.
             :rtype: LabelTensor
             """
@@ -101,7 +101,7 @@ def equation(input_, output_):
             :param LabelTensor input_: Input points where the equation is
                 evaluated.
             :param LabelTensor output_: Output tensor, eventually produced by a
-                :class:`~torch.nn.Module` instance.
+                :class:`torch.nn.Module` instance.
             :return: The computed residual of the equation.
             :rtype: LabelTensor
             """
@@ -136,7 +136,7 @@ def equation(input_, output_):
             :param LabelTensor input_: Input points where the equation is
                 evaluated.
             :param LabelTensor output_: Output tensor, eventually produced by a
-                :class:`~torch.nn.Module` instance.
+                :class:`torch.nn.Module` instance.
             :return: The computed residual of the equation.
             :rtype: LabelTensor
             """
diff --git a/pina/equation/equation_interface.py b/pina/equation/equation_interface.py
@@ -6,6 +6,18 @@
 class EquationInterface(metaclass=ABCMeta):
     """
     Abstract base class for equations.
+
+    Equations in PINA simplify the training process. When defining a problem,
+    each equation passed to a :class:`~pina.condition.condition.Condition`
+    object must be either an :class:`~pina.equation.equation.Equation` or a
+    :class:`~pina.equation.system_equation.SystemEquation` instance.  
+
+    An :class:`~pina.equation.equation.Equation` is a wrapper for a callable
+    function, while :class:`~pina.equation.system_equation.SystemEquation`
+    wraps a list of callable functions. To streamline code writing, PINA
+    provides a diverse set of pre-implemented equations, such as
+    :class:`~pina.equation.equation_factory.FixedValue`,
+    :class:`~pina.equation.equation_factory.FixedGradient`, and many others.
     """
 
     @abstractmethod
@@ -15,9 +27,9 @@ def residual(self, input_, output_, params_):
 
         :param LabelTensor input_: Input points where the equation is evaluated.
         :param LabelTensor output_: Output tensor, eventually produced by a
-            :class:`~torch.nn.Module` instance.
+            :class:`torch.nn.Module` instance.
         :param dict params_: Dictionary of unknown parameters, associated with a
-            :class:`~pina.problem.InverseProblem` instance.
+            :class:`~pina.problem.inverse_problem.InverseProblem` instance.
         :return: The computed residual of the equation.
         :rtype: LabelTensor
         """
diff --git a/pina/equation/system_equation.py b/pina/equation/system_equation.py
@@ -9,8 +9,9 @@
 class SystemEquation(EquationInterface):
     """
     Implementation of the System of Equations. Every ``equation`` passed to a
-    :class:`~pina.condition.Condition` object must be either a :class:`Equation`
-    or a :class:`~pina.equation.SystemEquation` instance.
+    :class:`~pina.condition.condition.Condition` object must be either a
+    :class:`~pina.equation.equation.Equation` or a
+    :class:`~pina.equation.system_equation.SystemEquation` instance.
     """
 
     def __init__(self, list_equation, reduction=None):
@@ -56,10 +57,11 @@ def residual(self, input_, output_, params_=None):
         :param LabelTensor input_: Input points where each equation of the
             system is evaluated.
         :param LabelTensor output_: Output tensor, eventually produced by a
-            :class:`~torch.nn.Module` instance.
+            :class:`torch.nn.Module` instance.
         :param dict params_: Dictionary of unknown parameters, associated with a
-            :class:`~pina.problem.InverseProblem` instance. If the equation is
-            not related to a :class:`~pina.problem.InverseProblem` instance, the
+            :class:`~pina.problem.inverse_problem.InverseProblem` instance.
+            If the equation is not related to a
+            :class:`~pina.problem.inverse_problem.InverseProblem` instance, the
             parameters must be initialized to ``None``. Default is ``None``.
 
         :return: The aggregated residuals of the system of equations.
diff --git a/pina/optim/torch_optimizer.py b/pina/optim/torch_optimizer.py
@@ -15,8 +15,8 @@ def __init__(self, optimizer_class, **kwargs):
         """
         Initialization of the :class:`TorchOptimizer` class.
 
-        :param torch.optim.Optimizer optimizer_class: The PyTorch optimizer
-            class.
+        :param torch.optim.Optimizer optimizer_class: A
+            :class:`torch.optim.Optimizer` class.
         :param dict kwargs: Additional parameters passed to `optimizer_class`,
             see more: <https://pytorch.org/docs/stable/optim.html#algorithms>_.
         """
diff --git a/pina/optim/torch_scheduler.py b/pina/optim/torch_scheduler.py
@@ -21,8 +21,8 @@ def __init__(self, scheduler_class, **kwargs):
         """
         Initialization of the :class:`TorchScheduler` class.
 
-        :param torch.optim.LRScheduler scheduler_class: The PyTorch scheduler
-            class.
+        :param torch.optim.LRScheduler scheduler_class: A
+            :class:`torch.optim.LRScheduler` class.
         :param dict kwargs: Additional parameters passed to `scheduler_class`,
             see more: <https://pytorch.org/docs/stable/optim.html#algorithms>_.
         """
diff --git a/pina/problem/abstract_problem.py b/pina/problem/abstract_problem.py
@@ -188,11 +188,15 @@ def discretise_domain(
 
         .. warning::
             ``random`` is currently the only implemented ``mode`` for all
-            geometries, i.e. ``EllipsoidDomain``, ``CartesianDomain``,
-            ``SimplexDomain``, and geometry compositions ``Union``,
-            ``Difference``, ``Exclusion``, ``Intersection``. The
-            modes ``latin`` or ``lh``,  ``chebyshev``, ``grid`` are only
-            implemented for ``CartesianDomain``.
+            geometries, i.e. :class:`~pina.domain.ellipsoid.EllipsoidDomain`,
+            :class:`~pina.domain.cartesian.CartesianDomain`,
+            :class:`~pina.domain.simplex.SimplexDomain`, and geometry
+            compositions :class:`~pina.domain.union_domain.Union`,
+            :class:`~pina.domain.difference_domain.Difference`,
+            :class:`~pina.domain.exclusion_domain.Exclusion`, and
+            :class:`~pina.domain.intersection_domain.Intersection`.
+            The modes ``latin`` or ``lh``,  ``chebyshev``, ``grid`` are only
+            implemented for :class:`~pina.domain.cartesian.CartesianDomain`.
         """
 
         # check consistecy n, mode, variables, locations
diff --git a/pina/trainer.py b/pina/trainer.py
@@ -34,8 +34,9 @@ def __init__(
         """
         Initialization of the :class:`Trainer` class.
 
-        :param SolverInterface solver: A :class:`~pina.solver.SolverInterface`
-            solver used to solve a :class:`~pina.problem.AbstractProblem`.
+        :param SolverInterface solver: A 
+            :class:`~pina.solver.solver.SolverInterface` solver used to solve a
+            :class:`~pina.problem.abstract_problem.AbstractProblem`.
         :param int batch_size: The number of samples per batch to load.
             If ``None``, all samples are loaded and data is not batched.
             Default is ``None``.
@@ -56,11 +57,10 @@ def __init__(
             transfer to GPU. Default is ``False``.
         :param bool shuffle: Whether to shuffle the data during training.
             Default is ``True``.
-
-        :Keyword Arguments:
-            Additional keyword arguments that specify the training setup.
-            These can be selected from the pytorch-lightning Trainer API
-            <https://lightning.ai/docs/pytorch/stable/common/trainer.html#trainer-class-api>_.
+        :param dict kwargs: Additional keyword arguments that specify the
+            training setup. These can be selected from the `pytorch-lightning
+            Trainer API
+            <https://lightning.ai/docs/pytorch/stable/common/trainer.html#trainer-class-api>`_.
         """
         # check consistency for init types
         self._check_input_consistency(
@@ -132,7 +132,8 @@ def __init__(
     def _move_to_device(self):
         """
         Moves the ``unknown_parameters`` of an instance of
-        :class:`~pina.problem.AbstractProblem` to the :class:`Trainer` device.
+        :class:`~pina.problem.abstract_problem.AbstractProblem` to the
+        :class:`Trainer` device.
         """
         device = self._accelerator_connector._parallel_devices[0]
         # move parameters to device
@@ -205,12 +206,16 @@ def _create_datamodule(
     def train(self, **kwargs):
         """
         Manage the training process of the solver.
+
+        :param dict kwargs: Additional keyword arguments.
         """
         return super().fit(self.solver, datamodule=self.data_module, **kwargs)
 
     def test(self, **kwargs):
         """
         Manage the test process of the solver.
+
+        :param dict kwargs: Additional keyword arguments.
         """
         return super().test(self.solver, datamodule=self.data_module, **kwargs)
 
diff --git a/pina/utils.py b/pina/utils.py
@@ -60,14 +60,14 @@ class or, if ``subclass=True``, whether it is a subclass of the specified
 
 def labelize_forward(forward, input_variables, output_variables):
     """
-    Decorator to enable or disable the use of :class:`~pina.LabelTensor`
-    during the forward pass.
+    Decorator to enable or disable the use of
+    :class:`~pina.label_tensor.LabelTensor` during the forward pass.
 
     :param Callable forward: The forward function of a :class:`torch.nn.Module`.
     :param list[str] input_variables: The names of the input variables of a
-        :class:`~pina.problem.AbstractProblem`.
+        :class:`~pina.problem.abstract_problem.AbstractProblem`.
     :param list[str] output_variables: The names of the output variables of a
-        :class:`~pina.problem.AbstractProblem`.
+        :class:`~pina.problem.abstract_problem.AbstractProblem`.
     :return: The decorated forward function.
     :rtype: Callable
     """
@@ -95,9 +95,9 @@ def wrapper(x):
 
 def merge_tensors(tensors):
     """
-    Merge a list of :class:`~pina.LabelTensor` instances into a single
-    :class:`~pina.LabelTensor` tensor, by applying iteratively the cartesian
-    product.
+    Merge a list of :class:`~pina.label_tensor.LabelTensor` instances into a
+    single :class:`~pina.label_tensor.LabelTensor` tensor, by applying
+    iteratively the cartesian product.
 
     :param list[LabelTensor] tensors: The list of tensors to merge.
     :raises ValueError: If the list of tensors is empty.
@@ -111,8 +111,9 @@ def merge_tensors(tensors):
 
 def merge_two_tensors(tensor1, tensor2):
     """
-    Merge two :class:`~pina.LabelTensor` instances into a single
-    :class:`~pina.LabelTensor` tensor, by applying the cartesian product.
+    Merge two :class:`~pina.label_tensor.LabelTensor` instances into a single
+    :class:`~pina.label_tensor.LabelTensor` tensor, by applying the cartesian
+    product.
 
     :param LabelTensor tensor1: The first tensor to merge.
     :param LabelTensor tensor2: The second tensor to merge.
