Skip to content

rakytap/sequential-quantum-gate-decomposer

BranchesTags

Repository files navigation

DOI

SQUANDER Logo

Sequential Quantum Gate Decomposer (SQUANDER)

A High-Performance C++/Python Library for Quantum Circuit Decomposition and Optimization

Installation • Documentation • Features • Citation

Overview

The Sequential Quantum Gate Decomposer (SQUANDER) is a state-of-the-art computational library designed for training parametric quantum circuits and performing quantum gate synthesis. SQUANDER provides a comprehensive Python interface that enables researchers and developers to conduct advanced numerical experiments in quantum computing, including quantum gate synthesis, variational quantum eigensolver (VQE) applications, and quantum state preparation.

Key Capabilities

SQUANDER excels in decomposing n-qubit unitaries into sequences of one-qubit rotations and two-qubit controlled gates using advanced synthesis methods. The library leverages a high-performance parallel C/C++ framework with gate fusion and vectorized AVX gate kernels, delivering exceptional computational efficiency for quantum circuit simulations.

Optimization Techniques

Beyond conventional gradient-based optimizers (gradient descent, ADAM, and BFGS), SQUANDER incorporates an innovative gradient-free optimization technique that demonstrates robust numerical behavior and is particularly effective in circumventing barren plateaus—a common challenge in quantum circuit training. The library's handcrafted optimization strategies are specifically designed to accommodate the periodicity inherent in quantum optimization landscapes, ensuring resilient numerical efficiency.

Installation

SQUANDER is available as pre-built Python wheels for Windows, Linux, and macOS, making installation straightforward for most users. The package can be installed directly from the Python Package Index (PyPI):

pip install squander

System Requirements

  • Python: 3.10 or higher (tested with Python 3.10-3.13)
  • Operating Systems: Windows, Linux, macOS

Python Dependencies

The following packages are automatically installed as dependencies:

Development Installation

For developers who wish to build SQUANDER from source or contribute to the project, the following development installation instructions are provided.

Prerequisites

The following dependencies are required to compile and build SQUANDER from source:

Build Tools

Libraries

Optional Tools

  • Doxygen (for generating documentation)
  • Ninja (speeds up compilation)

Development Build on Unix/Linux/macOS

1. Clone the Repository

git clone https://github.com/rakytap/sequential-quantum-gate-decomposer.git
cd sequential-quantum-gate-decomposer

2. Set Up Environment Variables (if needed)

If TBB is installed at a non-standard location or using GNU compiler:

export TBB_LIB_DIR=path/to/TBB/lib(64)
export TBB_INC_DIR=path/to/TBB/include

Note: When TBB is installed via the tbb-devel Python package, these environment variables are not necessary.

3. Build from Source

The SQUANDER package uses a Python build script (setup.py) that automatically detects the CBLAS library used by NumPy and configures CMake accordingly:

python3 setup.py build_ext

This command compiles the SQUANDER C++ library and builds the Python interface extensions in place.

4. Install in Development Mode

After a successful build, install the package in editable (development) mode:

python -m pip install -e .

Development Build with Conda (Recommended)

We recommend using Anaconda/Miniconda for development environments:

1. Create Environment from Configuration File

conda env create -f conda_env_example.yaml

2. Activate Environment

conda activate qgd

3. Build and Install

python3 setup.py build_ext
python -m pip install -e .

Development Build on Windows

Prerequisites

  • CMake must be in the system PATH
  • Microsoft Visual C++ compiler

Build Steps

set PATH=%PATH%;C:\Program Files\cmake\bin

set TBB_LOCATION=<Python_Folder>/LocalCache/local-packages
set TBB_INC_DIR=%TBB_LOCATION%/Library/include
set TBB_LIB_DIR=%TBB_LOCATION%/Library/lib
set LIB=<BLAS_Location>/lib;<LAPACK_Location>/lib

python setup.py build_ext -DTBB_HEADER=<TBB_Location>\Library\include\

Install DLL Files

Copy required DLL files to the package directory:

