qdecomp 1.0.1
Clifford+T quantum gate compiler.
Requires Python: >=3.9
Keywords: quantum, decomposition, python, compiler, clifford+t, quantum-computing, quantum-circuits

[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://qdecomp.readthedocs.io/en/latest/)

# QDecomp
`QDecomp` is a standalone software package to perform multiple decompositions of single-qubit and two-qubit quantum gates.

The package primarily focuses on decomposing gates into the Clifford+T universal subset by implementing the algorithm proposed by Ross and Selinger [[1]](#ref1).

This package was made in collaboration with D-Wave and Polytechnique Montréal.

The package contains 4 main subpackages:
* **decompositions** : Proposes user-oriented functions for decomposing various quantum gates
* **utils** : Contains the core algorithms and additional utility functions
* **rings** : Implements classes for symbolic calculations in mathematical rings
* **plot** : Offers visualization tools of core parts of the algorithm used mainly for debugging

Below is a figure illustrating the subpackages (green) and their associated modules (yellow) and classes (orange). 

![Package Structure](https://github.com/polyquantique/QDecomp/raw/main/docs/source/_static/package_structure.svg)

## Documentation

Complete API documentation is available and can be built locally using Sphinx:

```bash
cd docs
make html
./build/html/index.html
```

The documentation is generated in `docs/build/html/`. Open `docs/build/html/index.html` in a browser to view it.

## Installation

The `QDecomp` package can be installed from source by following the following steps:

1. Clone the repository

```bash
git clone https://github.com/polyquantique/QDecomp.git
cd QDecomp
```

2. (Optional) Create and activate a virtual environment

- Linux / macOS:

    ```bash
    python3 -m venv venv
    source venv/bin/activate
    ```
- Windows (Command Prompt):

    ```bash
    python -m venv venv
    venv\Scripts\activate
    ```

3. Install the package and dependencies

- Standard installation:

    ```bash
    pip install .
    ```
- Editable (developer) installation:

    ```bash
    pip install -e .[dev]
    ```

4. (Optional) Run the tests

```bash
pip install pytest
pytest tests
```

## Usage Examples

### Example #1: Single-Qubit Gate Decomposition

This example demonstrates the use of the `qdcomp.decompositions.sqg_decomp` function to decompose single-qubit gates (SQG) into the Clifford+T universal subset up to a tolerance error $\varepsilon$. Note that the algorithm guarantees the specified error only for $R_z$ gates, meaning the total error for SQG may exceed the user-defined tolerance due to error propagation.   

```pycon
>>> from scipy.stats import unitary_group
>>> from qdecomp.decompositions import sqg_decomp

>>> # Decompose a random single qubit gate with tolerance 0.001
>>> sqg = unitary_group.rvs(2, random_state=42)
>>> sequence, alpha = sqg_decomp(sqg, epsilon=0.001, add_global_phase=True)
>>> print(sequence, alpha)

sequence : T H S T H S T [...] S H S W W W W
alpha : 0.27

>>> # Decompose a random single qubit gate with tolerance 0.001 up to a global phase
>>> sqg = unitary_group.rvs(2, random_state=42)
>>> sequence, _ = sqg_decomp(sqg, epsilon=0.001, add_global_phase=False)
>>> print(sequence)

T H S T H S T [...] Z T H Z S H S
```

### Example #2: Two-Qubit Gate Decomposition
This example demonstrates the use of the `qdecomp.decompositions.tqg_decomp` function to decompose two-qubit gates (TQG) into the Clifford+T universal subset up to a tolerance error $\varepsilon$. The function outputs a `list` of `QGate` objects representing the circuit. The target qubits and the corresponding sequence can be accessed through the `QGate.target` and `QGate.sequence` properties respectively.

```pycon
>>> from scipy.stats import unitary_group
>>> from qdecomp.decompositions import tqg_decomp

>>> # Decompose a radnom single qubit gate with tolerance 0.001
>>> tqg = unitary_group.rvs(4, random_state=42)
>>> circuit = tqg_decomp(tqg, epsilon=0.001)
>>> for gates in circuit:
...     print(f"{gate.target} -> {gate.sequence}")

(0,) -> S T H T [...] H Z S T
(1,) -> S T H T [...] S H S T
(0, 1) -> CNOT1
...
(1,) -> H T H S [...] T H Z S
```

## License

Released under the Apache License 2.0. See [LICENSE](LICENSE) file.

## Citing this package

If you use `QDecomp` in your research or projects, please cite it using the following BibTeX entry:

```bibtex
@software{qdecomp,
  author = {Romain, Olivier and Girouard, Vincent and Trudeau, Marius and Blais, Francis},
  title = {QDecomp},
  year = {2025},
  version = {1.0.1},
  url = {https://github.com/polyquantique/QDecomp}
}
```

## References

* <a id="ref1"></a> [1] N. J. Ross and P. Selinger, *Optimal ancilla-free Clifford+T approximation of z-rotations*, 2014. [https://arxiv.org/abs/1403.2975](https://arxiv.org/abs/1403.2975)

* [2] V. Kliuchnikov, D. Maslov, and M. Mosca, *Fast and efficient exact synthesis of single qubit unitaries generated by Clifford and T gates*, 2012. [https://arxiv.org/abs/1206.5538](https://arxiv.org/abs/1206.5538)

* [3] G. E. Crooks, *Quantum gates*, March 2024, version 0.11.0, [https://threeplusone.com/pubs/on_gates.pdf](https://threeplusone.com/pubs/on_gates.pdf)