# pauljoohyunkim/libsolace architecture

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

- Interactive diagram: https://gitdiagram.com/pauljoohyunkim/libsolace
- Repository: https://github.com/pauljoohyunkim/libsolace

## Overview

libsolace is a demonstrative C++ quantum-computing emulator. A user creates qubits and gates, applies gates, then observes the resulting state; the README illustrates this with a Hadamard gate. Separate capabilities include common gates, quantum phase estimation, circuit construction and execution, and protobuf compilation. Edges are limited to relationships shown in excerpts or documented in the README; unsampled implementation details are not inferred.

Main entry points: [`src/libsolace.cpp`](https://github.com/pauljoohyunkim/libsolace/blob/main/src/libsolace.cpp) (Qubit states), [`src/circuit.cpp`](https://github.com/pauljoohyunkim/libsolace/blob/main/src/circuit.cpp) (Circuit execution), [`src/algorithm.cpp`](https://github.com/pauljoohyunkim/libsolace/blob/main/src/algorithm.cpp) (Phase estimation), [`src/utility.cpp`](https://github.com/pauljoohyunkim/libsolace/blob/main/src/utility.cpp) (Entanglement helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Quantum simulation"]
  node_qubits["Qubit states<br/>[libsolace.cpp]"]
  node_gates["Gate operations<br/>[libsolace.cpp]"]
  node_common_gates["Common gates<br/>[common_gates.hpp]"]
end

subgraph group_circuits["Circuit workflows"]
  node_circuit_api["Circuit model<br/>[circuit.hpp]"]
  node_circuit_runtime["Circuit execution<br/>[circuit.cpp]"]
  node_circuit_format["Compiled format<br/>[solace.proto]"]
end

subgraph group_extensions["Algorithms and utilities"]
  node_phase_estimation["Phase estimation<br/>[algorithm.cpp]"]
  node_algorithm_api["Algorithm API<br/>[algorithm.hpp]"]
  node_entangle_helpers["Entanglement helpers<br/>[utility.cpp]"]
  node_utility_api["Utility API<br/>[utility.hpp]"]
end

node_user(("Library user"))

node_user -->|"applies gate"| node_gates
node_gates -->|"transforms state"| node_qubits
node_user -->|"observes state"| node_qubits
node_common_gates -->|"extends"| node_gates
node_user -->|"builds circuit"| node_circuit_api
node_circuit_api -->|"runs circuit"| node_circuit_runtime
node_circuit_runtime -->|"observes bound state"| node_qubits
node_circuit_runtime -->|"serializes circuit"| node_circuit_format
node_user -->|"requests estimate"| node_phase_estimation
node_phase_estimation -->|"uses IQFT"| node_common_gates
node_phase_estimation -->|"measures register"| node_qubits
node_user -->|"requests entanglement"| node_entangle_helpers
node_entangle_helpers -->|"tensor-products states"| node_qubits
node_utility_api -->|"declares helpers"| node_entangle_helpers

click node_qubits "https://github.com/pauljoohyunkim/libsolace/blob/main/src/libsolace.cpp"
click node_gates "https://github.com/pauljoohyunkim/libsolace/blob/main/src/libsolace.cpp"
click node_common_gates "https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/common_gates.hpp"
click node_circuit_api "https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/circuit.hpp"
click node_circuit_runtime "https://github.com/pauljoohyunkim/libsolace/blob/main/src/circuit.cpp"
click node_circuit_format "https://github.com/pauljoohyunkim/libsolace/blob/main/proto/solace.proto"
click node_phase_estimation "https://github.com/pauljoohyunkim/libsolace/blob/main/src/algorithm.cpp"
click node_algorithm_api "https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/algorithm.hpp"
click node_entangle_helpers "https://github.com/pauljoohyunkim/libsolace/blob/main/src/utility.cpp"
click node_utility_api "https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/utility.hpp"

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_qubits,node_gates,node_common_gates,node_user toneBlue
class node_circuit_api,node_circuit_runtime,node_circuit_format toneAmber
class node_phase_estimation,node_algorithm_api,node_entangle_helpers,node_utility_api toneMint
```

## Components

### Quantum simulation

- [Qubit states](https://github.com/pauljoohyunkim/libsolace/blob/main/src/libsolace.cpp): `src/libsolace.cpp`
- [Gate operations](https://github.com/pauljoohyunkim/libsolace/blob/main/src/libsolace.cpp): `src/libsolace.cpp`
- [Common gates](https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/common_gates.hpp): `include/solace/common_gates.hpp`

### Circuit workflows

- [Circuit model](https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/circuit.hpp): `include/solace/circuit.hpp`
- [Circuit execution](https://github.com/pauljoohyunkim/libsolace/blob/main/src/circuit.cpp): `src/circuit.cpp`
- [Compiled format](https://github.com/pauljoohyunkim/libsolace/blob/main/proto/solace.proto): `proto/solace.proto`

### Algorithms and utilities

- [Phase estimation](https://github.com/pauljoohyunkim/libsolace/blob/main/src/algorithm.cpp): `src/algorithm.cpp`
- [Algorithm API](https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/algorithm.hpp): `include/solace/algorithm.hpp`
- [Entanglement helpers](https://github.com/pauljoohyunkim/libsolace/blob/main/src/utility.cpp): `src/utility.cpp`
- [Utility API](https://github.com/pauljoohyunkim/libsolace/blob/main/include/solace/utility.hpp): `include/solace/utility.hpp`

### Other components

- **Library user**

## Connections

- Library user → Gate operations: applies gate (evidence: `README.md`)
- Gate operations → Qubit states: transforms state (evidence: `README.md`)
- Library user → Qubit states: observes state (evidence: `README.md`)
- Common gates → Gate operations: extends (evidence: `include/solace/common_gates.hpp`)
- Library user → Circuit model: builds circuit (evidence: `include/solace/circuit.hpp`)
- Circuit model → Circuit execution: runs circuit (evidence: `include/solace/circuit.hpp`)
- Circuit execution → Qubit states: observes bound state (evidence: `src/circuit.cpp`)
- Circuit execution → Compiled format: serializes circuit (evidence: `src/circuit.cpp`)
- Library user → Phase estimation: requests estimate (evidence: `src/algorithm.cpp`)
- Phase estimation → Common gates: uses IQFT (evidence: `src/algorithm.cpp`)
- Phase estimation → Qubit states: measures register (evidence: `src/algorithm.cpp`)
- Library user → Entanglement helpers: requests entanglement
- Entanglement helpers → Qubit states: tensor-products states (evidence: `src/utility.cpp`)
- Utility API → Entanglement helpers: declares helpers (evidence: `include/solace/utility.hpp`)
