vqe-pennylane 0.2.2__py3-none-any.whl

vqe/visualize.py

@@ -0,0 +1,308 @@
+"""
+vqe.visualize
+-------------
+Unified plotting utilities for VQE and SSVQE.
+All plots save into vqe/io_utils.IMG_DIR.
+
+This module intentionally avoids external dependencies (e.g. common.plotting)
+for maximum portability and internal cohesion.
+"""
+
+from __future__ import annotations
+
+import os
+import matplotlib.pyplot as plt
+
+from .io_utils import IMG_DIR
+
+
+# ================================================================
+# INTERNAL HELPERS
+# ================================================================
+def _safe_filename(*parts):
+    """
+    Build a safe filename from components such as:
+        ("VQE", "H2", "Adam", "UCCSD", "noisy")
+    """
+    clean = []
+    for p in parts:
+        if p is None:
+            continue
+        # Basic sanitisation
+        p = str(p).replace(" ", "_").replace("+", "plus")
+        clean.append(p)
+    return "_".join(clean) + ".png"
+
+
+def _safe_title(*parts):
+    """
+    Build a human-readable plot title.
+    """
+    return " — ".join([str(p) for p in parts if p is not None])
+
+
+def _save_plot(fname):
+    os.makedirs(IMG_DIR, exist_ok=True)
+    path = os.path.join(IMG_DIR, fname)
+    plt.savefig(path, dpi=300, bbox_inches="tight")
+    print(f"📁 Saved → {path}")
+
+
+# ================================================================
+# BASIC VQE CONVERGENCE
+# ================================================================
+def plot_convergence(
+    energies_noiseless,
+    molecule: str,
+    energies_noisy=None,
+    optimizer: str = "Adam",
+    ansatz: str = "UCCSD",
+    dep_prob: float = 0.0,
+    amp_prob: float = 0.0,
+    show=True,
+):
+    """
+    Plot VQE energy convergence (noisy + noiseless overlay).
+    """
+    plt.figure(figsize=(8, 5))
+    steps = range(len(energies_noiseless))
+    plt.plot(steps, energies_noiseless, label="Noiseless", lw=2)
+
+    noisy = energies_noisy is not None
+    if noisy:
+        plt.plot(range(len(energies_noisy)), energies_noisy,
+                 label="Noisy", lw=2, linestyle="--")
+
+    # Title
+    if noisy:
+        title = _safe_title(
+            f"{molecule}",
+            f"VQE Convergence ({optimizer}, {ansatz})",
+            f"Noise: dep={dep_prob}, amp={amp_prob}",
+        )
+    else:
+        title = _safe_title(
+            f"{molecule}", f"VQE Convergence ({optimizer}, {ansatz})"
+        )
+
+    plt.title(title)
+    plt.xlabel("Iteration")
+    plt.ylabel("Energy (Ha)")
+    plt.grid(True, alpha=0.4)
+    plt.legend()
+    plt.tight_layout()
+
+    # Filename
+    fname = _safe_filename(
+        "VQE_Convergence",
+        molecule,
+        optimizer,
+        ansatz,
+        "noisy" if noisy else "noiseless",
+        f"dep{dep_prob}" if noisy else "",
+        f"amp{amp_prob}" if noisy else "",
+    )
+    _save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()
+
+
+# ================================================================
+# OPTIMIZER COMPARISON
+# ================================================================
+def plot_optimizer_comparison(molecule: str, results: dict, ansatz: str = "UCCSD", show=True):
+    """
+    Plot multiple optimizers on a shared convergence graph.
+    """
+    plt.figure(figsize=(8, 5))
+
+    min_len = min(len(v) for v in results.values())
+
+    for opt, energies in results.items():
+        plt.plot(range(min_len), energies[:min_len], label=opt)
+
+    plt.title(_safe_title(molecule, f"VQE Optimizer Comparison ({ansatz})"))
+    plt.xlabel("Iteration")
+    plt.ylabel("Energy (Ha)")
+    plt.legend()
+    plt.grid(True, alpha=0.4)
+    plt.tight_layout()
+
+    fname = _safe_filename("VQE_Optimizer_Comparison", molecule, ansatz)
+    _save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()
+
+
+# ================================================================
+# ANSATZ COMPARISON
+# ================================================================
+def plot_ansatz_comparison(molecule: str, results: dict, show=True, optimizer: str = "Adam"):
+    """
+    Plot multiple ansatzes on a shared convergence graph.
+    """
+    plt.figure(figsize=(8, 5))
+
+    min_len = min(len(v) for v in results.values())
+
+    for ans, energies in results.items():
+        plt.plot(range(min_len), energies[:min_len], label=ans)
+
+    plt.title(_safe_title(molecule, f"VQE Ansatz Comparison ({optimizer})"))
+    plt.xlabel("Iteration")
+    plt.ylabel("Energy (Ha)")
+    plt.legend()
+    plt.grid(True, alpha=0.4)
+    plt.tight_layout()
+
+    fname = _safe_filename("VQE_Ansatz_Comparison", molecule, optimizer)
+    _save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()
+
+
+# ================================================================
+# NOISE STATISTICS
+# ================================================================
+def plot_noise_statistics(
+    molecule: str,
+    noise_levels,
+    energy_means,
+    energy_stds,
+    fidelity_means,
+    fidelity_stds,
+    show=True,
+    optimizer_name="Adam",
+    ansatz_name="UCCSD",
+    noise_type="Depolarizing",
+):
+    """
+    Plot (ΔE vs noise) and (fidelity vs noise) as two subplots.
+    """
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(8, 8), sharex=True)
+
+    # ΔE vs noise level
+    ax1.errorbar(noise_levels, energy_means, yerr=energy_stds,
+                 fmt="o-", capsize=4)
+    ax1.set_ylabel("ΔE (Ha)")
+    ax1.set_title(
+        _safe_title(
+            molecule,
+            f"VQE Noise Impact — {noise_type}",
+            f"{optimizer_name}, {ansatz_name}",
+        )
+    )
+    ax1.grid(True, alpha=0.4)
+
+    # Fidelity vs noise level
+    ax2.errorbar(noise_levels, fidelity_means, yerr=fidelity_stds,
+                 fmt="s-", capsize=4)
+    ax2.set_xlabel("Noise Probability")
+    ax2.set_ylabel("Fidelity")
+    ax2.grid(True, alpha=0.4)
+
+    plt.tight_layout()
+
+    fname = _safe_filename(
+        "VQE_Noise_Stats",
+        molecule,
+        optimizer_name,
+        ansatz_name,
+        noise_type,
+    )
+    _save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()
+
+
+# ---------------------------------------------------------------------
+# SSVQE Multi-State Convergence Plot
+# ---------------------------------------------------------------------
+def plot_ssvqe_convergence_multi(
+    energies_per_state,
+    *,
+    molecule="molecule",
+    ansatz="UCCSD",
+    optimizer="Adam",
+    show=True,
+    save=True,
+):
+    """
+    Plot convergence for multiple states from SSVQE.
+
+    Parameters
+    ----------
+    energies_per_state : dict or list
+        Either:
+            {0: [...], 1: [...], 2: [...]}  
+        or a list-of-lists:
+            [[...], [...], [...]]
+        Each entry is the energy trajectory for one state.
+
+    molecule : str
+        Molecule label.
+    ansatz : str
+        Ansatz name.
+    optimizer : str
+        Optimizer name.
+    show : bool
+        Whether to display the plot.
+    save : bool
+        Whether to save the PNG via common.plotting.
+    """
+
+    import matplotlib.pyplot as plt
+    from vqe_qpe_common.plotting import build_filename, save_plot, format_molecule_name
+
+    # Normalise molecule name
+    mol_norm = format_molecule_name(molecule)
+
+    # Handle dict or list input
+    if isinstance(energies_per_state, dict):
+        trajectories = [energies_per_state[k] for k in sorted(energies_per_state.keys())]
+    else:
+        trajectories = energies_per_state
+
+    n_states = len(trajectories)
+
+    # Plot
+    plt.figure(figsize=(7, 4.5))
+    for i, E_list in enumerate(trajectories):
+        plt.plot(E_list, label=f"State {i}")
+
+    plt.xlabel("Iteration")
+    plt.ylabel("Energy (Ha)")
+    plt.title(f"{molecule} SSVQE ({n_states} states) – {ansatz}, {optimizer}")
+    plt.grid(True, alpha=0.3)
+    plt.legend()
+    plt.tight_layout()
+
+    # Save if requested
+    if save:
+        fname = build_filename(
+            molecule=mol_norm,
+            topic="ssvqe_convergence",
+            extras={
+                "states": n_states,
+                "ans": ansatz,
+                "opt": optimizer,
+            }
+        )
+        save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()

