# qqq-wisc/wisq architecture

> Architecture diagram of the GitHub repository qqq-wisc/wisq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qqq-wisc/wisq
- Repository: https://github.com/qqq-wisc/wisq

## Overview

wisq is a Python quantum-circuit compiler with optimization-only, mapping/routing-only, and combined fault-tolerant modes. The main user workflow accepts OpenQASM, optionally optimizes it, maps logical qubits to a surface-code architecture, routes gates, and emits QASM or a schedule JSON. The graph preserves the documented GUOQ, BQSKit/Synthetiq, Qualtran, DASCOT, SAT-SCMR, and custom-layout capabilities. Some subsystem links rely on README statements or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/wisq/__init__.py`](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/__init__.py) (Mode selection), [`src/wisq/dascot.py`](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/dascot.py) (DASCOT orchestration), [`src/wisq/guoq.py`](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/guoq.py) (Optimization pass), [`src/wisq/resynth.py`](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/resynth.py) (Resynthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Compiler entry"]
  node_cli["Mode selection<br/>[__init__.py]"]
end

subgraph group_optimization["Circuit optimization"]
  node_optimizer["Optimization pass<br/>[guoq.py]"]
  node_guoq["GUOQ optimizer"]
  node_resynth["Resynthesis<br/>[resynth.py]"]
  node_qualtran["Rotation synthesis"]
  node_synthetiq["Synthetiq backend"]
end

subgraph group_mapping["Mapping and routing"]
  node_dascot["DASCOT orchestration<br/>[dascot.py]"]
  node_phased["Phased mapping<br/>[phased_graph.py]"]
  node_sa_route["Annealing router<br/>[sarouting.py]"]
  node_sat["SAT scheduler<br/>[sat_scmr.py]"]
end

subgraph group_layouts["Architecture and output"]
  node_architecture["Architecture helpers<br/>[architecture.py]"]
  node_layout_search["Arbitrary layouts"]
  node_output_writer["Schedule writer<br/>[dascot.py]"]
end

node_user(("Circuit user"))
node_qasm["OpenQASM input"]
node_result["Compiled result"]

node_user -->|"supplies"| node_qasm
node_qasm -->|"loads"| node_cli
node_cli -->|"runs optimization"| node_optimizer
node_optimizer -->|"invokes"| node_guoq
node_optimizer -->|"uses"| node_resynth
node_optimizer -->|"uses"| node_qualtran
node_resynth -.->|"runs backend"| node_synthetiq
node_cli -->|"dispatches mapping"| node_dascot
node_dascot -->|"builds mapping"| node_phased
node_dascot -->|"routes gates"| node_sa_route
node_dascot -->|"solves schedule"| node_sat
node_sa_route -->|"reads neighbors"| node_architecture
node_cli -.->|"selects layout"| node_architecture
node_cli -.->|"may optimize layout"| node_layout_search
node_dascot -->|"returns schedule"| node_output_writer
node_cli -->|"writes output"| node_result
node_output_writer -->|"serializes JSON"| node_result

click node_cli "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/__init__.py"
click node_optimizer "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/guoq.py"
click node_guoq "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/lib/GUOQ-1.0-jar-with-dependencies.jar"
click node_resynth "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/resynth.py"
click node_qualtran "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/qualtran_rotation_synthesis.py"
click node_synthetiq "https://github.com/qqq-wisc/wisq/tree/main/src/wisq/lib/synthetiq"
click node_architecture "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/architecture.py"
click node_layout_search "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/optimal_arb_layout.py"
click node_dascot "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/dascot.py"
click node_phased "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/phased_graph.py"
click node_sa_route "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/sarouting.py"
click node_sat "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/sat_scmr.py"
click node_output_writer "https://github.com/qqq-wisc/wisq/blob/main/src/wisq/dascot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_optimizer,node_guoq,node_resynth,node_qualtran,node_synthetiq toneAmber
class node_dascot,node_phased,node_sa_route,node_sat toneMint
class node_architecture,node_layout_search,node_output_writer toneRose
class node_qasm,node_result toneIndigo
```

## Components

### Compiler entry

- [Mode selection](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/__init__.py): `src/wisq/__init__.py`

### Circuit optimization

- [Optimization pass](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/guoq.py): `src/wisq/guoq.py`
- [GUOQ optimizer](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/lib/GUOQ-1.0-jar-with-dependencies.jar): `src/wisq/lib/GUOQ-1.0-jar-with-dependencies.jar`
- [Resynthesis](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/resynth.py): `src/wisq/resynth.py`
- [Rotation synthesis](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/qualtran_rotation_synthesis.py): `src/wisq/qualtran_rotation_synthesis.py`
- [Synthetiq backend](https://github.com/qqq-wisc/wisq/tree/main/src/wisq/lib/synthetiq): `src/wisq/lib/synthetiq`

### Mapping and routing

- [DASCOT orchestration](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/dascot.py): `src/wisq/dascot.py`
- [Phased mapping](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/phased_graph.py): `src/wisq/phased_graph.py`
- [Annealing router](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/sarouting.py): `src/wisq/sarouting.py`
- [SAT scheduler](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/sat_scmr.py): `src/wisq/sat_scmr.py`

### Architecture and output

- [Architecture helpers](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/architecture.py): `src/wisq/architecture.py`
- [Arbitrary layouts](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/optimal_arb_layout.py): `src/wisq/optimal_arb_layout.py`
- [Schedule writer](https://github.com/qqq-wisc/wisq/blob/main/src/wisq/dascot.py): `src/wisq/dascot.py`

### Other components

- **Circuit user**
- **OpenQASM input**
- **Compiled result**

## Connections

- Circuit user → OpenQASM input: supplies (evidence: `README.md`)
- OpenQASM input → Mode selection: loads (evidence: `README.md`)
- Mode selection → Optimization pass: runs optimization (evidence: `src/wisq/__init__.py`)
- Optimization pass → GUOQ optimizer: invokes (evidence: `src/wisq/guoq.py`)
- Optimization pass → Resynthesis: uses (evidence: `src/wisq/guoq.py`)
- Optimization pass → Rotation synthesis: uses (evidence: `src/wisq/guoq.py`)
- Resynthesis → Synthetiq backend: runs backend
- Mode selection → DASCOT orchestration: dispatches mapping (evidence: `src/wisq/__init__.py`)
- DASCOT orchestration → Phased mapping: builds mapping (evidence: `src/wisq/dascot.py`)
- DASCOT orchestration → Annealing router: routes gates (evidence: `src/wisq/dascot.py`)
- DASCOT orchestration → SAT scheduler: solves schedule (evidence: `src/wisq/dascot.py`)
- Annealing router → Architecture helpers: reads neighbors (evidence: `src/wisq/sarouting.py`)
- Mode selection → Architecture helpers: selects layout (evidence: `src/wisq/__init__.py`)
- Mode selection → Arbitrary layouts: may optimize layout
- DASCOT orchestration → Schedule writer: returns schedule (evidence: `src/wisq/dascot.py`)
- Mode selection → Compiled result: writes output (evidence: `src/wisq/__init__.py`)
- Schedule writer → Compiled result: serializes JSON (evidence: `src/wisq/dascot.py`)
