fields.mixins.dense_mathops.DenseTensorFieldDMOMixin.adjust_tensor_signature#

Adjust the variance (covariant or contravariant) of multiple tensor indices.

This method applies metric contractions to raise or lower selected slots of the field’s element shape, transforming them between covariant and contravariant form. It modifies only the specified indices and leaves all other slots unchanged.

Under the hood, this wraps dense_adjust_tensor_signature(), which applies one or more contractions using either the metric \(g_{\mu\nu}\) or its inverse \(g^{\mu\nu}\), depending on the target signature.

Parameters:

indices (list of int) –
The tensor slots (i.e., axes 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), indices=[0] contracts the first value index (e.g., the row), while indices=[1] contracts the second (e.g., the column).
metric_field (array-like, optional) –
Optional precomputed metric and inverse metric tensors used during contraction.
- metric_field is used to lower covariant indices and must correspond to \(g_{\mu\nu}\)
- inverse_metric_field is used to raise contravariant indices and must correspond to \(g^{\mu\nu}\)
You may provide one or both, depending on which indices are being modified. Any missing tensor will be computed automatically from the grid’s coordinate system.

Expected shapes:
- Diagonal (orthogonal) systems: (*spatial_shape, ndim)
- Full (non-orthogonal) systems: (*spatial_shape, ndim, ndim)
Here, spatial_shape refers to the shape of the field over its domain grid axes.
inverse_metric_field (array-like, optional) –
Optional precomputed metric and inverse metric tensors used during contraction.
- metric_field is used to lower covariant indices and must correspond to \(g_{\mu\nu}\)
- inverse_metric_field is used to raise contravariant indices and must correspond to \(g^{\mu\nu}\)
You may provide one or both, depending on which indices are being modified. Any missing tensor will be computed automatically from the grid’s coordinate system.

Expected shapes:
- Diagonal (orthogonal) systems: (*spatial_shape, ndim)
- Full (non-orthogonal) systems: (*spatial_shape, ndim, ndim)
Here, spatial_shape refers to the shape of the field over its domain grid axes.
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.
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.
**kwargs – Passed straight to the low-level metric-contraction kernels (e.g. where= masks).
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).
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.

Returns:

The tensor field with updated variance on the specified slots. It will match the shape of the calling field.

Return type:

DenseTensorField or numpy.ndarray

Notes

Variance Adjustment Logic

Each entry in indices is matched against the corresponding component in the current tensor signature (stored in self.signature). Based on the desired transformation, the following logic is applied:

If the current slot is covariant (−1) and the target is +1 → raise
If the current slot is contravariant (+1) and the target is −1 → lower
If the slot already matches the target signature, no action is taken.

Metric Field Requirements

Orthogonal metrics (diagonal): shape (*spatial_shape, ndim)
Non-orthogonal metrics (full): shape (*spatial_shape, ndim, ndim)

Chunking Behavior

If in_chunks=True, each grid chunk is processed independently with 1-cell halo padding for stencil accuracy. This mode is especially useful with HDF5-backed or large fields.

Buffer Handling

If as_array=False, the result is wrapped using the buffer system. The buffer type may be explicitly controlled via buffer_class, buffer_registry, and related args.

If as_array=True, the raw NumPy array is returned, and no wrapping occurs.

fields.mixins.dense_mathops.DenseTensorFieldDMOMixin.adjust_tensor_signature#

This Page