Metadata-Version: 2.4
Name: qutritium
Version: 1.3.0
Summary: A hardware-agnostic Python library for qutrit (3-level) quantum computing: gates, circuits, simulation, and SU(3) decomposition.
Author: Tien Nguyen, Bao Bach, Charlie He
Author-email: Son Pham <sph40@duke.edu>
Maintainer-email: Son Pham <sph40@duke.edu>
License: Copyright (c) 2023 SON PHAM and TIEN NGUYEN
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Homepage, https://github.com/spham1611/qutritium
Project-URL: Documentation, https://spham1611.github.io/qutritium/
Project-URL: Repository, https://github.com/spham1611/qutritium
Project-URL: Issues, https://github.com/spham1611/qutritium/issues
Keywords: quantum,quantum-computing,qutrit,qudit,su3,decomposition,simulator
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Provides-Extra: plot
Requires-Dist: matplotlib>=3.9; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Dynamic: license-file

<div align="center">

[![Tests](https://github.com/spham1611/qutritium/actions/workflows/test.yml/badge.svg)](https://github.com/spham1611/qutritium/actions)
[![Unitary Fund](https://img.shields.io/badge/Supported%20By-UNITARY%20FUND-brightgreen.svg?style=for-the-badge)](https://unitary.fund)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE.txt)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-yellow.svg?style=for-the-badge)](https://www.python.org/)

# Qutritium

**A hardware-agnostic Python library for qutrit quantum computing.**

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

</div>

---

## Installation

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

## Quick Start

```python
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:

```python
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`](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](https://github.com/spham1611)** — Duke University · sph40@duke.edu
- **[Tien Nguyen](https://github.com/ngdnhtien)** — École Polytechnique, France · tienphys@gmail.com
- **[Bao Bach](https://github.com/bachbao)** — University of Delaware, USA · bachgiabao12@gmail.com
- **[Charlie (abdomsisn)](https://github.com/abdomsisn)** — Duke University · abdomsisn.haobei@gmail.com

## License

[MIT](LICENSE.txt)
