Periodic Boundary Condition Embedding#

class PeriodicBoundaryEmbedding(input_dimension, periods, output_dimension=None)[source]#

Bases: Module

Enforcing hard-constrained periodic boundary conditions by embedding the input.

A function \(u:\mathbb{R}^{\rm{in}} \rightarrow\mathbb{R}^{\rm{out}}\) is periodic with respect to the spatial coordinates \(\mathbf{x}\) with period \(\mathbf{L}\) if:

\[u(\mathbf{x}) = u(\mathbf{x} + n \mathbf{L})\;\; \forall n\in\mathbb{N}.\]

The PeriodicBoundaryEmbedding augments the input as follows:

\[\mathbf{x} \rightarrow \tilde{\mathbf{x}} = \left[1, \cos\left(\frac{2\pi}{L_1} x_1 \right), \sin\left(\frac{2\pi}{L_1}x_1\right), \cdots, \cos\left(\frac{2\pi}{L_{\rm{in}}}x_{\rm{in}}\right), \sin\left(\frac{2\pi}{L_{\rm{in}}}x_{\rm{in}}\right)\right],\]

where \(\text{dim}(\tilde{\mathbf{x}}) = 3\text{dim}(\mathbf{x})\).

See also

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. DOI: 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. DOI: arXiv preprint arXiv:2308.0846.

Warning

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 \(\sim 2,3\). This is not guaranteed for orders \(>3\). The PINA module is tested only for periodic boundary conditions on the function itself.

Initialization of the PeriodicBoundaryEmbedding block.

Parameters:

  • input_dimension (int) – The dimension of the input tensor.

  • periods (float | int | dict) – 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 torch.Tensor, or str if working with pina.label_tensor.LabelTensor.

  • output_dimension (int) – The dimension of the output after the fourier embedding. If not None, a torch.nn.Linear layer is applied to the fourier embedding output to match the desired dimensionality. Default is None.

Raises:

TypeError – If the periods dict is not consistent.

forward(x)[source]#

Forward pass.

Parameters:

x (torch.Tensor | LabelTensor) – The input tensor.

Returns:

Periodic embedding of the input.

Return type:

torch.Tensor

property period#

The period of the function.

Returns:

The period of the function.

Return type:

dict | float | int