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].

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).

Documentation

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

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

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

2. (Optional) Create and activate a virtual environment

• Linux / macOS:

  python3 -m venv venv
  source venv/bin/activate
  

• Windows (Command Prompt):

  python -m venv venv
  venv\Scripts\activate
  

3. Install the package and dependencies

• Standard installation:

  pip install .
  

• Editable (developer) installation:

  pip install -e .[dev]
  

4. (Optional) Run the tests

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.

>>> 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.

>>> 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 file.

Citing this package

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

@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

• [1] N. J. Ross and P. Selinger, Optimal ancilla-free Clifford+T approximation of z-rotations, 2014. 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

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