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 FilippoOlivo
parent 06e6c4763d
commit f420b09960
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__ = [
"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__ = [

37
pina/equation/equation.py
View File

@@ -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:

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 ..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)

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
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
"""

55
pina/equation/system_equation.py
View File

@@ -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(