grids.mixins.mathops.DenseMathOpsMixin.dense_scalar_laplacian#

Compute the element-wise Laplacian of a tensor field.

For a generic array field \(T_{\ldots}^{\ldots}\), the Laplacian of a given element (denoted \(\phi\)) is

\[\nabla^2 \phi = \nabla \cdot \nabla \phi = \frac{1}{\rho}\partial_\mu \left(\rho g^{\mu\nu} \partial_\nu \phi\right).\]

A more numerically stable expression of this result is

\[\nabla^2\phi = \frac{1}{\rho}\partial_\mu \left[g^{\mu\nu} \rho\right] \partial_\nu \phi + g^{\mu\nu} \partial_\mu\partial_\nu \phi = L^\nu \partial_\nu \phi + g^{\mu\nu} \partial_\mu\partial_\nu \phi.\]

This is the formula used here.

Hint

This method wraps the low-level dense_scalar_laplacian_full() or (if the metric tensor is diagonal), it wraps dense_scalar_laplacian_diag().

Parameters:

field (array-like) – The tensor field on which to operate. This must meet all the necessary shape criteria (see Notes).
field_axes (list of str) – The coordinate axes over which the tensor_field spans. This should be a sequence of strings referring to the various coordinates of the underlying coordinate_system of the grid. For each element in field_axes, tensor_field’s i-th index should match the shape of the grid for that coordinate. (See Notes for more details).
out (array-like, optional) – An optional buffer in which to store the result. This can be used to reduce memory usage when performing computations. The shape of out must be compliant with broadcasting rules (see Notes). out may be a buffer or any other array-like object.
Lterm_field (array-like, optional) –
The volume log-derivative field \(L^\nu = \frac{1}{\rho} \partial_\mu [g^{\mu\nu} \rho]\). If not provided, it is computed automatically using the coordinate system. This argument can be filled to reduce numerical error and improve computational efficiency if it is known.

If specified, Lterm_field must be shape compliant (see Notes).
inverse_metric_field (array-like, optional) –
A buffer containing the inverse metric field \(g^{\mu\nu}\). inverse_metric_field can be provided to improve computation speed (by avoiding computing it in stride); however, it is not required.

The inverse metric can be derived from the coordinate system when this argument is not provided. See Notes below for details on the shape of inverse_metric_field.
derivative_field (array-like, optional) –
A buffer containing the first derivatives of the field. Can be provided to improve computation speed (by avoiding computing it in stride); however, it is not required.

If specified, derivative_field must be shape compliant (see Notes).
second_derivative_field (array-like, optional) –
A buffer containing the second derivatives of the field. Can be provided to improve computation speed (by avoiding computing it in stride); however, it is not required.

If specified, second_derivative_field must be shape compliant (see Notes).
output_axes (list of str, optional) –
The axes of the coordinate system over which the result should span. By default, output_axes is the same as field_axes and the output field matches the span of the input field.

This argument may be specified to expand the number of axes onto which the output field is computed. output_axes must be a superset of the field_axes.
in_chunks (bool, optional) – Whether to perform the computation in chunks. This can help reduce memory usage during the operation but will increase runtime due to increased computational load. If input buffers are all fully-loaded into memory, chunked performance will only marginally improve; however, if buffers are lazy loaded, then chunked operations will significantly improve efficiency. Defaults to False.
edge_order ({1, 2}, optional) – Order of the finite difference scheme to use when computing derivatives. See numpy.gradient() for more details on this argument. Defaults to 2.
pbar (bool, optional) – Whether to display a progress bar when in_chunks=True.
pbar_kwargs (dict, optional) – Additional keyword arguments passed to the progress bar utility. These can be any valid arguments to tqdm.tqdm().
**kwargs – Additional keyword arguments passed to dense_scalar_laplacian_full() or dense_scalar_laplacian_diag().

Returns:

The computed partial derivatives. The resulting array will have a field shape matching the grid’s shape over the output_axes and an element shape matching that of field but with an additional (ndim,) sized dimension containing each of the partial derivatives for each index.

Return type:

array-like

Notes

Shape and Broadcasting Requirements

The spatial dimensions of field must match the grid shape exactly over the field_axes. For a scalar field on a grid with shape (G1, ..., Gm), and field_axes = [‘x’, ‘z’], the field must have shape (Gₓ, G_z). For tensor fields, additional trailing dimensions (beyond the spatial ones) are interpreted as tensor indices and must either match ndim exactly or be nested in a form that makes the Laplacian contractable (i.e., act elementwise).

The output shape will match the shape of tensor_field unless output_axes introduces additional broadcasting (e.g., singleton axes added by broadcast_array_to_axes).

Lterm and Inverse Metric

The Laplacian operator requires knowledge of both the inverse metric and the volume derivative term (Lterm). These are automatically computed from the coordinate system unless explicitly provided. If supplied manually:

Lterm_field must have shape (..., ndim)
inverse_metric_field must be either (..., ndim) (diagonal) or (..., ndim, ndim) (full)

Additionally, the derivative fields may be supplied. In that case,

derivative_field must have shape (..., ndim)
second_derivative_field must have shape (..., ndim) if the metric is diagonal and (..., ndim, ndim) if it is full.

Chunked Execution

When in_chunks=True, the Laplacian is computed in small memory-efficient blocks with halo padding of 1 cell. This is especially useful when tensor_field and out are backed by HDF5 or other lazy-loading array backends. Chunking requires the grid to support iter_chunk_slices(…).

When to Use This

This method is suitable for computing the Laplace–Beltrami operator in arbitrary curvilinear coordinate systems. It generalizes to higher-rank tensors when tensor_field contains dense component axes. For fields with symbolic or sparse component structure, see symbolic APIs.

grids.mixins.mathops.DenseMathOpsMixin.dense_scalar_laplacian#

This Page