add exhaustive doc for condition module (#629)

Author: GiovanniCanali

pina/condition/condition.py

@@ -1,100 +1,91 @@
 """Module for the Condition class."""
 
-import warnings
 from .data_condition import DataCondition
 from .domain_equation_condition import DomainEquationCondition
 from .input_equation_condition import InputEquationCondition
 from .input_target_condition import InputTargetCondition
-from ..utils import custom_warning_format
 
-# Set the custom format for warnings
-warnings.formatwarning = custom_warning_format
-warnings.filterwarnings("always", category=DeprecationWarning)
 
+class Condition:
+    """
+    The :class:`Condition` class is a core component of the PINA framework that
+    provides a unified interface to define heterogeneous constraints that must
+    be satisfied by a :class:`~pina.problem.abstract_problem.AbstractProblem`.
 
-def warning_function(new, old):
-    """Handle the deprecation warning.
+    It encapsulates all types of constraints - physical, boundary, initial, or
+    data-driven - that the solver must satisfy during training. The specific
+    behavior is inferred from the arguments passed to the constructor.
 
-    :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 "
-        f"in future versions. Please use '{new}' instead.",
-        DeprecationWarning,
-    )
+    Multiple types of conditions can be used within the same problem, allowing
+    for a high degree of flexibility in defining complex problems.
 
+    The :class:`Condition` class behavior specializes internally based on the
+    arguments provided during instantiation. Depending on the specified keyword
+    arguments, the class automatically selects the appropriate internal
+    implementation.
 
-class Condition:
-    """
-    Represents constraints (such as physical equations, boundary conditions,
-    etc.) that must be satisfied in a given problem. Condition objects are used
-    to formulate the PINA
-    :class:`~pina.problem.abstract_problem.AbstractProblem` object.
 
-    There are different types of conditions:
+    Available `Condition` types:
 
     - :class:`~pina.condition.input_target_condition.InputTargetCondition`:
-      Defined by specifying both the input and the target of the condition. In
-      this case, the model is trained to produce the target given the input. The
-      input and output   data must be one of the :class:`torch.Tensor`,
-      :class:`~pina.label_tensor.LabelTensor`,
-      :class:`~torch_geometric.data.Data`, or :class:`~pina.graph.Graph`.
-      Different implementations exist depending on the type of input and target.
-      For more details, see
-      :class:`~pina.condition.input_target_condition.InputTargetCondition`.
+      represents a supervised condition defined by both ``input`` and ``target``
+      data. The model is trained to reproduce the ``target`` values given the
+      ``input``. Supported data types include :class:`torch.Tensor`,
+      :class:`~pina.label_tensor.LabelTensor`, :class:`~pina.graph.Graph`, or
+      :class:`~torch_geometric.data.Data`.
+      The class automatically selects the appropriate implementation based on
+      the types of ``input`` and ``target``.
 
     - :class:`~pina.condition.domain_equation_condition.DomainEquationCondition`
-      : Defined by specifying both the domain and the equation of the condition.
-      Here, the model is trained to minimize the equation residual by evaluating
-      it at sampled points within the domain.
+      : represents a general physics-informed condition defined by a ``domain``
+      and an ``equation``. The model learns to minimize the equation residual
+      through evaluations performed at points sampled from the specified domain.
 
     - :class:`~pina.condition.input_equation_condition.InputEquationCondition`:
-      Defined by specifying the input and the equation of the condition. In this
-      case, the model is trained to minimize the equation residual by evaluating
-      it at the provided input. The input must be either a
-      :class:`~pina.label_tensor.LabelTensor` or a :class:`~pina.graph.Graph`.
-      Different implementations exist depending on the type of input. For more
-      details, see
-      :class:`~pina.condition.input_equation_condition.InputEquationCondition`.
-
-    - :class:`~pina.condition.data_condition.DataCondition`:
-      Defined by specifying only the input. In this case, the model is trained
-      with an unsupervised custom loss while using the provided data during
-      training. The input data must be one of :class:`torch.Tensor`,
-      :class:`~pina.label_tensor.LabelTensor`,
-      :class:`~torch_geometric.data.Data`, or :class:`~pina.graph.Graph`.
-      Additionally, conditional variables can be provided when the model
-      depends on extra parameters. These conditional variables must be either
-      :class:`torch.Tensor` or :class:`~pina.label_tensor.LabelTensor`.
-      Different implementations exist depending on the type of input.
-      For more details, see
-      :class:`~pina.condition.data_condition.DataCondition`.
+      represents a general physics-informed condition defined by ``input``
+      points and an ``equation``. The model learns to minimize the equation
+      residual through evaluations performed at the provided ``input``.
+      Supported data types for the ``input`` include
+      :class:`~pina.label_tensor.LabelTensor` or :class:`~pina.graph.Graph`.
+      The class automatically selects the appropriate implementation based on
+      the types of the ``input``.
+
+    - :class:`~pina.condition.data_condition.DataCondition`: represents an
+      unsupervised, data-driven condition defined by the ``input`` only.
+      The model is trained using a custom unsupervised loss determined by the
+      chosen :class:`~pina.solver.solver.SolverInterface`, while leveraging the
+      provided data during training. Optional ``conditional_variables`` can be
+      specified when the model depends on additional parameters.
+      Supported data types include :class:`torch.Tensor`,
+      :class:`~pina.label_tensor.LabelTensor`, :class:`~pina.graph.Graph`, or
+      :class:`~torch_geometric.data.Data`.
+      The class automatically selects the appropriate implementation based on
+      the type of the ``input``.
+
+    .. note::
+
+        The user should always instantiate :class:`Condition` directly, without
+        manually creating subclass instances. Please refer to the specific
+        :class:`Condition` classes for implementation details.
 
     :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
-    ... )
 
+    >>> # Example of InputTargetCondition signature
+    >>> condition = Condition(input=input, target=target)
+
+    >>> # Example of DomainEquationCondition signature
+    >>> condition = Condition(domain=domain, equation=equation)
+
+    >>> # Example of InputEquationCondition signature
+    >>> condition = Condition(input=input, equation=equation)
+
+    >>> # Example of DataCondition signature
+    >>> condition = Condition(input=data, conditional_variables=cond_vars)
     """
 
