# dr206/quantum-circuit-simulator architecture

> Architecture diagram of the GitHub repository dr206/quantum-circuit-simulator, 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/dr206/quantum-circuit-simulator
- Repository: https://github.com/dr206/quantum-circuit-simulator

## Overview

This Python package simulates circuit-based quantum programs: a caller supplies an initial state and gate program, circuit execution constructs and applies each gate operator, then experiment functions sample measurement outcomes and aggregate shot counts. Gate definitions and the shared logarithm helper support those stages. The README also documents variational-algorithm examples, represented by the notebook. Edges reflect the sampled calls or README statements; the notebook’s internal implementation was not sampled.

Main entry points: [`quantumcircuitsimulator/circuit.py`](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py) (Program runner), [`quantumcircuitsimulator/experiment.py`](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/experiment.py) (Single measurement), [`quantumcircuitsimulator/utils.py`](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/utils.py) (Log helper), [`jupyter/Variational_Quantum_Algorithm.ipynb`](https://github.com/dr206/quantum-circuit-simulator/blob/main/jupyter/Variational_Quantum_Algorithm.ipynb) (Variational example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Circuit execution"]
  node_ground_state["Ground state<br/>[circuit.py]"]
  node_program_runner["Program runner<br/>[circuit.py]"]
  node_operator_builder["Operator builder<br/>[circuit.py]"]
  node_state_vector["State evolution<br/>[circuit.py]"]
  node_log_helper["Log helper<br/>[utils.py]"]
end

subgraph group_gate_system["Gate system"]
  node_gate_catalog["Gate catalog<br/>[gates.py]"]
  node_parametric_gates["Parametric gates<br/>[gates.py]"]
end

subgraph group_measurement["Measurement"]
  node_single_measurement["Single measurement<br/>[experiment.py]"]
  node_shot_counts["Shot counts<br/>[experiment.py]"]
end

node_caller(("Simulator user"))
node_variational_example["Variational example"]

node_caller -.->|"requests initialization"| node_ground_state
node_caller -.->|"provides program"| node_program_runner
node_caller -.->|"requests measurement"| node_single_measurement
node_caller -.->|"requests shots"| node_shot_counts
node_program_runner -->|"builds operators"| node_operator_builder
node_program_runner -->|"calculates qubits"| node_log_helper
node_program_runner -->|"updates state"| node_state_vector
node_operator_builder -->|"looks up gates"| node_gate_catalog
node_operator_builder -->|"evaluates parameters"| node_parametric_gates
node_single_measurement -->|"formats outcome"| node_log_helper
node_shot_counts -->|"samples repeatedly"| node_single_measurement
node_variational_example -.->|"uses package"| node_program_runner

click node_ground_state "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py"
click node_program_runner "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py"
click node_operator_builder "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py"
click node_state_vector "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py"
click node_gate_catalog "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/gates.py"
click node_parametric_gates "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/gates.py"
click node_log_helper "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/utils.py"
click node_single_measurement "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/experiment.py"
click node_shot_counts "https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/experiment.py"
click node_variational_example "https://github.com/dr206/quantum-circuit-simulator/blob/main/jupyter/Variational_Quantum_Algorithm.ipynb"

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_ground_state,node_program_runner,node_operator_builder,node_state_vector,node_log_helper,node_caller toneBlue
class node_gate_catalog,node_parametric_gates toneAmber
class node_single_measurement,node_shot_counts toneMint
class node_variational_example toneTeal
```

## Components

### Circuit execution

- [Ground state](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py): `quantumcircuitsimulator/circuit.py`
- [Program runner](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py): `quantumcircuitsimulator/circuit.py`
- [Operator builder](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py): `quantumcircuitsimulator/circuit.py`
- [State evolution](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/circuit.py): `quantumcircuitsimulator/circuit.py`
- [Log helper](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/utils.py): `quantumcircuitsimulator/utils.py`

### Gate system

- [Gate catalog](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/gates.py): `quantumcircuitsimulator/gates.py`
- [Parametric gates](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/gates.py): `quantumcircuitsimulator/gates.py`

### Measurement

- [Single measurement](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/experiment.py): `quantumcircuitsimulator/experiment.py`
- [Shot counts](https://github.com/dr206/quantum-circuit-simulator/blob/main/quantumcircuitsimulator/experiment.py): `quantumcircuitsimulator/experiment.py`

### Other components

- **Simulator user**
- [Variational example](https://github.com/dr206/quantum-circuit-simulator/blob/main/jupyter/Variational_Quantum_Algorithm.ipynb): `jupyter/Variational_Quantum_Algorithm.ipynb`

## Connections

- Simulator user → Ground state: requests initialization
- Simulator user → Program runner: provides program
- Simulator user → Single measurement: requests measurement
- Simulator user → Shot counts: requests shots
- Program runner → Operator builder: builds operators (evidence: `quantumcircuitsimulator/circuit.py`)
- Program runner → Log helper: calculates qubits (evidence: `quantumcircuitsimulator/circuit.py`)
- Program runner → State evolution: updates state (evidence: `quantumcircuitsimulator/circuit.py`)
- Operator builder → Gate catalog: looks up gates (evidence: `quantumcircuitsimulator/circuit.py`)
- Operator builder → Parametric gates: evaluates parameters (evidence: `quantumcircuitsimulator/circuit.py`)
- Single measurement → Log helper: formats outcome (evidence: `quantumcircuitsimulator/experiment.py`)
- Shot counts → Single measurement: samples repeatedly (evidence: `quantumcircuitsimulator/experiment.py`)
- Variational example → Program runner: uses package
