fields.mixins.dense_mathops.DenseTensorFieldDMOMixin.vector_divergence#

Compute the divergence of a vector field.

This method applies the divergence operator to a rank-1 tensor field (i.e., a vector field) by contracting the gradient with the metric or its inverse, depending on the field’s basis. For a vector field \(V^\mu\) or covector field \(V_\mu\), the divergence is:

\[\nabla \cdot V = \frac{1}{\rho} \partial_\mu (\rho V^\mu) = \partial_\mu V^\mu + \frac{1}{\rho} V^\mu \partial_\mu \rho\]

for contravariant vectors, or

\[\nabla \cdot V = \frac{1}{\rho} \partial_\mu (\rho g^{\mu\nu} V_\nu)\]

for covariant vectors.

The appropriate form is automatically selected based on the tensor signature.

Hint

This is a wrapper around dense_vector_divergence(), which delegates to either dense_vector_divergence_contravariant() or dense_vector_divergence_covariant().

Parameters:

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.
Dterm_field (array-like, optional) –
The D-term field \(D_\mu = \frac{\partial_\mu \rho}{\rho}\), where \(\rho = \sqrt{|g|}\) is the metric volume element of the coordinate system.

This term arises in expressions for the divergence and Laplacian in curved coordinates, and accounts for coordinate-dependent geometric volume effects.
- If not provided, the D-term is automatically computed from the coordinate system.
- If supplied, this can reduce redundant computation or improve accuracy if an analytical expression is known.
inverse_metric_field (array-like, optional) –
The inverse metric tensor \(g^{\mu\nu}\), used to raise covariant vector components when the field’s basis (as inferred from its tensor signature) is covariant.
- Required only if the field is covariant (i.e., its signature is (-1,)).
- Ignored when the field is contravariant (i.e., its signature is (+1,)).
If not provided, the inverse metric is automatically computed from the coordinate system.
derivative_field (array-like, optional) –
Precomputed partial derivatives of the input vector field: \(\partial_\mu V^\nu\).

This array is only used if the field is contravariant, and will be ignored if the field is covariant.

Providing this can reduce runtime and improve numerical accuracy when the derivatives are analytically known or already computed elsewhere. Otherwise, they are approximated using finite differences.
in_chunks (bool, default False) – If True, compute the result in streaming fashion over grid chunks to reduce memory usage.
pbar (bool, default True) – Show a progress bar during chunked computation.
pbar_kwargs (dict, optional) – Extra keyword arguments passed to the progress bar (e.g., desc or position).
as_array (bool, default False) – If True, return the raw array representing the result. If False, return a new symbolic field with the raised index.
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 class. Required for advanced dispatch.
buffer_args (Sequence, optional) – Positional arguments forwarded to the buffer constructor.
buffer_kwargs (dict, optional) – Keyword arguments forwarded to the buffer constructor.

Returns:

The scalar divergence of the field.

If as_array=False (default), returns a new DenseTensorField instance representing the divergence as a scalar field defined over the appropriate grid axes.
If as_array=True, returns a raw NumPy array with shape:
```
(grid_shape over output_axes)
```

This result contains one scalar value per spatial grid point and is rank-0 in element shape.

Return type:

DenseTenseField or ndarray

Notes

Field Signature Requirements

This operation is valid only for rank-1 tensor fields with one of the following signatures:

(+1,): a contravariant vector field
(-1,): a covariant vector field

An error is raised for all other signatures.

Output Shape

The result is a scalar field with the same spatial shape as the input, over the output_axes.

For example, if the input field spans (Nx, Ny, Nz) over [‘x’, ‘y’, ‘z’], the output will have shape (Nx, Ny, Nz).
No trailing element axes are retained in the result.

Auxiliary Inputs

Dterm_field must have shape (*spatial_shape, ndim), where the last axis indexes coordinate directions.
inverse_metric_field must have shape:
- (*spatial_shape, ndim) for diagonal metrics
- (*spatial_shape, ndim, ndim) for full metrics
derivative_field must have shape (*spatial_shape, ndim) if supplied, and is ignored for covariant fields.

Chunked Evaluation

When in_chunks=True, the divergence is computed block-by-block. A 1-cell halo is added around each chunk to preserve stencil accuracy in derivative operations. This is especially useful when:

Working with memory-mapped or HDF5-backed buffers
Reducing memory overhead for large grids

Coordinate System Handling

All required geometric quantities—including the metric, inverse metric, volume factor, and D-terms—are computed from the grid’s associated coordinate system unless manually overridden.

fields.mixins.dense_mathops.DenseTensorFieldDMOMixin.vector_divergence#

This Page