copy "%TBB_LOCATION%\Library\bin\tbb12.dll" .\squander\decomposition
copy "%TBB_LOCATION%\Library\bin\tbbmalloc.dll" .\squander\decomposition

Verify Installation

python -m pytest

Building Distribution Packages

Binary Wheel Distribution

To build a wheel binary for distribution:

python3 setup.py bdist_wheel

The wheel will be created in the dist/ directory. Note that the created wheel is not portable, as it contains hard-coded links to external libraries (TBB and CBLAS).

Source Distribution

To create a portable source distribution:

python3 setup.py sdist

The source distribution tarball will be created in the dist/ directory.

Features

SQUANDER provides a comprehensive suite of tools for quantum circuit manipulation and optimization:

Core Functionality

  • Unitary Decomposition: Decompose unitaries into quantum circuits using multiple methods:

    • Standard decomposition (N_Qubit_Decomposition)
    • Adaptive decomposition with circuit compression (N_Qubit_Decomposition_adaptive)
    • Custom topology decomposition (N_Qubit_Decomposition_custom)
    • Tree search decomposition (N_Qubit_Decomposition_Tree_Search)
    • Tabu search decomposition (N_Qubit_Decomposition_Tabu_Search)

  • Circuit Optimization: Optimize wide quantum circuits using the Wide_Circuit_Optimization class

  • State Preparation: Prepare quantum states via adaptive state preparation (N_Qubit_State_Preparation_adaptive)

  • Variational Quantum Algorithms:

    • Variational Quantum Eigensolver (VQE) (Variational_Quantum_Eigensolver)
    • Generative Quantum Machine Learning (GQML) (Generative_Quantum_Machine_Learning)

  • Circuit Simulation: High-performance state vector evolution for quantum circuit simulation

  • Circuit Synthesis: SABRE algorithm for qubit routing and mapping

  • Circuit Partitioning: Partition large circuits for efficient decomposition and optimization

  • Qiskit Integration: Seamless integration with Qiskit through the Qiskit_IO module

Python Interface

SQUANDER exposes its C++ functionality through a comprehensive Python interface. The main modules include:

Module Description
squander.decomposition Quantum gate decomposition classes for decomposing unitaries and preparing quantum states
squander.gates Quantum gate implementations and circuit building blocks (CNOT, H, RX, RY, RZ, and custom gates)
squander.VQA Classes for VQE and generative quantum machine learning algorithms
squander.synthesis Circuit synthesis tools including SABRE algorithm for qubit routing and mapping
squander.partitioning Circuit partitioning utilities for breaking down large circuits into manageable sub-circuits
squander.IO_interfaces Input/output interfaces including Qiskit integration (Qiskit_IO)
squander.utils Utility functions for working with quantum circuits and unitaries
squander.nn Experimental neural network interface for quantum machine learning

Example Usage

Comprehensive examples demonstrating SQUANDER's capabilities are available in the examples/ directory:

  • examples/decomposition/: Examples of unitary decomposition with various methods
  • examples/VQE/: Variational quantum eigensolver examples
  • examples/state_preparation/: Quantum state preparation examples
  • examples/simulation/: Quantum circuit simulation benchmarks
  • examples/partitioning/: Circuit partitioning examples

Additional usage patterns and test cases can be found in the tests/ directory.

Documentation

Comprehensive documentation for the SQUANDER package is available at:

CodeDocs[xyz]

Citation

If you use SQUANDER in your research, please cite the following publications:

[1] Péter Rakyta, Zoltán Zimborás, Approaching the theoretical limit in quantum gate decomposition, Quantum 6, 710 (2022).
[2] Péter Rakyta, Zoltán Zimborás, Efficient quantum gate decomposition via adaptive circuit compression, arXiv:2203.04426.
[3] Peter Rakyta, Gregory Morse, Jakab Nádori, Zita Majnay-Takács, Oskar Mencer, Zoltán Zimborás, Highly optimized quantum circuits synthesized via data-flow engines, Journal of Computational Physics 500, 112756 (2024).
[4] Jakab Nádori, Gregory Morse, Barna Fülöp Villám, Zita Majnay-Takács, Zoltán Zimborás, Péter Rakyta, Batched Line Search Strategy for Navigating through Barren Plateaus in Quantum Circuit Training, Quantum 9, 1841 (2025).

