differential_geometry.general_ops.dense_element_wise_partial_derivatives#

differential_geometry.general_ops.dense_element_wise_partial_derivatives(field: ndarray, rank: int, *varargs, field_axes: Sequence[int] | None = None, output_indices: Sequence[int] | None = None, edge_order: Literal[1, 2] = 2, out: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, **_) → ndarray[source]#

Compute the element-wise covariant gradient of an array-valued field.

This function computes the raw partial derivatives \(\partial_\mu T\) of a tensor (or array) field with respect to its grid coordinates, treating each tensor component independently.

It returns the gradient along all spatial axes (or a subset, if specified), storing results in the final axis of the output. This is the covariant gradient in the sense of component-wise partial derivatives, without applying connection terms (i.e., no Christoffel symbols). It is not the covariant derivative.

Warning

This is a low-level utility function. It does not validate input shapes or ensure coordinate consistency. It assumes that the tensor rank and grid structure are correct.

Parameters:

  • field (numpy.ndarray) – Field of shape (F_1, ..., F_m, N, ...), where the last rank axes are the tensor index dimensions. The partial derivatives are computed over the first m axes.

  • rank (int) – Number of trailing axes that represent tensor indices (i.e., tensor rank). The rank determines the number of identified coordinate axes and therefore determines the shape of the returned array.

  • *varargs –

    Grid spacing for each spatial axis. Follows the same format as numpy.gradient(), and can be:

    • A single scalar (applied to all spatial 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 field_axes is provided, varargs must match its length. If axes is not provided, then varargs should be field.ndim - rank in length (or be a scalar).

  • field_axes (list of int, optional) – The spatial axes over which to compute the component-wise partial derivatives. If field_axes is not specified, then all field.ndim - rank axes are computed.

  • output_indices (list of int, optional) –

    Explicit mapping from each axis listed in field_axes to the indices in the output’s final dimension of size ndim. This parameter allows precise control over the placement of computed gradients within the output array.

    If provided, output_indices must have the same length as field_axes. Each computed gradient along the spatial axis field_axes[i] will be stored at index output_indices[i] in the last dimension of the output.

    If omitted, the default behavior is output_indices = field_axes, i.e., gradients are placed in the output slot corresponding to their source axis.

    Note

    All positions in the final axis of the output array not listed in output_indices are left unmodified (typically zero-filled unless out was pre-populated).

  • edge_order ({1, 2}, optional) – Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1.

  • out (numpy.ndarray, optional) – Buffer in which to store the output to preserve memory. If provided, out must have shape field.shape + (ndim,). If out is not specified, then it is allocated during the function call.

Return type:

numpy.ndarray

See also

numpy.gradient

The computational backend for this operation.

dense_gradient_contravariant_full

Contravariant gradient for full metric.

dense_gradient_contravariant_diag

Contravariant gradient for diagonal metric.

dense_gradient

Wrapper for user-facing gradient computations.