How s-tevens/miraichem works
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: runner.py VQE runner · storage.py Results storage · hardware_eval.py Fixed-parameter evaluation · config.py Run configuration
Components 22
Chemistry setup
- Run configuration
src/miraichem/config.py - Classical references
src/miraichem/chemistry/classical.py - Active space
src/miraichem/chemistry/active_space.py - Qubit Hamiltonian
src/miraichem/mapping/hamiltonian.py
VQE execution
- VQE runner
src/miraichem/vqe/runner.py - Ansatz circuits
src/miraichem/ansatz/uccsd.py - Optimizers
src/miraichem/optim/optimizers.py - Estimator interface
src/miraichem/backends/base.py - Ideal simulator
src/miraichem/backends/ideal.py - Noisy simulator
src/miraichem/backends/noisy.py - Error mitigation
src/miraichem/mitigation/zne.py - Run record
src/miraichem/vqe/result.py
Benchmarking
- Sweep engine
src/miraichem/benchmark/sweep.py - Results storage
src/miraichem/benchmark/storage.py - Ranking and recommendation
src/miraichem/benchmark/ranking.py - Curve ranking
src/miraichem/benchmark/ranking_scan.py - Dissociation curves
src/miraichem/analysis/dissociation.py
Hardware validation
- Fixed-parameter evaluation
src/miraichem/backends/hardware_eval.py - IBM hardware backend
src/miraichem/backends/hardware.py
Results and views
- Results dashboard
dashboard/app.py - Benchmark report
src/miraichem/benchmark/report.py
Other components
- Researcher
Connections 31
- Researcher → Run configuration: sets options
README.md - Run configuration → Sweep engine: defines sweep
README.md - Run configuration → Classical references: configures molecule
src/miraichem/chemistry/classical.py - Classical references → Active space: resolves space
src/miraichem/chemistry/classical.py - Run configuration → Qubit Hamiltonian: sets mapping
src/miraichem/mapping/hamiltonian.py - Qubit Hamiltonian → Active space: resolves space
src/miraichem/mapping/hamiltonian.py - Sweep engine → VQE runner: runs configurations
README.md - VQE runner → Classical references: gets references
README.md - VQE runner → Qubit Hamiltonian: builds problem
src/miraichem/vqe/runner.py - VQE runner → Ansatz circuits: builds circuit
src/miraichem/vqe/runner.py - VQE runner → Optimizers: optimizes parameters
src/miraichem/vqe/runner.py - VQE runner → Estimator interface: estimates energy
src/miraichem/vqe/runner.py - Estimator interface → Ideal simulator: implemented by
src/miraichem/backends/ideal.py - Estimator interface → Noisy simulator: implemented by
src/miraichem/backends/noisy.py - Noisy simulator → Error mitigation: uses mitigation
src/miraichem/backends/noisy.py - VQE runner → Run record: records run
src/miraichem/vqe/runner.py - Sweep engine → Results storage: caches runs
README.md - Run record → Results storage: saved as
README.md - Results storage → Ranking and recommendation: supplies runs
README.md - Results storage → Dissociation curves: supplies scan data
README.md - Ranking and recommendation → Curve ranking: ranks across curves
README.md - Researcher → Fixed-parameter evaluation: requests validation
README.md - Results storage → Fixed-parameter evaluation: loads selected run
src/miraichem/backends/hardware_eval.py - Fixed-parameter evaluation → Qubit Hamiltonian: rebuilds problem
src/miraichem/backends/hardware_eval.py - Fixed-parameter evaluation → Ideal simulator: checks ideal energy
src/miraichem/backends/hardware_eval.py - Fixed-parameter evaluation → IBM hardware backend: evaluates parameters
src/miraichem/backends/hardware_eval.py - Fixed-parameter evaluation → Results storage: saves validation
README.md - Results storage → Results dashboard: reads saved results
README.md - Ranking and recommendation → Benchmark report: generates report
README.md - Dissociation curves → Results dashboard: visualized in
dashboard/app.py - Ranking and recommendation → Results dashboard: shown in
dashboard/app.py