Metadata-Version: 2.4
Name: gulps
Version: 0.4.0
Summary: optimally compile arbitrary two-qubit unitaries into heterogeneous native gate sets
Author-email: Evan McKinney <evmckinney9@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/evmckinney9/gulps
Project-URL: Documentation, https://evm9.dev/gulps/
Project-URL: Repository, https://github.com/evmckinney9/gulps
Project-URL: Issues, https://github.com/evmckinney9/gulps/issues
Project-URL: Paper, https://doi.org/10.1109/QCE68830.2026.00091
Keywords: quantum,compiler,qiskit,two-qubit,gate-decomposition,quantum-gates,unitary-decomposition
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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 :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit<2.6,>=2.5
Requires-Dist: numpy
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Requires-Dist: pylatexenc; extra == "viz"
Provides-Extra: format
Requires-Dist: pre-commit; extra == "format"
Requires-Dist: ruff; extra == "format"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-benchmark<6,>=5.2; extra == "test"
Provides-Extra: docs
Requires-Dist: gulps[viz]; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: jupyter-sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: sphinx-copybutton<1,>=0.5; extra == "docs"
Requires-Dist: sphinx-sitemap<3,>=2.9; extra == "docs"
Requires-Dist: qiskit-sphinx-theme>=2; extra == "docs"
Provides-Extra: dev
Requires-Dist: gulps[docs,format,test]; extra == "dev"
Dynamic: license-file

# GULPS

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![PyPI - Version](https://img.shields.io/pypi/v/gulps)](https://pypi.org/project/gulps/)
[![CI](https://github.com/evmckinney9/gulps/actions/workflows/ci.yml/badge.svg)](https://github.com/evmckinney9/gulps/actions/workflows/ci.yml)
[![DOI](https://img.shields.io/badge/DOI-10.1109%2FQCE68830.2026.00091-blue)](https://doi.org/10.1109/QCE68830.2026.00091)
[![Qiskit Ecosystem](https://qisk.it/e-0a8128d0)](https://qisk.it/e)
[![Docs](https://github.com/evmckinney9/gulps/actions/workflows/docs.yml/badge.svg?branch=main)](https://evm9.dev/gulps/)

GULPS is a two-qubit gate synthesis package for arbitrary native instruction sets.
Given a set of native two-qubit gates and a cost for each, it selects the least-cost sentence, an ordered list of native gates with single-qubit gates before, between, and after them, that implements a target unitary.
It then constructs those single-qubit gates with a dedicated solver, [can_sandwich](https://github.com/evmckinney9/can_sandwich).

```bash
pip install gulps
```

The native gates can be any two-qubit gates with fixed parameters: Qiskit standard gates with bound parameters, or your own matrices wrapped in `UnitaryGate`.

```python
from qiskit.circuit.library import CSXGate, iSwapGate
from qiskit.quantum_info import random_unitary
from gulps.decomposition import GulpsDecomposer

decomposer = GulpsDecomposer([CSXGate(), iSwapGate().power(1 / 3)], costs=[90, 120])
circuit = decomposer(random_unitary(4, seed=0))
print(circuit.draw("text"))
```

A cost can be a gate duration or any other quantity that adds up along a sentence.

- [Compilation](https://evm9.dev/gulps/compile.html): charge for single-qubit layers, run GULPS in a Qiskit pass manager, and query synthesis costs from other transpiler passes.
- [Pulse duration calibration](https://evm9.dev/gulps/calibration.html): choose which native gate durations to calibrate for your workload.
- [How synthesis works](https://evm9.dev/gulps/synthesis.html): how reachable regions guide sentence selection and circuit construction.

The [paper](https://doi.org/10.1109/QCE68830.2026.00091) describes the method, which builds on [monodromy](https://github.com/qiskit-community/monodromy).

> [!IMPORTANT]
> This software is provided as-is with no guarantee of support or maintenance.
> AI tools were used to assist in writing code in this repository.
> Bug reports and pull requests are welcome. For more information, see [the contribution guide](https://github.com/evmckinney9/gulps/blob/main/.github/CONTRIBUTING.md).
