differential_geometry.dense_ops.dense_vector_divergence_covariant_diag#

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

Compute the divergence of a covariant vector field in a general curvilinear coordinate system using a diagonal inverse metric tensor.

This function raises the index of the covariant field using a diagonal inverse metric, and then computes the divergence of the resulting contravariant vector field. The method implements:

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

where:

  • \(V^\mu = g^{\mu\mu} V_\mu\) is the contravariant vector field obtained by index raising,

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

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

This is a low-level routine and assumes input arrays are already correctly aligned and broadcast-compatible.

Parameters:

  • vector_field (numpy.ndarray) – Covariant vector field of shape (F1, ..., Fm, ndim), where the final axis indexes vector components, and the leading m axes define the spatial grid dimensions. This field must be broadcast-compatible with Dterm_field and inverse_metric_field.

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

  • inverse_metric_field (numpy.ndarray) – Diagonal inverse metric tensor with shape (..., ndim), where the final dimension indexes the diagonal entries \(g^{\mu\mu}\). The leading dimensions must be broadcast-compatible with the spatial shape of vector_field.

  • *varargs –

    Grid spacing for each axis. Accepts:

    • A single scalar (applied to all axes),

    • A list of scalars (one per axis),

    • A list of coordinate arrays,

    • A mix of scalars and arrays.

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

  • field_axes (list of int, optional) – Indices mapping each spatial grid axis to a corresponding component in the final axis of vector_field. Defaults to [0, 1, ..., m-1] if not provided.

  • derivative_axes (list of int, optional) – Subset of spatial axes over which to compute derivatives. This allows partial divergence over a subset of axes. Defaults to field_axes if not specified.

  • edge_order ({1, 2}, default 2) – Accuracy order for finite difference gradients at the array boundaries.

  • out (numpy.ndarray, optional) – Optional output buffer to store the result. Must have shape equal to the broadcasted grid shape of vector_field and Dterm_field (i.e., (F1, ..., Fm)). If not provided, it is allocated internally.

Returns:

Scalar divergence of the covariant vector field after index raising, with shape equal to the broadcasted spatial shape of vector_field and Dterm_field.

Return type:

numpy.ndarray

Notes

This routine is equivalent to:

V_contra = g^{mumu} * V_cov
div = D_mu * V^mu + diff_mu V^mu

but optimized for diagonal metrics to avoid unnecessary full tensor contractions.

No validation is performed on input shapes—use higher-level wrappers for shape checking and metric inference.

See also

dense_vector_divergence_contravariant

Computes divergence from contravariant vector fields.

dense_vector_divergence_covariant_full

Version supporting full inverse metric tensors.

compute_divergence

High-level user-facing wrapper.

Examples

>>> import numpy as np
>>> from pymetric.differential_geometry.dense_ops import dense_vector_divergence_covariant_diag
>>>
>>> # Grid
>>> x = np.linspace(0.01, 1.0, 100)
>>> y = np.linspace(0.1, np.pi - 0.1, 100)
>>> X, Y = np.meshgrid(x, y, indexing='ij')
>>>
>>> # Covariant field: V_r = x, V_theta = sin(theta)
>>> V = np.stack([X, np.sin(Y)], axis=-1)
>>>
>>> # D-terms (e.g., spherical coords): D_r = 2/x, D_theta = 1/tan(theta)
>>> Dr = 2 / X
>>> Dtheta = 1 / np.tan(Y)
>>> D = np.stack([Dr, Dtheta], axis=-1)
>>>
>>> # Diagonal inverse metric: g^rr = 1, g^thetatheta = 1/x^2
>>> IM_diag = np.stack([np.ones_like(X), 1 / X**2], axis=-1)
>>>
>>> # Compute divergence
>>> div = dense_vector_divergence_covariant_diag(V, D, IM_diag, x, y)
>>> div.shape
(100, 100)