Improve doc condition

FilippoOlivo · dario-coscia · commit c2f966eb7ac5 · 2025-03-13T20:47:24.000+01:00
diff --git a/pina/condition/condition.py b/pina/condition/condition.py
@@ -1,6 +1,4 @@
-"""
-Condition module.
-"""
+"""Condition module."""
 
 import warnings
 from .data_condition import DataCondition
@@ -15,11 +13,12 @@
 
 
 def warning_function(new, old):
-    """
-    Handle the deprecation warning.
+    """Handle the deprecation warning.
 
-    :param str new: Object to use instead of the old one.
-    :param str old: Object to deprecate.
+    :param new: Object to use instead of the old one.
+    :type new: str
+    :param old: Object to deprecate.
+    :type old: str
     """
     warnings.warn(
         f"'{old}' is deprecated and will be removed "
@@ -30,49 +29,58 @@ def warning_function(new, old):
 
 class Condition:
     """
-    The class `Condition` is used to represent the constraints (physical
+    The class ``Condition`` is used to represent the constraints (physical
     equations, boundary conditions, etc.) that should be satisfied in the
     problem at hand. Condition objects are used to formulate the
     PINA :obj:`pina.problem.abstract_problem.AbstractProblem` object.
     Conditions can be specified in four ways:
 
-        1. By specifying the input and output points of the condition; in such a
+        1. By specifying the input and target of the condition; in such a
         case, the model is trained to produce the output points given the input
-        points. Those points can either be torch.Tensor, LabelTensors, Graph
+        points. Those points can either be torch.Tensor, LabelTensors, Graph.
+        Based on the type of the input and target, there are different
+        implementations of the condition. For more details, see
+        :class:`~pina.condition.input_target_condition.InputTargetCondition`.
 
-        2. By specifying the location and the equation of the condition; in such
+        2. By specifying the domain and the equation of the condition; in such
         a case, the model is trained to minimize the equation residual by
-        evaluating it at some samples of the location.
+        evaluating it at some samples of the domain.
 
-        3. By specifying the input points and the equation of the condition; in
+        3. By specifying the input and the equation of the condition; in
         such a case, the model is trained to minimize the equation residual by
         evaluating it at the passed input points. The input points must be
-        a LabelTensor.
+        a LabelTensor. Based on the type of the input, there are different
+        implementations of the condition. For more details, see
+        :class:`~pina.condition.input_equation_condition.InputEquationCondition`
+        .
 
-        4. By specifying only the data matrix; in such a case the model is
+        4. By specifying only the input data; in such a case the model is
         trained with an unsupervised costum loss and uses the data in training.
         Additionaly conditioning variables can be passed, whenever the model
-        has extra conditioning variable it depends on.
+        has extra conditioning variable it depends on. Based on the type of the
+        input, there are different implementations of the condition. For more
+        details, see :class:`~pina.condition.data_condition.DataCondition`.
 
     Example::
 
-        >>> from pina import Condition
-        >>> condition = Condition(
-        ...     input=input,
-        ...     target=target
-        ... )
-        >>> condition = Condition(
-        ...     domain=location,
-        ...     equation=equation
-        ... )
-        >>> condition = Condition(
-        ...     input=input,
-        ...     equation=equation
-        ... )
-        >>> condition = Condition(
-        ...     input=data,
-        ...     conditional_variables=conditional_variables
-        ... )
+    >>> from pina import Condition
+    >>> condition = Condition(
+    ...     input=input,
+    ...     target=target
+    ... )
+    >>> condition = Condition(
+    ...     domain=location,
+    ...     equation=equation
+    ... )
+    >>> condition = Condition(
+    ...     input=input,
+    ...     equation=equation
+    ... )
+    >>> condition = Condition(
+    ...     input=data,
+    ...     conditional_variables=conditional_variables
+    ... )
+
     """
 
     __slots__ = list(
@@ -86,24 +94,14 @@ class Condition:
 
     def __new__(cls, *args, **kwargs):
         """
-        Create a new condition object based on the keyword arguments passed.
-
-        - `input` and `target`:
-            :class:`~pina.condition.input_target_condition.InputTargetCondition`
-        - `domain` and `equation`:
-            :class:`~pina.condition.domain_equation_condition.
-            DomainEquationCondition`
-        - `input` and `equation`: :class:`~pina.condition.
-            input_equation_condition.InputEquationCondition`
-        - `input`: :class:`~pina.condition.data_condition.DataCondition`
-        - `input` and `conditional_variables`:
-            :class:`~pina.condition.data_condition.DataCondition`
-        :return: A new condition instance belonging to the proper class.
-        :rtype: InputTargetCondition | DomainEquationCondition |
-                InputEquationCondition | DataCondition
-
-        :raises ValueError: No valid condition has been found.
+        Check the input arguments and return the appropriate Condition object.
+
+        :raises ValueError: If no keyword arguments are passed.
+        :raises ValueError: If the keyword arguments are invalid.
+        :return: The appropriate Condition object.
+        :rtype: ConditionInterface
         """
+
         if len(args) != 0:
             raise ValueError(
                 "Condition takes only the following keyword "
diff --git a/pina/condition/condition_interface.py b/pina/condition/condition_interface.py
@@ -11,47 +11,61 @@
 class ConditionInterface(metaclass=ABCMeta):
     """
     Abstract class which defines a common interface for all the conditions.
+    It defined a common interface for all the conditions.
+
     """
 
     def __init__(self):
+        """
+        Initialize the ConditionInterface object.
+        """
+
         self._problem = None
 
     @property
     def problem(self):
         """
         Return the problem to which the condition is associated.
 
-        :return: Problem to which the condition is associated.
+        :return: Problem to which the condition is associated
         :rtype: pina.problem.AbstractProblem
         """
-
         return self._problem
 
     @problem.setter
     def problem(self, value):
         """
         Set the problem to which the condition is associated.
 
-        :param pina.problem.AbstractProblem value: Problem to which the
-        condition is associated.
+        :param pina.problem.abstract_problem.AbstractProblem value: Problem to
+            which the condition is associated
         """
-
         self._problem = value
 
     @staticmethod
     def _check_graph_list_consistency(data_list):
         """
-        Check if the list of :class:`~torch_geometric.data.Data` or
-        class:`pina.graphGraph` objects is consistent.
-
-        :param data_list: List of graph type objects.
-        :type data_list: Data | Graph | list[Data] | list[Graph]
-
-        :raises ValueError: Input data must be either Data
-            or Graph objects.
-        :raises ValueError: All elements in the list must have the same keys.
-        :raises ValueError: Type mismatch in data tensors.
-        :raises ValueError: Label mismatch in LabelTensors.
+        Check the consistency of the list of Data/Graph objects. It performs
+        the following checks:
+
+        1. All elements in the list must be of the same type (either Data or
+        Graph).
+        2. All elements in the list must have the same keys.
+        3. The type of each tensor must be consistent across all elements in
+        the list.
+        4. If the tensor is a LabelTensor, the labels must be consistent across
+        all elements in the list.
+
+        :param data_list: List of Data/Graph objects to check
+        :type data_list: list[Data] | list[Graph] | tuple[Data] | tuple[Graph]
+
+        :raises ValueError:  If the input types are invalid.
+        :raises ValueError: If all elements in the list do not have the same
+            keys.
+        :raises ValueError: If the type of each tensor is not consistent across
+            all elements in the list.
+        :raises ValueError: If the labels of the LabelTensors are not consistent
+            across all elements in the list.
         """
 
         # If the data is a Graph or Data object, return (do not need to check
diff --git a/pina/condition/data_condition.py b/pina/condition/data_condition.py
@@ -12,7 +12,13 @@
 class DataCondition(ConditionInterface):
     """
     Condition defined by input data and conditional variables. It can be used
-    in unsupervised learning problems.
+    in unsupervised learning problems. Based on the type of the input,
+    different condition implementations are available:
+
+    - :class:`TensorDataCondition`: For :class:`torch.Tensor` or
+      :class:`~pina.label_tensor.LabelTensor` input data.
+    - :class:`GraphDataCondition`: For :class:`~pina.graph.Graph` or
+      :class:`~torch_geometric.data.Data` input data.
     """
 
     __slots__ = ["input", "conditional_variables"]
diff --git a/pina/condition/input_equation_condition.py b/pina/condition/input_equation_condition.py
@@ -13,7 +13,13 @@
 class InputEquationCondition(ConditionInterface):
     """
     Condition defined by input data and an equation. This condition can be
-    used in a Physics Informed problems.
+    used in a Physics Informed problems. Based on the type of the input,
+    different condition implementations are available:
+
+    - :class:`InputTensorEquationCondition`: For
+        :class:`~pina.label_tensor.LabelTensor` input data.
+    - :class:`InputGraphEquationCondition`: For :class:`~pina.graph.Graph`
+        input data.
     """
 
     __slots__ = ["input", "equation"]
diff --git a/pina/condition/input_target_condition.py b/pina/condition/input_target_condition.py
@@ -12,7 +12,20 @@
 class InputTargetCondition(ConditionInterface):
     """
     Condition defined by input and target data. This condition can be used in
-    both supervised learning and Physics-informed problems.
+    both supervised learning and Physics-informed problems. Based on the type of
+    the input and target, different condition implementations are available:
+
+    - :class:`TensorInputTensorTargetCondition`: For :class:`torch.Tensor` or
+        :class:`~pina.label_tensor.LabelTensor` input and target data.
+    - :class:`TensorInputGraphTargetCondition`: For :class:`torch.Tensor` or
+        :class:`~pina.label_tensor.LabelTensor` input and
+        :class:`~pina.graph.Graph` or :class:`~torch_geometric.data.Data`
+        target data.
+    - :class:`GraphInputTensorTargetCondition`: For :class:`~pina.graph.Graph`
+        or :class:`~torch_geometric.data.Data` input and :class:`torch.Tensor`
+        or :class:`~pina.label_tensor.LabelTensor` target data.
+    - :class:`GraphInputGraphTargetCondition`: For :class:`~pina.graph.Graph` or
+        :class:`~torch_geometric.data.Data` input and target data.
     """
 
     __slots__ = ["input", "target"]
