CGSpec

Full specification of a CG tensor: its external edges and internal fusion tree.

CGSpec

Full specification of a CG tensor: external edges and the internal left-associative fusion tree.

Use from_edges to construct; do not call the constructor directly.

Examples:

>>> import yuzuha
>>> jhalf = yuzuha.Spin(1)
>>> spec  = yuzuha.CGSpec.from_edges([
...     yuzuha.Edge.incoming(jhalf),
...     yuzuha.Edge.incoming(jhalf),
...     yuzuha.Edge.outgoing(yuzuha.Spin(2)),
... ])
>>> print(spec.num_external())
3
>>> print(spec.om_dimension())
1

from_edges staticmethod

from_edges(edges: list[Edge]) -> CGSpec

Construct a CGSpec from a list of edges.

Automatically enumerates all valid internal spin configurations (alpha values) using the triangle inequality.

Parameters:

Name	Type	Description	Default
edges	list[Edge]	External edges of the tensor, at least 2.	required

Returns:

Type	Description
CGSpec	A new spec with all valid OM configurations.

Raises:

Type	Description
ValueError	If the edge list has fewer than 2 elements or if no valid internal coupling exists.

num_external

num_external() -> int

Return the number of external edges.

Returns:

Type	Description
int	Number of external edges.

om_dimension

om_dimension() -> int

Return the outer-multiplicity (OM) dimension.

The OM dimension is the number of valid internal spin paths through the left-associative fusion tree.

Returns:

Type	Description
int	Number of valid OM configurations.

with_inverted_axes

with_inverted_axes(axes: list[int]) -> CGSpec

Return a new CGSpec with the edge directions at the given axes flipped.

The internal OM configurations (alphas) are reused unchanged because they depend only on spin values, not directions.

Parameters:

Name	Type	Description	Default
axes	list[int]	Indices of edges whose direction should be flipped (Incoming ↔ Outgoing).	required

Returns:

Type	Description
CGSpec	A new CGSpec with the specified edge directions inverted.

Raises:

Type	Description
ValueError	If any axis index is out of bounds.

Examples:

>>> import yuzuha
>>> j = yuzuha.Spin(2)
>>> spec = yuzuha.CGSpec.from_edges([
...     yuzuha.Edge.incoming(j),
...     yuzuha.Edge.incoming(j),
...     yuzuha.Edge.outgoing(j),
... ])
>>> flipped = spec.with_inverted_axes([0, 1])
>>> [e.dir for e in flipped.edges]
[Direction.outgoing, Direction.outgoing, Direction.outgoing]

Description

CGSpec (Clebsch-Gordan specification) is the central data structure in Yuzuha. It records everything needed to identify a CG tensor uniquely:

• The external edges — a list of Edge values, one per external edge
• The internal spins (\(\alpha\) values) — one per intermediate fusion step in the left-associative fusion tree

For an \(n\)th-order tensor there are \(n - 2\) internal spins. from_edges automatically enumerates all valid internal spin configurations using the triangle inequality and stores them in the alphas field.

Constructor

import yuzuha

jhalf = yuzuha.Spin(1)   # j = 1/2
j1    = yuzuha.Spin(2)   # j = 1

# 3rd-order spec: two incoming spin-1/2, one outgoing spin-1
spec = yuzuha.CGSpec.from_edges([
    yuzuha.Edge.incoming(jhalf),
    yuzuha.Edge.incoming(jhalf),
    yuzuha.Edge.outgoing(j1),
])
print(spec.num_external())   # 3
print(spec.om_dimension())   # 1
print(spec.shape)            # (2, 2, 3)

Key Properties

Method / Attribute	Description
num_external()	Number of external edges
om_dimension()	Outer-multiplicity (OM) dimension — number of valid internal spin paths
shape	Tuple of (2j+1) for each external edge
with_inverted_axes(axes)	Returns a copy with selected edge directions flipped

Axis Inversion

with_inverted_axes(axes) creates a new CGSpec with the edge directions at the specified axis indices flipped (Incoming ↔ Outgoing). The internal spin configurations (alphas) are preserved because they depend only on spin values:

# Flip the direction of edge 0
spec_inv = spec.with_inverted_axes([0])

# Flip multiple edges
spec_inv2 = spec.with_inverted_axes([0, 2])

This is used in tensor network algorithms to account for Frobenius-Schur phases when reversing contracted pairs; see the 0.1.3 changelog for background.

See Also

• Edge: Building block for CGSpec
• Canonical Basis: Compute the canonical basis for a spec
• X-Symbol: Contract two CGSpec tensors
• R-Symbol: Permute the edges of a CGSpec tensor
• Contraction: Specify which edges to contract
• Yuzuha Protocol — Type System: Abstract Spec specification

Notes

CGSpec objects are immutable after construction. The with_inverted_axes method always returns a new object; the original is unchanged.

The from_edges constructor raises ValueError if the provided edges are inconsistent (e.g. fewer than 2 edges) or if no valid internal spin configuration exists (triangle inequality violated for all candidates).