differential_geometry.dense_ops.dense_vector_divergence#

differential_geometry.dense_ops.dense_vector_divergence(vector_field: ndarray, Dterm_field: ndarray, *varargs, basis: Literal['contravariant', 'covariant'] = 'contravariant', inverse_metric_field: ndarray | None = None, derivative_field: ndarray | None = None, field_axes: Sequence[int] | None = None, derivative_axes: Sequence[int] | None = None, out: ndarray | None = None, edge_order: Literal[1, 2] = 2, **kwargs) → ndarray[source]#

Compute the divergence of a vector field in a general coordinate system.

This high-level routine supports both contravariant and covariant vector fields. For covariant fields, the divergence is computed by first raising the index using the inverse metric tensor, then applying the conservative divergence formula:

\[\nabla_\mu V^\mu = D_\mu V^\mu + \partial_\mu V^\mu\]

where:

  • \(V^\mu\) is a contravariant vector field,

  • \(D_\mu = (\partial_\mu \rho)/\rho\) is the logarithmic derivative of the volume element,

  • The divergence is evaluated as a sum of the D-term contraction and raw partial derivatives.

The metric can be either full or diagonal, and this function automatically dispatches to the appropriate backend implementation.

Parameters:

  • vector_field (numpy.ndarray) –

    Input vector field of shape (F1, ..., Fm, ndim), where the final axis indexes the vector components and the first m axes represent spatial grid dimensions.

    If basis=”covariant”, this is treated as a covariant field whose index will be raised. If basis=”contravariant”, the field is used directly.

  • Dterm_field (numpy.ndarray) – Log-volume term array of shape (..., ndim), where the final axis matches the number of coordinate axes. Must be broadcast-compatible with the spatial dimensions of vector_field.

  • *varargs –

    Grid spacing for each spatial axis. Accepts:

    • A single scalar (applied to all axes),

    • A list of scalars (one per axis),

    • A list of coordinate arrays (one per axis),

    • A mix of scalars and arrays (broadcast-compatible).

    If derivative_axes is provided, the number of elements in varargs must match its length. Otherwise, varargs must match the number of spatial dimensions in vector_field.

  • basis ({'contravariant', 'covariant'}, optional) –

    Specifies the form of the input vector field:

    • 'contravariant' (default): treat the input as a contravariant field.

    • 'covariant': raise the index using the inverse metric before computing divergence.

  • inverse_metric_field (numpy.ndarray, optional) –

    Inverse metric tensor. Required if basis=’covariant’.

    Accepts:

    • Shape (..., ndim) for diagonal metric (\(g^{\mu\mu}\)),

    • Shape (..., ndim, ndim) for full metric (\(g^{\mu\nu}\)).

    Must be broadcast-compatible with the spatial shape of vector_field.

  • derivative_field (numpy.ndarray, optional) – Optional precomputed partial derivatives of the vector field components. If provided, must have shape (..., k), where k is the number of derivatives being taken (i.e., length of derivative_axes).

  • field_axes (list of int, optional) – Maps each spatial axis to the corresponding component index in vector_field. Defaults to [0, 1, ..., m-1] if not specified.

  • derivative_axes (list of int, optional) – Axes over which to compute partial derivatives. Defaults to field_axes if not provided.

  • out (numpy.ndarray, optional) – Output buffer for storing the divergence result. Must have shape equal to the broadcasted grid shape of vector_field and Dterm_field (excluding the final axis). If not provided, the buffer is allocated automatically.

  • edge_order ({1, 2}, default 2) – Order of accuracy for finite differencing used by numpy.gradient.

  • **kwargs – Additional keyword arguments forwarded to internal contraction routines.

Returns:

Scalar field representing the divergence of the input vector field. Shape is the broadcasted grid shape of vector_field and Dterm_field.

Return type:

numpy.ndarray

Raises:

ValueError – If required arguments are missing, incompatible with the basis, or have shape mismatches.

See also

dense_gradient

Computes the gradient of a tensor field.

dense_vector_divergence_contravariant

Low-level divergence for contravariant fields.

dense_vector_divergence_covariant_full

Divergence for covariant fields with full metrics.

dense_vector_divergence_covariant_diag

Divergence for covariant fields with diagonal metrics.

Examples

Compute the divergence of a vector field in 2D spherical coordinates \((r, \theta)\):

\[\vec{V}(r, \theta) = \begin{bmatrix} r \ \cos(k\theta) \end{bmatrix}\]

with known volume density:

\[\rho(r, \theta) = r^2 \sin(\theta)\]

which gives:

\[D_r = \frac{2}{r}, \quad D_\theta = \frac{1}{\tan(\theta)}, \quad g^{rr} = 1, \quad g^{\theta\theta} = \frac{1}{r^2}\]
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from pymetric.differential_geometry.dense_ops import compute_divergence
>>>
>>> # Create coordinate grid
>>> r = np.linspace(0.01, 1.0, 100)
>>> theta = np.linspace(0.1, np.pi - 0.1, 100)  # avoid singularities
>>> R, THETA = np.meshgrid(r, theta, indexing='ij')
>>>
>>> # Define vector field: V^r = r, V^theta = cos(theta)
>>> Vr = R
>>> Vtheta = np.cos(THETA)
>>> vector = np.stack([Vr, Vtheta], axis=-1)
>>>
>>> # D-terms
>>> D_r = 2 / R
>>> D_theta = 1 / np.tan(THETA)
>>> Dterm = np.stack([D_r, D_theta], axis=-1)
>>>
>>> # Inverse metric (diagonal)
>>> g_inv = np.stack([np.ones_like(R), 1 / R**2], axis=-1)
>>>
>>> # Compute divergence (contravariant)
>>> div = compute_divergence(vector, Dterm, r, theta, inverse_metric_field=g_inv, basis="contravariant")
>>>
>>> # Visualize
>>> _ = plt.imshow(div.T, extent=[0.01, 1.0, 0.1, np.pi-0.1], origin='lower', aspect='auto', cmap='RdBu')
>>> _ = plt.xlabel("r")
>>> _ = plt.ylabel(r"$\theta$")
>>> _ = plt.title(r"Divergence of $V = [r, \cos(\theta)]$ in Spherical Coordinates")
>>> _ = plt.colorbar(label="Divergence")
>>> _ = plt.tight_layout()
>>> _ = plt.show()
On this page

This Page