add interface + base class structure for losses

Author: GiovanniCanali

docs/source/_rst/_code.rst

@@ -310,8 +310,9 @@ Losses and Weightings
     :titlesonly:
 
     LossInterface <loss/loss_interface.rst>
-    LpLoss <loss/lploss.rst>
-    PowerLoss <loss/powerloss.rst>
+    BaseLoss <loss/base_loss.rst>
+    LpLoss <loss/lp_loss.rst>
+    PowerLoss <loss/power_loss.rst>
     WeightingInterface <loss/weighting_interface.rst>
     ScalarWeighting <loss/scalar_weighting.rst>
     NeuralTangentKernelWeighting <loss/ntk_weighting.rst>

docs/source/_rst/loss/base_loss.rst

@@ -0,0 +1,9 @@
+Base Loss
+===============
+.. currentmodule:: pina.loss.base_loss
+
+.. automodule:: pina._src.loss.base_loss
+
+.. autoclass:: pina._src.loss.base_loss.BaseLoss
+   :members:
+   :show-inheritance:

docs/source/_rst/loss/loss_interface.rst

@@ -1,4 +1,4 @@
-LossInterface
+Loss Interface
 ===============
 .. currentmodule:: pina.loss.loss_interface
 

docs/source/_rst/loss/lploss.rst docs/source/_rst/loss/lp_loss.rstdocs/source/_rst/loss/lploss.rst renamed to docs/source/_rst/loss/lp_loss.rst

@@ -1,4 +1,4 @@
-LpLoss
+Lp Loss
 ===============
 .. currentmodule:: pina.loss.lp_loss
 

docs/source/_rst/loss/powerloss.rst docs/source/_rst/loss/power_loss.rstdocs/source/_rst/loss/powerloss.rst renamed to docs/source/_rst/loss/power_loss.rst

@@ -1,4 +1,4 @@
-PowerLoss
+Power Loss
 ====================
 .. currentmodule:: pina.loss.power_loss
 

pina/_src/loss/base_loss.py

@@ -0,0 +1,53 @@
+"""Module for the BaseLoss class."""
+
+import torch
+from pina._src.loss.loss_interface import LossInterface
+
+
+class BaseLoss(LossInterface):
+    """
+    Base class for all losses, implementing common functionality.
+
+    All specific loss types should inherit from this class and implement its
+    abstract methods.
+
+    This class is not meant to be instantiated directly.
+    """
+
+    # Define available reduction methods
+    _REDUCTION_METHOD = {
+        "sum": lambda x: torch.sum(x, keepdim=True, dim=-1),
+        "mean": lambda x: torch.mean(x, keepdim=True, dim=-1),
+        "none": lambda x: x,
+    }
+
+    def __init__(self, reduction="mean"):
+        """
+        Initialization of the :class:`BaseLoss` class.
+
+        :param str reduction: The reduction method to aggregate pointwise loss
+            values. Available options include: ``"none"`` for unreduced loss,
+            ``"mean"`` for the average of the loss values, and ``"sum"`` for
+            their total sum. Default is ``"mean"``.
+        :raises ValueError: If the specified reduction method is not among the
+            available options.
+        """
+        # Check that the reduction method is available
+        if reduction not in self._REDUCTION_METHOD:
+            raise ValueError(
+                f"Invalid reduction method. Available options: "
+                f"{list(self._REDUCTION_METHOD.keys())}. Got {reduction}."
+            )
+
+        # Initialization
+        super().__init__(reduction=reduction, size_average=None, reduce=None)
+
+    def _reduction(self, loss):
+        """
+        Apply the configured reduction operation to pointwise loss values.
+
+        :param torch.Tensor loss: The tensor of pointwise losses.
+        :return: The reduced loss tensor.
+        :rtype: torch.Tensor
+        """
+        return self._REDUCTION_METHOD[self.reduction](loss)

pina/_src/loss/loss_interface.py

@@ -2,51 +2,30 @@
 
 from abc import ABCMeta, abstractmethod
 from torch.nn.modules.loss import _Loss
