diff --git a/pina/domain/__init__.py b/pina/domain/__init__.py index fd32be6..cf0f03b 100644 --- a/pina/domain/__init__.py +++ b/pina/domain/__init__.py @@ -1,4 +1,4 @@ -"""Modules to create and handle domains.""" +"""Module to create and handle domains.""" __all__ = [ "DomainInterface", diff --git a/pina/equation/__init__.py b/pina/equation/__init__.py index 8716814..ab18fa1 100644 --- a/pina/equation/__init__.py +++ b/pina/equation/__init__.py @@ -1,5 +1,5 @@ """ -Module for defining equations and system of equations. +Module to define equations and systems of equations. """ __all__ = [ diff --git a/pina/equation/equation.py b/pina/equation/equation.py index 7306ea8..34a4703 100644 --- a/pina/equation/equation.py +++ b/pina/equation/equation.py @@ -1,21 +1,22 @@ -"""Module for Equation.""" +"""Module for the Equation.""" from .equation_interface import EquationInterface class Equation(EquationInterface): """ - Equation class for specifing any equation in PINA. + 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. """ def __init__(self, equation): """ - Each ``equation`` passed to a ``Condition`` object - must be an ``Equation`` or ``SystemEquation``. + Initialization of the :class:`Equation` class. - :param equation: A ``torch`` callable equation to - evaluate the residual. - :type equation: Callable + :param Callable equation: A ``torch`` callable function used to compute + the residual of a mathematical equation. + :raises ValueError: If the equation is not a callable function. """ if not callable(equation): raise ValueError( @@ -27,20 +28,16 @@ class Equation(EquationInterface): def residual(self, input_, output_, params_=None): """ - Residual computation of the equation. + Compute the residual of the equation. - :param LabelTensor input_: Input points to evaluate the equation. - :param LabelTensor output_: Output vectors given by a model (e.g, - a ``FeedForward`` model). - :param dict params_: Dictionary of parameters related to the inverse - problem (if any). - If the equation is not related to an ``InverseProblem``, the - parameters are initialized to ``None`` and the residual is - computed as ``equation(input_, output_)``. - Otherwise, the parameters are automatically initialized in the - ranges specified by the user. - - :return: The residual evaluation of the specified equation. + :param LabelTensor input_: Input points where the equation is evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :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 + parameters must be initialized to ``None``. Default is ``None``. + :return: The computed residual of the equation. :rtype: LabelTensor """ if params_ is None: diff --git a/pina/equation/equation_factory.py b/pina/equation/equation_factory.py index cc27109..14862ee 100644 --- a/pina/equation/equation_factory.py +++ b/pina/equation/equation_factory.py @@ -1,4 +1,4 @@ -"""Module for defining different equations.""" +"""Module for defining various general equations.""" from .equation import Equation from ..operator import grad, div, laplacian @@ -6,24 +6,32 @@ from ..operator import grad, div, laplacian class FixedValue(Equation): """ - Fixed Value Equation class. + Equation to enforce a fixed value. Can be used to enforce Dirichlet Boundary + conditions. """ def __init__(self, value, components=None): """ - This class can be - used to enforced a fixed value for a specific - condition, e.g. Dirichlet Boundary conditions. + Initialization of the :class:`FixedValue` class. - :param float value: Value to be mantained fixed. - :param list(str) components: the name of the output - variables to calculate the gradient for. It should - be a subset of the output labels. If ``None``, - all the output variables are considered. + :param float value: The fixed value to be enforced. + :param list[str] components: The name of the output variables for which + the fixed value condition is applied. It should be a subset of the + output labels. If ``None``, all output variables are considered. Default is ``None``. """ def equation(input_, output_): + """ + Definition of the equation to enforce a fixed value. + + :param LabelTensor input_: Input points where the equation is + evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :class:`~torch.nn.Module` instance. + :return: The computed residual of the equation. + :rtype: LabelTensor + """ if components is None: return output_ - value return output_.extract(components) - value @@ -33,27 +41,35 @@ class FixedValue(Equation): class FixedGradient(Equation): """ - Fixed Gradient Equation class. + Equation to enforce a fixed gradient for a specific condition. """ def __init__(self, value, components=None, d=None): """ - This class can beused to enforced a fixed gradient for a specific - condition. + Initialization of the :class:`FixedGradient` class. - :param float value: Value to be mantained fixed. - :param list(str) components: the name of the output - variables to calculate the gradient for. It should - be a subset of the output labels. If ``None``, - all the output variables are considered. + :param float value: The fixed value to be enforced to the gradient. + :param list[str] components: The name of the output variables for which + the fixed gradient condition is applied. It should be a subset of + the output labels. If ``None``, all output variables are considered. + Default is ``None``. + :param list[str] d: The name of the input variables on which the + gradient is computed. It should be a subset of the input labels. + If ``None``, all the input variables are considered. Default is ``None``. - :param list(str) d: the name of the input variables on - which the gradient is calculated. d should be a subset - of the input labels. If ``None``, all the input variables - are considered. Default is ``None``. """ def equation(input_, output_): + """ + Definition of the equation to enforce a fixed gradient. + + :param LabelTensor input_: Input points where the equation is + evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :class:`~torch.nn.Module` instance. + :return: The computed residual of the equation. + :rtype: LabelTensor + """ return grad(output_, input_, components=components, d=d) - value super().__init__(equation) @@ -61,27 +77,34 @@ class FixedGradient(Equation): class FixedFlux(Equation): """ - Fixed Flux Equation class. + Equation to enforce a fixed flux, or divergence, for a specific condition. """ def __init__(self, value, components=None, d=None): """ - This class can be used to enforced a fixed flux for a specific - condition. + Initialization of the :class:`FixedFlux` class. - :param float value: Value to be mantained fixed. - :param list(str) components: the name of the output - variables to calculate the flux for. It should - be a subset of the output labels. If ``None``, - all the output variables are considered. + :param float value: The fixed value to be enforced to the flux. + :param list[str] components: The name of the output variables for which + the fixed flux condition is applied. It should be a subset of the + output labels. If ``None``, all output variables are considered. Default is ``None``. - :param list(str) d: the name of the input variables on - which the flux is calculated. d should be a subset - of the input labels. If ``None``, all the input variables - are considered. Default is ``None``. + :param list[str] d: The name of the input variables on which the flux + is computed. It should be a subset of the input labels. If ``None``, + all the input variables are considered. Default is ``None``. """ def equation(input_, output_): + """ + Definition of the equation to enforce a fixed flux. + + :param LabelTensor input_: Input points where the equation is + evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :class:`~torch.nn.Module` instance. + :return: The computed residual of the equation. + :rtype: LabelTensor + """ return div(output_, input_, components=components, d=d) - value super().__init__(equation) @@ -89,27 +112,34 @@ class FixedFlux(Equation): class Laplace(Equation): """ - Laplace Equation class. + Equation to enforce a null laplacian for a specific condition. """ def __init__(self, components=None, d=None): """ - This class can be - used to enforced a Laplace equation for a specific - condition (force term set to zero). + Initialization of the :class:`Laplace` class. - :param list(str) components: the name of the output - variables to calculate the flux for. It should - be a subset of the output labels. If ``None``, - all the output variables are considered. + :param list[str] components: The name of the output variables for which + the null laplace condition is applied. It should be a subset of the + output labels. If ``None``, all output variables are considered. + Default is ``None``. + :param list[str] d: The name of the input variables on which the + laplacian is computed. It should be a subset of the input labels. + If ``None``, all the input variables are considered. Default is ``None``. - :param list(str) d: the name of the input variables on - which the flux is calculated. d should be a subset - of the input labels. If ``None``, all the input variables - are considered. Default is ``None``. """ def equation(input_, output_): + """ + Definition of the equation to enforce a null laplacian. + + :param LabelTensor input_: Input points where the equation is + evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :class:`~torch.nn.Module` instance. + :return: The computed residual of the equation. + :rtype: LabelTensor + """ return laplacian(output_, input_, components=components, d=d) super().__init__(equation) diff --git a/pina/equation/equation_interface.py b/pina/equation/equation_interface.py index 6c25418..8941d1e 100644 --- a/pina/equation/equation_interface.py +++ b/pina/equation/equation_interface.py @@ -1,28 +1,23 @@ -"""Module for EquationInterface class""" +"""Module for the Equation Interface""" from abc import ABCMeta, abstractmethod class EquationInterface(metaclass=ABCMeta): """ - The abstract `AbstractProblem` class. All the class defining a PINA Problem - should be inheritied from this class. - - In the definition of a PINA problem, the fundamental elements are: - the output variables, the condition(s), and the domain(s) where the - conditions are applied. + Abstract base class for equations. """ @abstractmethod def residual(self, input_, output_, params_): """ - Residual computation of the equation. + Abstract method to compute the residual of an equation. - :param LabelTensor input_: Input points to evaluate the equation. - :param LabelTensor output_: Output vectors given by my model (e.g., - a ``FeedForward`` model). - :param dict params_: Dictionary of unknown parameters, eventually - related to an ``InverseProblem``. - :return: The residual evaluation of the specified equation. + :param LabelTensor input_: Input points where the equation is evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :class:`~torch.nn.Module` instance. + :param dict params_: Dictionary of unknown parameters, associated with a + :class:`~pina.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 index 4200199..68ab8d0 100644 --- a/pina/equation/system_equation.py +++ b/pina/equation/system_equation.py @@ -1,4 +1,4 @@ -"""Module for SystemEquation.""" +"""Module for the System of Equation.""" import torch from .equation_interface import EquationInterface @@ -8,25 +8,25 @@ from ..utils import check_consistency class SystemEquation(EquationInterface): """ - System of Equation class for specifing any system - of equations in PINA. + 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. """ def __init__(self, list_equation, reduction=None): """ - Each ``equation`` passed to a ``Condition`` object - must be an ``Equation`` or ``SystemEquation``. - A ``SystemEquation`` is specified by a list of - equations. + Initialization of the :class:`SystemEquation` class. - :param Callable equation: A ``torch`` callable equation to - evaluate the residual - :param str reduction: Specifies the reduction to apply to the output: - None | ``mean`` | ``sum`` | callable. None: no reduction - will be applied, ``mean``: the output sum will be divided - by the number of elements in the output, ``sum``: the output will - be summed. *callable* is a callable function to perform reduction, - no checks guaranteed. Default: None. + :param Callable equation: A ``torch`` callable function used to compute + the residual of a mathematical equation. + :param str reduction: The reduction method to aggregate the residuals of + each equation. Available options are: ``None``, ``mean``, ``sum``, + ``callable``. + If ``None``, no reduction is applied. If ``mean``, the output sum is + divided by the number of elements in the output. If ``sum``, the + output is summed. ``callable`` is a user-defined callable function + to perform reduction, no checks guaranteed. Default is ``None``. + :raises NotImplementedError: If the reduction is not implemented. """ check_consistency([list_equation], list) @@ -49,22 +49,19 @@ class SystemEquation(EquationInterface): def residual(self, input_, output_, params_=None): """ - Residual computation for the equations of the system. + Compute the residual for each equation in the system of equations and + aggregate it according to the ``reduction`` specified in the + ``__init__`` method. - :param LabelTensor input_: Input points to evaluate the system of - equations. - :param LabelTensor output_: Output vectors given by a model (e.g, - a ``FeedForward`` model). - :param dict params_: Dictionary of parameters related to the inverse - problem (if any). - If the equation is not related to an ``InverseProblem``, the - parameters are initialized to ``None`` and the residual is - computed as ``equation(input_, output_)``. - Otherwise, the parameters are automatically initialized in the - ranges specified by the user. + :param LabelTensor input_: Input points where each equation is evaluated. + :param LabelTensor output_: Output tensor, eventually produced by a + :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 + parameters must be initialized to ``None``. Default is ``None``. - :return: The residual evaluation of the specified system of equations, - aggregated by the ``reduction`` defined in the ``__init__``. + :return: The aggregated residuals of the system of equations. :rtype: LabelTensor """ residual = torch.hstack(