Metadata-Version: 2.4
Name: qutritium
Version: 1.5.2
Summary: A hardware-agnostic Python library for qutrit (3-level) quantum computing: gates, circuits, simulation, and SU(3) decomposition.
Author-email: Son Pham <sph40@duke.edu>
Maintainer-email: Son Pham <sph40@duke.edu>
License: Copyright (c) 2023-2026 Son Pham
        
        The original Qiskit-pulse calibration code preserved under legacy/
        includes contributions copyright (c) 2023 Tien Nguyen and Bao Bach.
        
        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
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 — with metrics, noise modeling, and state & process
tomography.*

</div>

---

## Installation

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

## Quick Start

```python
from qutritium import QutritCircuit, StatevectorSimulator
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 = StatevectorSimulator(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
```

Or run it with noise — noise lives on the simulator, not the circuit:

```python
from qutritium import QutritCircuit, DensityMatrixSimulator
from qutritium.channels import NoiseModel, depolarizing_channel
from qutritium.gates import X01

qc = QutritCircuit(1, None)
qc.append(X01(), first_qutrit=0)
qc.measure_all()

nm = NoiseModel()
nm.add_quantum_error(depolarizing_channel(0.1), "X01")  # noise lives on the sim, not the circuit
dm = DensityMatrixSimulator(qc)
dm.set_noise_model(nm)
dm.run(num_shots=2000)
print(dm.get_counts())
```

## 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⟩                         |
| `CPhaseDag` | \|c,t⟩ → ω^{−c·t} \|c,t⟩ (CPhase inverse)       |
| `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`.

## How it fits together

```text
  Gate                  qutritium.gates - X01, H3, CSUM, Rx01, ...
    |                   a unitary; has .matrix() / .inverse()
    |  qc.append(gate, qutrit)
    v
  QutritCircuit         ordered operations (+ measure_all)
    |                   - each append wraps the gate as an Instruction
    |                     (gate + target qutrit(s); lazy 3^n x 3^n effect_matrix)
    |                   - introspect: .draw() .depth() .gate_count() .to_matrix()
    |  hand the circuit to a simulator
    v
  Simulator             StatevectorSimulator (psi - pure states)
    |                   DensityMatrixSimulator (rho - mixed states, noise)
    |                   - optional: .set_noise_model(NoiseModel(...))
    v
  results               .get_counts()  .probabilities()  .return_final_state()
    |
    +--> tomography.reconstruct_state   counts -> reconstructed rho
    +--> tomography.reconstruct_process counts -> Choi matrix -> Kraus ops
    +--> metrics                        state_fidelity, purity, entropy, ...

  SU3Decomposition(U) --> QutritCircuit   decompose any 3x3 unitary into
                                          native gates, then run it
```

## Package Structure

```
src/qutritium/
├── gates/               # Gate objects
│   ├── base.py          #   Gate ABC + _DaggerGate
│   ├── single_qutrit.py #   29 single-qutrit gates
│   └── two_qutrit.py    #   6 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/           # StatevectorSimulator + DensityMatrixSimulator
├── channels/            # Noise channels, NoiseModel, ReadoutError, SPAM
├── metrics/             # Fidelity, trace distance, purity, entropy
├── tomography/          # MUB state + process tomography + visualization
└── decomposition/       # SU(3) → native rotations
```

Supporting files at repo root:

```
.github/workflows/       # CI + release (test.yml, docs.yml, release.yml)
docs/                    # MkDocs source → spham1611.github.io/qutritium
examples/                # Bell-state, noise+tomography, process-tomography notebooks
test/                    # pytest suite
legacy/                  # v0.0.x Qiskit-pulse code (archived, not installed)
```

## Documentation

Full docs: **<https://spham1611.github.io/qutritium/>**

Tutorial notebooks: [`examples/tutorial.ipynb`](examples/tutorial.ipynb) (core),
[`examples/noise_and_tomography.ipynb`](examples/noise_and_tomography.ipynb) (noise + state tomography), and
[`examples/process_tomography.ipynb`](examples/process_tomography.ipynb) (process tomography)

## 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/`.

## Author

- **[Son Pham](https://github.com/spham1611)** — Duke University · sph40@duke.edu

## Acknowledgments

- **[Tien Nguyen](https://github.com/ngdnhtien)** (École Polytechnique, France) and
  **[Bao Bach](https://github.com/bachbao)** (University of Delaware, USA) — contributors
  to the original Qiskit-pulse calibration code preserved under `legacy/`
- **[Charlie He](https://github.com/abdomsisn)** (Duke University) — insight on qutrit physics

## License

[MIT](LICENSE.txt)
