# s-tevens/miraichem architecture

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

- Interactive diagram: https://gitdiagram.com/s-tevens/miraichem
- Repository: https://github.com/s-tevens/miraichem

## Overview

MiraiChem automates VQE benchmarking for small molecules: a user supplies molecule and sweep configurations, the system computes classical references and qubit Hamiltonians, runs and records VQE configurations, ranks them, and recommends one. It also evaluates recommended parameters on real IBM hardware and plots bond-dissociation scans; the dashboard reads saved results. The core implementation excerpts show how VQE selects a backend and optimizer, while the README documents the broader sweep, ranking, storage, and reporting workflow. Some subsystem internals were not sampled, so their links rely on documented behavior.

Main entry points: [`src/miraichem/vqe/runner.py`](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/vqe/runner.py) (VQE runner), [`src/miraichem/benchmark/storage.py`](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/storage.py) (Results storage), [`src/miraichem/backends/hardware_eval.py`](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/hardware_eval.py) (Fixed-parameter evaluation), [`src/miraichem/config.py`](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/config.py) (Run configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chemistry["Chemistry setup"]
  node_configuration["Run configuration<br/>[config.py]"]
  node_references["Classical references<br/>[classical.py]"]
  node_active_space["Active space<br/>[active_space.py]"]
  node_hamiltonian["Qubit Hamiltonian<br/>[hamiltonian.py]"]
end

subgraph group_execution["VQE execution"]
  node_vqe["VQE runner<br/>[runner.py]"]
  node_ansatz["Ansatz circuits<br/>[uccsd.py]"]
  node_optimizer["Optimizers<br/>[optimizers.py]"]
  node_backend_interface["Estimator interface<br/>[base.py]"]
  node_ideal["Ideal simulator<br/>[ideal.py]"]
  node_noisy["Noisy simulator<br/>[noisy.py]"]
  node_mitigation["Error mitigation<br/>[zne.py]"]
  node_run_result["Run record<br/>[result.py]"]
end

subgraph group_evaluation["Benchmarking"]
  node_sweep["Sweep engine<br/>[sweep.py]"]
  node_storage[("Results storage<br/>[storage.py]")]
  node_ranking["Ranking and recommendation<br/>[ranking.py]"]
  node_scan_ranking["Curve ranking<br/>[ranking_scan.py]"]
  node_dissociation["Dissociation curves<br/>[dissociation.py]"]
end

subgraph group_validation["Hardware validation"]
  node_hardware_eval["Fixed-parameter evaluation<br/>[hardware_eval.py]"]
  node_hardware_backend["IBM hardware backend<br/>[hardware.py]"]
end

subgraph group_presentation["Results and views"]
  node_dashboard["Results dashboard<br/>[app.py]"]
  node_report["Benchmark report<br/>[report.py]"]
end

node_user(("Researcher"))

node_user -->|"sets options"| node_configuration
node_configuration -->|"defines sweep"| node_sweep
node_configuration -->|"configures molecule"| node_references
node_references -->|"resolves space"| node_active_space
node_configuration -->|"sets mapping"| node_hamiltonian
node_hamiltonian -->|"resolves space"| node_active_space
node_sweep -->|"runs configurations"| node_vqe
node_vqe -->|"gets references"| node_references
node_vqe -->|"builds problem"| node_hamiltonian
node_vqe -->|"builds circuit"| node_ansatz
node_vqe -->|"optimizes parameters"| node_optimizer
node_vqe -->|"estimates energy"| node_backend_interface
node_backend_interface -->|"implemented by"| node_ideal
node_backend_interface -->|"implemented by"| node_noisy
node_noisy -->|"uses mitigation"| node_mitigation
node_vqe -->|"records run"| node_run_result
node_sweep -->|"caches runs"| node_storage
node_run_result -->|"saved as"| node_storage
node_storage -->|"supplies runs"| node_ranking
node_storage -->|"supplies scan data"| node_dissociation
node_ranking -->|"ranks across curves"| node_scan_ranking
node_user -->|"requests validation"| node_hardware_eval
node_storage -->|"loads selected run"| node_hardware_eval
node_hardware_eval -->|"rebuilds problem"| node_hamiltonian
node_hardware_eval -->|"checks ideal energy"| node_ideal
node_hardware_eval -->|"evaluates parameters"| node_hardware_backend
node_hardware_eval -->|"saves validation"| node_storage
node_storage -->|"reads saved results"| node_dashboard
node_ranking -->|"generates report"| node_report
node_dissociation -->|"visualized in"| node_dashboard
node_ranking -->|"shown in"| node_dashboard

click node_configuration "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/config.py"
click node_references "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/chemistry/classical.py"
click node_active_space "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/chemistry/active_space.py"
click node_hamiltonian "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/mapping/hamiltonian.py"
click node_sweep "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/sweep.py"
click node_vqe "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/vqe/runner.py"
click node_ansatz "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/ansatz/uccsd.py"
click node_optimizer "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/optim/optimizers.py"
click node_backend_interface "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/base.py"
click node_ideal "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/ideal.py"
click node_noisy "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/noisy.py"
click node_mitigation "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/mitigation/zne.py"
click node_run_result "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/vqe/result.py"
click node_storage "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/storage.py"
click node_ranking "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/ranking.py"
click node_scan_ranking "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/ranking_scan.py"
click node_dissociation "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/analysis/dissociation.py"
click node_hardware_eval "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/hardware_eval.py"
click node_hardware_backend "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/hardware.py"
click node_dashboard "https://github.com/s-tevens/miraichem/blob/main/dashboard/app.py"
click node_report "https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/report.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_configuration,node_references,node_active_space,node_hamiltonian toneBlue
class node_vqe,node_ansatz,node_optimizer,node_backend_interface,node_ideal,node_noisy,node_mitigation,node_run_result toneAmber
class node_sweep,node_storage,node_ranking,node_scan_ranking,node_dissociation toneMint
class node_hardware_eval,node_hardware_backend toneRose
class node_dashboard,node_report,node_user toneIndigo
```

## Components

### Chemistry setup

- [Run configuration](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/config.py): `src/miraichem/config.py`
- [Classical references](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/chemistry/classical.py): `src/miraichem/chemistry/classical.py`
- [Active space](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/chemistry/active_space.py): `src/miraichem/chemistry/active_space.py`
- [Qubit Hamiltonian](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/mapping/hamiltonian.py): `src/miraichem/mapping/hamiltonian.py`

### VQE execution

- [VQE runner](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/vqe/runner.py): `src/miraichem/vqe/runner.py`
- [Ansatz circuits](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/ansatz/uccsd.py): `src/miraichem/ansatz/uccsd.py`
- [Optimizers](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/optim/optimizers.py): `src/miraichem/optim/optimizers.py`
- [Estimator interface](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/base.py): `src/miraichem/backends/base.py`
- [Ideal simulator](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/ideal.py): `src/miraichem/backends/ideal.py`
- [Noisy simulator](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/noisy.py): `src/miraichem/backends/noisy.py`
- [Error mitigation](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/mitigation/zne.py): `src/miraichem/mitigation/zne.py`
- [Run record](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/vqe/result.py): `src/miraichem/vqe/result.py`

### Benchmarking

- [Sweep engine](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/sweep.py): `src/miraichem/benchmark/sweep.py`
- [Results storage](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/storage.py): `src/miraichem/benchmark/storage.py`
- [Ranking and recommendation](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/ranking.py): `src/miraichem/benchmark/ranking.py`
- [Curve ranking](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/ranking_scan.py): `src/miraichem/benchmark/ranking_scan.py`
- [Dissociation curves](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/analysis/dissociation.py): `src/miraichem/analysis/dissociation.py`

### Hardware validation

- [Fixed-parameter evaluation](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/hardware_eval.py): `src/miraichem/backends/hardware_eval.py`
- [IBM hardware backend](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/backends/hardware.py): `src/miraichem/backends/hardware.py`

### Results and views

- [Results dashboard](https://github.com/s-tevens/miraichem/blob/main/dashboard/app.py): `dashboard/app.py`
- [Benchmark report](https://github.com/s-tevens/miraichem/blob/main/src/miraichem/benchmark/report.py): `src/miraichem/benchmark/report.py`

### Other components

- **Researcher**

## Connections

- Researcher → Run configuration: sets options (evidence: `README.md`)
- Run configuration → Sweep engine: defines sweep (evidence: `README.md`)
- Run configuration → Classical references: configures molecule (evidence: `src/miraichem/chemistry/classical.py`)
- Classical references → Active space: resolves space (evidence: `src/miraichem/chemistry/classical.py`)
- Run configuration → Qubit Hamiltonian: sets mapping (evidence: `src/miraichem/mapping/hamiltonian.py`)
- Qubit Hamiltonian → Active space: resolves space (evidence: `src/miraichem/mapping/hamiltonian.py`)
- Sweep engine → VQE runner: runs configurations (evidence: `README.md`)
- VQE runner → Classical references: gets references (evidence: `README.md`)
- VQE runner → Qubit Hamiltonian: builds problem (evidence: `src/miraichem/vqe/runner.py`)
- VQE runner → Ansatz circuits: builds circuit (evidence: `src/miraichem/vqe/runner.py`)
- VQE runner → Optimizers: optimizes parameters (evidence: `src/miraichem/vqe/runner.py`)
- VQE runner → Estimator interface: estimates energy (evidence: `src/miraichem/vqe/runner.py`)
- Estimator interface → Ideal simulator: implemented by (evidence: `src/miraichem/backends/ideal.py`)
- Estimator interface → Noisy simulator: implemented by (evidence: `src/miraichem/backends/noisy.py`)
- Noisy simulator → Error mitigation: uses mitigation (evidence: `src/miraichem/backends/noisy.py`)
- VQE runner → Run record: records run (evidence: `src/miraichem/vqe/runner.py`)
- Sweep engine → Results storage: caches runs (evidence: `README.md`)
- Run record → Results storage: saved as (evidence: `README.md`)
- Results storage → Ranking and recommendation: supplies runs (evidence: `README.md`)
- Results storage → Dissociation curves: supplies scan data (evidence: `README.md`)
- Ranking and recommendation → Curve ranking: ranks across curves (evidence: `README.md`)
- Researcher → Fixed-parameter evaluation: requests validation (evidence: `README.md`)
- Results storage → Fixed-parameter evaluation: loads selected run (evidence: `src/miraichem/backends/hardware_eval.py`)
- Fixed-parameter evaluation → Qubit Hamiltonian: rebuilds problem (evidence: `src/miraichem/backends/hardware_eval.py`)
- Fixed-parameter evaluation → Ideal simulator: checks ideal energy (evidence: `src/miraichem/backends/hardware_eval.py`)
- Fixed-parameter evaluation → IBM hardware backend: evaluates parameters (evidence: `src/miraichem/backends/hardware_eval.py`)
- Fixed-parameter evaluation → Results storage: saves validation (evidence: `README.md`)
- Results storage → Results dashboard: reads saved results (evidence: `README.md`)
- Ranking and recommendation → Benchmark report: generates report (evidence: `README.md`)
- Dissociation curves → Results dashboard: visualized in (evidence: `dashboard/app.py`)
- Ranking and recommendation → Results dashboard: shown in (evidence: `dashboard/app.py`)
