# ichec/quex architecture

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

- Interactive diagram: https://gitdiagram.com/ichec/quex
- Repository: https://github.com/ichec/quex

## Overview

Quex is a quantum-circuit construction and state-vector simulation library. The principal workflow is to create a circuit from OpenQASM or operations, attach a simulator, and run it to obtain a state tensor; circuits also support parameter binding and topology visualization, while random circuit generators provide an alternate construction path. The README describes hardware dispatch as work in progress, rather than an implemented runtime stage. Relationships below use excerpts, the source index, or README statements; unsampled implementation details are not inferred.

Main entry points: [`src/quex/__init__.py`](https://github.com/ichec/quex/blob/main/src/quex/__init__.py) (Quex API), [`src/quex/backends/numpy_sim.py`](https://github.com/ichec/quex/blob/main/src/quex/backends/numpy_sim.py) (NumPy Simulator), [`src/quex/circuit.py`](https://github.com/ichec/quex/blob/main/src/quex/circuit.py) (Circuit Model), [`src/quex/backends/jax_sim.py`](https://github.com/ichec/quex/blob/main/src/quex/backends/jax_sim.py) (JAX Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_circuit["Circuit Model"]
  node_qasm_parser["OpenQASM Parser<br/>[parser.py]"]
  node_circuit_model["Circuit Model<br/>[circuit.py]"]
  node_operation_list["Operation Cache List<br/>[utils.py]"]
end

subgraph group_execution["Simulation"]
  node_gate_matrices["Gate Matrices<br/>[gates.py]"]
  node_simulator_base["Simulator Base<br/>[base.py]"]
  node_numpy_sim["NumPy Simulator<br/>[numpy_sim.py]"]
  node_jax_sim["JAX Simulator<br/>[jax_sim.py]"]
  node_cupy_sim["CuPy Simulator<br/>[cupy_sim.py]"]
  node_hardware_dispatch["Hardware Dispatcher"]
  node_state_result["State Tensor"]
end

subgraph group_tools["Circuit Tools"]
  node_random_circuits["Random Circuits<br/>[qrandom.py]"]
  node_visualization["Circuit Visualization<br/>[vis.py]"]
end

subgraph group_api["Public API"]
  node_public_api["Quex API<br/>[__init__.py]"]
end

node_user(("Circuit User"))

node_user -->|"uses"| node_public_api
node_public_api -->|"exports"| node_circuit_model
node_public_api -->|"exports"| node_qasm_parser
node_public_api -->|"exports"| node_numpy_sim
node_public_api -->|"exports"| node_jax_sim
node_public_api -->|"exports"| node_cupy_sim
node_public_api -->|"exports"| node_random_circuits
node_public_api -->|"exports"| node_visualization
node_circuit_model -->|"parses through"| node_qasm_parser
node_circuit_model -->|"stores operations in"| node_operation_list
node_circuit_model -->|"calls run"| node_simulator_base
node_numpy_sim -->|"implements"| node_simulator_base
node_numpy_sim -->|"uses gates"| node_gate_matrices
node_jax_sim -->|"extends"| node_numpy_sim
node_cupy_sim -->|"extends"| node_numpy_sim
node_random_circuits -->|"builds circuits"| node_circuit_model
node_numpy_sim -->|"returns state"| node_state_result
node_user -->|"views topology"| node_visualization
node_user -.->|"awaits routing"| node_hardware_dispatch

click node_public_api "https://github.com/ichec/quex/blob/main/src/quex/__init__.py"
click node_qasm_parser "https://github.com/ichec/quex/blob/main/src/quex/parser.py"
click node_circuit_model "https://github.com/ichec/quex/blob/main/src/quex/circuit.py"
click node_operation_list "https://github.com/ichec/quex/blob/main/src/quex/utils.py"
click node_gate_matrices "https://github.com/ichec/quex/blob/main/src/quex/gates.py"
click node_simulator_base "https://github.com/ichec/quex/blob/main/src/quex/backends/base.py"
click node_numpy_sim "https://github.com/ichec/quex/blob/main/src/quex/backends/numpy_sim.py"
click node_jax_sim "https://github.com/ichec/quex/blob/main/src/quex/backends/jax_sim.py"
click node_cupy_sim "https://github.com/ichec/quex/blob/main/src/quex/backends/cupy_sim.py"
click node_random_circuits "https://github.com/ichec/quex/blob/main/src/quex/qrandom.py"
click node_visualization "https://github.com/ichec/quex/blob/main/src/quex/vis.py"
click node_hardware_dispatch "https://github.com/ichec/quex/tree/main/src/quex/backends"

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_qasm_parser,node_circuit_model,node_operation_list,node_user toneBlue
class node_gate_matrices,node_simulator_base,node_numpy_sim,node_jax_sim,node_cupy_sim,node_hardware_dispatch,node_state_result toneAmber
class node_random_circuits,node_visualization toneMint
class node_public_api toneRose
```

## Components

### Circuit Model

- [OpenQASM Parser](https://github.com/ichec/quex/blob/main/src/quex/parser.py): `src/quex/parser.py`
- [Circuit Model](https://github.com/ichec/quex/blob/main/src/quex/circuit.py): `src/quex/circuit.py`
- [Operation Cache List](https://github.com/ichec/quex/blob/main/src/quex/utils.py): `src/quex/utils.py`

### Simulation

- [Gate Matrices](https://github.com/ichec/quex/blob/main/src/quex/gates.py): `src/quex/gates.py`
- [Simulator Base](https://github.com/ichec/quex/blob/main/src/quex/backends/base.py): `src/quex/backends/base.py`
- [NumPy Simulator](https://github.com/ichec/quex/blob/main/src/quex/backends/numpy_sim.py): `src/quex/backends/numpy_sim.py`
- [JAX Simulator](https://github.com/ichec/quex/blob/main/src/quex/backends/jax_sim.py): `src/quex/backends/jax_sim.py`
- [CuPy Simulator](https://github.com/ichec/quex/blob/main/src/quex/backends/cupy_sim.py): `src/quex/backends/cupy_sim.py`
- [Hardware Dispatcher](https://github.com/ichec/quex/tree/main/src/quex/backends): `src/quex/backends`
- **State Tensor**

### Circuit Tools

- [Random Circuits](https://github.com/ichec/quex/blob/main/src/quex/qrandom.py): `src/quex/qrandom.py`
- [Circuit Visualization](https://github.com/ichec/quex/blob/main/src/quex/vis.py): `src/quex/vis.py`

### Public API

- [Quex API](https://github.com/ichec/quex/blob/main/src/quex/__init__.py): `src/quex/__init__.py`

### Other components

- **Circuit User**

## Connections

- Circuit User → Quex API: uses (evidence: `README.md`)
- Quex API → Circuit Model: exports (evidence: `src/quex/__init__.py`)
- Quex API → OpenQASM Parser: exports (evidence: `src/quex/__init__.py`)
- Quex API → NumPy Simulator: exports (evidence: `src/quex/__init__.py`)
- Quex API → JAX Simulator: exports (evidence: `src/quex/__init__.py`)
- Quex API → CuPy Simulator: exports (evidence: `src/quex/__init__.py`)
- Quex API → Random Circuits: exports (evidence: `src/quex/__init__.py`)
- Quex API → Circuit Visualization: exports (evidence: `src/quex/__init__.py`)
- Circuit Model → OpenQASM Parser: parses through (evidence: `src/quex/circuit.py`)
- Circuit Model → Operation Cache List: stores operations in (evidence: `src/quex/circuit.py`)
- Circuit Model → Simulator Base: calls run (evidence: `src/quex/circuit.py`)
- NumPy Simulator → Simulator Base: implements (evidence: `src/quex/backends/numpy_sim.py`)
- NumPy Simulator → Gate Matrices: uses gates (evidence: `src/quex/backends/numpy_sim.py`)
- JAX Simulator → NumPy Simulator: extends (evidence: `src/quex/backends/jax_sim.py`)
- CuPy Simulator → NumPy Simulator: extends (evidence: `src/quex/backends/cupy_sim.py`)
- Random Circuits → Circuit Model: builds circuits (evidence: `src/quex/qrandom.py`)
- NumPy Simulator → State Tensor: returns state (evidence: `README.md`)
- Circuit User → Circuit Visualization: views topology (evidence: `README.md`)
- Circuit User → Hardware Dispatcher: awaits routing (evidence: `README.md`)
