tensorcircuit.quditgates

Single-qudit and two-qudit gates and their matrix representations.

This module implements gates for qudits (d-level systems), providing d-dimensional analogues of familiar qubit gates as well as qudit-specific primitives.

Registry Single-qudit builders: I, X, Z, H, RX, RY, RZ, U8. Two-qudit builders: RXX, RZZ, CPHASE, CSUM.

These names are used by higher-level APIs (e.g. tensorcircuit.quditcircuit.QuditCircuit).

tensorcircuit.quditgates.cphase_matrix_func(d: int, cv: int | None = None, omega: complex | None = None) → Any

Qudit controlled-phase (CPHASE) gate.

Logical definition:

\[\lvert r \rangle \lvert s \rangle \;\longmapsto\; \omega^{rs} \lvert r \rangle \lvert s \rangle\]

Matrix form:

\[\begin{split}\mathrm{SUMZ}_d = \begin{bmatrix} I_d & 0 & 0 & \cdots & 0 \\ 0 & Z_d & 0 & \cdots & 0 \\ 0 & 0 & Z_d^2 & \cdots & 0 \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & 0 & \cdots & Z_d^{d-1} \end{bmatrix}\end{split}\]

Parameters:

• d (int) – Qudit dimension (for each register).

• cv (Optional[int]) – Optional control value in [0, d-1]. If None, builds the full SUMZ block-diagonal.

• omega (Optional[complex]) – Optional primitive d-th root of unity for Z_d.

Returns:

(d*d, d*d) matrix representing the controlled-phase.

Return type:

Tensor

Raises:

ValueError – If cv is provided and is outside [0, d-1].

tensorcircuit.quditgates.csum_matrix_func(d: int, cv: int | None = None) → Any

Qudit controlled-sum (CSUM / SUMX) gate.

Logical definition:

\[\lvert r \rangle \lvert s \rangle \;\longmapsto\; \lvert r \rangle \lvert r+s \pmod d \rangle\]

Matrix form:

\[\begin{split}\mathrm{SUMX}_d = \begin{bmatrix} I_d & 0 & 0 & \cdots & 0 \\ 0 & X_d & 0 & \cdots & 0 \\ 0 & 0 & X_d^2 & \cdots & 0 \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & 0 & \cdots & X_d^{d-1} \end{bmatrix}\end{split}\]

Parameters:

• d (int) – Qudit dimension (for each register).

• cv (Optional[int]) – Optional control value in [0, d-1]. If None, builds the full SUMX block-diagonal.

Returns:

(d*d, d*d) matrix representing the controlled-sum.

Return type:

Tensor

Raises:

ValueError – If cv is provided and is outside [0, d-1].

tensorcircuit.quditgates.h_matrix_func(d: int, omega: complex | None = None) → Any

Discrete Fourier transform (Hadamard-like) on d levels.

\[H_d\lvert j \rangle = \frac{1}{\sqrt{d}} \sum_{k=0}^{d-1} \omega^{jk}\lvert k \rangle\]

Parameters:

• d (int) – Qudit dimension.

• omega (Optional[complex]) – Optional primitive d-th root of unity. Defaults to \(e^{2\pi i/d}\).

Returns:

(d, d) matrix for \(H_d\).

Return type:

Tensor

tensorcircuit.quditgates.i_matrix_func(d: int) → Any

Identity matrix of size d.

Parameters:

d (int) – Qudit dimension.

Returns:

(d, d) identity matrix.

Return type:

Tensor

tensorcircuit.quditgates.rx_matrix_func(d: int, theta: float, j: int = 0, k: int = 1) → Any

Rotation-X (RX) on a selected two-level subspace of a qudit.

Acts like the qubit \(RX(\theta)\) on levels \(j\) and \(k\), identity elsewhere. On the \(\{\lvert j\rangle,\lvert k\rangle\}\) subspace the matrix equals

\[RX(\theta) = \cos\tfrac{\theta}{2}\,(\lvert j\rangle\!\langle j\rvert+\lvert k\rangle\!\langle k\rvert) - i\,\sin\tfrac{\theta}{2}\,(\lvert j\rangle\!\langle k\rvert + \lvert k\rangle\!\langle j\rvert) + I.\]