+    # Combine all possible keyword arguments from the different Condition types
     __slots__ = list(
         set(
             InputTargetCondition.__slots__
@@ -106,46 +97,45 @@ class Condition:
 
     def __new__(cls, *args, **kwargs):
         """
-        Instantiate the appropriate Condition object based on the keyword
-        arguments passed.
+        Instantiate the appropriate :class:`Condition` object based on the
+        keyword arguments passed.
 
-        :raises ValueError: If no keyword arguments are passed.
+        :param tuple args: The positional arguments (should be empty).
+        :param dict kwargs: The keyword arguments corresponding to the
+            parameters of the specific :class:`Condition` type to instantiate.
+        :raises ValueError: If unexpected positional arguments are provided.
         :raises ValueError: If the keyword arguments are invalid.
-        :return: The appropriate Condition object.
+        :return: The appropriate :class:`Condition` object.
         :rtype: ConditionInterface
         """
-
+        # Check keyword arguments
         if len(args) != 0:
             raise ValueError(
                 "Condition takes only the following keyword "
                 f"arguments: {Condition.__slots__}."
             )
 
-        # back-compatibility 0.1
-        keys = list(kwargs.keys())
-        if "location" in keys:
-            kwargs["domain"] = kwargs.pop("location")
-            warning_function(new="domain", old="location")
-
-        if "input_points" in keys:
-            kwargs["input"] = kwargs.pop("input_points")
-            warning_function(new="input", old="input_points")
-
-        if "output_points" in keys:
-            kwargs["target"] = kwargs.pop("output_points")
-            warning_function(new="target", old="output_points")
-
+        # Class specialization based on keyword arguments
         sorted_keys = sorted(kwargs.keys())
+
+        # Input - Target Condition
         if sorted_keys == sorted(InputTargetCondition.__slots__):
             return InputTargetCondition(**kwargs)
+
+        # Input - Equation Condition
         if sorted_keys == sorted(InputEquationCondition.__slots__):
             return InputEquationCondition(**kwargs)
+
+        # Domain - Equation Condition
         if sorted_keys == sorted(DomainEquationCondition.__slots__):
             return DomainEquationCondition(**kwargs)
+
+        # Data Condition
         if (
             sorted_keys == sorted(DataCondition.__slots__)
             or sorted_keys[0] == DataCondition.__slots__[0]
         ):
             return DataCondition(**kwargs)
 
+        # Invalid keyword arguments
         raise ValueError(f"Invalid keyword arguments {kwargs.keys()}.")

pina/condition/condition_interface.py

@@ -8,115 +8,118 @@
 
 class ConditionInterface(metaclass=ABCMeta):
     """
-    Abstract class which defines a common interface for all the conditions.
-    It defined a common interface for all the conditions.
+    Abstract base class for PINA conditions. All specific conditions must
+    inherit from this interface.
 
+    Refer to :class:`pina.condition.condition.Condition` for a thorough
+    description of all available conditions and how to instantiate them.
     """
 
     def __init__(self):
         """
-        Initialize the ConditionInterface object.
+        Initialization of the :class:`ConditionInterface` class.
         """
-
         self._problem = None
 
     @property
     def problem(self):
         """
-        Return the problem to which the condition is associated.
+        Return the problem associated with this condition.
 
-        :return: Problem to which the condition is associated.
+        :return: Problem associated with this condition.
         :rtype: ~pina.problem.abstract_problem.AbstractProblem
         """
         return self._problem
 
     @problem.setter
     def problem(self, value):
         """
-        Set the problem to which the condition is associated.
+        Set the problem associated with this condition.
 
-        :param pina.problem.abstract_problem.AbstractProblem value: Problem to
-            which the condition is associated
+        :param pina.problem.abstract_problem.AbstractProblem value: The problem
+            to associate with this condition
         """
         self._problem = value
 
     @staticmethod
     def _check_graph_list_consistency(data_list):
         """
-        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]
+        Check the consistency of the list of Data | Graph objects.
+        The following checks are performed:
+
+        - All elements in the list must be of the same type (either
+          :class:`~torch_geometric.data.Data` or :class:`~pina.graph.Graph`).
+
+        - All elements in the list must have the same keys.
+
+        - The data type of each tensor must be consistent across all elements.
 
-        :raises ValueError:  If the input types are invalid.
+        - If a tensor is a :class:`~pina.label_tensor.LabelTensor`, its labels
+          must also be consistent across all elements.
+
+        :param data_list: The 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
-        # anything)
+        # If the data is a Graph or Data object, perform no checks
         if isinstance(data_list, (Graph, Data)):
             return
 
-        # check all elements in the list are of the same type
+        # Check all elements in the list are of the same type
         if not all(isinstance(i, (Graph, Data)) for i in data_list):
             raise ValueError(
-                "Invalid input types. "
-                "Please provide either Data or Graph objects."
+                "Invalid input. Please, provide either Data or Graph objects."
             )
+
+        # Store the keys, data types and labels of the first element
         data = data_list[0]
-        # Store the keys of the first element in the list
         keys = sorted(list(data.keys()))
-
-        # Store the type of each tensor inside first element Data/Graph object
         data_types = {name: tensor.__class__ for name, tensor in data.items()}
-
-        # Store the labels of each LabelTensor inside first element Data/Graph
-        # object
         labels = {
             name: tensor.labels
             for name, tensor in data.items()
             if isinstance(tensor, LabelTensor)
         }
 
-        # Iterate over the list of Data/Graph objects
+        # Iterate over the list of Data | Graph objects
         for data in data_list[1:]:
-            # Check if the keys of the current element are the same as the first
-            # element
+
+            # Check that all elements in the list have the same keys
             if sorted(list(data.keys())) != keys:
                 raise ValueError(
                     "All elements in the list must have the same keys."
                 )
+
+            # Iterate over the tensors in the current element
             for name, tensor in data.items():
-                # Check if the type of each tensor inside the current element
-                # is the same as the first element
+                # Check that the type of each tensor is consistent
                 if tensor.__class__ is not data_types[name]:
                     raise ValueError(
                         f"Data {name} must be a {data_types[name]}, got "
                         f"{tensor.__class__}"
                     )
-                # If the tensor is a LabelTensor, check if the labels are the
-                # same as the first element
+
+                # Check that the labels of each LabelTensor are consistent
                 if isinstance(tensor, LabelTensor):
                     if tensor.labels != labels[name]:
                         raise ValueError(
                             "LabelTensor must have the same labels"
                         )
 
     def __getattribute__(self, name):
+        """
+        Get an attribute from the object.
+
+        :param str name: The name of the attribute to get.
+        :return: The requested attribute.
+        :rtype: Any
+        """
         to_return = super().__getattribute__(name)
         if isinstance(to_return, (Graph, Data)):
             to_return = [to_return]