# flagos-ai/flagquantum architecture

> Architecture diagram of the GitHub repository flagos-ai/flagquantum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flagos-ai/flagquantum
- Repository: https://github.com/flagos-ai/flagquantum

## Overview

FlagQuantum is a PyTorch-first framework for differentiable quantum computing. Its principal workflow is to define a circuit and requested observable, train circuit parameters, then evaluate the trained circuit through a selected local or remote target and inspect the result. The repository also includes compiler and execution-planning layers, several simulation representations, hardware/provider integrations, QPU digital twins, and quantum-error-correction research tools. Some execution and integration internals were not sampled, so those connections are shown only where documented or are marked unverified.

Main entry points: [`flagquantum/runtime/execution_plan.py`](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/execution_plan.py) (Execution planning), [`flagquantum/_api.py`](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/_api.py) (Public run API), [`flagquantum/circuit.py`](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/circuit.py) (Circuit API), [`flagquantum/simulation/statevector/local.py`](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/statevector/local.py) (Statevector simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Circuit authoring"]
  node_circuit["Circuit API<br/>[circuit.py]"]
  node_ir["Circuit IR<br/>[ir.py]"]
  node_observables["Observable requests<br/>[__init__.py]"]
  node_training["PyTorch training<br/>[training.py]"]
end

subgraph group_runtime["Execution runtime"]
  node_public_api["Public run API<br/>[_api.py]"]
  node_planning["Execution planning<br/>[execution_plan.py]"]
  node_compiler["Circuit compiler<br/>[pipeline.py]"]
  node_result["Execution result<br/>[result.py]"]
end

subgraph group_targets["Execution targets"]
  node_statevector["Statevector simulation<br/>[local.py]"]
  node_tensor_network["Tensor-network simulation<br/>[models.py]"]
  node_mps["MPS simulation<br/>[entrypoints.py]"]
  node_distributed["Distributed training<br/>[training_engine.py]"]
  node_compute["Compute runtimes<br/>[registry.py]"]
  node_remote_compute["Jiuding workspace<br/>[jiuding.py]"]
  node_qpu["Remote QPU<br/>[execution.py]"]
  node_ecosystem["SDK adapters<br/>[registry.py]"]
end

subgraph group_research["Research capabilities"]
  node_qec["Error correction<br/>[circuit.py]"]
  node_twin["QPU digital twins<br/>[candidate.py]"]
  node_algorithms["Quantum algorithms"]
end

node_user(("Quantum developer"))

node_user -->|"defines circuit"| node_circuit
node_user -->|"chooses outputs"| node_observables
node_circuit -->|"records operations"| node_ir
node_circuit -->|"initializes state"| node_statevector
node_user -->|"trains model"| node_training
node_user -->|"runs circuit"| node_public_api
node_public_api -.->|"returns result"| node_result
node_public_api -.->|"plans execution"| node_planning
node_public_api -.->|"compiles circuit"| node_compiler
node_planning -.->|"selects simulator"| node_statevector
node_planning -.->|"selects simulator"| node_tensor_network
node_planning -.->|"selects simulator"| node_mps
node_planning -.->|"selects target"| node_remote_compute
node_planning -.->|"selects target"| node_qpu
node_compute -.->|"provides runtime"| node_distributed
node_user -->|"requests simulation"| node_remote_compute
node_user -->|"requests hardware run"| node_qpu
node_user -->|"explores QEC"| node_qec
node_user -->|"compares device data"| node_twin
node_user -.->|"uses algorithms"| node_algorithms
node_user -.->|"uses SDK adapters"| node_ecosystem

click node_circuit "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/circuit.py"
click node_ir "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/core/ir.py"
click node_observables "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/observables/__init__.py"
click node_training "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/training.py"
click node_public_api "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/_api.py"
click node_planning "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/execution_plan.py"
click node_compiler "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/compiler/pipeline.py"
click node_result "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/result.py"
click node_statevector "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/statevector/local.py"
click node_tensor_network "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/tensor_network/models.py"
click node_mps "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/mps/entrypoints.py"
click node_distributed "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/executors/mps/training_engine.py"
click node_compute "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/compute/registry.py"
click node_remote_compute "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/remote/compute/jiuding.py"
click node_qpu "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/remote/qpu/execution.py"
click node_ecosystem "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/ecosystem/registry.py"
click node_qec "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/qec/circuit.py"
click node_twin "https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/twin/candidate.py"
click node_algorithms "https://github.com/flagos-ai/flagquantum/tree/main/flagquantum/algorithms"

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_ir,node_observables,node_training toneBlue
class node_public_api,node_planning,node_compiler,node_result toneAmber
class node_statevector,node_tensor_network,node_mps,node_distributed,node_compute,node_remote_compute,node_qpu,node_ecosystem toneMint
class node_qec,node_twin,node_algorithms toneRose
class node_user toneIndigo
```

## Components

### Circuit authoring

- [Circuit API](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/circuit.py): `flagquantum/circuit.py`
- [Circuit IR](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/core/ir.py): `flagquantum/core/ir.py`
- [Observable requests](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/observables/__init__.py): `flagquantum/observables/__init__.py`
- [PyTorch training](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/training.py): `flagquantum/runtime/training.py`

### Execution runtime

- [Public run API](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/_api.py): `flagquantum/_api.py`
- [Execution planning](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/execution_plan.py): `flagquantum/runtime/execution_plan.py`
- [Circuit compiler](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/compiler/pipeline.py): `flagquantum/compiler/pipeline.py`
- [Execution result](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/result.py): `flagquantum/runtime/result.py`

### Execution targets

- [Statevector simulation](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/statevector/local.py): `flagquantum/simulation/statevector/local.py`
- [Tensor-network simulation](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/tensor_network/models.py): `flagquantum/simulation/tensor_network/models.py`
- [MPS simulation](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/simulation/mps/entrypoints.py): `flagquantum/simulation/mps/entrypoints.py`
- [Distributed training](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/runtime/executors/mps/training_engine.py): `flagquantum/runtime/executors/mps/training_engine.py`
- [Compute runtimes](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/compute/registry.py): `flagquantum/compute/registry.py`
- [Jiuding workspace](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/remote/compute/jiuding.py): `flagquantum/remote/compute/jiuding.py`
- [Remote QPU](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/remote/qpu/execution.py): `flagquantum/remote/qpu/execution.py`
- [SDK adapters](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/ecosystem/registry.py): `flagquantum/ecosystem/registry.py`

### Research capabilities

- [Error correction](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/qec/circuit.py): `flagquantum/qec/circuit.py`
- [QPU digital twins](https://github.com/flagos-ai/flagquantum/blob/main/flagquantum/twin/candidate.py): `flagquantum/twin/candidate.py`
- [Quantum algorithms](https://github.com/flagos-ai/flagquantum/tree/main/flagquantum/algorithms): `flagquantum/algorithms`

### Other components

- **Quantum developer**

## Connections

- Quantum developer → Circuit API: defines circuit (evidence: `README.md`)
- Quantum developer → Observable requests: chooses outputs (evidence: `README.md`)
- Circuit API → Circuit IR: records operations (evidence: `flagquantum/circuit.py`)
- Circuit API → Statevector simulation: initializes state (evidence: `flagquantum/circuit.py`)
- Quantum developer → PyTorch training: trains model (evidence: `README.md`)
- Quantum developer → Public run API: runs circuit (evidence: `README.md`)
- Public run API → Execution result: returns result (evidence: `flagquantum/_api.py`)
- Public run API → Execution planning: plans execution (evidence: `flagquantum/_api.py`)
- Public run API → Circuit compiler: compiles circuit
- Execution planning → Statevector simulation: selects simulator
- Execution planning → Tensor-network simulation: selects simulator
- Execution planning → MPS simulation: selects simulator
- Execution planning → Jiuding workspace: selects target
- Execution planning → Remote QPU: selects target
- Compute runtimes → Distributed training: provides runtime
- Quantum developer → Jiuding workspace: requests simulation (evidence: `README.md`)
- Quantum developer → Remote QPU: requests hardware run (evidence: `README.md`)
- Quantum developer → Error correction: explores QEC (evidence: `README.md`)
- Quantum developer → QPU digital twins: compares device data (evidence: `README.md`)
- Quantum developer → Quantum algorithms: uses algorithms
- Quantum developer → SDK adapters: uses SDK adapters