# rqm-technologies-dev/rqm-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/rqm-technologies-dev/rqm-compiler
- Repository: https://github.com/rqm-technologies-dev/rqm-compiler

## Overview

rqm-compiler is a backend-neutral quantum circuit planner and optimizer. Users provide a circuit and observable; representation-aware planning selects a validated query/readout route, or the compiler normalizes and optimizes the circuit, verifies equivalence, and prepares backend-neutral materialization. Its major branches include relational representation analysis, observable evaluation, and backend capability planning. Backend bridges execute compiled work; this package does not execute or simulate it. Relationships are based on the README and SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`src/rqm_compiler/compile.py`](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/compile.py) (Circuit optimizer), [`src/rqm_compiler/planner.py`](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/planner.py) (Representation planner), [`src/rqm_compiler/__init__.py`](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/__init__.py) (Compiler API), [`src/rqm_compiler/circuit.py`](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/circuit.py) (Circuit model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Circuit model"]
  node_circuit["Circuit model<br/>[circuit.py]"]
  node_operation["Operation model<br/>[ops.py]"]
end

subgraph group_compiler["Compiler pipeline"]
  node_validation["Circuit validation<br/>[validate.py]"]
  node_normalization["IR normalization<br/>[normalize.py]"]
  node_compile["Circuit optimizer<br/>[compile.py]"]
  node_passes["Optimization passes"]
  node_depth["Circuit depth<br/>[depth.py]"]
  node_adaptive["Adaptive Cartan<br/>[adaptive.py]"]
  node_regional["Regional optimization<br/>[regional.py]"]
  node_verification["Semantic verification<br/>[verification.py]"]
  node_blocks["SU4 block analysis<br/>[su4_blocks.py]"]
  node_report["Compiler report<br/>[report.py]"]
end

subgraph group_planning["Query planning"]
  node_planner["Representation planner<br/>[planner.py]"]
  node_observables["Observable evaluation<br/>[observables.py]"]
  node_direct_readout["Direct readout<br/>[direct_readout.py]"]
  node_topology["Topology readout"]
  node_frontier["Readout frontier<br/>[frontier.py]"]
end

subgraph group_interfaces["Interoperability"]
  node_public_api["Compiler API<br/>[__init__.py]"]
  node_descriptors["Backend descriptors<br/>[descriptors.py]"]
  node_backend_plan["Backend capabilities<br/>[backends.py]"]
  node_circuit_io["Descriptor conversion<br/>[from_dict.py]"]
end

node_user(("Circuit user"))
node_backend_bridge["Backend bridge"]

node_user -->|"calls"| node_public_api
node_public_api -->|"exposes planning"| node_planner
node_public_api -->|"exposes optimization"| node_compile
node_circuit -->|"stores"| node_operation
node_compile -->|"validates"| node_validation
node_compile -->|"normalizes"| node_normalization
node_compile -->|"runs passes"| node_passes
node_compile -->|"routes adaptively"| node_adaptive
node_compile -->|"measures depth"| node_depth
node_compile -->|"verifies candidate"| node_verification
node_compile -->|"records outcome"| node_report
node_adaptive -->|"uses blocks"| node_blocks
node_regional -->|"invokes compiler"| node_compile
node_blocks -->|"proves extraction"| node_verification
node_verification -->|"canonicalizes for comparison"| node_passes
node_planner -->|"uses routing"| node_adaptive
node_planner -->|"evaluates queries"| node_observables
node_planner -->|"selects readout"| node_direct_readout
node_planner -->|"selects topology route"| node_topology
node_planner -->|"uses frontier"| node_frontier
node_planner -->|"compiles circuit"| node_compile
node_circuit -->|"plans materialization"| node_backend_plan
node_backend_plan -.->|"plans descriptors"| node_descriptors
node_descriptors -->|"provides lowering input"| node_backend_bridge
node_backend_bridge -.->|"returns result"| node_user
node_circuit_io -->|"constructs circuit"| node_circuit

click node_public_api "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/__init__.py"
click node_circuit "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/circuit.py"
click node_operation "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/ops.py"
click node_validation "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/validate.py"
click node_normalization "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/normalize.py"
click node_compile "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/compile.py"
click node_passes "https://github.com/rqm-technologies-dev/rqm-compiler/tree/main/src/rqm_compiler/passes"
click node_depth "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/depth.py"
click node_adaptive "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/adaptive.py"
click node_regional "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/regional.py"
click node_verification "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/verification.py"
click node_blocks "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/su4_blocks.py"
click node_report "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/report.py"
click node_planner "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/planner.py"
click node_observables "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/observables.py"
click node_direct_readout "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/direct_readout.py"
click node_topology "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/topology_readout.py"
click node_frontier "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/frontier.py"
click node_descriptors "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/descriptors.py"
click node_backend_plan "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/backends.py"
click node_circuit_io "https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/io/from_dict.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_circuit,node_operation,node_user toneBlue
class node_validation,node_normalization,node_compile,node_passes,node_depth,node_adaptive,node_regional,node_verification,node_blocks,node_report toneAmber
class node_planner,node_observables,node_direct_readout,node_topology,node_frontier toneMint
class node_public_api,node_descriptors,node_backend_plan,node_circuit_io toneRose
class node_backend_bridge toneIndigo
```

## Components

### Circuit model

- [Circuit model](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/circuit.py): `src/rqm_compiler/circuit.py`
- [Operation model](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/ops.py): `src/rqm_compiler/ops.py`

### Compiler pipeline

- [Circuit validation](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/validate.py): `src/rqm_compiler/validate.py`
- [IR normalization](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/normalize.py): `src/rqm_compiler/normalize.py`
- [Circuit optimizer](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/compile.py): `src/rqm_compiler/compile.py`
- [Optimization passes](https://github.com/rqm-technologies-dev/rqm-compiler/tree/main/src/rqm_compiler/passes): `src/rqm_compiler/passes`
- [Circuit depth](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/depth.py): `src/rqm_compiler/depth.py`
- [Adaptive Cartan](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/adaptive.py): `src/rqm_compiler/adaptive.py`
- [Regional optimization](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/regional.py): `src/rqm_compiler/regional.py`
- [Semantic verification](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/verification.py): `src/rqm_compiler/verification.py`
- [SU4 block analysis](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/su4_blocks.py): `src/rqm_compiler/su4_blocks.py`
- [Compiler report](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/report.py): `src/rqm_compiler/report.py`

### Query planning

- [Representation planner](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/planner.py): `src/rqm_compiler/planner.py`
- [Observable evaluation](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/observables.py): `src/rqm_compiler/observables.py`
- [Direct readout](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/direct_readout.py): `src/rqm_compiler/direct_readout.py`
- [Topology readout](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/topology_readout.py): `src/rqm_compiler/topology_readout.py`
- [Readout frontier](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/frontier.py): `src/rqm_compiler/frontier.py`

### Interoperability

- [Compiler API](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/__init__.py): `src/rqm_compiler/__init__.py`
- [Backend descriptors](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/descriptors.py): `src/rqm_compiler/descriptors.py`
- [Backend capabilities](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/backends.py): `src/rqm_compiler/backends.py`
- [Descriptor conversion](https://github.com/rqm-technologies-dev/rqm-compiler/blob/main/src/rqm_compiler/io/from_dict.py): `src/rqm_compiler/io/from_dict.py`

### Other components

- **Circuit user**
- **Backend bridge**

## Connections

- Circuit user → Compiler API: calls (evidence: `README.md`)
- Compiler API → Representation planner: exposes planning (evidence: `src/rqm_compiler/__init__.py`)
- Compiler API → Circuit optimizer: exposes optimization (evidence: `src/rqm_compiler/__init__.py`)
- Circuit model → Operation model: stores (evidence: `src/rqm_compiler/circuit.py`)
- Circuit optimizer → Circuit validation: validates (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → IR normalization: normalizes (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → Optimization passes: runs passes (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → Adaptive Cartan: routes adaptively (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → Circuit depth: measures depth (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → Semantic verification: verifies candidate (evidence: `src/rqm_compiler/compile.py`)
- Circuit optimizer → Compiler report: records outcome (evidence: `src/rqm_compiler/compile.py`)
- Adaptive Cartan → SU4 block analysis: uses blocks (evidence: `src/rqm_compiler/adaptive.py`)
- Regional optimization → Circuit optimizer: invokes compiler (evidence: `src/rqm_compiler/regional.py`)
- SU4 block analysis → Semantic verification: proves extraction (evidence: `src/rqm_compiler/su4_blocks.py`)
- Semantic verification → Optimization passes: canonicalizes for comparison (evidence: `src/rqm_compiler/verification.py`)
- Representation planner → Adaptive Cartan: uses routing (evidence: `src/rqm_compiler/planner.py`)
- Representation planner → Observable evaluation: evaluates queries (evidence: `src/rqm_compiler/planner.py`)
- Representation planner → Direct readout: selects readout
- Representation planner → Topology readout: selects topology route
- Representation planner → Readout frontier: uses frontier
- Representation planner → Circuit optimizer: compiles circuit (evidence: `src/rqm_compiler/planner.py`)
- Circuit model → Backend capabilities: plans materialization (evidence: `README.md`)
- Backend capabilities → Backend descriptors: plans descriptors
- Backend descriptors → Backend bridge: provides lowering input (evidence: `README.md`)
- Backend bridge → Circuit user: returns result
- Descriptor conversion → Circuit model: constructs circuit (evidence: `src/rqm_compiler/io/from_dict.py`)
