fields.mixins.dense_mathops.DenseTensorFieldDMOMixin.raise_index#

DenseTensorFieldDMOMixin.raise_index(index, inverse_metric_field: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, out: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, *, output_axes: Sequence[str] | None = None, as_array: bool = False, buffer_class: Type[BufferBase] | None = None, buffer_registry: BufferRegistry | None = None, buffer_args: Sequence[Any] | None = None, buffer_kwargs: Dict | None = None, **kwargs)[source]#

Raise a single covariant index of this tensor field.

This method contracts one of the tensor’s value axes with the inverse metric \(g^{\mu\nu}\) to convert a covariant component into a contravariant one. The operation modifies only the specified slot and leaves all other indices unchanged.

Hint

This is a convenience wrapper around dense_raise_index(), which itself wraps dense_contract_with_metric().

Parameters:

  • index (int) –

    The tensor slot (i.e., axis in the field’s trailing element shape) to operate on.

    This refers to the position among the field’s value axes, not its spatial grid axes. For example, in a rank-2 tensor field with shape (Nx, Ny, 3, 3), index=0 contracts the first value index (e.g., the row), while index=1 contracts the second (e.g., the column).

  • inverse_metric_field (array-like, optional) –

    The inverse metric tensor \(g^{\mu\nu}\), used for curved-coordinate contraction.

    • For diagonal metrics: shape (*spatial_shape, ndim)

    • For full metrics: shape (*spatial_shape, ndim, ndim)

    where spatial_shape is this field’s spatial_shape.

    If not provided, it is derived from the coordinate system.

  • 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.

  • output_axes (list of str, optional) –

    The axes of the coordinate system over which the result should span. By default, the dependence is calculated internally.

    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 axes of the calling field.

  • **kwargs – Passed straight to the low-level metric-contraction kernels (e.g. where= masks).

  • as_array (bool, default False) – If True, return the raw array representing the result. If False, return a new symbolic field with the raised index.

  • buffer_class (type, optional) –

    Class to use when wrapping the result buffer, e.g., fields.buffers.core.ArrayBuffer or fields.buffers.core.UnytArrayBuffer.

    Defaults to buffer resolution to determine a fitting buffer for the resulting array result.

  • buffer_registry (BufferRegistry, optional) – Registry to use when resolving the buffer class. Required for advanced dispatch.

  • buffer_args (Sequence, optional) – Positional arguments forwarded to the buffer constructor.

  • buffer_kwargs (dict, optional) – Keyword arguments forwarded to the buffer constructor.

  • in_chunks (bool, default False) – If True, compute the result in streaming fashion over grid chunks to reduce memory usage.

  • pbar (bool, default True) – Show a progress bar during chunked computation.

  • pbar_kwargs (dict, optional) – Extra keyword arguments passed to the progress bar (e.g., desc or position).

Returns:

The resulting tensor field with the specified index raised.

  • If as_array=False (default), returns a new field of the same type as this one (e.g., DenseField) with the indicated slot raised to contravariant form.

  • If as_array=True, returns a raw NumPy array with shape:

    (grid_shape over output_axes, ..., element_shape)

    where the element_shape reflects the updated tensor signature.

Return type:

DenseTensorField or numpy.ndarray

Notes

Index Contraction

This operation raises a single index of the field by contracting it with the inverse metric \(g^{\mu\nu}\). The index position is given by index, which refers to one of the trailing component axes in the field’s element shape (not spatial grid axes).

The rank of the tensor remains the same; only the variance (covariant → contravariant) of the specified slot is updated.

Metric Handling

If inverse_metric_field is not supplied, it is computed from the grid’s coordinate system:

  • For orthogonal systems (diagonal metric): shape (*spatial_shape, ndim)

  • For general systems (full metric): shape (*spatial_shape, ndim, ndim)

You may precompute this expression using compute_expression_from_coordinates() to avoid repeated work.

Chunked Evaluation

If in_chunks=True, the contraction is performed chunk-by-chunk across the domain. This can reduce memory pressure for large or lazily loaded fields.

Buffer Customization

If as_array=False, the resulting array is wrapped in a new field using the specified buffer_class, buffer_registry, and optional constructor arguments.

If as_array=True, those options are ignored and the raw array is returned directly.