differential_geometry.dense_utils.dense_lower_index#

differential_geometry.dense_utils.dense_lower_index(tensor_field: ndarray, index: int, rank: int, metric_field: ndarray, out: ndarray | None = None, **kwargs) → ndarray[source]#

Lowers a specified index of a tensor field using the metric tensor.

Parameters:

  • tensor_field (numpy.ndarray) –

    The tensor field whose index signature is to be adjusted. The array should have shape (F₁, ..., F_m, I₁, ..., I_r), where:

    • (F₁, ..., F_m) are the field (spatial or grid) dimensions,

    • (I₁, ..., I_r) are the tensor index dimensions, and

    • r is the tensor rank (i.e., the number of tensor indices, inferred from tensor_signature).

  • index (int) – The index to lower, ranging from 0 to rank-1.

  • rank (int) – The tensor rank (number of tensor indices, not including grid dimensions).

  • metric_field (numpy.ndarray, optional) –

    The metric tensor used to lower contravariant indices. This can be either:

    • A full metric of shape (…, N, N), where N is the size of each tensor slot.

    • A diagonal metric of shape (…, N), representing only the diagonal components.

    Must be broadcast-compatible with the grid shape of tensor_field.

  • out (numpy.ndarray, optional) – Optional output array to store the result. If provided, must have the same shape and dtype as the expected output, and will be used for in-place storage.

Returns:

A tensor field with the specified index lowered. Has the same shape as tensor_field.

Return type:

numpy.ndarray

See also

raise_index, adjust_tensor_signature

Raises:

ValueError – If the input shapes or indices are invalid.

Examples

In spherical coordinates, the metric tensor is diagonal:

\[g_{\mu\nu} = \mathrm{diag}(1, r^2, r^2 \sin^2\theta)\]

If you have a contravariant vector with components:

\[v^\mu = [0,\ r,\ 0]\]

then the covariant version (with one index lowered) is given by:

\[v_\mu = g_{\mu\nu} v^\nu = [0,\ r^3,\ 0]\]

Let’s see this work in practice:

>>> import numpy as np
>>> from pymetric.differential_geometry.dense_utils import dense_lower_index
>>>
>>> # Construct the contravariant vector field at a point.
>>> r, theta = 2.0, np.pi / 4
>>> v_contra = np.array([0.0, r, 0.0])  # v^theta = r
>>>
>>> # Construct the spherical coordinate metric (diagonal)
>>> g_diag = np.array([1.0, r**2, r**2 * np.sin(theta)**2])  # g_{rr}, g_{θθ}, g_{φφ}
>>>
>>> # Lower the index
>>> v_cov = dense_lower_index(v_contra, index=0, rank=1, metric_field=g_diag)
>>> v_cov
array([0., 8., 0.])
On this page

This Page