-import torch
 
 
 class LossInterface(_Loss, metaclass=ABCMeta):
     """
-    Abstract base class for all losses. All classes defining a loss function
-    should inherit from this interface.
+    Abstract interface for all losses.
     """
 
-    def __init__(self, reduction="mean"):
-        """
-        Initialization of the :class:`LossInterface` class.
-
-        :param str reduction: The reduction method for the loss.
-            Available options: ``none``, ``mean``, ``sum``.
-            If ``none``, no reduction is applied. If ``mean``, the sum of the
-            loss values is divided by the number of values. If ``sum``, the loss
-            values are summed. Default is ``mean``.
-        """
-        super().__init__(reduction=reduction, size_average=None, reduce=None)
-
     @abstractmethod
     def forward(self, input, target):
         """
         Forward method of the loss function.
 
-        :param torch.Tensor input: Input tensor from real data.
-        :param torch.Tensor target: Model tensor output.
+        :param torch.Tensor input: The input tensor.
+        :param torch.Tensor target: The target tensor.
+        :return: The computed loss.
+        :rtype: torch.Tensor
         """
 
+    @abstractmethod
     def _reduction(self, loss):
         """
-        Apply the reduction to the loss.
+        Apply the configured reduction operation to pointwise loss values.
 
-        :param torch.Tensor loss: The tensor containing the pointwise losses.
-        :raises ValueError: If the reduction method is not valid.
-        :return: Reduced loss.
+        :param torch.Tensor loss: The tensor of pointwise losses.
+        :return: The reduced loss tensor.
         :rtype: torch.Tensor
         """
-        if self.reduction == "none":
-            ret = loss
-        elif self.reduction == "mean":
-            ret = torch.mean(loss, keepdim=True, dim=-1)
-        elif self.reduction == "sum":
-            ret = torch.sum(loss, keepdim=True, dim=-1)
-        else:
-            raise ValueError(self.reduction + " is not valid")
-        return ret

pina/_src/loss/lp_loss.py

@@ -1,74 +1,91 @@
-"""Module for the LpLoss class."""
+"""Module for the Lp Loss class."""
 
 import torch
-from pina._src.loss.loss_interface import LossInterface
+from pina._src.loss.base_loss import BaseLoss
 from pina._src.core.utils import check_consistency
 
 
