isometry_n

Create an n-to-1 fusion isometry tensor.

isometry_n

isometry_n(
    indices: Sequence[Index],
    *,
    dtype: dtype = torch.float64,
    device: Optional[device] = None,
    itags: Optional[Sequence[str]] = None,
    direction: Direction = Direction.OUT,
) -> Tensor

Return an (n+1)th order tensor that fuses n indices into a single fused index.

This function constructs an n-to-1 isometry by sequentially applying 2-to-1 isometries. Indices are fused in order of increasing dimension to minimize intermediate tensor sizes and computational complexity.

The resulting isometry has n indices with directions opposite to the input indices (to enable natural contraction), plus one fused index whose direction is specified by the direction parameter.

Parameters:

Name	Type	Description	Default
indices	Sequence[Index]	Sequence of indices to be fused. Must contain at least 2 indices, and all indices must share the same symmetry group.	required
dtype	dtype	Data type for the emitted fusion blocks.	float64
device	Optional[device]	Device for the tensor blocks. If None, defaults to torch.get_default_device().	None
itags	Optional[Sequence[str]]	Optional sequence of tags for all tensor indices (n unfused + 1 fused). Length must be len(indices) + 1. Defaults to all "_init_".	None
direction	Direction	Direction for the fused output index. Defaults to Direction.OUT.	OUT

Returns:

Type	Description
Tensor	Tensor with (n+1) indices: the first n indices have opposite directions to the input indices, and the last index is the fused index with the specified direction.

Raises:

Type	Description
ValueError	If fewer than 2 indices are provided, if indices don't share the same symmetry group, or if itags length doesn't match len(indices) + 1.

Description

Constructs an (n+1)th-order tensor that fuses n indices into a single fused index. This generalizes the 2-to-1 isometry function to arbitrary n≥2.

The function works by sequentially applying 2-to-1 isometries, fusing indices in order of increasing dimension to minimize intermediate tensor sizes and computational complexity.

The resulting isometry has n indices with directions opposite to the input indices (to enable natural contraction), plus one fused index whose direction is specified by the direction parameter.

Usage

Basic fusion

from nicole import Index, Sector, Direction, U1Group, isometry_n

group = U1Group()
idx1 = Index(Direction.OUT, group, sectors=(Sector(0, 2), Sector(1, 1)))
idx2 = Index(Direction.OUT, group, sectors=(Sector(0, 3), Sector(1, 2)))
idx3 = Index(Direction.OUT, group, sectors=(Sector(0, 1), Sector(1, 1)))

# Create 3-to-1 isometry
iso = isometry_n([idx1, idx2, idx3], itags=("a", "b", "c", "fused"))

# iso has 4 indices: first 3 are flipped (IN), last is fused (OUT by default)
print(iso.itags)  # ('a', 'b', 'c', 'fused')

Contract with tensor to merge axes

from nicole import Tensor, contract

# Create a 3-index tensor
T = Tensor.random([idx1, idx2, idx3], itags=["a", "b", "c"])

# Create isometry and contract to merge all axes
iso = isometry_n([idx1, idx2, idx3], itags=("a", "b", "c", "merged"))
merged = contract(T, iso)  # Now has single index "merged"

Specify fused direction

# Create isometry with IN direction for fused index
iso = isometry_n(
    [idx1, idx2, idx3],
    direction=Direction.IN,
    itags=("a", "b", "c", "fused_in")
)

See Also

• isometry: 2-to-1 fusion isometry
• merge_axes: High-level axis merging
• contract: Tensor contraction
• identity: Identity tensor

Notes

• Requires at least 2 indices to fuse
• All indices must share the same symmetry group
• Indices are fused in order of increasing dimension for efficiency
• The first n output indices have opposite directions to the input indices
• The last output index is the fused index with specified direction
• If itags is provided, length must be n+1 (n indices + 1 fused)