vqe_pennylane-0.2.2.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: vqe-pennylane
+Version: 0.2.2
+Summary: Lightweight Quantum Simulation Suite with VQE and QPE modules (PennyLane-based)
+Author-email: Sid Richards <siddrichards@hotmail.co.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver
+Project-URL: Issues, https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver/issues
+Project-URL: Documentation, https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver#readme
+Keywords: quantum,VQE,QPE,simulation,pennylane,quantum-chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pennylane<0.45,>=0.42
+Requires-Dist: numpy<2.0,>=1.23
+Requires-Dist: scipy<2.0,>=1.10; python_version >= "3.10"
+Requires-Dist: scipy<2.0,>=1.9; python_version == "3.9"
+Requires-Dist: matplotlib
+Requires-Dist: openfermion
+Requires-Dist: openfermionpyscf
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Dynamic: license-file
+
+# Quantum Simulation Suite — VQE + QPE (PennyLane)
+
+<p align="center">
+
+  <a href="https://pypi.org/project/vqe-pennylane/">
+    <img src="https://img.shields.io/pypi/v/vqe-pennylane?style=flat-square" alt="PyPI Version">
+  </a>
+
+  <a href="https://pypi.org/project/vqe-pennylane/">
+    <img src="https://img.shields.io/pypi/dm/vqe-pennylane?style=flat-square" alt="PyPI Downloads">
+  </a>
+
+  <a href="https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver/actions/workflows/tests.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/SidRichardsQuantum/Variational_Quantum_Eigensolver/tests.yml?label=tests&style=flat-square" alt="Tests">
+  </a>
+
+  <img src="https://img.shields.io/pypi/pyversions/vqe-pennylane?style=flat-square" alt="Python Versions">
+
+  <img src="https://img.shields.io/github/license/SidRichardsQuantum/Variational_Quantum_Eigensolver?style=flat-square" alt="License">
+
+</p>
+
+A modern, modular, and fully reproducible **quantum-chemistry simulation suite** built on  
+**PennyLane**, featuring:
+
+- **Variational Quantum Eigensolver (VQE)**  
+- **State-Specific VQE (SSVQE)**  
+- **Quantum Phase Estimation (QPE)**  
+- **Unified molecule registry, geometry generators, and plotting tools**  
+- **Consistent caching and reproducibility across all solvers**
+
+This project refactors all previous notebooks into a clean Python package with  
+a shared `vqe_qpe_common/` layer for Hamiltonians, molecules, geometry, and plotting.
+
+- **[THEORY.md](THEORY.md)** — Full background on VQE, QPE, ansatzes, optimizers, mappings, and noise models.  
+- **[USAGE.md](USAGE.md)** — Practical guide for installation, CLI usage, running simulations, caching, and plotting.
+
+These documents complement the README and provide both the *theoretical foundation* and the *hands-on execution details* of the VQE/QPE suite.
+
+---
+
+# Project Structure
+
+```
+Variational_Quantum_Eigensolver/
+├── README.md
+├── THEORY.md
+├── USAGE.md
+├── LICENSE
+├── pyproject.toml
+│
+├── vqe_qpe_common/          # Shared logic for VQE + QPE
+│   ├── molecules.py         # Unified molecule registry
+│   ├── geometry.py          # Bond/angle geometry generators
+│   ├── hamiltonian.py       # Unified Hamiltonian builder (PennyLane/OpenFermion)
+│   └── plotting.py          # Shared plotting + filename builders
+│
+├── vqe/                     # Variational Quantum Eigensolver package
+│   ├── __main__.py          # CLI: python -m vqe
+│   ├── core.py              # VQE orchestration (runs, scans, sweeps)
+│   ├── engine.py            # Devices, noise, ansatz/optimizer plumbing
+│   ├── ansatz.py            # UCCSD, RY-CZ, HEA, minimal ansätze
+│   ├── optimizer.py         # Adam, GD, Momentum, SPSA, etc.
+│   ├── hamiltonian.py       # VQE-specific wrapper → uses vqe_qpe_common.hamiltonian
+│   ├── io_utils.py          # JSON caching, run signatures
+│   ├── visualize.py         # Convergence, scans, noise plots
+│   └── ssvqe.py             # Subspace-search VQE (excited states)
+│
+├── qpe/                     # Quantum Phase Estimation package
+│   ├── __main__.py          # CLI: python -m qpe
+│   ├── core.py              # Controlled-U, trotterized dynamics, iQFT
+│   ├── hamiltonian.py       # QPE-specific wrapper → uses vqe_qpe_common.hamiltonian
+│   ├── io_utils.py          # JSON caching, run signatures
+│   ├── noise.py             # Depolarizing + amplitude damping channels
+│   └── visualize.py         # Phase histograms + sweep plots
+│
+├── results/                 # JSON outputs
+├── images/                  # Saved plots (VQE + QPE)
+├── data/                    # Optional molecule configs, external data
+│
+└── notebooks/               # Notebooks importing from the vqe/ and qpe/ packages
+```
+
+This structure ensures:
+
+- **VQE and QPE share the same chemistry** (`vqe_qpe_common/`)
+- **All results are cached consistently** (`results/`)
+- **All plots use one naming system** (`vqe_qpe_common/plotting.py`)
+- **Notebooks import from the real package** (no duplicated code)
+- **CLI tools are production-ready** (`python -m vqe`, `python -m qpe`)
+
+---
+
+# ⚙️ Installation
+
+### Install from PyPI
+
+```bash
+pip install vqe-pennylane
+```
+
+### Install from source (development mode)
+
+```bash
+git clone https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver.git
+cd Variational_Quantum_Eigensolver
+pip install -e .
+```
+
+### Confirm installation
+
+```bash
+python -c "import vqe, qpe; print('VQE+QPE imported successfully!')"
+```
+
+---
+
+# Common Core (Shared by VQE & QPE)
+
+The following modules ensure full consistency between solvers:
+
+| Module | Purpose |
+|--------|---------|
+| `vqe_qpe_common/molecules.py` | Canonical molecule definitions |
+| `vqe_qpe_common/geometry.py` | Bond/angle/coordinate generators |
+| `vqe_qpe_common/hamiltonian.py` | Hamiltonian construction + OpenFermion fallback |
+| `vqe_qpe_common/plotting.py` | Unified filename builder + PNG export |
+
+---
+
+# 🔹 VQE Package
+
+Features:
+- Ground-state VQE
+- Excited-state SSVQE
+- Geometry scans
+- Noise sweeps
+- Mapping comparisons
+- Optimizer registry
+- Result caching
+
+Run example:
+
+```python
+from vqe.core import run_vqe
+result = run_vqe("H2", ansatz_name="UCCSD", optimizer_name="Adam", n_steps=50)
+print(result["energy"])
+```
+
+---
+
+# 🔹 QPE Package
+
+Features:
+- Noiseless & noisy QPE  
+- Trotterized exp(-iHt)  
+- Inverse QFT  
+- Noise channels  
+- Cached results  
+
+Example:
+
+```python
+from vqe_qpe_common.hamiltonian import build_hamiltonian
+from qpe.core import run_qpe
+
+H, n_qubits, hf_state = build_hamiltonian(["H","H"], coords, 0, "STO-3G")
+result = run_qpe(H, hf_state, n_ancilla=4)
+```
+
+---
+
+# CLI Usage
+
+### VQE  
+```bash
+python -m vqe -m H2 -a UCCSD -o Adam --steps 50
+```
+
+### QPE  
+```bash
+python -m qpe --molecule H2 --ancillas 4 --shots 2000
+```
+
+---
+
+# 🧪 Tests
+
+```bash
+pytest -v
+```
+
+---
+
+📘 Author: Sid Richards (SidRichardsQuantum)
+
+<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/linkedin/linkedin-original.svg" width="20" /> LinkedIn: https://www.linkedin.com/in/sid-richards-21374b30b/
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

