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

fix doc model part 2

Browse Source
This commit is contained in:
giovanni
2025-03-14 16:07:08 +01:00
committed by Nicola Demo
parent 001d1fc9cf
commit f9881a79b5
18 changed files with 887 additions and 851 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
pina/model/block/embedding.py
View File

@@ -1,4 +1,4 @@
"""Embedding modulus."""
"""Modules for the Embedding blocks."""
import torch
from pina.utils import check_consistency
@@ -6,20 +6,18 @@ from pina.utils import check_consistency
class PeriodicBoundaryEmbedding(torch.nn.Module):
r"""
Imposing hard constraint periodic boundary conditions by embedding the
Enforcing hard-constrained periodic boundary conditions by embedding the
input.
A periodic function :math:`u:\mathbb{R}^{\rm{in}}
\rightarrow\mathbb{R}^{\rm{out}}` periodic in the spatial
coordinates :math:`\mathbf{x}` with periods :math:`\mathbf{L}` is such that:
A function :math:`u:\mathbb{R}^{\rm{in}} \rightarrow\mathbb{R}^{\rm{out}}`
is periodic with respect to the spatial coordinates :math:`\mathbf{x}`
with period :math:`\mathbf{L}` if:
.. math::
u(\mathbf{x}) = u(\mathbf{x} + n \mathbf{L})\;\;
\forall n\in\mathbb{N}.
The :meth:`PeriodicBoundaryEmbedding` augments the input such that the
periodic conditonsis guarantee. The input is augmented by the following
formula:
The :class:`PeriodicBoundaryEmbedding` augments the input as follows:
.. math::
\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[1,
@@ -32,44 +30,48 @@ class PeriodicBoundaryEmbedding(torch.nn.Module):
.. seealso::
**Original reference**:
1. Dong, Suchuan, and Naxian Ni (2021). *A method for representing
periodic functions and enforcing exactly periodic boundary
conditions with deep neural networks*. Journal of Computational
Physics 435, 110242.
1. Dong, Suchuan, and Naxian Ni (2021).
*A method for representing periodic functions and enforcing
exactly periodic boundary conditions with deep neural networks*.
Journal of Computational Physics 435, 110242.
DOI: `10.1016/j.jcp.2021.110242.
<https://doi.org/10.1016/j.jcp.2021.110242>`_
2. Wang, S., Sankaran, S., Wang, H., & Perdikaris, P. (2023). *An
expert's guide to training physics-informed neural networks*.
2. Wang, S., Sankaran, S., Wang, H., & Perdikaris, P. (2023).
*An expert's guide to training physics-informed neural
networks*.
DOI: `arXiv preprint arXiv:2308.0846.
<https://arxiv.org/abs/2308.08468>`_
.. warning::
The embedding is a truncated fourier expansion, and only ensures
function PBC and not for its derivatives. Ensuring approximate
periodicity in
the derivatives of :math:`u` can be done, and extensive
tests have shown (also in the reference papers) that this implementation
can correctly compute the PBC on the derivatives up to the order
:math:`\sim 2,3`, while it is not guarantee the periodicity for
:math:`>3`. The PINA code is tested only for function PBC and not for
its derivatives.
The embedding is a truncated fourier expansion, and enforces periodic
boundary conditions only for the function, and not for its derivatives.
Enforcement of the approximate periodicity in the derivatives can be
performed. Extensive tests have shown (see referenced papers) that this
implementation can correctly enforce the periodic boundary conditions on
the derivatives up to the order :math:`\sim 2,3`. This is not guaranteed
for orders :math:`>3`. The PINA module is tested only for periodic
boundary conditions on the function itself.
"""
def __init__(self, input_dimension, periods, output_dimension=None):
"""
:param int input_dimension: The dimension of the input tensor, it can
be checked with `tensor.ndim` method.
:param float | int | dict periods: The periodicity in each dimension for
the input data. If ``float`` or ``int`` is passed,
the period is assumed constant for all the dimensions of the data.
If a ``dict`` is passed the `dict.values` represent periods,
while the ``dict.keys`` represent the dimension where the
periodicity is applied. The `dict.keys` can either be `int`
if working with ``torch.Tensor`` or ``str`` if
working with ``LabelTensor``.
Initialization of the :class:`PeriodicBoundaryEmbedding` block.
:param int input_dimension: The dimension of the input tensor.
:param periods: The periodicity with respect to each dimension for the
input data. If ``float`` or ``int`` is passed, the period is assumed
to be constant over all the dimensions of the data. If a ``dict`` is
passed the `dict.values` represent periods, while the ``dict.keys``
represent the dimension where the periodicity is enforced.
The `dict.keys` can either be `int` if working with
:class:`torch.Tensor`, or ``str`` if working with
:class:`pina.label_tensor.LabelTensor`.
:type periods: float | int | dict
:param int output_dimension: The dimension of the output after the
fourier embedding. If not ``None`` a ``torch.nn.Linear`` layer
fourier embedding. If not ``None``, a :class:`torch.nn.Linear` layer
is applied to the fourier embedding output to match the desired
dimensionality, default ``None``.
dimensionality. Default is ``None``.
:raises TypeError: If the periods dict is not consistent.
"""
super().__init__()
@@ -98,9 +100,10 @@ class PeriodicBoundaryEmbedding(torch.nn.Module):
def forward(self, x):
"""
Forward pass to compute the periodic boundary conditions embedding.
Forward pass.
:param torch.Tensor x: Input tensor.
:param x: The input tensor.
:type x: torch.Tensor | LabelTensor
:return: Periodic embedding of the input.
:rtype: torch.Tensor
"""
@@ -125,12 +128,16 @@ class PeriodicBoundaryEmbedding(torch.nn.Module):
def _get_vars(self, x, indeces):
"""
Get variables from input tensor ordered by specific indeces.
Get the variables from input tensor ordered by specific indeces.
:param torch.Tensor x: The input tensor to extract.
:param list[int] | list[str] indeces: List of indeces to extract.
:return: The extracted tensor given the indeces.
:rtype: torch.Tensor
:param x: The input tensor from which to extract.
:type x: torch.Tensor | LabelTensor
:param indeces: The indeces to extract.
:type indeces: list[int] | list[str]
:raises RuntimeError: If the indeces are not consistent.
:raises RuntimeError: If the extraction is not possible.
:return: The extracted tensor.
:rtype: torch.Tensor | LabelTensor
"""
if isinstance(indeces[0], str):
try:
@@ -146,75 +153,79 @@ class PeriodicBoundaryEmbedding(torch.nn.Module):
return x[..., indeces]
else:
raise RuntimeError(
"Not able to extract right indeces for tensor."
"Not able to extract correct indeces for tensor."
" For more information refer to warning in the documentation."
)
@property
def period(self):
"""
The period of the periodic function to approximate.
The period of the function.
:return: The period of the function.
:rtype: dict | float | int
"""
return self._period
class FourierFeatureEmbedding(torch.nn.Module):
"""
Fourier Feature Embedding class for encoding input features
using random Fourier features.
r"""
Fourier Feature Embedding class to encode the input features using random
Fourier features.
This class applies a Fourier transformation to the input features, which can
help in learning high-frequency variations in data. The class supports
multiscale feature embedding, creating embeddings for each scale specified
by the ``sigma`` parameter.
The Fourier Feature Embedding augments the input features as follows
(3.10 of original paper):
.. math::
\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[
\cos\left( \mathbf{B} \mathbf{x} \right),
\sin\left( \mathbf{B} \mathbf{x} \right)\right],
where :math:`\mathbf{B}_{ij} \sim \mathcal{N}(0, \sigma^2)`.
If multiple ``sigma`` are passed, the resulting embeddings are concateneted:
.. math::
\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[
\cos\left( \mathbf{B}^1 \mathbf{x} \right),
\sin\left( \mathbf{B}^1 \mathbf{x} \right),
\cos\left( \mathbf{B}^2 \mathbf{x} \right),
\sin\left( \mathbf{B}^3 \mathbf{x} \right),
\dots,
\cos\left( \mathbf{B}^M \mathbf{x} \right),
\sin\left( \mathbf{B}^M \mathbf{x} \right)\right],
where :math:`\mathbf{B}^k_{ij} \sim \mathcal{N}(0, \sigma_k^2) \quad k \in
(1, \dots, M)`.
.. seealso::
**Original reference**:
Wang, S., Wang, H., and Perdikaris, P. (2021).
*On the eigenvector bias of Fourier feature networks: From regression to
solving multi-scale PDEs with physics-informed neural networks.*
Computer Methods in Applied Mechanics and Engineering 384 (2021):
113938.
DOI: `10.1016/j.cma.2021.113938.
<https://doi.org/10.1016/j.cma.2021.113938>`_
"""
def __init__(self, input_dimension, output_dimension, sigma):
r"""
This class applies a Fourier transformation to the input features,
which can help in learning high-frequency variations in data.
If multiple sigma are provided, the class
supports multiscale feature embedding, creating embeddings for
each scale specified by the sigma.
"""
Initialization of the :class:`FourierFeatureEmbedding` block.
The :obj:`FourierFeatureEmbedding` augments the input
by the following formula (3.10 of original paper):
.. math::
\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[
\cos\left( \mathbf{B} \mathbf{x} \right),
\sin\left( \mathbf{B} \mathbf{x} \right)\right],
where :math:`\mathbf{B}_{ij} \sim \mathcal{N}(0, \sigma^2)`.
In case multiple ``sigma`` are passed, the resulting embeddings
are concateneted:
.. math::
\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[
\cos\left( \mathbf{B}^1 \mathbf{x} \right),
\sin\left( \mathbf{B}^1 \mathbf{x} \right),
\cos\left( \mathbf{B}^2 \mathbf{x} \right),
\sin\left( \mathbf{B}^3 \mathbf{x} \right),
\dots,
\cos\left( \mathbf{B}^M \mathbf{x} \right),
\sin\left( \mathbf{B}^M \mathbf{x} \right)\right],
where :math:`\mathbf{B}^k_{ij} \sim \mathcal{N}(0, \sigma_k^2) \quad
k \in (1, \dots, M)`.
.. seealso::
**Original reference**:
Wang, Sifan, Hanwen Wang, and Paris Perdikaris. *On the eigenvector
bias of Fourier feature networks: From regression to solving
multi-scale PDEs with physics-informed neural networks.*
Computer Methods in Applied Mechanics and
Engineering 384 (2021): 113938.
DOI: `10.1016/j.cma.2021.113938.
<https://doi.org/10.1016/j.cma.2021.113938>`_
:param int input_dimension: The input vector dimension of the layer.
:param int output_dimension: The output dimension of the layer. The
output is obtained as a concatenation of the cosine and sine
embedding, hence it must be a multiple of two (even number).
:param int | float sigma: The standard deviation used for the
Fourier Embedding. This value must reflect the granularity of the
scale in the differential equation solution.
:param int input_dimension: The dimension of the input tensor.
:param int output_dimension: The dimension of the output tensor. The
output is obtained as a concatenation of cosine and sine embeddings.
:param sigma: The standard deviation used for the Fourier Embedding.
This value must reflect the granularity of the scale in the
differential equation solution.
:type sigma: float | int
:raises RuntimeError: If the output dimension is not an even number.
"""
super().__init__()
@@ -242,10 +253,11 @@ class FourierFeatureEmbedding(torch.nn.Module):
def forward(self, x):
"""
Forward pass to compute the fourier embedding.
Forward pass.
:param torch.Tensor x: Input tensor.
:return: Fourier embeddings of the input.
:param x: The input tensor.
:type x: torch.Tensor | LabelTensor
:return: Fourier embedding of the input.
:rtype: torch.Tensor
"""
# compute random matrix multiplication
@@ -259,6 +271,9 @@ class FourierFeatureEmbedding(torch.nn.Module):
@property
def sigma(self):
"""
Returning the variance of the sampled matrix for Fourier Embedding.
The standard deviation used for the Fourier Embedding.
:return: The standard deviation used for the Fourier Embedding.
:rtype: float | int
"""
return self._sigma