grids.mixins.mathops.DenseMathOpsMixin.dense_vector_divergence#

Compute the divergence of a vector field, with automatic basis dispatching.

This is a convenience wrapper around: - dense_vector_divergence_contravariant() if basis=’contravariant’ - dense_vector_divergence_covariant() if basis=’covariant’

Parameters:

vector_field (array-like) – The vector field on which to compute the divergence. This should be an array-like object with a compliant shape (see Notes below).
field_axes (list of str) – The coordinate axes over which the 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, field’s i-th index should match the shape of the grid for that coordinate. (See Notes for more details).
basis ({'contravariant', 'covariant'}, optional) –
The basis in which the input vector field is represented:
- If 'contravariant' (default), the input is assumed to be a contravariant vector \(V^\mu\), and the divergence is computed directly using:
  
  \[\nabla \cdot V = \partial_\mu V^\mu + D_\mu V^\mu\]
  
  The inverse_metric_field is not required or used. The derivative_field can be supplied in this case.
- If 'covariant', the input is assumed to be a covector field \(V_\mu\). In this case, the divergence is computed via:
  
  \[\nabla \cdot V = \frac{1}{\rho} \partial_\mu(\rho g^{\mu\nu} V_\nu)\]
  
  which requires contraction with the inverse metric \(g^{\mu\nu}\). If not provided, this is derived automatically from the coordinate system. The derivative_field is ignored for this basis.
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}\) for the coordinate system, where \(\rho = \sqrt{|g|}\) is the metric volume element.

If not provided, it is computed automatically from the coordinate system. Supplying it can improve performance or accuracy.

The array must be broadcast-compatible with the grid shape over output_axes, and have a final dimension of size equal to ndim, one per coordinate direction.
inverse_metric_field (array-like, optional) –
The inverse metric tensor \(g^{\mu\nu}\) used to raise covariant components.

This field is only required if basis='covariant' and will be ignored in contravariant mode.

If omitted, it is computed from the coordinate system. The expected shape depends on the metric type:
- For diagonal (orthogonal) metrics: shape (…, ndim)
- For full (non-orthogonal) metrics: shape (…, ndim, ndim)
In both cases, the leading shape must match the grid domain over output_axes.
derivative_field (array-like, optional) –
The first derivatives of the input vector field \(\partial_\mu V^\nu\).

This is optional—if not provided, derivatives are computed numerically. If known analytically or precomputed, supplying this can improve accuracy and reduce compute time.

The array must be broadcast-compatible with the grid over output_axes, and its final dimension should match the number of coordinate axes over which derivatives are taken (typically ndim).
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_vector_divergence_contravariant().

Returns:

Scalar divergence on the grid. The shape equals the broadcasted grid shape over output_axes (ghost zones included when the grid carries them).

Return type:

array‑like

Notes

The divergence formula used depends on the input basis. The contravariant case requires only the vector field and optionally its derivatives. The covariant case requires the inverse metric for contraction.
If output_axes is provided, all fields (vector_field, Dterm_field, etc.) must be broadcastable over that domain.
If in_chunks=True, each chunk is extended by a 1-cell halo for stencil accuracy and processed independently. Chunking is useful when working with HDF5-backed or lazily loaded buffers.

grids.mixins.mathops.DenseMathOpsMixin.dense_vector_divergence#

This Page