# songhaotian694-oss/cpp-quantum-circuit-simulator architecture

> Architecture diagram of the GitHub repository songhaotian694-oss/cpp-quantum-circuit-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/songhaotian694-oss/cpp-quantum-circuit-simulator
- Repository: https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator

## Overview

This is a small C++ state-vector quantum-circuit simulator, with command-line access to Deutsch’s algorithm and library implementations of Deutsch and Deutsch–Jozsa. The workflow accepts an oracle choice, builds a circuit, simulates its gates on a quantum state, and reports probabilities and the inferred function class. Gate operations are the internal execution layer. The tree documents optimization as a goal, but its optimizer directories contain only placeholders, so no optimizer behavior is mapped.

Main entry points: [`src/core/Simulator.cpp`](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Simulator.cpp) (Simulator), [`src/algorithms/Deutsch.cpp`](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/Deutsch.cpp) (Deutsch), [`app/cli/main.cpp`](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/app/cli/main.cpp) (CLI demo), [`src/algorithms/DeutschJozsa.cpp`](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/DeutschJozsa.cpp) (Deutsch–Jozsa)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI demo<br/>[main.cpp]"]
end

subgraph group_algorithms["Quantum algorithms"]
  node_deutsch["Deutsch<br/>[Deutsch.cpp]"]
  node_dj["Deutsch–Jozsa<br/>[DeutschJozsa.cpp]"]
end

subgraph group_simulation["Simulation core"]
  node_circuit["Circuit<br/>[Circuit.cpp]"]
  node_gate_model["Gate model<br/>[Gate.cpp]"]
  node_simulator["Simulator<br/>[Simulator.cpp]"]
  node_state["Quantum state<br/>[QuantumState.cpp]"]
end

subgraph group_gates["Gate operations"]
  node_single_gate["Single-qubit gates"]
  node_controlled_gate["Controlled gates<br/>[ControlledGate.cpp]"]
end

node_user(("User"))

node_user -->|"chooses oracle"| node_cli
node_cli -->|"calls algorithm"| node_deutsch
node_deutsch -->|"adds gates"| node_circuit
node_deutsch -->|"creates gates"| node_gate_model
node_dj -->|"adds gates"| node_circuit
node_dj -->|"creates gates"| node_gate_model
node_deutsch -->|"runs circuit"| node_simulator
node_dj -->|"runs circuit"| node_simulator
node_simulator -->|"reads gates"| node_circuit
node_simulator -->|"creates state"| node_state
node_simulator -->|"dispatches gates"| node_single_gate
node_simulator -->|"dispatches gates"| node_controlled_gate
node_single_gate -->|"mutates amplitudes"| node_state
node_controlled_gate -->|"mutates amplitudes"| node_state
node_deutsch -->|"returns result"| node_cli
node_cli -->|"prints result"| node_user

click node_cli "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/app/cli/main.cpp"
click node_deutsch "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/Deutsch.cpp"
click node_dj "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/DeutschJozsa.cpp"
click node_circuit "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Circuit.cpp"
click node_gate_model "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Gate.cpp"
click node_simulator "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Simulator.cpp"
click node_state "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/QuantumState.cpp"
click node_single_gate "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/gates/SingleQubitGate.cpp"
click node_controlled_gate "https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/gates/ControlledGate.cpp"

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_cli,node_user toneBlue
class node_deutsch,node_dj toneAmber
class node_circuit,node_gate_model,node_simulator,node_state toneMint
class node_single_gate,node_controlled_gate toneRose
```

## Components

### User interface

- [CLI demo](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/app/cli/main.cpp): `app/cli/main.cpp`

### Quantum algorithms

- [Deutsch](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/Deutsch.cpp): `src/algorithms/Deutsch.cpp`
- [Deutsch–Jozsa](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/algorithms/DeutschJozsa.cpp): `src/algorithms/DeutschJozsa.cpp`

### Simulation core

- [Circuit](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Circuit.cpp): `src/core/Circuit.cpp`
- [Gate model](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Gate.cpp): `src/core/Gate.cpp`
- [Simulator](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/Simulator.cpp): `src/core/Simulator.cpp`
- [Quantum state](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/core/QuantumState.cpp): `src/core/QuantumState.cpp`

### Gate operations

- [Single-qubit gates](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/gates/SingleQubitGate.cpp): `src/gates/SingleQubitGate.cpp`
- [Controlled gates](https://github.com/songhaotian694-oss/cpp-quantum-circuit-simulator/blob/main/src/gates/ControlledGate.cpp): `src/gates/ControlledGate.cpp`

### Other components

- **User**

## Connections

- User → CLI demo: chooses oracle
- CLI demo → Deutsch: calls algorithm
- Deutsch → Circuit: adds gates
- Deutsch → Gate model: creates gates
- Deutsch–Jozsa → Circuit: adds gates
- Deutsch–Jozsa → Gate model: creates gates
- Deutsch → Simulator: runs circuit
- Deutsch–Jozsa → Simulator: runs circuit
- Simulator → Circuit: reads gates
- Simulator → Quantum state: creates state
- Simulator → Single-qubit gates: dispatches gates
- Simulator → Controlled gates: dispatches gates
- Single-qubit gates → Quantum state: mutates amplitudes
- Controlled gates → Quantum state: mutates amplitudes
- Deutsch → CLI demo: returns result
- CLI demo → User: prints result