grids.mixins.mathops.DenseMathOpsMixin.dense_contract_with_metric#

Contract a tensor index with the metric tensor or its inverse.

This method raises or lowers a single index of a tensor field by contracting it with the metric tensor \(g_{\mu\nu}\) or its inverse \(g^{\mu\nu}\).

Depending on the mode:

mode='lower' applies \(T^\mu \mapsto T_\nu = g_{\mu\nu} T^\mu\)
mode='raise' applies \(T_\mu \mapsto T^\nu = g^{\mu\nu} T_\mu\)

The appropriate form (full vs. diagonal) of the metric is automatically chosen based on the coordinate system’s geometry.

Hint

Internally wraps dense_contract_with_metric(), using the diagonal or full version depending on the metric type.

Parameters:

tensor_field (array-like) – The tensor field whose index signature is to be adjusted. See Notes for more details on the shape requirements.
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).
index (int) – Slot to raise or lower (0 <= index < rank).
mode ({'raise', 'lower'}, default 'lower') – Conversion direction. If 'raise', then the inverse metric tensor is used in the contraction. Otherwise, the metric tensor is used.
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) –
Optional precomputed metric or inverse metric to use in the contraction: - For mode='raise', this must be the inverse metric. - For mode='lower', this must be the metric.

May be diagonal (shape (..., ndim)) or full ((..., ndim, ndim)). If not provided, it is computed from the coordinate system. See Notes for more details on the shape requirements.
in_chunks (bool, default False) – 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:

The tensor with the selected slot converted. Shape equals broadcast(grid_shape over output_axes) + element_shape.

Return type:

array-like

Notes

Shape and Broadcasting Requirements

The shape of tensor_field must exactly match the grid shape over field_axes. Any trailing axes are treated as component dimensions of the tensor, and must match the expected rank.

The out buffer (if supplied) must match the computed output shape.

Metric Input

If metric_field is not supplied, it is computed from the coordinate system. Supported metric shapes:

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

Chunked Execution

When in_chunks=True, the grid is processed in small chunks (with ghost zones). This reduces memory overhead and improves performance with lazy buffers like HDF5.

grids.mixins.mathops.DenseMathOpsMixin.dense_contract_with_metric#

This Page