squander 1.9.6

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

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:

• NumPy
• SciPy
• Qiskit
• NetworkX
• Matplotlib

---

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

• CMake (>=3.10.2)
• C++/C compiler:
  • Intel Compiler (>=14.0.1), or
  • GNU Compiler Collection (>=v4.8.1)

Libraries

• TBB (Threading Building Blocks) library
  • Can be installed via Python package: pip install tbb-devel
  • Or system package: sudo apt install libtbb-dev (Linux)
• LAPACKE
• BLAS Library (choose one):
  • Intel MKL (optional)
  • OpenBLAS (optional, recommended)
  • GNU Scientific Library CBLAS

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

---

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:

• Zoltán Zimborás (Researcher): [e-mail]
• Peter Rakyta (Developer): [e-mail]
• Gregory Morse (Developer): [e-mail]

---

License

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