folivo/PINA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix equation doc

Browse Source
This commit is contained in:
giovanni
2025-03-12 16:19:11 +01:00
committed by Nicola Demo
parent ce35af6397
commit 0b7fc80325
6 changed files with 130 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
pina/domain/__init__.py
View File

@@ -1,4 +1,4 @@
"""Modules to create and handle domains.""" """Module to create and handle domains."""
__all__ = [ __all__ = [
"DomainInterface", "DomainInterface",

2
pina/equation/__init__.py
View File

@@ -1,5 +1,5 @@
""" """
Module for defining equations and system of equations. Module to define equations and systems of equations.
""" """
__all__ = [ __all__ = [

37
pina/equation/equation.py
View File

@@ -1,21 +1,22 @@
"""Module for Equation.""" """Module for the Equation."""
from .equation_interface import EquationInterface from .equation_interface import EquationInterface
class Equation(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): def __init__(self, equation):
""" """
Each ``equation`` passed to a ``Condition`` object Initialization of the :class:`Equation` class.
must be an ``Equation`` or ``SystemEquation``.
:param equation: A ``torch`` callable equation to :param Callable equation: A ``torch`` callable function used to compute
evaluate the residual. the residual of a mathematical equation.
:type equation: Callable :raises ValueError: If the equation is not a callable function.
""" """
if not callable(equation): if not callable(equation):
raise ValueError( raise ValueError(
@@ -27,20 +28,16 @@ class Equation(EquationInterface):
def residual(self, input_, output_, params_=None): 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 input_: Input points where the equation is evaluated.
:param LabelTensor output_: Output vectors given by a model (e.g, :param LabelTensor output_: Output tensor, eventually produced by a
a ``FeedForward`` model). :class:`~torch.nn.Module` instance.
:param dict params_: Dictionary of parameters related to the inverse :param dict params_: Dictionary of unknown parameters, associated with a
problem (if any). :class:`~pina.problem.InverseProblem` instance. If the equation is
If the equation is not related to an ``InverseProblem``, the not related to a :class:`~pina.problem.InverseProblem` instance, the
parameters are initialized to ``None`` and the residual is parameters must be initialized to ``None``. Default is ``None``.
computed as ``equation(input_, output_)``. :return: The computed residual of the equation.
Otherwise, the parameters are automatically initialized in the
ranges specified by the user.
:return: The residual evaluation of the specified equation.
:rtype: LabelTensor :rtype: LabelTensor
""" """
if params_ is None: if params_ is None:

122
pina/equation/equation_factory.py
View File

@@ -1,4 +1,4 @@
"""Module for defining different equations.""" """Module for defining various general equations."""
from .equation import Equation from .equation import Equation
from ..operator import grad, div, laplacian from ..operator import grad, div, laplacian
@@ -6,24 +6,32 @@ from ..operator import grad, div, laplacian
class FixedValue(Equation): 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): def __init__(self, value, components=None):
""" """
This class can be Initialization of the :class:`FixedValue` class.
used to enforced a fixed value for a specific
condition, e.g. Dirichlet Boundary conditions.
:param float value: Value to be mantained fixed. :param float value: The fixed value to be enforced.
:param list(str) components: the name of the output :param list[str] components: The name of the output variables for which
variables to calculate the gradient for. It should the fixed value condition is applied. It should be a subset of the
be a subset of the output labels. If ``None``, output labels. If ``None``, all output variables are considered.
all the output variables are considered.
Default is ``None``. Default is ``None``.
""" """
def equation(input_, output_): 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: if components is None:
return output_ - value return output_ - value
return output_.extract(components) - value return output_.extract(components) - value
@@ -33,27 +41,35 @@ class FixedValue(Equation):
class FixedGradient(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): def __init__(self, value, components=None, d=None):
""" """
This class can beused to enforced a fixed gradient for a specific Initialization of the :class:`FixedGradient` class.
condition.
:param float value: Value to be mantained fixed. :param float value: The fixed value to be enforced to the gradient.
:param list(str) components: the name of the output :param list[str] components: The name of the output variables for which
variables to calculate the gradient for. It should the fixed gradient condition is applied. It should be a subset of
be a subset of the output labels. If ``None``, the output labels. If ``None``, all output variables are considered.
all the 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``. 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_): 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 return grad(output_, input_, components=components, d=d) - value
super().__init__(equation) super().__init__(equation)
@@ -61,27 +77,34 @@ class FixedGradient(Equation):
class FixedFlux(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): def __init__(self, value, components=None, d=None):
""" """
This class can be used to enforced a fixed flux for a specific Initialization of the :class:`FixedFlux` class.
condition.
:param float value: Value to be mantained fixed. :param float value: The fixed value to be enforced to the flux.
:param list(str) components: the name of the output :param list[str] components: The name of the output variables for which
variables to calculate the flux for. It should the fixed flux condition is applied. It should be a subset of the
be a subset of the output labels. If ``None``, output labels. If ``None``, all output variables are considered.
all the output variables are considered.
Default is ``None``. Default is ``None``.
:param list(str) d: the name of the input variables on :param list[str] d: The name of the input variables on which the flux
which the flux is calculated. d should be a subset is computed. It should be a subset of the input labels. If ``None``,
of the input labels. If ``None``, all the input variables all the input variables are considered. Default is ``None``.
are considered. Default is ``None``.
""" """
def equation(input_, output_): 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 return div(output_, input_, components=components, d=d) - value
super().__init__(equation) super().__init__(equation)
@@ -89,27 +112,34 @@ class FixedFlux(Equation):
class Laplace(Equation): class Laplace(Equation):
""" """
Laplace Equation class. Equation to enforce a null laplacian for a specific condition.
""" """
def __init__(self, components=None, d=None): def __init__(self, components=None, d=None):
""" """
This class can be Initialization of the :class:`Laplace` class.
used to enforced a Laplace equation for a specific
condition (force term set to zero).
:param list(str) components: the name of the output :param list[str] components: The name of the output variables for which
variables to calculate the flux for. It should the null laplace condition is applied. It should be a subset of the
be a subset of the output labels. If ``None``, output labels. If ``None``, all output variables are considered.
all the 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``. 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_): 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) return laplacian(output_, input_, components=components, d=d)
super().__init__(equation) super().__init__(equation)

23
pina/equation/equation_interface.py
View File

@@ -1,28 +1,23 @@
"""Module for EquationInterface class""" """Module for the Equation Interface"""
from abc import ABCMeta, abstractmethod from abc import ABCMeta, abstractmethod
class EquationInterface(metaclass=ABCMeta): class EquationInterface(metaclass=ABCMeta):
""" """
The abstract `AbstractProblem` class. All the class defining a PINA Problem Abstract base class for equations.
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.
""" """
@abstractmethod @abstractmethod
def residual(self, input_, output_, params_): 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 input_: Input points where the equation is evaluated.
:param LabelTensor output_: Output vectors given by my model (e.g., :param LabelTensor output_: Output tensor, eventually produced by a
a ``FeedForward`` model). :class:`~torch.nn.Module` instance.
:param dict params_: Dictionary of unknown parameters, eventually :param dict params_: Dictionary of unknown parameters, associated with a
related to an ``InverseProblem``. :class:`~pina.problem.InverseProblem` instance.
:return: The residual evaluation of the specified equation. :return: The computed residual of the equation.
:rtype: LabelTensor :rtype: LabelTensor
""" """

55
pina/equation/system_equation.py
View File

@@ -1,4 +1,4 @@
"""Module for SystemEquation.""" """Module for the System of Equation."""
import torch import torch
from .equation_interface import EquationInterface from .equation_interface import EquationInterface
@@ -8,25 +8,25 @@ from ..utils import check_consistency
class SystemEquation(EquationInterface): class SystemEquation(EquationInterface):
""" """
System of Equation class for specifing any system Implementation of the System of Equations. Every ``equation`` passed to a
of equations in PINA. :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): def __init__(self, list_equation, reduction=None):
""" """
Each ``equation`` passed to a ``Condition`` object Initialization of the :class:`SystemEquation` class.
must be an ``Equation`` or ``SystemEquation``.
A ``SystemEquation`` is specified by a list of
equations.
:param Callable equation: A ``torch`` callable equation to :param Callable equation: A ``torch`` callable function used to compute
evaluate the residual the residual of a mathematical equation.
:param str reduction: Specifies the reduction to apply to the output: :param str reduction: The reduction method to aggregate the residuals of
None | ``mean`` | ``sum`` | callable. None: no reduction each equation. Available options are: ``None``, ``mean``, ``sum``,
will be applied, ``mean``: the output sum will be divided ``callable``.
by the number of elements in the output, ``sum``: the output will If ``None``, no reduction is applied. If ``mean``, the output sum is
be summed. *callable* is a callable function to perform reduction, divided by the number of elements in the output. If ``sum``, the
no checks guaranteed. Default: None. 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) check_consistency([list_equation], list)
@@ -49,22 +49,19 @@ class SystemEquation(EquationInterface):
def residual(self, input_, output_, params_=None): 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 :param LabelTensor input_: Input points where each equation is evaluated.
equations. :param LabelTensor output_: Output tensor, eventually produced by a
:param LabelTensor output_: Output vectors given by a model (e.g, :class:`~torch.nn.Module` instance.
a ``FeedForward`` model). :param dict params_: Dictionary of unknown parameters, associated with a
:param dict params_: Dictionary of parameters related to the inverse :class:`~pina.problem.InverseProblem` instance. If the equation is
problem (if any). not related to a :class:`~pina.problem.InverseProblem` instance, the
If the equation is not related to an ``InverseProblem``, the parameters must be initialized to ``None``. Default is ``None``.
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 system of equations, :return: The aggregated residuals of the system of equations.
aggregated by the ``reduction`` defined in the ``__init__``.
:rtype: LabelTensor :rtype: LabelTensor
""" """
residual = torch.hstack( residual = torch.hstack(