-class LpLoss(LossInterface):
+class LpLoss(BaseLoss):
     r"""
-    Implementation of the Lp Loss. It defines a criterion to measures the 
-    pointwise Lp error between values in the input :math:`x` and values in the
-    target :math:`y`.
+    Implementation of the :math:`L^p` loss measuring the pointwise :math:`L^p`
+    distance between an input tensor :math:`x` and a target tensor :math:`y`.
 
-    If ``reduction`` is set to ``none``, the loss can be written as:
+    Given a batch of size :math:`N` and feature dimension :math:`D`, the
+    unreduced loss (``reduction="none"``) is defined as:
 
     .. math::
-        \ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
-        l_n = \left[\sum_{i=1}^{D} \left| x_n^i - y_n^i \right|^p \right],
-    
-    If ``relative`` is set to ``True``, the relative Lp error is computed:
+        L = \{l_1, \dots, l_N\}^\top, \quad
+        l_n = \left( \sum_{i=1}^{D} \left| x_n^i - y_n^i \right|^p \right)^{1/p}
+
+    If ``relative=True``, each term is normalized by the :math:`L^p` norm of the
+    input tensor :math:`x`:
 
     .. math::
-        \ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
-        l_n = \frac{ [\sum_{i=1}^{D} | x_n^i - y_n^i|^p] }
-        {[\sum_{i=1}^{D}|y_n^i|^p]},
+        l_n = \frac{\left( \sum_{i=1}^{D} |x_n^i - y_n^i|^p \right)^{1/p}}
+                {\left( \sum_{i=1}^{D} |x_n^i|^p \right)^{1/p}}
 
-    where :math:`N` is the batch size.
-    
-    If ``reduction`` is not ``none``, then:
+    If ``reduction`` is set to ``"mean"`` or ``"sum"``, the vector :math:`L`
+    is aggregated accordingly:
 
     .. math::
         \ell(x, y) =
         \begin{cases}
-            \operatorname{mean}(L), & \text{if reduction} = \text{`mean';}\\
-            \operatorname{sum}(L),  & \text{if reduction} = \text{`sum'.}
+            \operatorname{mean}(L), & \text{if reduction} = \text{``mean''} \\
+            \operatorname{sum}(L),  & \text{if reduction} = \text{``sum''}
         \end{cases}
+
+    where :math:`N` is the batch size.
     """
 
     def __init__(self, p=2, reduction="mean", relative=False):
         """
         Initialization of the :class:`LpLoss` class.
 
-        :param int p: Degree of the Lp norm. It specifies the norm to be
-            computed. Default is ``2`` (euclidean norm).
-        :param str reduction: The reduction method for the loss.
-            Available options: ``none``, ``mean``, ``sum``.
-            If ``none``, no reduction is applied. If ``mean``, the sum of the
-            loss values is divided by the number of values. If ``sum``, the loss
-            values are summed. Default is ``mean``.
-        :param bool relative: If ``True``, the relative error is computed.
+        :param p: The order of the norm. It can be a numeric value for standard
+            p-norms or one of the following strings: ``"inf"`` for maximum
+            absolute value, ``"-inf"`` for minimum absolute value. The values
+            ``"inf"`` and ``"-inf"`` are internally converted to their floating
+            counterparts. Default is ``2``.
+        :type p: int | float | str
+        :param str reduction: The reduction method to aggregate pointwise loss
+            values. Available options include: ``"none"`` for unreduced loss,
+            ``"mean"`` for the average of the loss values, and ``"sum"`` for
+            their total sum. Default is ``"mean"``.
+        :param bool relative: If ``True``, computes the relative error.
             Default is ``False``.
+        :raises ValueError: If ``relative`` is not a boolean.
+        :raises ValueError: If ``p`` is not a valid norm order.
         """
         super().__init__(reduction=reduction)
 
-        # check consistency
-        check_consistency(p, (str, int, float))
+        # Convert to float if inf or -inf
+        if p == "inf":
+            p = float("inf")
+        elif p == "-inf":
+            p = float("-inf")
+
+        # Check consistency
         check_consistency(relative, bool)
+        check_consistency(p, (int, float))
 
+        # Initialize attributes
         self.p = p
         self.relative = relative
 
     def forward(self, input, target):
         """
         Forward method of the loss function.
 
-        :param torch.Tensor input: Input tensor from real data.
-        :param torch.Tensor target: Model tensor output.
-        :return: Loss evaluation.
+        :param torch.Tensor input: The input tensor.
+        :param torch.Tensor target: The target tensor.
+        :return: The computed loss.
         :rtype: torch.Tensor
         """
+        # Compute the standard loss
         loss = torch.linalg.norm((input - target), ord=self.p, dim=-1)
+
+        # Compute the input norm for relative error
         if self.relative:
             loss = loss / torch.linalg.norm(input, ord=self.p, dim=-1)
+
         return self._reduction(loss)

pina/_src/loss/power_loss.py

@@ -1,76 +1,81 @@
-"""Module for the PowerLoss class."""
+"""Module for the Power Loss class."""
 
 import torch
+from pina._src.loss.base_loss import BaseLoss
+from pina._src.core.utils import check_consistency, check_positive_integer
 
-from pina._src.loss.loss_interface import LossInterface
-from pina._src.core.utils import check_consistency
 