Posters and Conference Presentations

  • Conference talk. Péter Rakyta. Efficient quantum gate decomposition via adaptive circuit compression. GPU Day 2022 - Massive parallel computing for science and industrial application. June 21, 2022, 10:10-10:40. https://gpuday.com/gpu-day-2022
  • Conference talk. Péter Rakyta. Simulation of quantum computers on tensor streaming processors. GPU Day 2023. Budapest, Hungary, May 15-16, 2023. https://gpuday.com/gpu-day-2023
  • Conference talk (QCW track). Gregory Morse, Peter Rakyta, Tamás Kozsik. Simulation of quantum computers on tensor streaming processors. ICCS 2023 (International Conference on Computational Science), Quantum Computing Workshop (QCW), Prague, Czech Republic. July 3, 2023, 17:40. Program link: https://easychair.org/smart-program/ICCS2023/2023-07-03.html#talk:223488
  • Workshop talk. Péter Rakyta. SQUANDER: a classical framework to train quantum circuits. Workshop on Methods and Applications of Quantum Computing with Light and Qubits. Faculty of Nuclear Sciences and Physical Engineering, B-111, Brehova 7, Prague. October 17, 2023, 14:45-15:30. https://indico.fjfi.cvut.cz/event/269/contributions/4309/
  • Conference talk. Péter Rakyta. Batched Line Search Strategy for Navigating through Barren Plateaus in Quantum Circuit Training. GPU Day 2025 - Massive parallel computing for science and industrial application. HUN-REN Centre, Budapest. May 22, 2025, 12:00-12:30. https://gpuday.com/gpu-day-2025
  • Poster session. Muhammad Al Farizi, Gregory Morse, Jakab Nádori, László Hajas, Péter Rakyta. Scalable Quantum Circuit Design: Partitioning and Optimization Strategies. Quantum Informatics National Laboratory Workshop 2025. Bosch Budapest Innovation Campus, June 5, 2025, 16:30-18:30. https://qi.nemzetilabor.hu/events/quantum-information-national-laboratory-workshop-2025
  • Invited lecturer. Gregory Morse. Scalable Globally Optimal Partitioning of Quantum Circuits. Lectures on Modern Scientific Programming 2025, HUN-REN Wigner RCP. November 25, 2025, 9:20-10:30 lecture and 14:00-15:30 hands-on session. https://indico.wigner.hu/event/1709/
  • Poster session. Zoltán Kégli, Gregory Morse, Jakab Nádori, Barna Fülöp Villám, Muhammad Al Farizi, Tamás Kozsik, Péter Rakyta. SQUANDER: a classical technique to train quantum circuits. The 13th International Conference on Applied Informatics (ICAI2026). Eszterházy Károly Catholic University, Eger, February 20, 2026, 10:15-11:15. https://icai.uni-eszterhazy.hu/2026/program/

Acknowledgments

This project was supported by:

  • Grant OTKA PD123927
  • The Ministry of Innovation and Technology and the National Research, Development and Innovation Office within the Quantum Information National Laboratory of Hungary

Contact

For questions, support, or collaboration inquiries, please contact:

License

SQUANDER is licensed under the Apache License 2.0. See the LICENSE file for details.

About

C++ library with Python interface to train quantum circuits, quantum gate synthesis and state preparation.

Topics

quantum-computing high-performance-computing quantum-algorithms quantum-circuits variational-quantum-algorithms quantum-gate-synthesis

Resources

Readme

License

Apache-2.0 license
Activity

Stars

42 stars

Watchers

4 watching

Forks

12 forks
Report repository

Releases 15

v1.9.6 Latest
Dec 5, 2025
+ 14 releases

Packages

 
 
 

Contributors

Languages