fields.mixins.dense_mathops.DenseFieldDMOMixin.element_wise_laplacian#

Compute the element-wise Laplacian of the field.

This method evaluates the Laplacian operator for each scalar component of the field using the generalized curved-space expression:

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

which, for numerical stability, is implemented in expanded form as:

\[\nabla^2 \phi = \left( \frac{1}{\rho} \partial_\mu \left[ g^{\mu\nu} \rho \right] \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\]

where \(L^\nu\) is the “log-volume derivative” term for the coordinate system.

This method wraps the corresponding grid-level Laplacian operator and performs chunked or full-domain computation as needed. It supports optional auxiliary fields to bypass internal derivative or metric computations for improved efficiency or accuracy.

Hint

Internally wraps dense_element_wise_laplacian(), which delegates to dense_scalar_laplacian_diag() or dense_scalar_laplacian_full().

Parameters:

out (array-like, optional) – Optional buffer to store the result. Must match the grid shape over the evaluation domain (see output_axes) and the element shape of the field. If not provided, a new buffer is allocated.
Lterm_field (array-like, optional) –
Precomputed log-volume term:

\[L^\nu = \frac{1}{\rho} \partial_\mu \left( g^{\mu\nu} \rho \right)\]

Used to reduce numerical error and avoid redundant computation. Must have shape (*spatial_shape, ndim), where spatial_shape is this field’s spatial_shape.

If not supplied, it is computed automatically from the coordinate system.
inverse_metric_field (array-like, optional) –
The inverse metric tensor \(g^{\mu\nu}\), used for curved-coordinate contraction.
- For diagonal metrics: shape (*spatial_shape, ndim)
- For full metrics: shape (*spatial_shape, ndim, ndim)
where spatial_shape is this field’s spatial_shape.

If not provided, it is derived from the coordinate system.
derivative_field (array-like, optional) –
Precomputed first derivatives \(\partial_\nu \phi\) for each scalar component. This avoids re-computation of first-order gradients.

Must have shape (*spatial_shape, ..., ndim) where spatial_shape is this field’s spatial_shape, and the trailing ndim axis corresponds to derivatives with respect to each coordinate direction.
second_derivative_field (array-like, optional) –
Precomputed second derivatives \(\partial_\mu \partial_\nu \phi\).

Required shape depends on the metric type:
- Diagonal metric: (*spatial_shape, ..., ndim)
- Full metric: (*spatial_shape, ..., ndim, ndim)
where spatial_shape is this field’s spatial_shape, and the trailing ndim axis corresponds to derivatives with respect to each coordinate direction.
output_axes (list of str, optional) –
The axes of the coordinate system over which the result should span. By default, the dependence is calculated internally.

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 axes of the calling field.
in_chunks (bool, default False) – Whether to compute the result chunk-by-chunk using the grid’s chunking logic. This can reduce memory usage for large domains or lazy-loaded buffers.
edge_order ({1, 2}, default 2) – The order of the finite difference scheme to use for numerical derivatives. Passed to numpy.gradient().
pbar (bool, default True) – If in_chunks=True, whether to display a progress bar during processing.
pbar_kwargs (dict, optional) – Additional keyword arguments forwarded to the progress bar utility (tqdm).
as_array (bool, default False) – If True, return the raw NumPy array result. If False (default), wrap the result in a new DenseField instance.
buffer_class (type, optional) –
Class to use when wrapping the result buffer, e.g., fields.buffers.core.ArrayBuffer or fields.buffers.core.UnytArrayBuffer.

Defaults to buffer resolution to determine a fitting buffer for the resulting array result.
buffer_registry (BufferRegistry, optional) – Registry to use when resolving the buffer type.
buffer_args (optional) – Arguments forwarded to fields.buffers.base.buffer_from_array() when constructing the buffer.
buffer_kwargs (optional) – Arguments forwarded to fields.buffers.base.buffer_from_array() when constructing the buffer.
**kwargs – Additional arguments forwarded to the underlying numerical Laplacian routines.

Returns:

The computed Laplacian. Shape matches the field’s spatial domain and element shape.

If as_array=True, returns a NumPy array with shape (grid_shape, ..., element_shape).
If as_array=False, returns a new DenseField instance.

Return type:

DenseField or ndarray

Notes

Element-wise Behavior

The Laplacian is applied independently to each scalar component of the field. This includes each entry of a vector or tensor field. No automatic raising/lowering of indices is performed.

Shape Compatibility

The field must be defined over a structured grid. Its shape should follow: (grid_shape, ..., element_shape)

where grid_shape matches the dimensions of the field’s domain, and element_shape represents any trailing vector/tensor axes.

The result will have the same shape as the input field, unless output_axes introduces broadcasting.

Auxiliary Field Requirements

When provided, auxiliary fields must be shape-compatible with the grid and derivatives:

Lterm_field: shape (..., ndim)
inverse_metric_field: shape (..., ndim) or (..., ndim, ndim)
derivative_field: shape (..., ndim)
second_derivative_field: shape (..., ndim) or (..., ndim, ndim) depending on metric type

Chunked Execution

When in_chunks=True, each chunk of the domain is processed independently. Ghost cells (1-cell halo) are included automatically to preserve stencil accuracy during finite difference operations.

fields.mixins.dense_mathops.DenseFieldDMOMixin.element_wise_laplacian#

This Page