trace

Compute trace over index pairs within a tensor.

trace

trace(
    T: Tensor,
    axes: Optional[Tuple[int, int] | Sequence[Tuple[int, int]]] = None,
    excl: Optional[int | str | Sequence[int] | Sequence[str]] = None,
) -> Tensor

Trace over pairs of indices on a single tensor while preserving symmetry.

This function performs a partial trace by summing over diagonal elements of specified index pairs. Each pair must have matching charges, opposite directions, and equal dimensions within each symmetry block.

Parameters:

Name	Type	Description	Default
T	Tensor	Tensor to be traced.	required
axes	Optional[Tuple[int, int] | Sequence[Tuple[int, int]]]	Optional specification of axes to trace. Can be either: Single pair: (axis_a, axis_b) for tracing one pair Multiple pairs: [(a1, b1), (a2, b2), ...] for tracing multiple pairs Must use integer indices only. Validates that each pair has matching itags and opposite directions. Mutually exclusive with excl.	None
excl	Optional[int | str | Sequence[int] | Sequence[str]]	Optional specification of axes to exclude from automatic tracing. Can be a single int/str or sequence of ints/strs. When specified, automatically traces all indices with matching itags and opposite directions, except those in the exclusion list. Mutually exclusive with axes.	None

Returns:

Type	Description
Tensor	Tensor with the traced indices removed. The remaining indices retain their original order.

Raises:

Type	Description
ValueError	If both axes and excl are specified, or if paired indices have the same direction, mismatched charges, incompatible dimensions, or if no valid pairs are found, or if automatic detection encounters ambiguous pairing.

Notes

The trace operation sums over matching diagonal entries: Tr(A) = Σᵢ Aᵢᵢ.

For multiple pairs, traces are performed sequentially to ensure consistency: trace(T, [(a,b), (c,d)]) is equivalent to trace(trace(T, (a,b)), (c,d)). This guarantees that the result does not depend on whether pairs are traced simultaneously or one at a time. The order of pairs does not affect the final result for commuting traces.

Examples:

Automatic tracing (recommended for most cases):

>>> # Tensors with matching itags and opposite directions
>>> T = Tensor.random([idx_a, idx_a_flip, idx_b], itags=["left", "left", "mid"])
>>> result = trace(T)  # Automatically traces "left" pair

Manual tracing with axes parameter:

>>> # Single pair: concise syntax
>>> result = trace(T, axes=(0, 1))

>>> # Single pair: also works with sequence syntax
>>> result = trace(T, axes=[(0, 1)])

>>> # Multiple pairs
>>> result = trace(T, axes=[(0, 1), (2, 3)])

Using excl parameter for automatic tracing with exclusions:

>>> # Trace all matching pairs except axis 0
>>> result = trace(T, excl=0)

>>> # Trace all matching pairs except "left" indices
>>> result = trace(T, excl="left")

>>> # Exclude multiple axes
>>> result = trace(T, excl=[0, 2])

Description

Computes the trace by summing over matching indices. Index pairs must have:

• Opposite directions (OUT ↔ IN)
• Matching symmetry groups and itags (for automatic mode)
• Compatible charge sectors

The function supports three modes:

1. Automatic mode (no parameters): Automatically finds and traces all pairs with matching itags and opposite directions
2. Manual mode (axes parameter): Explicitly specify which index pairs to trace
3. Exclusion mode (excl parameter): Automatically trace all matching pairs except specified exclusions

Result has reduced dimensionality (2 indices removed per pair).

See Also

• contract: General contraction between two tensors
• Examples: Contraction

Notes

For a scalar result, trace over all index pairs. The automatic mode provides the most convenient API for tensors with clear itag structure.