-
-class PowerLoss(LossInterface):
+class PowerLoss(BaseLoss):
     r"""
-    Implementation of the Power Loss. It defines a criterion to measures the 
-    pointwise error between values in the input :math:`x` and values in the
-    target :math:`y`.
+    Implementation of the Power loss, measuring the pointwise averaged
+    :math:`p`-power error between an input tensor :math:`x` and a target tensor
+    :math:`y`.
 
-    If ``reduction`` is set to ``none``, the loss can be written as:
+    Given a batch of size :math:`N` and feature dimension :math:`D`, the
+    unreduced loss (``reduction="none"``) is defined as:
 
     .. math::
-        \ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
-        l_n = \frac{1}{D}\left[\sum_{i=1}^{D} 
-        \left| x_n^i - y_n^i \right|^p\right],
-    
-    If ``relative`` is set to ``True``, the relative error is computed:
+        L = \{l_1, \dots, l_N\}^\top, \quad
+        l_n = \frac{1}{D} \sum_{i=1}^{D} \left| x_n^i - y_n^i \right|^p
+
+    If ``relative=True``, each term is normalized by the averaged
+    :math:`p`-power magnitude of the input tensor :math:`x`:
 
     .. math::
-        \ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
-        l_n = \frac{ \sum_{i=1}^{D} | x_n^i - y_n^i|^p }
-        {\sum_{i=1}^{D}|y_n^i|^p},
+        l_n = \frac{\frac{1}{D} \sum_{i=1}^{D} |x_n^i - y_n^i|^p}
+                {\frac{1}{D} \sum_{i=1}^{D} |x_n^i|^p}
 
-    where :math:`N` is the batch size.
-    
-    If ``reduction`` is not ``none``, then:
+    If ``reduction`` is set to ``"mean"`` or ``"sum"``, the vector :math:`L`
+    is aggregated accordingly:
 
     .. math::
         \ell(x, y) =
         \begin{cases}
-            \operatorname{mean}(L), & \text{if reduction} = \text{`mean';}\\
-            \operatorname{sum}(L),  & \text{if reduction} = \text{`sum'.}
+            \operatorname{mean}(L), & \text{if reduction} = \text{``mean''} \\
+            \operatorname{sum}(L),  & \text{if reduction} = \text{``sum''}
         \end{cases}
+
+    where :math:`N` is the batch size.
     """
 
     def __init__(self, p=2, reduction="mean", relative=False):
         """
         Initialization of the :class:`PowerLoss` class.
 
-        :param int p: Degree of the Lp norm. It specifies the norm to be
-            computed. Default is ``2`` (euclidean norm).
-        :param str reduction: The reduction method for the loss.
-            Available options: ``none``, ``mean``, ``sum``.
-            If ``none``, no reduction is applied. If ``mean``, the sum of the
-            loss values is divided by the number of values. If ``sum``, the loss
-            values are summed. Default is ``mean``.
-        :param bool relative: If ``True``, the relative error is computed.
+        :param int p: The order of the p-norm. Default is ``2``.
+        :param str reduction: The reduction method to aggregate pointwise loss
+            values. Available options include: ``"none"`` for unreduced loss,
+            ``"mean"`` for the average of the loss values, and ``"sum"`` for
+            their total sum. Default is ``"mean"``.
+        :param bool relative: If ``True``, computes the relative error.
             Default is ``False``.
+        :raises ValueError: If ``relative`` is not a boolean.
+        :raises ValueError: If ``p`` is not a positive integer.
         """
         super().__init__(reduction=reduction)
 
-        # check consistency
-        check_consistency(p, (str, int, float))
+        # Check consistency
         check_consistency(relative, bool)
+        check_positive_integer(p, strict=True)
 
+        # Initialize attributes
         self.p = p
         self.relative = relative
 
     def forward(self, input, target):
         """
         Forward method of the loss function.
 
-        :param torch.Tensor input: Input tensor from real data.
-        :param torch.Tensor target: Model tensor output.
-        :return: Loss evaluation.
+        :param torch.Tensor input: The input tensor.
+        :param torch.Tensor target: The target tensor.
+        :return: The computed loss.
         :rtype: torch.Tensor
         """
+        # Compute the standard loss
         loss = torch.abs((input - target)).pow(self.p).mean(-1)
+
+        # Compute the input norm for relative error
         if self.relative:
             loss = loss / torch.abs(input).pow(self.p).mean(-1)
+
         return self._reduction(loss)