Derivative Functionals#

Note

The rectilinear_grid_divergence, rectilinear_grid_curl, and rectilinear_grid_laplacian functionals support periodic boundary conditions only.

Where available, Warp implementations of the derivative functionals on this page compute internally in float32. Non-float32 floating-point inputs are cast to float32 for computation, and outputs are cast back to the input field or value dtype. Consequently, float64 outputs retain their dtype but are limited to float32 numerical precision.

physicsnemo.nn.functional.uniform_grid_gradient( field: Tensor, spacing: float | Sequence[float] = 1.0, order: int = 2, derivative_orders: int | Sequence[int] = 1, include_mixed: bool = False, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic central-difference gradients on a uniform grid.

This functional computes first-order and/or second-order derivatives of a scalar field defined on a 1D/2D/3D uniform Cartesian grid with periodic indexing.

For each axis \(k\), the first derivative is:

\[\partial_k f(\mathbf{i}) \approx \frac{f(\mathbf{i}+\hat{e}_k) - f(\mathbf{i}-\hat{e}_k)}{2\,\Delta x_k}\]

and the pure second derivative is:

\[\partial_{kk} f(\mathbf{i}) \approx \frac{f(\mathbf{i}+\hat{e}_k)-2f(\mathbf{i})+f(\mathbf{i}-\hat{e}_k)} {\Delta x_k^2}\]

with periodic wrap-around at boundaries.

Parameters:

field (torch.Tensor) – Scalar grid field with shape (n0,), (n0,n1), or (n0,n1,n2).
spacing (float | Sequence[float], optional) – Uniform spacing per axis. Use a scalar for isotropic spacing or a sequence matching field dimensionality.
order (int, optional) – Central-difference accuracy order. Supported values are 2 and 4.
derivative_orders (int | Sequence[int], optional) – Derivative orders to compute. Supported values are 1, 2, or (1, 2).
include_mixed (bool, optional) – Include mixed second derivatives when requesting second derivatives. Mixed terms are appended in axis-pair order (x,y), (x,z), (y,z).
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, rank-based backend dispatch is used.

Returns:

Gradient tensor of shape (num_derivatives, *field.shape).

Return type:

torch.Tensor

physicsnemo.nn.functional.rectilinear_grid_gradient( field: Tensor, coordinates: Sequence[Tensor], periods: float | Sequence[float] | None = None, derivative_orders: int | Sequence[int] = 1, include_mixed: bool = False, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic gradients on rectilinear grids with nonuniform spacing.

This functional computes first-order and/or second-order derivatives of a scalar field on a 1D/2D/3D rectilinear grid where each axis has independent, potentially nonuniform coordinate spacing.

For each axis \(k\), first-order nonuniform central differencing is:

\[\partial_k f_i \approx a_i\,f_{i-1} + b_i\,f_i + c_i\,f_{i+1}\]

with

\[a_i = -\frac{h_i^+}{h_i^-(h_i^-+h_i^+)}, \quad b_i = \frac{h_i^+ - h_i^-}{h_i^- h_i^+}, \quad c_i = \frac{h_i^-}{h_i^+(h_i^-+h_i^+)}\]

and pure second derivatives are:

\[\partial_{kk} f_i \approx \tilde{a}_i\,f_{i-1} + \tilde{b}_i\,f_i + \tilde{c}_i\,f_{i+1}\]

with

\[\tilde{a}_i = \frac{2}{h_i^-(h_i^-+h_i^+)}, \quad \tilde{b}_i = -\frac{2}{h_i^- h_i^+}, \quad \tilde{c}_i = \frac{2}{h_i^+(h_i^-+h_i^+)}\]

where \(h_i^-\) and \(h_i^+\) are left/right periodic distances along that axis.

Parameters:

field (torch.Tensor) – Scalar grid field with shape (n0,), (n0,n1), or (n0,n1,n2).
coordinates (Sequence[torch.Tensor]) – Per-axis coordinate tensors (x0, x1, x2) matching field dimensions. Each axis tensor must be rank-1, strictly increasing, and length compatible with field.shape[axis].
periods (float | Sequence[float] | None, optional) – Period length per axis. If None, each axis is inferred as coords[-1] - coords[0] + (coords[1] - coords[0]).
derivative_orders (int | Sequence[int], optional) – Derivative orders to compute. Supported values are 1, 2, or (1, 2).
include_mixed (bool, optional) – Include mixed second derivatives when requesting second derivatives. Mixed terms are appended in axis-pair order (x,y), (x,z), (y,z).
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Gradient tensor of shape (num_derivatives, *field.shape).

Return type:

torch.Tensor

physicsnemo.nn.functional.rectilinear_grid_divergence( vector_field: Tensor, coordinates: Sequence[Tensor], periods: float | Sequence[float] | None = None, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic divergence on rectilinear grids with nonuniform spacing.

This functional evaluates the divergence of a channel-first vector field on a 1D/2D/3D periodic rectilinear grid. Each coordinate axis may have independent nonuniform spacing, and the derivative along each axis uses the same second-order central-difference stencil as physicsnemo.nn.functional.rectilinear_grid_gradient().

Parameters:

vector_field (torch.Tensor) – Channel-first vector field with shape (dim, *grid_shape) where dim is 1, 2, or 3.
coordinates (Sequence[torch.Tensor]) – Per-axis coordinate tensors matching grid_shape. Each tensor must be rank-1, strictly increasing, and on the same device as vector_field.
periods (float | Sequence[float] | None, optional) – Period length per axis. If None, each period is inferred from the coordinate span plus the first spacing.
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Scalar divergence field with shape grid_shape.

Return type:

torch.Tensor

physicsnemo.nn.functional.rectilinear_grid_curl( vector_field: Tensor, coordinates: Sequence[Tensor], periods: float | Sequence[float] | None = None, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic curl on rectilinear grids with nonuniform spacing.

This functional evaluates the curl of a channel-first vector field on a 2D or 3D periodic rectilinear grid. In 2D, the scalar out-of-plane curl d(v_y)/dx - d(v_x)/dy is returned. In 3D, the returned tensor is a channel-first vector field with the same shape as the input.

Parameters:

vector_field (torch.Tensor) – Channel-first vector field with shape (2, n0, n1) or (3, n0, n1, n2).
coordinates (Sequence[torch.Tensor]) – Per-axis coordinate tensors matching the grid dimensions. Each tensor must be rank-1, strictly increasing, and on the same device as vector_field.
periods (float | Sequence[float] | None, optional) – Period length per axis. If None, each period is inferred from the coordinate span plus the first spacing.
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Scalar curl field for 2D inputs or channel-first vector curl field for 3D inputs.

Return type:

torch.Tensor

Examples

Compute the scalar curl of a two-dimensional periodic vector field:

>>> import torch
>>> x = torch.linspace(0.0, 1.0, 9)[:-1]
>>> y = torch.linspace(0.0, 1.0, 7)[:-1]
>>> xx, yy = torch.meshgrid(x, y, indexing="ij")
>>> vector_field = torch.stack(
...     (torch.zeros_like(xx), torch.sin(2.0 * torch.pi * xx))
... )
>>> curl = rectilinear_grid_curl(
...     vector_field,
...     (x, y),
...     periods=(1.0, 1.0),
...     implementation="torch",
... )
>>> curl.shape
torch.Size([8, 6])

physicsnemo.nn.functional.rectilinear_grid_laplacian( field: Tensor, coordinates: Sequence[Tensor], periods: float | Sequence[float] | None = None, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic scalar Laplacians on nonuniform rectilinear grids.

This functional evaluates the sum of pure second derivatives of a scalar field on a 1D/2D/3D periodic rectilinear grid. Each axis uses the same nonuniform second-derivative stencil as physicsnemo.nn.functional.rectilinear_grid_gradient().

Parameters:

field (torch.Tensor) – Scalar grid field with shape (n0,), (n0, n1), or (n0, n1, n2).
coordinates (Sequence[torch.Tensor]) – Per-axis coordinate tensors matching field.shape. Each tensor must be rank-1, strictly increasing, and on the same device as field.
periods (float | Sequence[float] | None, optional) – Period length per axis. If None, each period is inferred from the coordinate span plus the first spacing.
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Scalar Laplacian field with the same shape as field.

Return type:

torch.Tensor

Examples

Compute the Laplacian of a one-dimensional periodic scalar field:

>>> import torch
>>> x = torch.linspace(0.0, 1.0, 9)[:-1]
>>> field = torch.sin(2.0 * torch.pi * x)
>>> laplacian = rectilinear_grid_laplacian(
...     field,
...     (x,),
...     periods=1.0,
...     implementation="torch",
... )
>>> laplacian.shape
torch.Size([8])
>>> torch.isfinite(laplacian).all().item()
True

physicsnemo.nn.functional.mesh_lsq_gradient( points: Tensor, values: Tensor, neighbor_offsets: Tensor, neighbor_indices: Tensor, weight_power: float = 2.0, min_neighbors: int = 0, safe_epsilon: float | None = None, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Weighted least-squares gradient reconstruction on unstructured entities.

This functional computes gradients from unstructured neighborhoods provided as CSR adjacency (neighbor_offsets, neighbor_indices).

For each entity \(i\), it solves the weighted least-squares problem:

\[\nabla \phi_i = \arg\min_g \sum_{j \in \mathcal{N}(i)} w_{ij} \left(g^T(x_j - x_i) - (\phi_j - \phi_i)\right)^2\]

with inverse-distance weighting:

\[w_{ij} = ||x_j - x_i||^{-\alpha}\]

where \(\alpha\) is weight_power.

Parameters:

points (torch.Tensor) – Entity coordinates with shape (n_entities, dims).
values (torch.Tensor) – Scalar or tensor values with shape (n_entities,) or (n_entities, ...).
neighbor_offsets (torch.Tensor) – CSR offsets with shape (n_entities + 1,).
neighbor_indices (torch.Tensor) – CSR flattened neighbor indices with shape (nnz,).
weight_power (float, optional) – Inverse-distance exponent used for weighting.
min_neighbors (int, optional) – Entities with fewer than this count get zero gradients.
safe_epsilon (float | None, optional) – Positive floor applied to squared neighbor distances before inverse-distance weighting. When None, a dtype-derived default is used by each backend.
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Gradients with shape (n_entities, dims) for scalar values or (n_entities, dims, ...) for tensor values.

Return type:

torch.Tensor

physicsnemo.nn.functional.mesh_green_gauss_gradient( points: Tensor, cells: Tensor, neighbors: Tensor, values: Tensor, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute cell-centered gradients using Green-Gauss face flux balances.

This functional reconstructs gradients from cell-centered values on simplicial meshes (2D triangles or 3D tetrahedra) using:

\[\nabla \phi_i \approx \frac{1}{V_i} \sum_{f \in \partial i} \phi_f \, \mathbf{A}_{i,f}\]

where \(V_i\) is cell volume/area, \(\mathbf{A}_{i,f}\) is outward face-area vector, and face value \(\phi_f\) uses centered interpolation on interior faces:

\[\phi_f = \tfrac{1}{2}(\phi_i + \phi_j)\]

while boundary faces use \(\phi_f=\phi_i\).

Parameters:

points (torch.Tensor) – Mesh point coordinates with shape (n_points, dims) for dims in {2, 3}.
cells (torch.Tensor) – Simplicial connectivity with shape (n_cells, dims+1).
neighbors (torch.Tensor) – Precomputed cell-neighbor indices with shape (n_cells, n_faces), where boundary faces are marked with -1.
values (torch.Tensor) – Cell-centered values with shape (n_cells,) or (n_cells, ...).
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, dispatch selects by rank.

Returns:

Reconstructed gradients with shape (n_cells, dims) for scalar values or (n_cells, dims, ...) for tensor values.

Return type:

torch.Tensor

physicsnemo.nn.functional.spectral_grid_gradient( field: Tensor, lengths: float | Sequence[float] = 1.0, derivative_orders: int | Sequence[int] = 1, include_mixed: bool = False, *, implementation: Literal['torch'] | None = None, ) → Tensor#

Compute periodic derivatives with Fourier spectral differentiation.

This functional computes first-order and/or second-order derivatives on 1D/2D/3D periodic scalar fields by transforming to Fourier space, applying exact derivative multipliers, and transforming back.

Parameters:

field (torch.Tensor) – Scalar field on a periodic uniform grid with shape (n0,), (n0, n1), or (n0, n1, n2).
lengths (float | Sequence[float], optional) – Physical domain lengths per axis. A scalar applies the same length to every axis.
derivative_orders (int | Sequence[int], optional) – Derivative orders to compute. Supported values are 1, 2, or (1, 2).
include_mixed (bool, optional) – Include mixed second derivatives when requesting second derivatives.
implementation ({"torch"} or None) – Implementation to use. When None, dispatch selects the available implementation.

Returns:

Stacked derivative tensor with shape (num_derivatives, *field.shape). Derivative ordering is deterministic: first derivatives, then pure second derivatives, then mixed second derivatives in axis-pair order (x,y), (x,z), (y,z).

Return type:

torch.Tensor

physicsnemo.nn.functional.meshless_fd_derivatives( stencil_values: Tensor, spacing: float | Sequence[float] = 1.0, derivative_orders: int | Sequence[int] = 1, include_mixed: bool = False, *, implementation: Literal['torch'] | None = None, ) → Tensor#

Compute meshless finite-difference derivatives from local stencil values.

This functional expects values already sampled on a canonical Cartesian {-1, 0, 1} stencil around each query point. It does not build stencil coordinates internally; it only maps stencil values to derivative estimates using central finite-difference formulas.

Parameters:

stencil_values (torch.Tensor) – Values sampled on a canonical {-1,0,1} stencil with shape (num_points, stencil_size) or (num_points, stencil_size, channels). Stencil sizes must be 3, 9, or 27.
spacing (float | Sequence[float], optional) – Stencil spacing per axis.
derivative_orders (int | Sequence[int], optional) – Derivative orders to compute. Supported values are 1, 2, or (1, 2).
include_mixed (bool, optional) – Include mixed second derivatives when requesting second derivatives.
implementation ({"torch"} or None) – Implementation to use. When None, dispatch selects the available implementation.

Returns:

Stacked derivatives with shape (num_derivatives, num_points) for scalar input or (num_derivatives, num_points, channels) for vector input.

Return type:

torch.Tensor

Notes

Derivative stack ordering is deterministic: first derivatives, then pure second derivatives, then mixed second derivatives in axis-combination order.

The stencil size infers dimensionality: 3 -> 1D, 9 -> 2D, 27 -> 3D.

Uniform Grid Vector Calculus#

Note

The uniform_grid_divergence, uniform_grid_curl, and uniform_grid_laplacian functionals support periodic boundary conditions only.

Their Warp implementations compute internally in float32. Non-float32 floating-point inputs are cast to float32 for computation, and outputs are cast back to the input field or value dtype. Consequently, float64 outputs retain their dtype but are limited to float32 numerical precision.

physicsnemo.nn.functional.uniform_grid_divergence( vector_field: Tensor, spacing: float | Sequence[float] = 1.0, order: int = 2, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic divergence on a uniform grid.

This functional accepts channel-first vector fields with shape (dim, *grid_shape) where dim matches the 1D/2D/3D grid dimensionality. Divergence is computed as the trace of the Jacobian,

\[\nabla \cdot u = \sum_i \partial_i u_i.\]

Parameters:

vector_field (torch.Tensor) – Channel-first vector field with shape (dim, *grid_shape).
spacing (float | Sequence[float], optional) – Uniform spacing per grid axis. A scalar applies the same spacing to every axis.
order (int, optional) – Central-difference accuracy order. Supported values match physicsnemo.nn.functional.uniform_grid_gradient().
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, rank-based backend dispatch is used.

Returns:

Scalar divergence field with shape grid_shape.

Return type:

torch.Tensor

physicsnemo.nn.functional.uniform_grid_curl( vector_field: Tensor, spacing: float | Sequence[float] = 1.0, order: int = 2, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic curl on a uniform grid.

This functional accepts channel-first vector fields with shape (dim, *grid_shape) for 2D or 3D uniform grids. For 2D inputs, it returns scalar vorticity. For 3D inputs, it returns the channel-first vector curl.

Parameters:

vector_field (torch.Tensor) – Channel-first vector field with shape (2, n0, n1) or (3, n0, n1, n2).
spacing (float | Sequence[float], optional) – Uniform spacing per grid axis. A scalar applies the same spacing to every axis.
order (int, optional) – Central-difference accuracy order. Supported values match physicsnemo.nn.functional.uniform_grid_gradient().
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, rank-based backend dispatch is used.

Returns:

Scalar curl with shape grid_shape for 2D inputs, or vector curl with shape (3, *grid_shape) for 3D inputs.

Return type:

torch.Tensor

physicsnemo.nn.functional.uniform_grid_laplacian( field: Tensor, spacing: float | Sequence[float] = 1.0, order: int = 2, *, implementation: Literal['warp', 'torch'] | None = None, ) → Tensor#

Compute periodic Laplacians on a uniform grid.

This functional accepts scalar fields defined on a 1D/2D/3D uniform Cartesian grid and computes the trace of the Hessian,

\[\nabla^2 f = \sum_i \partial_{ii} f.\]

Parameters:

field (torch.Tensor) – Scalar grid field with shape (n0,), (n0,n1), or (n0,n1,n2).
spacing (float | Sequence[float], optional) – Uniform spacing per grid axis. A scalar applies the same spacing to every axis.
order (int, optional) – Central-difference accuracy order. Supported values match physicsnemo.nn.functional.uniform_grid_gradient().
implementation ({"warp", "torch"} or None) – Explicit backend selection. When None, rank-based backend dispatch is used.

Returns:

Scalar Laplacian field with the same shape as field.

Return type:

torch.Tensor