# rajarshitiwari/quex architecture

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

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

## Overview

Quex is a quantum-circuit construction and state-vector simulation library. Users can build circuits directly or ingest OpenQASM, then execute them with the NumPy backend and inspect the resulting state; optional JAX and CuPy backends reuse NumPy simulator logic. Circuit utilities also cover parameter binding, probabilities, sampling, cutting, random circuit generation, and visualization. The README describes hardware-aware dispatch and QIR ingestion as roadmap items; no implemented dispatcher is shown. Arrows reflect the excerpts, SOURCE INDEX references, or documented behavior; visualization’s connection to Circuit is documented but not shown in source excerpts.

Main entry points: [`src/quex/circuit.py`](https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py) (Circuit model), [`src/quex/backends/numpy_sim.py`](https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/numpy_sim.py) (NumPy simulator), [`src/quex/parser.py`](https://github.com/rajarshitiwari/quex/blob/main/src/quex/parser.py) (QASM parser), [`src/quex/qrandom.py`](https://github.com/rajarshitiwari/quex/blob/main/src/quex/qrandom.py) (Random circuits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and construction"]
  node_parser["QASM parser<br/>[parser.py]"]
  node_circuit["Circuit model<br/>[circuit.py]"]
end

subgraph group_circuit_tools["Circuit tools"]
  node_random["Random circuits<br/>[qrandom.py]"]
  node_oplist["Operation list<br/>[utils.py]"]
  node_cutting["Circuit cutting<br/>[circuit.py]"]
end

subgraph group_execution["Execution engines"]
  node_gates["Gate matrices<br/>[gates.py]"]
  node_sim_base["Simulator interface<br/>[base.py]"]
  node_numpy["NumPy simulator<br/>[numpy_sim.py]"]
  node_jax["JAX simulator<br/>[jax_sim.py]"]
  node_cupy["CuPy simulator<br/>[cupy_sim.py]"]
end

subgraph group_inspection["Results and visualization"]
  node_probabilities["Probabilities and sampling<br/>[circuit.py]"]
  node_visualization["Circuit visualization<br/>[vis.py]"]
  node_state["Final state tensor"]
end

node_user(("Circuit user"))
node_qasm["OpenQASM input"]

node_user -->|"provides"| node_qasm
node_qasm -->|"parses"| node_parser
node_parser -->|"builds operations"| node_circuit
node_user -->|"constructs"| node_circuit
node_user -->|"requests generation"| node_random
node_random -->|"adds operations"| node_circuit
node_circuit -->|"stores operations"| node_oplist
node_user -->|"requests execution"| node_circuit
node_circuit -->|"invokes run"| node_numpy
node_numpy -->|"implements"| node_sim_base
node_numpy -->|"uses gate definitions"| node_gates
node_numpy -->|"reads operations"| node_circuit
node_numpy -->|"returns state"| node_state
node_jax -->|"inherits execution"| node_numpy
node_cupy -->|"inherits execution"| node_numpy
node_circuit -->|"computes results"| node_probabilities
node_circuit -->|"supports cutting"| node_cutting
node_circuit -.->|"visualizes topology"| node_visualization
node_user -->|"requests drawing"| node_visualization

click node_parser "https://github.com/rajarshitiwari/quex/blob/main/src/quex/parser.py"
click node_circuit "https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py"
click node_gates "https://github.com/rajarshitiwari/quex/blob/main/src/quex/gates.py"
click node_sim_base "https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/base.py"
click node_numpy "https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/numpy_sim.py"
click node_jax "https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/jax_sim.py"
click node_cupy "https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/cupy_sim.py"
click node_random "https://github.com/rajarshitiwari/quex/blob/main/src/quex/qrandom.py"
click node_oplist "https://github.com/rajarshitiwari/quex/blob/main/src/quex/utils.py"
click node_probabilities "https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py"
click node_cutting "https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py"
click node_visualization "https://github.com/rajarshitiwari/quex/blob/main/src/quex/vis.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_parser,node_circuit,node_user toneBlue
class node_random,node_oplist,node_cutting toneAmber
class node_gates,node_sim_base,node_numpy,node_jax,node_cupy toneMint
class node_probabilities,node_visualization,node_state toneRose
class node_qasm toneIndigo
```

## Components

### Ingestion and construction

- [QASM parser](https://github.com/rajarshitiwari/quex/blob/main/src/quex/parser.py): `src/quex/parser.py`
- [Circuit model](https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py): `src/quex/circuit.py`

### Circuit tools

- [Random circuits](https://github.com/rajarshitiwari/quex/blob/main/src/quex/qrandom.py): `src/quex/qrandom.py`
- [Operation list](https://github.com/rajarshitiwari/quex/blob/main/src/quex/utils.py): `src/quex/utils.py`
- [Circuit cutting](https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py): `src/quex/circuit.py`

### Execution engines

- [Gate matrices](https://github.com/rajarshitiwari/quex/blob/main/src/quex/gates.py): `src/quex/gates.py`
- [Simulator interface](https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/base.py): `src/quex/backends/base.py`
- [NumPy simulator](https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/numpy_sim.py): `src/quex/backends/numpy_sim.py`
- [JAX simulator](https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/jax_sim.py): `src/quex/backends/jax_sim.py`
- [CuPy simulator](https://github.com/rajarshitiwari/quex/blob/main/src/quex/backends/cupy_sim.py): `src/quex/backends/cupy_sim.py`

### Results and visualization

- [Probabilities and sampling](https://github.com/rajarshitiwari/quex/blob/main/src/quex/circuit.py): `src/quex/circuit.py`
- [Circuit visualization](https://github.com/rajarshitiwari/quex/blob/main/src/quex/vis.py): `src/quex/vis.py`
- **Final state tensor**

### Other components

- **Circuit user**
- **OpenQASM input**

## Connections

- Circuit user → OpenQASM input: provides (evidence: `README.md`)
- OpenQASM input → QASM parser: parses (evidence: `README.md`)
- QASM parser → Circuit model: builds operations (evidence: `src/quex/circuit.py`)
- Circuit user → Circuit model: constructs (evidence: `README.md`)
- Circuit user → Random circuits: requests generation (evidence: `src/quex/qrandom.py`)
- Random circuits → Circuit model: adds operations (evidence: `src/quex/qrandom.py`)
- Circuit model → Operation list: stores operations (evidence: `src/quex/circuit.py`)
- Circuit user → Circuit model: requests execution (evidence: `README.md`)
- Circuit model → NumPy simulator: invokes run (evidence: `src/quex/circuit.py`)
- NumPy simulator → Simulator interface: implements (evidence: `src/quex/backends/numpy_sim.py`)
- NumPy simulator → Gate matrices: uses gate definitions (evidence: `src/quex/backends/numpy_sim.py`)
- NumPy simulator → Circuit model: reads operations (evidence: `src/quex/backends/numpy_sim.py`)
- NumPy simulator → Final state tensor: returns state (evidence: `src/quex/backends/numpy_sim.py`)
- JAX simulator → NumPy simulator: inherits execution (evidence: `src/quex/backends/jax_sim.py`)
- CuPy simulator → NumPy simulator: inherits execution (evidence: `src/quex/backends/cupy_sim.py`)
- Circuit model → Probabilities and sampling: computes results (evidence: `src/quex/circuit.py`)
- Circuit model → Circuit cutting: supports cutting (evidence: `src/quex/circuit.py`)
- Circuit model → Circuit visualization: visualizes topology
- Circuit user → Circuit visualization: requests drawing (evidence: `src/quex/vis.py`)
