# munich-quantum-toolkit/predictor architecture

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

- Interactive diagram: https://gitdiagram.com/munich-quantum-toolkit/predictor
- Repository: https://github.com/munich-quantum-toolkit/predictor

## Overview

MQT Predictor turns a quantum circuit into a device-specific compiled circuit: it predicts a suitable target, then uses a learned reinforcement-learning policy to select and apply compiler passes. Separate training workflows build the device-selection model and the RL compiler policy. The README also documents customizable figures of merit and mixed passes from Qiskit, TKET, and BQSKit. Several implementation details are unsampled, so the graph omits unverified links rather than implying a complete runtime sequence.

Main entry points: [`src/mqt/predictor/rl/predictorenv.py`](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/predictorenv.py) (Compiler environment), [`src/mqt/predictor/rl/actions/registry.py`](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/registry.py) (Pass registry), [`src/mqt/predictor/qcompile.py`](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/qcompile.py) (Compile API), [`src/mqt/predictor/ml/predictor.py`](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/ml/predictor.py) (Device predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Entry and orchestration"]
  node_qcompile["Compile API<br/>[qcompile.py]"]
end

subgraph group_selection["Device selection"]
  node_ml_predictor["Device predictor<br/>[predictor.py]"]
  node_ml_helpers["Training and features<br/>[helper.py]"]
end

subgraph group_compilation["RL compilation"]
  node_rl_compile["RL compile workflow<br/>[predictor.py]"]
  node_rl_env["Compiler environment<br/>[predictorenv.py]"]
  node_action_base["Pass action types<br/>[base.py]"]
  node_action_registry["Pass registry<br/>[registry.py]"]
  node_qiskit_actions["Qiskit passes<br/>[qiskit_actions.py]"]
  node_tket_actions["TKET passes<br/>[tket_actions.py]"]
  node_bqskit_actions["BQSKit passes<br/>[bqskit_actions.py]"]
  node_trace["Compilation tracing<br/>[tracer.py]"]
end

subgraph group_metrics["Scoring and features"]
  node_reward["Figures of merit<br/>[reward.py]"]
  node_hellinger["Hellinger metrics<br/>[utils.py]"]
  node_features["Circuit features<br/>[utils.py]"]
end

node_user(("Circuit user"))

node_user -->|"submits circuit"| node_qcompile
node_qcompile -->|"predicts device"| node_ml_predictor
node_qcompile -->|"compiles circuit"| node_rl_compile
node_ml_predictor -->|"trains per device"| node_rl_compile
node_ml_helpers -->|"extracts features"| node_features
node_rl_compile -->|"uses environment"| node_rl_env
node_rl_env -->|"loads actions"| node_action_registry
node_action_registry -->|"registers passes"| node_qiskit_actions
node_action_registry -->|"registers passes"| node_tket_actions
node_action_registry -->|"registers passes"| node_bqskit_actions
node_qiskit_actions -->|"defines actions"| node_action_base
node_tket_actions -->|"defines actions"| node_action_base
node_bqskit_actions -->|"defines actions"| node_action_base
node_rl_env -->|"calculates score"| node_reward
node_rl_env -->|"calculates metric"| node_hellinger
node_reward -->|"uses metric"| node_hellinger
node_rl_env -->|"records steps"| node_trace
node_ml_predictor -.->|"scores circuits"| node_reward

click node_qcompile "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/qcompile.py"
click node_ml_predictor "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/ml/predictor.py"
click node_ml_helpers "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/ml/helper.py"
click node_rl_compile "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/predictor.py"
click node_rl_env "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/predictorenv.py"
click node_action_base "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/base.py"
click node_action_registry "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/registry.py"
click node_qiskit_actions "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/qiskit_actions.py"
click node_tket_actions "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/tket_actions.py"
click node_bqskit_actions "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/bqskit_actions.py"
click node_trace "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/tracer.py"
click node_reward "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/reward.py"
click node_hellinger "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/hellinger/utils.py"
click node_features "https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/utils.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_qcompile,node_user toneBlue
class node_ml_predictor,node_ml_helpers toneAmber
class node_rl_compile,node_rl_env,node_action_base,node_action_registry,node_qiskit_actions,node_tket_actions,node_bqskit_actions,node_trace toneMint
class node_reward,node_hellinger,node_features toneRose
```

## Components

### Entry and orchestration

- [Compile API](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/qcompile.py): `src/mqt/predictor/qcompile.py`

### Device selection

- [Device predictor](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/ml/predictor.py): `src/mqt/predictor/ml/predictor.py`
- [Training and features](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/ml/helper.py): `src/mqt/predictor/ml/helper.py`

### RL compilation

- [RL compile workflow](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/predictor.py): `src/mqt/predictor/rl/predictor.py`
- [Compiler environment](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/predictorenv.py): `src/mqt/predictor/rl/predictorenv.py`
- [Pass action types](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/base.py): `src/mqt/predictor/rl/actions/base.py`
- [Pass registry](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/registry.py): `src/mqt/predictor/rl/actions/registry.py`
- [Qiskit passes](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/qiskit_actions.py): `src/mqt/predictor/rl/actions/qiskit_actions.py`
- [TKET passes](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/tket_actions.py): `src/mqt/predictor/rl/actions/tket_actions.py`
- [BQSKit passes](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/actions/bqskit_actions.py): `src/mqt/predictor/rl/actions/bqskit_actions.py`
- [Compilation tracing](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/rl/tracer.py): `src/mqt/predictor/rl/tracer.py`

### Scoring and features

- [Figures of merit](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/reward.py): `src/mqt/predictor/reward.py`
- [Hellinger metrics](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/hellinger/utils.py): `src/mqt/predictor/hellinger/utils.py`
- [Circuit features](https://github.com/munich-quantum-toolkit/predictor/blob/main/src/mqt/predictor/utils.py): `src/mqt/predictor/utils.py`

### Other components

- **Circuit user**

## Connections

- Circuit user → Compile API: submits circuit (evidence: `README.md`)
- Compile API → Device predictor: predicts device (evidence: `src/mqt/predictor/qcompile.py`)
- Compile API → RL compile workflow: compiles circuit (evidence: `src/mqt/predictor/qcompile.py`)
- Device predictor → RL compile workflow: trains per device (evidence: `src/mqt/predictor/ml/predictor.py`)
- Training and features → Circuit features: extracts features (evidence: `src/mqt/predictor/ml/helper.py`)
- RL compile workflow → Compiler environment: uses environment (evidence: `src/mqt/predictor/rl/predictor.py`)
- Compiler environment → Pass registry: loads actions (evidence: `src/mqt/predictor/rl/predictorenv.py`)
- Pass registry → Qiskit passes: registers passes (evidence: `src/mqt/predictor/rl/actions/registry.py`)
- Pass registry → TKET passes: registers passes (evidence: `src/mqt/predictor/rl/actions/registry.py`)
- Pass registry → BQSKit passes: registers passes (evidence: `src/mqt/predictor/rl/actions/registry.py`)
- Qiskit passes → Pass action types: defines actions (evidence: `src/mqt/predictor/rl/actions/qiskit_actions.py`)
- TKET passes → Pass action types: defines actions (evidence: `src/mqt/predictor/rl/actions/tket_actions.py`)
- BQSKit passes → Pass action types: defines actions (evidence: `src/mqt/predictor/rl/actions/bqskit_actions.py`)
- Compiler environment → Figures of merit: calculates score (evidence: `src/mqt/predictor/rl/predictorenv.py`)
- Compiler environment → Hellinger metrics: calculates metric (evidence: `src/mqt/predictor/rl/predictorenv.py`)
- Figures of merit → Hellinger metrics: uses metric (evidence: `src/mqt/predictor/reward.py`)
- Compiler environment → Compilation tracing: records steps (evidence: `src/mqt/predictor/rl/predictorenv.py`)
- Device predictor → Figures of merit: scores circuits (evidence: `src/mqt/predictor/ml/predictor.py`)
