This project implements a modular quantum simulation engine centered on Quantum Harmonic Oscillator and simplified nuclear-model problems. It supports configurable oscillator, fermionic, and custom Hamiltonians, and performs ground-state estimation using VQE.
This project implements a modular Quantum Harmonic Oscillator (QHO) simulation engine for simplified nuclear vibrational systems.
The engine constructs configurable Hamiltonians using OpenFermion, generates parameterised variational quantum circuits using Cirq, exports the circuits to OpenQASM 2.0, validates and processes them through PyQASM, translates the validated circuits to multiple quantum computing backends, and performs Variational Quantum Eigensolver (VQE) execution for ground-state energy estimation.
The architecture is designed around OpenQASM 2.0 as a hardware-independent intermediate representation between quantum circuit construction and backend-specific execution.
The project was developed as part of QIntern'26 (Project qi26_21).
- Modular Hamiltonian construction using OpenFermion
- Config-driven quantum problem definition
- Quantum Harmonic Oscillator Hamiltonian support
- Pairing and spin-orbit interaction support
- Cirq-based variational ansatz construction
- OpenQASM 2.0 circuit export
- PyQASM-based QASM2 validation
- Multi-backend QASM2 translation
- IBM Qiskit backend support
- Google Cirq backend support
- AWS Braket backend support
- VQE execution after backend translation
- Noiseless and noisy simulator execution
- Classical optimization using COBYLA
- Exact diagonalization for ground-state benchmarking
- Ground-state energy and convergence analysis
- Hardware-ready execution architecture
- FastAPI backend for programmatic execution
- HTML/JavaScript web interface
- Gradio-based user interface
- Automated pipeline and validation tests
The QHO Simulation Engine follows a modular pipeline that separates Hamiltonian construction, variational optimization, validation, and hardware execution.
┌──────────────────────────┐
│ User Interface │
│ HTML + FastAPI |
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ User Configuration │
│ Problem / Parameters / │
│ Backend / Noise / Ansatz │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Hamiltonian Construction │
│ OpenFermion │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ QubitOperator │
│ Representation │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Cirq Variational │
│ Ansatz │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ OpenQASM 2.0 │
│ Export │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ PyQASM Validation │
│ + Unrolling │
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ Gate Verification │
│ + Support Checking │
└────────────┬─────────────┘
│
┌───────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Qiskit │ │ Cirq │ │ Braket │
│ IBM │ │ Google │ │ AWS │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
└───────────────┼───────────────┘
│
▼
┌──────────────────────┐
│ VQE Execution │
│ Simulator / Hardware │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Energy Expectation │
│ Evaluation │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Classical Optimizer │
│ COBYLA │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Parameter Update & │
│ Convergence Check │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Final VQE Results │
│ Energy / Error / │
│ Iterations / Status │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ FastAPI JSON │
│ Response │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ HTML Interface │
│ User Results │
└──────────────────────┘
| Component | Description |
|---|---|
| Hamiltonian Builder | Constructs nuclear Hamiltonians as OpenFermion QubitOperator from user config. Supports three options: Quantum Oscillator (free QHO, pairing, spin-orbit), Fermion Mapping (free fermionic levels, BCS pairing, two-level model), and Custom (user-defined Pauli terms). |
| Ansatz Generator | Builds parameterised Cirq quantum circuits using SymPy symbolic parameters. RY gates control level occupancy; CNOT gates encode pair correlations. Same circuit structure used for all three Hamiltonian options. |
| QASM2 Export | Exports the Cirq circuit to OpenQASM 2.0 via cirq_circuit.to_qasm(). |
| PyQASM Utility | Single consolidated PyQASM layer in solver/pyqasm_utils.py. Parses and validates the raw QASM2 string, unrolls composite gates to basis gates, and checks that only supported gates (x, ry, cx, measure) are present. |
| Backend Translator | Three independent translators routing validated QASM2 to IBM (Qiskit QuantumCircuit), Google (Cirq circuit), or AWS (Braket Circuit). Complete gate mapping dictionary ensures circuit fidelity across backends. |
| VQE Executor | Executes the variational quantum eigensolver after translation. Supports noiseless statevector simulation, noisy simulation via depolarising error model, and real hardware via vendor APIs. Uses COBYLA or SLSQP as the classical optimiser. |
| Validation Utilities | exact_diagonalise() computes the exact ground state via numpy.linalg.eigh as ground truth. Both are library-independent NumPy functions. |
| Gradio Interface | Web interface built with Gradio. User selects Hamiltonian type, problem, parameters, backend, noise level, and optimizer. Results displayed: energy, error %, convergence plot, QASM2 export. |
| FastAPI Backend | REST API serving the HTML interface. /run_pipeline endpoint receives user config, runs the full pipeline, and returns JSON results to the frontend. |
QINTERN26_21/
│
├── hamiltonian/
│ ├── __init__.py
│ └── nuclear_hamiltonian.py
│
├── ansatz/
│ ├── __init__.py
│ └── cirq_ansatz.py
│
├── exports/
│ └── oscillator_ansatz.qasm
│
├── notebooks/
│ └── qho_engine_demo.ipynb
│
├── results/
│ └── (auto-generated at runtime)
│
├── solver/
│ ├── __init__.py
│ ├── pyqasm_utils.py
│ └── validation_utils.py
│
├── tests/
│ ├── __init__.py
│ ├── test_hamiltonian.py
│ └── test_pipeline.py
│
├── unified_interface/
│ ├── __init__.py
│ ├── api.py
│ ├── gradio_app.py
│ ├── qho_app.html
│ └── qho_interface.py
│
├── .gitignore
├── README.md
└── requirements.txt
Folder / File Purpose
────────────────────────────────────────────────────────────────────
hamiltonian/ Hamiltonian construction
nuclear_hamiltonian.py Builds the selected nuclear Hamiltonian
using OpenFermion
ansatz/ Variational circuit construction
cirq_ansatz.py Builds the parameterised Cirq ansatz
and exports it to OpenQASM 2.0
solver/ Validation and execution utilities
pyqasm_utils.py Validates QASM2 with PyQASM and translates
gates to IBM, Google and AWS formats
validation_utils.py Provides VQE execution and local
validation utilities
exports/ Generated quantum-circuit representations
oscillator_ansatz.qasm Exported/validated OpenQASM 2.0 circuit
notebooks/ Demonstration and experimentation
qho_engine_demo.ipynb Interactive QHO simulation demonstration
results/ Runtime-generated results
(created during execution)
tests/ Automated correctness tests
test_hamiltonian.py Tests Hamiltonian construction
test_pipeline.py Tests the end-to-end pipeline
unified_interface/ Unified application interface layer
qho_interface.py Main pipeline orchestrator
api.py FastAPI backend/API endpoint
gradio_app.py Gradio-based interface
qho_app.html HTML/JavaScript frontend
requirements.txt Python dependencies
.gitignore Git exclusion rules
README.md Project documentation
# 1. Clone the repository
git clone https://github.com/deeepakchauhan/qintern26_21_qho_module.git
cd qintern26_21_qho_module
# 2. Create a virtual environment (recommended)
python -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activate
# 3. Install all dependencies
pip install -r requirements.txt
# 4. Run the automated tests
pytest tests/ -v
# 5. Run the demonstration notebook
jupyter notebook notebooks/qho_engine_demo.ipynb
Running all cells in `qho_engine_demo.ipynb` top to bottom will reproduce:
- Hamiltonian construction and exact-diagonalization benchmark
- VQE runs on both the Cirq and Qiskit paths, with cross-check comparison
- Convergence plots and optimal-parameter reporting
- QASM2 export and PyQASM validation- Qiskit: https://www.ibm.com/quantum/qiskit
- Peruzzo et al. 2014 (Original VQE paper): arXiv: https://arxiv.org/abs/1304.3061 DOI: https://doi.org/10.1038/ncomms5213
- Tilly et al. 2022 (VQE review): arXiv: https://arxiv.org/abs/2111.05176 DOI: https://doi.org/10.1016/j.physrep.2022.08.003
- Ring & Schuck (The Nuclear Many-Body Problem) Publisher: https://link.springer.com/book/9783540212065
- OpenFermion documentation: https://quantumai.google/openfermion
- Cirq documentation: https://quantumai.google/cirq
- PyQASM: https://pypi.org/project/pyqasm/