Project Overview

Quantum Circuit Optimization is a comprehensive toolkit that bridges quantum computing and large language models (LLMs). It provides tools for generating quantum circuit datasets using Cirq and optimizing them via AI providers such as OpenRouter and Google Gemini.

The project follows an in-context learning approach — providing the LLM with example input/output circuit pairs so it learns the optimization pattern, then applying that learned pattern to new circuits.

Features

Project Structure

quantum-circuit-optimization/
├── src/
│   ├── data_generation/           # Quantum circuit dataset generation
│   │   ├── qc/                    # Core quantum computing modules
│   │   │   ├── circuit_generation.py  # Circuit creation & representation
│   │   │   ├── simulation.py         # Noise & statevector simulation
│   │   │   └── optimization.py       # Cirq built-in optimization
│   │   └── scripts/
│   │       └── generate_dataset.py   # CLI dataset generator
│   │   └── tests/
│   │       └── test_qc.py            # pytest + hypothesis tests
│   └── model_training/             # AI-powered circuit optimization
│       ├── config.py               # Provider configuration
│       ├── openrouter_optimizer.py  # OpenRouter API integration
│       ├── utils.py                # Validation & parsing utilities
│       └── cli/
│           └── predict.py           # Unified CLI for optimization
├── requirements.txt               # Pinned dependencies
├── pytest.ini                     # Test configuration
├── LICENSE                        # MIT-0 License
└── README.md

Installation

Prerequisites

• Python 3.10 or later
• Virtual environment support (venv, uv, conda)
• OpenRouter API key (for LLM optimization)

Clone & Setup

# Clone the repository
git clone https://github.com/waifuai/quantum-circuit-optimization.git
cd quantum-circuit-optimization

# Using uv (recommended)
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate         # Windows
pip install uv
uv pip install -r requirements.txt

# Or standard pip
pip install -r requirements.txt

Verify Installation

# Run the test suite
pytest

# Generate a test dataset
python -m src.data_generation.scripts.generate_dataset --n_circuits 5

Quick Start

1. Generate a Dataset

# Generate 100 circuits with default settings
python -m src.data_generation.scripts.generate_dataset

# Custom: 500 circuits, 2-10 gates, 3 qubits
python -m src.data_generation.scripts.generate_dataset \
    --n_circuits 500 \
    --min_gates 2 \
    --max_gates 10 \
    --n_qubits 3 \
    --output_file my_dataset.jsonl

2. Optimize a Circuit

# Set your API key
export OPENROUTER_API_KEY="sk-or-..."

# Optimize a simple circuit
python -m src.model_training.cli.predict \
    --input_circuit "H 0 ; CNOT 0 1 ; H 0"

# With custom examples
python -m src.model_training.cli.predict \
    --input_circuit "X 0 ; X 0 ; Y 1" \
    --example "H 0 ; CNOT 0 1 ; H 0||CNOT 0 1" \
    --example "X 0 ; X 0 ; Y 1||Y 1"

Data Generation Module

The src/data_generation/ package handles creating random quantum circuits, simulating them, and saving structured datasets in JSON Lines format.

Each generated circuit record contains:

Circuit Generation

circuit_generation.py provides the core circuit creation logic using Cirq.

Key Classes & Functions

QuantumConfig

Constants for default circuit parameters:

generate_random_circuit(qubits, n_gates, gate_set=None)

Creates a random quantum circuit. Default gate set: X, Y, Z, H (single-qubit) and CNOT, CZ (two-qubit). Appends a measurement on all qubits.

import cirq
from src.data_generation.qc.circuit_generation import generate_random_circuit

qubits = [cirq.GridQubit(0, i) for i in range(3)]
circuit = generate_random_circuit(qubits, n_gates=5)
print(circuit)

GateOperationData

Frozen dataclass for serializing gate operations: gate_type, qubits_repr, exponent.

circuit_to_operations_data(circuit)

Converts a Cirq circuit to a list of GateOperationData objects and returns the non-measurement gate count.

Simulation

simulation.py provides two simulation modes for quantum circuits.

simulate_with_noise(circuit, noise, noise_model, repetitions)

Simulates a circuit under noise and returns measurement histograms.

