README.md

---
title: Quantum Circuit Optimizer
emoji: "⚛️"
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
app_port: 7860
tags:
  - quantum
  - reinforcement-learning
  - circuit-optimization
  - gradio
  - qiskit
base_path: /web
---

# ⚛️ Quantum Circuit Optimizer

A web-based reinforcement learning environment for optimizing quantum circuits. Build and optimize quantum circuits step-by-step to maximize fidelity with target quantum states while respecting hardware constraints and noise.

## 🌟 Features

- **Interactive Web UI**: Built with Gradio for easy circuit construction
- **Reinforcement Learning Ready**: Compatible with RL algorithms for automated optimization
- **Hardware-Aware**: Respects qubit connectivity and gate constraints
- **Noise Simulation**: Includes noise models for realistic NISQ-era circuits
- **Multiple Tasks**: From simple Bell states to complex unitary approximations

## 🎯 Problem Statement

The agent must construct quantum circuits to:

1. **Maximize Fidelity** - Match target quantum states
2. **Minimize Depth** - Shorter circuits run faster
3. **Minimize Gate Count** - Fewer operations reduce noise
4. **Respect Connectivity** - Multi-qubit gates only on connected qubits
5. **Resist Noise** - Circuits must survive decoherence

## 🚀 Action Space

| Action | Description | Parameters |
|--------|-------------|------------|
| `ADD`  | Add a quantum gate | `gate` (H, X, CNOT, RX, RZ), `qubits`, `parameter` |
| `REMOVE` | Remove last gate | -- |
| `SWAP` | Swap two qubits | `qubits` [q1, q2] |
| `PARAM` | Tune parametric gate | `parameter` (angle in radians) |
| `STOP` | End episode | -- |

**Available Gates:**
- **H** - Hadamard (single qubit)
- **X** - Pauli-X / NOT (single qubit)
- **CNOT** - Controlled-NOT (two qubits)
- **RX(θ)** - Rotation around X-axis (parameterized)
- **RZ(θ)** - Rotation around Z-axis (parameterized)

## 🏗️ Architecture

- **Backend**: Qiskit for quantum state simulation
- **Frontend**: Gradio web interface
- **Server**: FastAPI with WebSocket support
- **Environment**: Custom Gym-compatible RL environment

## 🚀 Quick Start

### Local Development

1. **Clone and setup:**
   ```bash
   git clone https://github.com/viditkaushik/quantum_circuit_optimizer.git
   cd quantum_circuit_optimizer
   pip install -r requirements.txt
   ```

2. **Run locally:**
   ```bash
   python server/app.py
   # Or with uvicorn:
   uvicorn server.app:app --host 0.0.0.0 --port 7860
   ```

3. **Open browser:** http://localhost:7860

### Docker Deployment

```bash
# Build image
docker build -t quantum-circuit-optimizer .

# Run container
docker run -p 7860:7860 quantum-circuit-optimizer
```

## 📊 Tasks

- **Easy**: Bell State (2 qubits, no noise)
- **Medium**: GHZ State (3 qubits, depolarizing noise)
- **Hard**: Unitary Approximation (2 qubits, thermal noise)
- **Efficient**: Imperfect but Efficient (budget constraints)
- **Noisy**: Noise-Dominant (high decoherence)
- **Budget**: Budgeted Optimization (resource limits)
- **Approx**: Approximate Target (tolerance-based)

## 🔧 API Endpoints

- `POST /reset` - Reset environment with task
- `POST /step` - Execute action
- `GET /state` - Get current state
- `GET /health` - Health check

## 📈 Metrics

- **Fidelity**: How close circuit output is to target state
- **Efficiency**: Circuit depth and gate count
- **Noise Score**: Resilience to decoherence
- **Constraints Score**: Hardware constraint satisfaction
- **Aggregate Score**: Weighted combination of above

## 🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Add tests
5. Submit pull request

## 📄 License

This project is licensed under the BSD-style license.

## 🙏 Acknowledgments

Built using Qiskit, Gradio, FastAPI, and OpenEnv framework.
- **H** - Hadamard (single qubit)
- **X** - Pauli-X / NOT (single qubit)
- **CNOT** - Controlled-NOT (two qubits)
- **RX(θ)** - Rotation around X-axis (parameterized)
- **RZ(θ)** - Rotation around Z-axis (parameterized)