vqe_pennylane-0.2.2.dist-info/RECORD

@@ -0,0 +1,28 @@
+qpe/__init__.py,sha256=YByDVRXUEA4jGTT4m-TlP0i6ycQ7xbhaOipw0Tr7KMs,1789
+qpe/__main__.py,sha256=WGNEigwfRf3icEmTmUWKD1nAvZ0MzDtRxDzQV5zs-d0,6743
+qpe/core.py,sha256=jj3LIfKVytTTEscWbUcD59-BUhWo8ulWALZHuo0aDYU,9666
+qpe/hamiltonian.py,sha256=4AIWbfpN-HpL2Z1zKcRWrSO1_Pw-rIDGcshr7INfRSc,3099
+qpe/io_utils.py,sha256=4KZQrNzF9iLE_yd4hFOmxTC4lLREMAfwR72X2Tt0dNs,3814
+qpe/noise.py,sha256=MjK_x38FxxEatt21Rv3rrvBxF8fK8CL5uIsii8samSM,1303
+qpe/visualize.py,sha256=rwfCxeq8_NWWX53S-wbBQEnkqumhyM2240frvkfiBJM,5631
+vqe/__init__.py,sha256=9D-HoWKOzxL7g0lupHix-mrbYv9CIQMdf4W5XtJL8ko,3102
+vqe/__main__.py,sha256=dQq3tHeQQZst3Q8hGikv75K9FT87RXb_OnkZT-Mq_BE,11072
+vqe/ansatz.py,sha256=DMFBWF7qItFIoz1nXxBo8Dqb6JQeUROYpO2JqX9Ydeo,12573
+vqe/core.py,sha256=vh9eWg3qX1D8VU_JrnO3O1gvAMkJd5czdExwLzTzCv0,26137
+vqe/engine.py,sha256=zNpgXFko8u_ZEo18auriUuerOiGSAmVGctSLP1NPnuM,10372
+vqe/hamiltonian.py,sha256=tbxueGC1Ya6C6zr7oPgvpuFzolHyEMO_vVYb-nYc3zE,8334
+vqe/io_utils.py,sha256=f6YAw8uKZBWzmbOdyKndxfAnuskSLthzilF_SOlHux4,7528
+vqe/optimizer.py,sha256=nm04mxh4PW_c0iEQuKfF5vrfpopq9vNjSOjWCCu2TiI,1520
+vqe/ssvqe.py,sha256=mws-L1sqx4fr9bV9KOACBOFF59u1nQckU9C-MUdYuec,9139
+vqe/visualize.py,sha256=knIHDiXaRfK3gUuY48oNV2kaw3fv3hOVRZ1yjW8pMDU,8061
+vqe_pennylane-0.2.2.dist-info/licenses/LICENSE,sha256=8yjLrHRw7qIlfoogu8raXR4DVceIzWyMgJJ9veAAoKo,1069
+vqe_qpe_common/__init__.py,sha256=JTEF58TToTefiIQFFIUccV2dIzIrPw1MRZzO8FwfZtw,1658
+vqe_qpe_common/geometry.py,sha256=JZsseVexsOWw9OV0M1SX-VvSR05ZkEM-5WPtko-vNEY,1276
+vqe_qpe_common/hamiltonian.py,sha256=7kIaaMI86R9eQdpIQ4Bwwc0DWHeXZhTnIx8OJNPxKoE,1744
+vqe_qpe_common/molecules.py,sha256=Farn5t5Wmu_C4T7IGhPZM3aGeUQrMSimMnmqMMJsI5I,2582
+vqe_qpe_common/plotting.py,sha256=gOaqXq_Yspv9Q6_13Xalg9axgRYlBFH96k8ETfFzw-U,4495
+vqe_pennylane-0.2.2.dist-info/METADATA,sha256=syiTmdgyAv3qaXzBRsorztasdgzSflka7_ot8LMZDhU,8102
+vqe_pennylane-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+vqe_pennylane-0.2.2.dist-info/entry_points.txt,sha256=bFCrloF0q0q5nI7AXJBOpq5jUQ9Self-bwEPN3j44qg,66
+vqe_pennylane-0.2.2.dist-info/top_level.txt,sha256=S9LETqg-fWOc2Xq4YrzYAivDGdSntsQP5uLRPFhi6v8,23
+vqe_pennylane-0.2.2.dist-info/RECORD,,