Parameters:

• d (int) – Qudit dimension.

• theta (float) – Rotation angle \(\theta\).

• j (int) – First level index.

• k (int) – Second level index.

Returns:

(d, d) matrix for \(RX(\theta)\) on the \(j,k\) subspace.

Return type:

Tensor

tensorcircuit.quditgates.rxx_matrix_func(d: int, theta: float, j1: int = 0, k1: int = 1, j2: int = 0, k2: int = 1) → Any

Two-qudit RXX(\theta) on a selected two-state subspace.

Acts like a qubit \(RXX\) on the subspace spanned by \(\lvert j1, j2\rangle\) and \(\lvert k1, k2\rangle\).

Parameters:

• d (int) – Dimension of each qudit (assumed equal).

• theta (float) – Rotation angle.

• j1 (int) – Level on qudit-1.

• k1 (int) – Level on qudit-1.

• j2 (int) – Level on qudit-2.

• k2 (int) – Level on qudit-2.

Returns:

(d*d, d*d) matrix representing \(RXX(\theta)\) on the selected subspace.

Return type:

Tensor

tensorcircuit.quditgates.ry_matrix_func(d: int, theta: float, j: int = 0, k: int = 1) → Any

Rotation-Y (RY) on a selected two-level subspace of a qudit.

Acts like the qubit \(RY(\theta)\) on levels \(j\) and \(k\), identity elsewhere. On the \(\{\lvert j\rangle,\lvert k\rangle\}\) subspace the matrix equals

\[RY(\theta) = \cos\tfrac{\theta}{2}\,(\lvert j\rangle\!\langle j\rvert+\lvert k\rangle\!\langle k\rvert) + \sin\tfrac{\theta}{2}\,(\lvert k\rangle\!\langle j\rvert - \lvert j\rangle\!\langle k\rvert) + I.\]

Parameters:

• d (int) – Qudit dimension.

• theta (float) – Rotation angle \(\theta\).

• j (int) – First level index.

• k (int) – Second level index.

Returns:

(d, d) matrix for \(RY(\theta)\) on the \(j,k\) subspace.

Return type:

Tensor

tensorcircuit.quditgates.rz_matrix_func(d: int, theta: float, j: int = 0) → Any

Rotation-Z (RZ) on a selected level of a qudit.

Acts like the qubit \(RZ(\theta)\) but applies a phase only to level \(j\). On the computational basis it equals

\[RZ(\theta) = I + (e^{i\theta}-1)\,\lvert j\rangle\!\langle j\rvert,\]

i.e. \(\lvert j\rangle \mapsto e^{i\theta}\,\lvert j\rangle\) and all other levels unchanged.

Parameters:

• d (int) – Qudit dimension.

• theta (float) – Rotation angle \(\theta\).

• j (int) – Level index receiving the phase.

Returns:

(d, d) diagonal matrix implementing \(RZ(\theta)\) on level \(j\).

Return type:

Tensor

tensorcircuit.quditgates.rzz_matrix_func(d: int, theta: float, j1: int = 0, k1: int = 1, j2: int = 0, k2: int = 1) → Any

Two-qudit RZZ(\theta) on a selected two-state subspace.

Acts like a qubit \(RZZ(\theta)=\exp(-i\,\tfrac{\theta}{2}\,\sigma_z)\) on the two-dimensional subspace spanned by \(\lvert j1, j2\rangle\) and \(\lvert k1, k2\rangle\), and as identity elsewhere. The resulting block is diagonal with phases \(\mathrm{diag}(e^{-i\theta/2},\, e^{+i\theta/2})\).

Parameters:

• d (int) – Dimension of each qudit (assumed equal).

• theta (float) – Rotation angle.

• j1 (int) – Level on qudit-1 for the first basis state.

• k1 (int) – Level on qudit-1 for the second basis state.

• j2 (int) – Level on qudit-2 for the first basis state.

• k2 (int) – Level on qudit-2 for the second basis state.

Returns:

(d*d, d*d) matrix representing subspace \(RZZ(\theta)\).

Return type:

Tensor

Raises:

ValueError – If indices are out of range or select the same basis state.

