python-package-spiralqiskit

Python Package for Interfacing Spiral and Qiskit

A Python package and utility toolchain for interfacing Spiral and Qiskit. It provides bidirectional translation between OpenQASM 3.0 quantum circuits, Qiskit circuits, and Spiral Intermediate Code (icode / GAP Abstract Syntax Tree [AST]), alongside matrix extraction and circuit visualization.

Overview

This repository enables a round-trip workflow between quantum circuit representations and Spiral:

QASM 3 to Spiral icode: Parse OpenQASM 3.0 files into Spiral icode AST format, suitable for analysis or rewrite optimization in Spiral.

Qiskit to Spiral icode & Matrix: Export Qiskit circuits to GAP matrix definitions or Spiral AST records.

Spiral to Qiskit / QASM: Unparse Spiral quantum icode back to executable Python/Qiskit circuit definitions or OpenQASM 3.0 source text.

Installation & Environment Setup

A Python 3.10+ virtual environment is recommended.

bash
# Clone the repository
git clone https://github.com/spiralgen/python-package-spiralqiskit.git spiralqiskit
cd spiralqiskit

# Create and activate a virtual environment
python3 -m venv .qiskit
source .qiskit/bin/activate

# Install the package in editable mode with dependencies
pip install -e .

# Core requirements for Spiral / QASM / Qiskit translation
pip install qiskit qiskit-qasm3-import

# Optional: needed for graphical circuit diagram rendering (--draw)
pip install matplotlib pylatexenc

Once the packages are installed a simple smoketest, verify_test.py, is available. the test output is a simple circuit diagram, the corresponding unitary GAP matrix, and Spiral icode representation.

bash
python verify_test.py

Command Line Tools

The tools/ directory includes standalone python scripts for conversions and testing. Each tool accepts a --workdir (or -w) argument to specify a working directory to hold working files, and various converted or other output files. The tools/ directory should be added to your PATH before running spiral with the quantum package. Commands such as QMatrix() rely on some of the python tools and must be in your PATH to complete successfully.

1. qasm2icode.py This script translates OpenQASM 3.0 (and optionally OpenQASM 2.0) files into a Spiral icode AST representation (an ouput .g file).

bash
mkdir tmpout
cp tests/add2mod5.qasm tmpout

# Convert an OpenQASM 3.0 file to a Spiral .g script
# By default, the output file is name 'filestem'.g and is written to tmpout, or use -o <outfile>
python tools/qasm2icode.py --workdir tmpout add2mod5.qasm

2. qasm2mat.py This script translates OpenQASM 3.0 files, outputs the circuit diagram (with --draw option), and extracts the corresponding unitary matrix to a GAP .mat file.

bash
# Render a PNG diagram of the circuit and export the GAP matrix
python tools/qasm2mat.py --draw -w tmpout add2mod5.qasm

3. qiskit2mat.py This script imports a Python module defining BuildCircuit(), draws the circuit diagram (with --draw option), and extracts the corresponding unitary matrix to a GAP .mat file.

bash
# Render a PNG diagram of the circuit and export the GAP matrix
python tools/qiskit2mat.py --draw -w tmpout add2mod5_gen.py