SU(2)-equivariant circuits preserve global spin symmetry. A unitary is SU(2)-equivariant when it commutes with the three global spin generators S_x, S_y, and S_z.
Use these primitives when your variational model should stay inside a spin-symmetry-respecting subspace, such as Heisenberg-style spin systems.
This page is a workflow guide: it shows how the building blocks fit together, with runnable examples. For exact signatures, parameter defaults, and return types, see the SU(2)-equivariant gates API reference.
Overview
from haiqu.sdk.qml import (
brickwork_pattern,
is_su2_equivariant,
spin_generators,
su2_equivariant_2_qubit_gate,
su2_equivariant_3_qubit_gate,
su2_equivariant_ansatz,
total_spin_ops,
)
| Function | Purpose |
|---|
su2_equivariant_2_qubit_gate(theta) | Return the 2-qubit SU(2)-equivariant primitive gate. |
su2_equivariant_3_qubit_gate(theta0, theta1, theta2, theta3) | Return the exact 3-qubit SU(2)-equivariant gate. |
su2_equivariant_ansatz(num_qubits, layout="brickwork", num_layers=1, name="theta") | Build a parameterized equivariant ansatz from 2-qubit primitives. |
brickwork_pattern(num_qubits, num_layers) | Return nearest-neighbor even-then-odd pair layout. |
is_su2_equivariant(U, tol=1e-8) | Check whether a dense unitary commutes with all three global spin generators. |
spin_generators(num_qubits) | Return dense (S_x, S_y, S_z). |
total_spin_ops(num_qubits) | Return (S^2, S_z). |
Two-qubit equivariant gate
su2_equivariant_2_qubit_gate(theta) returns a 2-qubit QuantumCircuit. It phases the singlet sector and leaves the triplet sector unchanged, making it the basic building block for SU(2)-equivariant ansatze.
from qiskit import QuantumCircuit
from qiskit.quantum_info import Operator
from haiqu.sdk.qml import is_su2_equivariant, su2_equivariant_2_qubit_gate
su2_2q = su2_equivariant_2_qubit_gate(theta=0.7)
qc = QuantumCircuit(2)
qc.compose(su2_2q, qubits=[0, 1], inplace=True)
ok, violation = is_su2_equivariant(Operator(qc).data)
print(f"SU(2)-equivariant: {ok}")
print(f"max commutator violation: {violation:.2e}")
Three-qubit equivariant gate
su2_equivariant_3_qubit_gate(theta0, theta1, theta2, theta3) returns a 3-qubit QuantumCircuit. The four angles parameterize the allowed mixing between the two spin-1/2 copies while preserving the spin-3/2 sector.
from qiskit.quantum_info import Operator
from haiqu.sdk.qml import is_su2_equivariant, su2_equivariant_3_qubit_gate
su2_3q = su2_equivariant_3_qubit_gate(
theta0=0.8,
theta1=1.2,
theta2=0.5,
theta3=2.1,
)
ok, violation = is_su2_equivariant(Operator(su2_3q).data)
print(f"3-qubit gate equivariant: {ok}")
print(f"max commutator violation: {violation:.2e}")
Build an equivariant ansatz
su2_equivariant_ansatz(...) wires the 2-qubit gate into a parameterized circuit. Supported layouts are:
"brickwork": nearest-neighbor even bonds, then odd bonds, repeated."linear": adjacent chain pairs, repeated.- A custom list of qubit pairs, such as
[[0, 1], [1, 2], [0, 2]].
from haiqu.sdk.qml import brickwork_pattern, su2_equivariant_ansatz
print(brickwork_pattern(num_qubits=4, num_layers=1))
ansatz = su2_equivariant_ansatz(
num_qubits=4,
layout="brickwork",
num_layers=2,
name="theta",
)
print("number of parameters:", len(ansatz.parameters))
print(ansatz.draw())
from haiqu.sdk.qml import su2_equivariant_ansatz
triangle = su2_equivariant_ansatz(
num_qubits=3,
layout=[[0, 1], [1, 2], [0, 2]],
num_layers=2,
)
print("triangle ansatz parameters:", len(triangle.parameters))
Verify structural equivariance
The ansatz remains equivariant for any parameter values because every block is equivariant.
import numpy as np
from qiskit.quantum_info import Operator
from haiqu.sdk.qml import is_su2_equivariant, su2_equivariant_ansatz
rng = np.random.default_rng(7)
ansatz = su2_equivariant_ansatz(num_qubits=4, num_layers=2)
binding = {param: rng.uniform(0, 2 * np.pi) for param in ansatz.parameters}
bound_ansatz = ansatz.assign_parameters(binding)
ok, violation = is_su2_equivariant(Operator(bound_ansatz).data)
print(f"randomly bound ansatz equivariant: {ok}")
print(f"max commutator violation: {violation:.2e}")
import numpy as np
from qiskit.circuit.library import efficient_su2
from qiskit.quantum_info import Operator
from haiqu.sdk.qml import is_su2_equivariant
rng = np.random.default_rng(7)
hardware_efficient = efficient_su2(num_qubits=4, reps=1).decompose()
binding = {param: rng.uniform(0, 2 * np.pi) for param in hardware_efficient.parameters}
ok, violation = is_su2_equivariant(Operator(hardware_efficient.assign_parameters(binding)).data)
print(f"generic EfficientSU2 equivariant: {ok}")
print(f"max commutator violation: {violation:.2e}")
Spin operators
spin_generators(n) returns dense (S_x, S_y, S_z). total_spin_ops(n) returns (S^2, S_z). These are useful for diagnostics and for building symmetry-aware observables.
import numpy as np
from haiqu.sdk.qml import spin_generators, total_spin_ops
Sx, Sy, Sz = spin_generators(3)
S2, _ = total_spin_ops(3)
print("Sx shape:", Sx.shape)
print("distinct S^2 eigenvalues:", np.round(np.unique(np.linalg.eigvalsh(S2)), 3))
Compile an equivariant target
Use haiqu.su2_equivariant_compilation(...) to fit a shallow brickwork circuit of 2-qubit SU(2) gates to an equivariant target.
This is a Haiqu cloud job. It requires a logged-in SDK session and an API key. The target can be a QuantumCircuit, Gate, or dense numpy.ndarray. The fit builds a dense unitary, so targets are capped at 10 qubits.
from haiqu.sdk import haiqu
from haiqu.sdk.qml import su2_equivariant_3_qubit_gate
haiqu.login()
target = su2_equivariant_3_qubit_gate(0.8, 1.2, 0.5, 2.1)
job = haiqu.su2_equivariant_compilation(
target,
target_fidelity=0.99,
max_layers=6,
num_restarts=10,
seed=0,
)
compressed = job.result()
print("achieved process fidelity:", job.fidelity)
haiqu.draw(compressed)
device = haiqu.get_device("fake_marrakesh")
original_t = haiqu.transpile(target, device=device)
compiled_t = haiqu.transpile(compressed, device=device)
print("original 2-qubit gates:", original_t.analytics.gates_2q)
print("compiled 2-qubit gates:", compiled_t.analytics.gates_2q)
haiqu.compare_metrics(original_t, compiled_t)