tensorcircuit.quditgates.s_matrix_func(d: int, omega: complex | None = None) → Any

Diagonal phase gate S_d on d levels.

\[S_d\lvert j \rangle = \omega^{j(j+p_d)/2}\lvert j \rangle,\quad p_d = (d \bmod 2)\]

Parameters:

• d (int) – Qudit dimension.

• omega (Optional[complex]) – Optional primitive d-th root of unity. Defaults to \(e^{2\pi i/d}\).

Returns:

(d, d) diagonal matrix for \(S_d\).

Return type:

Tensor

tensorcircuit.quditgates.swap_matrix_func(d: int) → Any

SWAP gate for two qudits of equal dimension \(d\).

Exchanges basis states \(\lvert i\rangle\lvert j\rangle \to \lvert j\rangle\lvert i\rangle\).

Parameters:

d (int) – Qudit dimension (for each register).

Returns:

(d^2, d^2) permutation matrix implementing SWAP.

Return type:

Tensor

tensorcircuit.quditgates.u8_matrix_func(d: int, gamma: int = 2, z: int = 1, eps: int = 0, omega: complex | None = None) → Any

U8 diagonal single-qudit gate for prime dimensions.

See ref: Howard, Mark, and Jiri Vala. “Qudit versions of the qubit pi/8 gate.” Physical Review A 86, no. 2 (2012): 022316. https://doi.org/10.1103/PhysRevA.86.022316

This gate is the qudit analogue of the qubit \(\pi/8\) gate, defined in Howard & Campbell, Phys. Rev. A 86, 022316 (2012). It is diagonal in the computational basis with exponents determined by modular polynomials in the parameters \(\gamma, z, \epsilon\). These gates, together with Pauli and Clifford operations, generate the full single-qudit Clifford hierarchy.

• For \(d=2\), this reduces (up to global phase) to the standard qubit \(\pi/8\) gate.

• For \(d=3\), the exponents live in \(\mathbb{Z}_9\) and the primitive ninth root \(\zeta = e^{2\pi i/9}\) is used.

• For prime \(d>3\), the construction uses the modular inverse of 12 in \(\mathbb{Z}_d\).

Parameters:

• d (int) – Qudit dimension (must be prime).

• gamma (int) – Shear parameter \(\gamma' \in \mathbb{Z}_d\). If \(gamma = 0\), the gate is a diagonal Clifford. If \(gamma \neq 0\), the gate is a genuine non-Clifford (analogue of \(\pi/8\)).

• z (int) – Displacement parameter \(z' \in \mathbb{Z}_d\), which sets the symplectic part of the associated Clifford.

• eps (int) – Phase offset parameter \(\epsilon' \in \mathbb{Z}_d\). It only contributes a global phase factor \(\omega^{\epsilon'}\).

• omega (Optional[complex]) – Optional primitive \(d\)-th root of unity (complex). Defaults to \(e^{2\pi i/d}\) for d>3, and \(e^{2\pi i/9}\) for d=3.

Returns:

(d, d) diagonal matrix of dtype npdtype.

Return type:

Tensor

Raises:

ValueError – If d is not prime; if 12 has no modular inverse mod d (for d>3); or if the computed exponents do not sum to 0 mod d (or 0 mod 3 for d=3).

tensorcircuit.quditgates.x_matrix_func(d: int) → Any

Generalized Pauli-X on a d-level system.

\[X_d\lvert j \rangle = \lvert (j+1) \bmod d \rangle\]

Parameters:

d (int) – Qudit dimension.

Returns:

(d, d) matrix for \(X_d\).

Return type:

Tensor

tensorcircuit.quditgates.z_matrix_func(d: int, omega: complex | None = None) → Any

Generalized Pauli-Z on a d-level system.

\[Z_d\lvert j \rangle = \omega^{j}\lvert j \rangle,\quad \omega=e^{2\pi i/d}\]

Parameters:

• d (int) – Qudit dimension.

• omega (Optional[complex]) – Optional primitive d-th root of unity. Defaults to \(e^{2\pi i/d}\).

Returns:

(d, d) matrix for \(Z_d\).

Return type:

Tensor