grids.mixins.mathops.DenseMathOpsMixin.dense_lower_index#

DenseMathOpsMixin.dense_lower_index(tensor_field: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], field_axes: Sequence[str], index: int, /, out: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, metric_field: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, *, in_chunks: bool = False, output_axes: Sequence[str] | None = None, pbar: bool = True, pbar_kwargs: dict | None = None, **kwargs)[source]#

Lower a single contravariant index of a tensor field.

This method performs a metric contraction with the metric tensor \(g_{\mu\nu}\) to convert a contravariant (upper) index to covariant (lower) form. The index argument specifies which slot of the tensor should be lowered.

This is a specialized wrapper around dense_contract_with_metric() with mode='lower'.

Hint

Use this method to convert a component of a vector or higher-rank tensor into covariant form in curved coordinate systems.

Parameters:

  • tensor_field (array-like) – The input tensor field. Its shape must be compatible with the grid dimensions over field_axes, followed by one or more component axes representing the tensor rank.

  • field_axes (list of str) – The coordinate axes over which the tensor_field spans. This should be a sequence of strings referring to the various coordinates of the underlying coordinate_system of the grid. For each element in field_axes, field’s i-th index should match the shape of the grid for that coordinate. (See Notes for more details).

  • index (int) – The index of the tensor field to raise. This should range from 0 to rank and is measured from the last spatial dimension of the tensor field.

  • metric_field (array-like, optional) –

    A buffer containing the metric field \(g_{\mu\nu}\). metric_field can be provided to improve computation speed (by avoiding computing it in stride); however, it is not required.

    The metric can be derived from the coordinate system when this argument is not provided. See Notes below for details on the shape of metric_field.

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

  • in_chunks (bool, optional) – Whether to perform the computation in chunks. This can help reduce memory usage during the operation but will increase runtime due to increased computational load. If input buffers are all fully-loaded into memory, chunked performance will only marginally improve; however, if buffers are lazy loaded, then chunked operations will significantly improve efficiency. Defaults to False.

  • output_axes (list of str, optional) –

    The axes of the coordinate system over which the result should span. By default, output_axes is the same as field_axes and the output field matches the span of the input field.

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

  • pbar (bool, default True) – Show a progress bar when in_chunks=True.

  • pbar_kwargs (dict, optional) – Extra keyword arguments forwarded to tqdm.

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

Returns:

A tensor with the specified index lowered. Shape equals broadcast(grid_shape over output_axes) + element_shape.

Return type:

array-like

See also

dense_contract_with_metric

General routine for index contraction with a metric.

dense_raise_index

Inverse operation that raises an index using the inverse metric.