## 🏗️ Architecture

- **Backend**: Qiskit for quantum state simulation
- **Frontend**: Gradio web interface
- **Server**: FastAPI with WebSocket support
- **Environment**: Custom Gym-compatible RL environment

## 🚀 Quick Start

### Local Development

1. **Clone and setup:**
   ```bash
   git clone https://github.com/viditkaushik/quantum_circuit_optimizer.git
   cd quantum_circuit_optimizer
   pip install -r requirements.txt
   ```

2. **Run locally:**
   ```bash
   python server/app.py
   # Or with uvicorn:
   uvicorn server.app:app --host 0.0.0.0 --port 7860
   ```

3. **Open browser:** http://localhost:7860

### Docker Deployment

```bash
# Build image
docker build -t quantum-circuit-optimizer .

# Run container
docker run -p 7860:7860 quantum-circuit-optimizer
```

## 📊 Tasks

- **Easy**: Bell State (2 qubits, no noise)
- **Medium**: GHZ State (3 qubits, depolarizing noise)
- **Hard**: Unitary Approximation (2 qubits, thermal noise)
- **Efficient**: Imperfect but Efficient (budget constraints)
- **Noisy**: Noise-Dominant (high decoherence)
- **Budget**: Budgeted Optimization (resource limits)
- **Approx**: Approximate Target (tolerance-based)

## 🔧 API Endpoints

- `POST /reset` - Reset environment with task
- `POST /step` - Execute action
- `GET /state` - Get current state
- `GET /health` - Health check

## 📈 Metrics

- **Fidelity**: How close circuit output is to target state
- **Efficiency**: Circuit depth and gate count
- **Noise Score**: Resilience to decoherence
- **Constraints Score**: Hardware constraint satisfaction
- **Aggregate Score**: Weighted combination of above

## 🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Add tests
5. Submit pull request

## 📄 License

This project is licensed under the BSD-style license.

## 🙏 Acknowledgments

Built using Qiskit, Gradio, FastAPI, and OpenEnv framework.

**Gates available:** Hadamard (H), Pauli-X (X), CNOT, RX(theta), RZ(theta)

##  Observation Space

| Field | Type | Description |
|-------|------|-------------|
| `circuit_gates` | list | Current gates in the circuit |
| `fidelity` | float | Overlap with target state (0-1) |
| `depth` | int | Circuit depth |
| `gate_count` | int | Number of gates |
| `noise_estimate` | float | Estimated fidelity loss from noise |
| `valid_actions` | list | Legal action types |
| `score` | float | Aggregate grader score (0-1) |
| `target_description` | str | What state to build |

##  Reward Design

**Shaped reward** -- NOT sparse. The reward at each step is:

```
reward = current_aggregate_score - previous_aggregate_score
```

The aggregate score is a weighted combination of four modular graders:

| Grader | Weight | Measures |
|--------|--------|----------|
| **Fidelity** | 40-60% | State overlap with target |
| **Efficiency** | 20% | Depth + gate count vs limits |
| **Noise** | 15-25% | Gate-by-gate error probability |
| **Constraints** | 10-15% | Hardware connectivity compliance |

At episode end: **+0.2 bonus** if fidelity >= threshold, **-0.05 penalty** otherwise.

##  Tasks

**7 diverse tasks** covering different quantum circuit optimization challenges:

###  1. Easy -- Bell State
- **Target:** (|00> + |11>) / sqrt(2)
- **Qubits:** 2 | **Noise:** None | **Connectivity:** Full
- **Max depth:** 10 | **Max steps:** 20

###  2. Medium -- GHZ State
- **Target:** (|000> + |111>) / sqrt(2)
- **Qubits:** 3 | **Noise:** Depolarizing | **Connectivity:** Linear (0<->1<->2)
- **Max depth:** 15 | **Max steps:** 30

###  3. Hard -- Unitary Approximation
- **Target:** Ry(pi/3) @ Rz(pi/4) . CNOT
- **Qubits:** 2 | **Noise:** Thermal | **Connectivity:** Restricted (0<->1 only)
- **Max depth:** 20 | **Max steps:** 40