simulate_statevector(circuit)

Simulates without noise, returning a dictionary of computational basis states to probabilities. Filters out probabilities below 1e-10.

from src.data_generation.qc.simulation import simulate_with_noise, simulate_statevector

# Noisy simulation
counts = simulate_with_noise(circuit, noise=0.05, noise_model="bit_flip")

# Noiseless statevector
probs = simulate_statevector(circuit)
print(probs)  # {'state_000': 0.125, 'state_001': 0.125, ...}

Cirq Optimization

optimization.py wraps Cirq's built-in optimize_for_target_gateset routine.

optimize_circuit(circuit, qubits, gateset=None)

Optimizes a circuit for a target gateset. Defaults to cirq.CZTargetGateset() if none specified.

from src.data_generation.qc.optimization import optimize_circuit
import cirq

qubits = [cirq.GridQubit(0, i) for i in range(3)]
circuit = cirq.Circuit([cirq.H(q) for q in qubits])
optimized = optimize_circuit(circuit, qubits)

# Custom gateset
optimized_sqrt = optimize_circuit(circuit, qubits, gateset=cirq.SqrtIswapTargetGateset())

Model Training Module

The src/model_training/ package handles LLM-powered quantum circuit optimization using in-context learning. Currently supports OpenRouter as the primary provider.

How It Works

1. Provide input/output circuit examples (e.g., "H 0 ; CNOT 0 1 ; H 0" → "CNOT 0 1")
2. The examples are formatted into a prompt with clear "Unoptimized/Optimized" pairs
3. The target circuit is appended as the final "Unoptimized" entry
4. The LLM generates the "Optimized" output using the learned pattern
5. The optimized circuit string is returned

OpenRouter Integration

openrouter_optimizer.py handles API communication with OpenRouter's chat completions endpoint.

Authentication

The API key is resolved in this order:

1. OPENROUTER_API_KEY environment variable
2. ~/.api-openrouter file (containing the key on one line)

optimize_circuit_with_openrouter(...)

Returns the optimized circuit string. Raises ValueError for invalid inputs or missing API key, RuntimeError for API failures.

CLI Interface

The unified CLI (src.model_training.cli.predict) provides a single entry point for circuit optimization.

Usage

python -m src.model_training.cli.predict [OPTIONS]

Required:
  --input_circuit STR    Circuit string (e.g., "H 0 ; CNOT 0 1 ; H 0")

Options:
  --provider STR         Provider name (default: openrouter)
  --model STR            Override model name
  --timeout INT          HTTP timeout in seconds (default: 60)
  --example STR          Add example as "input||output" (repeatable)
  --verbose, -v          Enable DEBUG logging

Examples

# Basic optimization with defaults
python -m src.model_training.cli.predict \
    --input_circuit "H 0 ; CNOT 0 1 ; H 0"

# With custom examples and verbose output
python -m src.model_training.cli.predict \
    --input_circuit "X 0 ; X 0 ; Y 1" \
    --example "H 0 ; CNOT 0 1 ; H 0||CNOT 0 1" \
    --example "X 0 ; X 0 ; Y 1||Y 1" \
    --timeout 120 \
    --verbose

# Override model
python -m src.model_training.cli.predict \
    --provider openrouter \
    --model "deepseek/deepseek-chat-v3-0324" \
    --input_circuit "H 0 ; CNOT 0 1 ; H 0"

API Reference

Data Generation — qc.circuit_generation

Data Generation — qc.simulation

Data Generation — qc.optimization

Data Generation — scripts.generate_dataset

Model Training — openrouter_optimizer

Model Training — config

Model Training — utils

Configuration

API Keys

Model Selection

Override default models by creating dotfiles in your home directory:

# Set default OpenRouter model
echo "deepseek/deepseek-chat-v3-0324" > ~/.model-openrouter

Testing

The project uses pytest with Hypothesis for property-based testing.

Running Tests

# Run all tests
pytest

# Run data generation tests
pytest src/data_generation/tests/

# Run with verbose output
pytest -v

Test Coverage

License

This project is licensed under the MIT No Attribution (MIT-0) license.

MIT No Attribution

Copyright 2025 WaifuAI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

GitHub Repository  ·  Report Issues