grids.mixins.mathops.DenseMathOpsMixin.dense_adjust_tensor_signature#

DenseMathOpsMixin.dense_adjust_tensor_signature(tensor_field, field_axes, indices, tensor_signature, /, 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, 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]#

Adjust the index signature of a tensor field by raising or lowering multiple indices.

This method converts the variance (covariant vs. contravariant) of one or more indices of a tensor field to match a desired target signature. The transformation is applied in a single pass using the appropriate metric tensor, which may be full or diagonal depending on the coordinate system.

It generalizes dense_contract_with_metric() to allow simultaneous transformation of multiple indices and automatically selects raise/lower operations based on the desired tensor_signature.

Hint

Wraps _dense_adjust_tensor_signature() or its diagonal-metric variant.

Parameters:

  • tensor_field (array-like) – The input tensor field whose indices will be transformed. The array shape must match the grid over field_axes followed by rank trailing axes representing tensor components.

  • 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, tensor_field’s i-th index should match the shape of the grid for that coordinate. (See Notes for more details).

  • indices (list of int) – Indices among the last rank axes to be modified.

  • tensor_signature (list of int) – Current signature of the tensor’s component axes. Must be of length rank and contain values +1 for contravariant and -1 for covariant indices.

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

  • metric_field (array-like, optional) – Pre-computed metric and inverse metric used for the conversions. Provide one or both to avoid recomputation. Shape rules follow dense_contract_with_metric().

  • inverse_metric_field (array-like, optional) – Pre-computed metric and inverse metric used for the conversions. Provide one or both to avoid recomputation. Shape rules follow dense_contract_with_metric().

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

Tensor with the specified slots in the requested variance.

Return type:

array-like

Notes

Signature Logic

For each index k in indices, this method compares the target signature with the current one from tensor_signature:

  • If tensor_signature[k] == -1 and the index is currently contravariant, it is lowered.

  • If tensor_signature[k] == +1 and the index is currently covariant, it is raised.

  • If already in the correct form, no operation is applied to that index.

Metric Field Requirements

Depending on the operation and coordinate system, the following metric shapes are supported:

  • Diagonal metric: shape (..., ndim)

  • Full metric: shape (..., ndim, ndim)

If not provided, both metric and inverse metric are computed automatically from the coordinate system (globally or chunk-wise).

Chunked Execution

When in_chunks=True, the field is processed in chunks with halo padding. This is useful for HDF5-backed or large fields where full-domain memory use is undesirable.

Efficiency Tip

For repeated transformations over the same grid (e.g., adjusting multiple tensor fields), you can precompute metric_field and inverse_metric_field using compute_function_on_grid() or similar and pass them in to avoid redundant evaluation.

See also

dense_contract_with_metric

Lower- or raise a single tensor index.