###  4. Efficient -- Imperfect but Efficient
- **Target:** GHZ state with efficiency focus
- **Qubits:** 3 | **Noise:** None | **Grader weights:** 60% fidelity, 40% efficiency

###  5. Noisy -- Noise-Dominant
- **Target:** Bell state with noise focus
- **Qubits:** 2 | **Noise:** Thermal | **Grader weights:** 40% fidelity, 40% noise

###  6. Budget -- Budgeted Optimization
- **Target:** GHZ state with strict gate budget
- **Qubits:** 3 | **Max gates:** 3 | **Hard constraint on gate count**

###  7. Approx -- Approximate Target
- **Target:** 4-qubit GHZ state
- **Qubits:** 4 | **Tolerance:** 0.80 fidelity | **Rewards approximate solutions**

##  Quick Start

### Prerequisites

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync
```

### Run Server Locally

```bash
# Development mode
uvicorn server.app:app --reload --host 0.0.0.0 --port 8000

# Or via uv
uv run --project . server
```

### Test Directly (No Server)

```bash
python server/my_env_environment.py
```

### Build & Run Docker

```bash
docker build -t quantum-circuit-opt:latest .
docker run -p 8000:8000 quantum-circuit-opt:latest
```

### Run Inference

```bash
export HF_TOKEN="your-token"
export IMAGE_NAME="quantum-circuit-opt:latest"
python inference.py
```

### Deploy to HF Spaces

```bash
openenv push
```

##  Expected Baseline Results

With a capable LLM (e.g., Qwen2.5-72B):

| Task | Expected Score | Expected Fidelity |
|------|---------------|-------------------|
| Easy (Bell) | 0.65-0.85 | >= 0.90 |
| Medium (GHZ) | 0.45-0.65 | >= 0.80 |
| Hard (Unitary) | 0.30-0.50 | >= 0.60 |
| Efficient | 0.60-0.80 | >= 0.85 |
| Noisy | 0.40-0.60 | >= 0.75 |
| Budget | 0.50-0.70 | >= 0.80 |
| Approx | 0.55-0.75 | >= 0.70 |

Scores depend heavily on the LLM's ability to reason about quantum operations.

##  Validation & Testing

```bash
# Run compliance tests (verifies all OpenEnv requirements)
python test_compliance.py

# Run pre-deployment validation
python validate_deployment.py

# Run environment smoke tests
python server/my_env_environment.py
```

##  Project Structure

```
my_env/
|---- __init__.py                    # Module exports
|---- models.py                      # Pydantic action/observation/state models
|---- client.py                      # QuantumCircuitEnv client
|---- openenv.yaml                   # OpenEnv manifest
|---- pyproject.toml                 # Project dependencies
|---- inference.py                   # Baseline inference script
|---- Dockerfile                     # Container image
|---- README.md                      # This file
|---- graders/
|   |---- __init__.py
|   |---- fidelity.py                # State fidelity grader
|   |---- efficiency.py              # Depth + gate count grader
|   |---- noise.py                   # Noise resilience grader
|   |---- constraints.py             # Connectivity compliance grader
|   |---- aggregate.py               # Weighted score combiner
|---- server/
    |---- __init__.py
    |---- my_env_environment.py      # Core environment + statevector simulator
    |---- app.py                     # FastAPI application
    |---- tasks/
        |---- __init__.py            # Task registry
        |---- easy.py                # Bell state task
        |---- medium.py              # GHZ state task
        |---- hard.py                # Unitary approximation task
```

##  Technical Design

### Statevector Simulator

Uses a **pure-NumPy statevector simulator** for deterministic, dependency-light quantum simulation:
- No native C++ compilation required (unlike Qiskit Aer)
- Exact simulation for 2-3 qubit circuits
- Supports H, X, CNOT, RX(theta), RZ(theta), SWAP gates
- Fully deterministic -- same inputs always produce same outputs

### Noise Model

Analytical noise estimation rather than density matrix simulation:
- **Depolarizing:** Per-gate error rates (single-qubit: 0.1%, two-qubit: 1%)
- **Thermal:** 2x higher error rates than depolarizing
- Noise score = probability of no error across all gates

### Determinism

All scoring is deterministic: same circuit -> same score. This is critical for reliable RL training and reproducible evaluation.