qutritium 1.2.1

A hardware-agnostic Python library for qutrit (3-level) quantum computing: gates, circuits, simulation, and SU(3) decomposition.

Qutritium

A hardware-agnostic Python library for qutrit quantum computing.

Build, simulate, and decompose three-level quantum circuits.

---

Installation

pip install qutritium            # release
pip install -e ".[dev]"          # editable + dev tools

Quick Start

from qutritium import QutritCircuit, QASMSimulator
from qutritium.gates import H3, CSUM
import numpy as np

# Qutrit Bell state: H3 + CSUM → (|00⟩ + |11⟩ + |22⟩) / √3
qc = QutritCircuit(2, None)
qc.append(H3(), first_qutrit=0)
qc.append(CSUM(), first_qutrit=0, second_qutrit=1)
qc.measure_all()

sim = QASMSimulator(qc)
sim.run(num_shots=10_000)
print(sim.get_counts())   # {'00': ~3333, '11': ~3333, '22': ~3333}

Decompose an arbitrary SU(3) unitary:

from qutritium import SU3Decomposition
import numpy as np

U = ...  # any 3×3 unitary
dec = SU3Decomposition(U, qutrit_index=0, n_qutrits=1)
print(dec.angles)  # nine decomposition angles
print(dec.reconstruct())  # ≈ U to machine precision

Gate Library

Single-qutrit gates

Category	Gates
Pauli-X	X01, X02, X12
Pauli-Y	Y01, Y02, Y12
Pauli-Z	Z01, Z02, Z12
Shifts	XPlus (cyclic), XMinus (inverse)
Discrete	H3 (Hadamard/DFT), S3, T3, UFT, I3
Rotations	Rx01, Rx02, Rx12, Ry01, Ry02, Ry12, Rz01, Rz02, Rz12
Generalized	G01(θ,φ), G02(θ,φ), G12(θ,φ) — native trapped-ion gate
Diagonal	Ud(φ₁,φ₂,φ₃) — virtual-Z in hardware

Two-qutrit gates

Gate	Action
CSUM	|c,t⟩ → |c, (t+c) mod 3⟩
CSUMDag	|c,t⟩ → |c, (t−c) mod 3⟩ (CSUM inverse)
CPhase	|c,t⟩ → ω^{c·t} |c,t⟩
SWAP3	|a,b⟩ → |b,a⟩
CNOT3	Legacy v0.0.1 CNOT (= CSUM on adjacent qutrits)

All gates inherit from Gate and provide .matrix(), .inverse(), .is_unitary(), .label, .params.

Package Structure

src/qutritium/
├── gates/               # Gate objects
│   ├── base.py          #   Gate ABC + _DaggerGate
│   ├── single_qutrit.py #   29 single-qutrit gates
│   └── two_qutrit.py    #   5 two-qutrit gates
├── circuit/             # Circuit infrastructure
│   ├── elementary_matrices.py  # Raw 3×3 / 9×9 unitaries
│   ├── instruction.py          # Instruction + GATE_SET
│   ├── qutrit_circuit.py       # QutritCircuit container
│   └── utils.py                # Statevector utilities
├── simulator/           # QASMSimulator (statevector)
└── decomposition/       # SU(3) → native rotations

Supporting files at repo root:

.github/workflows/       # CI (test.yml, docs.yml)
docs/                    # MkDocs source → spham1611.github.io/qutritium
examples/tutorial.ipynb  # End-to-end Bell state tutorial
test/                    # pytest suite (168 tests)
legacy/                  # v0.0.x Qiskit-pulse code (archived, not installed)

Documentation

Full docs: https://spham1611.github.io/qutritium/

Tutorial notebook: examples/tutorial.ipynb

History

Qutritium was originally built for calibrating qutrits on IBM superconducting hardware, presented at the Munich Quantum Software Conference 2023 and funded by a Unitary Fund microgrant. The v1.0.0 release pivoted to a hardware-agnostic library; the original pulse code is preserved under legacy/.

Authors

• Son Pham — Duke University · [e-mail]
• Tien Nguyen — École Polytechnique, France · [e-mail]
• Bao Bach — University of Delaware, USA · [e-mail]
• Charlie (abdomsisn) — Duke University · [e-mail]

License

MIT