grids.mixins.mathops.DenseMathOpsMixin.dense_element_wise_laplacian#

Compute the element-wise Laplacian of an array-valued field on the grid.

For an array field \(T_{\ldots}^{\ldots}\), this method computes the Laplacian of each element individually. The scalar Laplacian of an element \(\phi\) is:

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

A numerically stable rearrangement is used in practice:

\[\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 form used internally for stable, metric-aware computation.

Hint

Internally calls either dense_scalar_laplacian_diag() (for diagonal metrics) or dense_scalar_laplacian_full() (for full metrics), depending on the coordinate system.

Parameters:

field (array-like) – The array-valued 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:

Array of the same shape as field, optionally broadcast over additional axes. Contains the computed Laplacian \(\nabla^2 \phi\) of each element in the input.

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

Use of Auxiliary Fields

Lterm_field is used to stabilize the Laplacian operator in curved coordinates.
inverse_metric_field allows skipping the on-the-fly metric computation.
derivative_field and second_derivative_field allow precomputing the necessary gradient terms.

Each of these inputs must conform to specific shape constraints:

Lterm_field: (…, ndim)
inverse_metric_field: (…, ndim) or (…, ndim, ndim)
derivative_field: (…, ndim)
second_derivative_field: (…, ndim) or (…, ndim, ndim)

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

Applicability

This method applies the scalar Laplacian element-wise to each component of the input field. It is appropriate for scalar fields, vector fields, or element-wise defined tensor fields in arbitrary curvilinear coordinates.

grids.mixins.mathops.DenseMathOpsMixin.dense_element_wise_laplacian#

This Page