vqe_pennylane-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vqe_pennylane-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+qpe = qpe.__main__:main
+vqe = vqe.__main__:main

vqe_pennylane-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sid Richards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vqe_pennylane-0.2.2.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+qpe
+vqe
+vqe_qpe_common

vqe_qpe_common/__init__.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+"""
+vqe_qpe_common
+======
+
+Shared utilities used across VQE, QPE, and future solvers.
+
+This subpackage contains:
+    • vqe_qpe_common.molecules   — canonical molecule registry
+    • vqe_qpe_common.geometry    — unified geometry generators (bond/angle scans)
+    • vqe_qpe_common.hamiltonian — single source of truth for Hamiltonian construction
+    • vqe_qpe_common.plotting    — global plotting + filename/dir management
+
+All high-level solvers (VQE, QPE, QSVT, etc.) should import molecule
+definitions, geometry logic, Hamiltonians, and plotting helpers from here
+to avoid duplication and ensure reproducibility.
+
+Example
+-------
+    from vqe_qpe_common import (
+        MOLECULES,
+        get_molecule_config,
+        generate_geometry,
+        build_hamiltonian,
+        build_filename,
+        save_plot,
+    )
+"""
+
+# Molecule data + helpers
+from .molecules import MOLECULES, get_molecule_config  # noqa: F401
+
+# Geometry (bond length, angle scans, parametrized coordinates)
+from .geometry import generate_geometry  # noqa: F401
+
+# Hamiltonian construction (PennyLane + OpenFermion fallback)
+from .hamiltonian import build_hamiltonian  # noqa: F401
+
+# Plotting utilities shared across VQE + QPE
+from .plotting import (
+    build_filename,
+    save_plot,
+    format_molecule_name,
+    format_token,
+)  # noqa: F401
+
+
+__all__ = [
+    # Molecules
+    "MOLECULES",
+    "get_molecule_config",
+
+    # Geometry
+    "generate_geometry",
+
+    # Hamiltonian
+    "build_hamiltonian",
+
+    # Plotting
+    "build_filename",
+    "save_plot",
+    "format_molecule_name",
+    "format_token",
+]