# ashiteshsingh/tpu-accelerated-quantum-jax architecture

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

- Interactive diagram: https://gitdiagram.com/ashiteshsingh/tpu-accelerated-quantum-jax
- Repository: https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax

## Overview

This repository is a JAX quantum-circuit simulator and research suite, with GPU and TPU-oriented execution paths. The main workflow is to define a circuit, simulate its state, then evaluate observables or measurements; research workloads apply that runtime to algorithms such as VQE, QAOA, and noisy-circuit studies. It also includes a separate statevector/density-matrix implementation and standalone TPU-scale, Shor, Grover, and supremacy programs. Edges are limited to relationships visible in excerpts or the README; unsampled TPU wiring is not inferred.

Main entry points: [`gpu/jax_qsim/circuit.py`](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/circuit.py) (Circuit API), [`gpu/jax_qsim/observables.py`](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/observables.py) (Observables), [`gpu/jax_qsim/core.py`](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/core.py) (State Engine), [`gpu/jax_qsim/ops.py`](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/ops.py) (Gate Operators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gpu["GPU Simulator"]
  node_gpu_circuit["Circuit API<br/>[circuit.py]"]
  node_gpu_core["State Engine<br/>[core.py]"]
  node_gpu_ops["Gate Operators<br/>[ops.py]"]
  node_gpu_noise["Noise Channels<br/>[noise.py]"]
  node_gpu_obs["Observables<br/>[observables.py]"]
end

subgraph group_research["Research Workloads"]
  node_workloads["Algorithm Studies"]
  node_plateau["Gradient Study"]
  node_scaling["GPU Scaling Study"]
  node_noisy_nisq["Noisy NISQ Study"]
  node_qaoa["QAOA MaxCut"]
  node_vqe["VQE H2"]
  node_monte_carlo["Noise Trajectories"]
  node_vqc["XOR Classifier"]
  node_ghz["GHZ Preparation"]
end

subgraph group_experiment["State Simulators"]
  node_exp_circuit["Functional Circuit<br/>[circuit.py]"]
  node_exp_gates["Gate Definitions<br/>[gates.py]"]
  node_exp_state["Statevector Runtime<br/>[statevector.py]"]
  node_exp_density["Density Matrix<br/>[density_matrix.py]"]
  node_exp_obs["Observable Types<br/>[observables.py]"]
end

subgraph group_scale["Large-Scale Runs"]
  node_tpu_suite["TPU Scale Suite"]
  node_shor["Shor Algorithm"]
  node_grover["Grover Runs"]
  node_supremacy42["42-Qubit Run"]
  node_supremacy75["75-Qubit Run"]
end

node_user(("Researcher"))

node_gpu_circuit -->|"applies gates"| node_gpu_core
node_gpu_circuit -->|"records operators"| node_gpu_ops
node_gpu_noise -->|"applies channels"| node_gpu_core
node_gpu_noise -->|"uses Kraus gates"| node_gpu_ops
node_gpu_obs -->|"applies observables"| node_gpu_core
node_gpu_obs -->|"uses Pauli gates"| node_gpu_ops
node_plateau -->|"uses circuits"| node_gpu_circuit
node_plateau -->|"evaluates observables"| node_gpu_obs
node_scaling -->|"uses state engine"| node_gpu_core
node_scaling -->|"uses operators"| node_gpu_ops
node_scaling -->|"builds circuits"| node_gpu_circuit
node_noisy_nisq -->|"uses state engine"| node_gpu_core
node_noisy_nisq -->|"uses operators"| node_gpu_ops
node_noisy_nisq -->|"uses channels"| node_gpu_noise
node_qaoa -->|"builds circuits"| node_gpu_circuit
node_qaoa -->|"evaluates observables"| node_gpu_obs
node_qaoa -->|"uses state engine"| node_gpu_core
node_vqe -->|"builds circuits"| node_gpu_circuit
node_vqe -->|"evaluates observables"| node_gpu_obs
node_monte_carlo -->|"uses operators"| node_gpu_ops
node_monte_carlo -->|"uses channels"| node_gpu_noise
node_monte_carlo -->|"evaluates observables"| node_gpu_obs
node_vqc -->|"evaluates observables"| node_gpu_obs
node_ghz -.->|"uses simulator API"| node_gpu_circuit
node_exp_circuit -->|"constructs gates"| node_exp_gates
node_exp_circuit -->|"runs statevector"| node_exp_state
node_exp_circuit -->|"runs density matrix"| node_exp_density
node_exp_density -->|"reuses gate application"| node_exp_state
node_exp_density -->|"builds channels"| node_exp_gates
node_exp_density -->|"uses observable types"| node_exp_obs
node_exp_state -->|"applies Pauli gates"| node_exp_gates
node_exp_state -->|"evaluates observables"| node_exp_obs
node_user -.->|"defines circuit"| node_gpu_circuit
node_user -->|"runs scaling suite"| node_tpu_suite
node_tpu_suite -.->|"executes distributed simulation"| node_gpu_core
node_user -.->|"runs algorithm"| node_shor
node_user -.->|"runs search"| node_grover
node_user -.->|"runs workload"| node_supremacy42
node_user -.->|"runs workload"| node_supremacy75

click node_gpu_circuit "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/circuit.py"
click node_gpu_core "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/core.py"
click node_gpu_ops "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/ops.py"
click node_gpu_noise "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/noise.py"
click node_gpu_obs "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/observables.py"
click node_workloads "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/tree/main/gpu/quantum_research"
click node_plateau "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/barren_plateau_gradient_vanishing.py"
click node_scaling "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py"
click node_noisy_nisq "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/noisy_nisq_circuit_simulation.py"
click node_qaoa "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py"
click node_vqe "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/variational_quantum_eigensolver_h2.py"
click node_monte_carlo "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/quantum_noise_simulation_monte_carlo.py"
click node_vqc "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/variational_quantum_classifier_xor.py"
click node_ghz "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/ghz_state_preparation.py"
click node_exp_circuit "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/circuit.py"
click node_exp_gates "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/gates.py"
click node_exp_state "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/statevector.py"
click node_exp_density "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/density_matrix.py"
click node_exp_obs "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/observables.py"
click node_tpu_suite "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/tpu/tpu_quantum_scale.py"
click node_shor "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/shors/shors_algorithm_33q.py"
click node_grover "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/tree/main/grover_simulation"
click node_supremacy42 "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/supremacy_42_tpu.py"
click node_supremacy75 "https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/supremacy_75_tpu.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_gpu_circuit,node_gpu_core,node_gpu_ops,node_gpu_noise,node_gpu_obs toneBlue
class node_workloads,node_plateau,node_scaling,node_noisy_nisq,node_qaoa,node_vqe,node_monte_carlo,node_vqc,node_ghz toneAmber
class node_exp_circuit,node_exp_gates,node_exp_state,node_exp_density,node_exp_obs toneMint
class node_tpu_suite,node_shor,node_grover,node_supremacy42,node_supremacy75 toneRose
class node_user toneIndigo
```

## Components

### GPU Simulator

- [Circuit API](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/circuit.py): `gpu/jax_qsim/circuit.py`
- [State Engine](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/core.py): `gpu/jax_qsim/core.py`
- [Gate Operators](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/ops.py): `gpu/jax_qsim/ops.py`
- [Noise Channels](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/noise.py): `gpu/jax_qsim/noise.py`
- [Observables](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/jax_qsim/observables.py): `gpu/jax_qsim/observables.py`

### Research Workloads

- [Algorithm Studies](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/tree/main/gpu/quantum_research): `gpu/quantum_research`
- [Gradient Study](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/barren_plateau_gradient_vanishing.py): `gpu/quantum_research/barren_plateau_gradient_vanishing.py`
- [GPU Scaling Study](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py): `gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py`
- [Noisy NISQ Study](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/noisy_nisq_circuit_simulation.py): `gpu/quantum_research/noisy_nisq_circuit_simulation.py`
- [QAOA MaxCut](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py): `gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py`
- [VQE H2](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/variational_quantum_eigensolver_h2.py): `gpu/quantum_research/variational_quantum_eigensolver_h2.py`
- [Noise Trajectories](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/quantum_noise_simulation_monte_carlo.py): `gpu/quantum_research/quantum_noise_simulation_monte_carlo.py`
- [XOR Classifier](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/variational_quantum_classifier_xor.py): `gpu/quantum_research/variational_quantum_classifier_xor.py`
- [GHZ Preparation](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/gpu/quantum_research/ghz_state_preparation.py): `gpu/quantum_research/ghz_state_preparation.py`

### State Simulators

- [Functional Circuit](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/circuit.py): `experiment/jax_qsim/circuit.py`
- [Gate Definitions](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/gates.py): `experiment/jax_qsim/gates.py`
- [Statevector Runtime](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/statevector.py): `experiment/jax_qsim/statevector.py`
- [Density Matrix](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/density_matrix.py): `experiment/jax_qsim/density_matrix.py`
- [Observable Types](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/experiment/jax_qsim/observables.py): `experiment/jax_qsim/observables.py`

### Large-Scale Runs

- [TPU Scale Suite](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/tpu/tpu_quantum_scale.py): `tpu/tpu_quantum_scale.py`
- [Shor Algorithm](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/shors/shors_algorithm_33q.py): `shors/shors_algorithm_33q.py`
- [Grover Runs](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/tree/main/grover_simulation): `grover_simulation`
- [42-Qubit Run](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/supremacy_42_tpu.py): `supremacy_42_tpu.py`
- [75-Qubit Run](https://github.com/ashiteshsingh/tpu-accelerated-quantum-jax/blob/main/supremacy_75_tpu.py): `supremacy_75_tpu.py`

### Other components

- **Researcher**

## Connections

- Circuit API → State Engine: applies gates (evidence: `gpu/jax_qsim/circuit.py`)
- Circuit API → Gate Operators: records operators (evidence: `gpu/jax_qsim/circuit.py`)
- Noise Channels → State Engine: applies channels (evidence: `gpu/jax_qsim/noise.py`)
- Noise Channels → Gate Operators: uses Kraus gates (evidence: `gpu/jax_qsim/noise.py`)
- Observables → State Engine: applies observables (evidence: `gpu/jax_qsim/observables.py`)
- Observables → Gate Operators: uses Pauli gates (evidence: `gpu/jax_qsim/observables.py`)
- Gradient Study → Circuit API: uses circuits (evidence: `gpu/quantum_research/barren_plateau_gradient_vanishing.py`)
- Gradient Study → Observables: evaluates observables (evidence: `gpu/quantum_research/barren_plateau_gradient_vanishing.py`)
- GPU Scaling Study → State Engine: uses state engine (evidence: `gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py`)
- GPU Scaling Study → Gate Operators: uses operators (evidence: `gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py`)
- GPU Scaling Study → Circuit API: builds circuits (evidence: `gpu/quantum_research/gpu_vram_and_qubit_scaling_benchmark.py`)
- Noisy NISQ Study → State Engine: uses state engine (evidence: `gpu/quantum_research/noisy_nisq_circuit_simulation.py`)
- Noisy NISQ Study → Gate Operators: uses operators (evidence: `gpu/quantum_research/noisy_nisq_circuit_simulation.py`)
- Noisy NISQ Study → Noise Channels: uses channels (evidence: `gpu/quantum_research/noisy_nisq_circuit_simulation.py`)
- QAOA MaxCut → Circuit API: builds circuits (evidence: `gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py`)
- QAOA MaxCut → Observables: evaluates observables (evidence: `gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py`)
- QAOA MaxCut → State Engine: uses state engine (evidence: `gpu/quantum_research/quantum_approximate_optimization_algorithm_maxcut.py`)
- VQE H2 → Circuit API: builds circuits (evidence: `gpu/quantum_research/variational_quantum_eigensolver_h2.py`)
- VQE H2 → Observables: evaluates observables (evidence: `gpu/quantum_research/variational_quantum_eigensolver_h2.py`)
- Noise Trajectories → Gate Operators: uses operators (evidence: `gpu/quantum_research/quantum_noise_simulation_monte_carlo.py`)
- Noise Trajectories → Noise Channels: uses channels (evidence: `gpu/quantum_research/quantum_noise_simulation_monte_carlo.py`)
- Noise Trajectories → Observables: evaluates observables (evidence: `gpu/quantum_research/quantum_noise_simulation_monte_carlo.py`)
- XOR Classifier → Observables: evaluates observables (evidence: `gpu/quantum_research/variational_quantum_classifier_xor.py`)
- GHZ Preparation → Circuit API: uses simulator API (evidence: `gpu/quantum_research/ghz_state_preparation.py`)
- Functional Circuit → Gate Definitions: constructs gates (evidence: `experiment/jax_qsim/circuit.py`)
- Functional Circuit → Statevector Runtime: runs statevector (evidence: `experiment/jax_qsim/circuit.py`)
- Functional Circuit → Density Matrix: runs density matrix (evidence: `experiment/jax_qsim/circuit.py`)
- Density Matrix → Statevector Runtime: reuses gate application (evidence: `experiment/jax_qsim/density_matrix.py`)
- Density Matrix → Gate Definitions: builds channels (evidence: `experiment/jax_qsim/density_matrix.py`)
- Density Matrix → Observable Types: uses observable types (evidence: `experiment/jax_qsim/density_matrix.py`)
- Statevector Runtime → Gate Definitions: applies Pauli gates (evidence: `experiment/jax_qsim/statevector.py`)
- Statevector Runtime → Observable Types: evaluates observables (evidence: `experiment/jax_qsim/statevector.py`)
- Researcher → Circuit API: defines circuit
- Researcher → TPU Scale Suite: runs scaling suite (evidence: `README.md`)
- TPU Scale Suite → State Engine: executes distributed simulation
- Researcher → Shor Algorithm: runs algorithm
- Researcher → Grover Runs: runs search
- Researcher → 42-Qubit Run: runs workload
- Researcher → 75-Qubit Run: runs workload
