grids.mixins.mathops.DenseMathOpsMixin.dense_raise_index#

DenseMathOpsMixin.dense_raise_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, inverse_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]#

Raise a single covariant index of a tensor field.

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

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

Hint

Use this method to promote a component of a mixed or covariant tensor in curvilinear coordinates.

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.

  • inverse_metric_field (array-like, optional) –

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

    The inverse metric can be derived from the coordinate system when this argument is not provided. See Notes below for details on the shape of inverse_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 raised. 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_lower_index

Inverse operation that lowers an index using the metric.