vqe-pennylane 0.2.2__py3-none-any.whl

qpe/hamiltonian.py

@@ -0,0 +1,100 @@
+"""
+common.hamiltonian.py
+==================
+
+Shared molecular configuration + Hamiltonian construction for QPE.
+
+This module mirrors the VQE architecture and ensures that QPE uses
+the *exact same Hamiltonian pipeline* as VQE, guaranteeing consistent
+chemistry, reproducibility, and shared geometry generation.
+
+Provides:
+    • get_molecule_config(name)
+    • generate_geometry(name, param)
+    • build_hamiltonian(symbols, coordinates, charge, basis)
+"""
+
+from __future__ import annotations
+import numpy as np
+import pennylane as qml
+from pennylane import qchem
+from typing import Dict, Any, Tuple
+
+# ---------------------------------------------------------------------
+# Import from VQE: SINGLE SOURCE OF TRUTH
+# ---------------------------------------------------------------------
+from vqe.hamiltonian import (
+    MOLECULES as VQE_MOLECULES,
+    generate_geometry as vqe_generate_geometry,
+)
+
+# Expose VQE molecule registry to QPE
+MOLECULES: Dict[str, Dict[str, Any]] = VQE_MOLECULES
+
+
+def get_molecule_config(name: str) -> Dict[str, Any]:
+    """
+    Retrieve molecular configuration from the unified registry.
+    """
+    if name not in MOLECULES:
+        raise KeyError(
+            f"Unknown molecule '{name}'. Available: {list(MOLECULES.keys())}"
+        )
+    return MOLECULES[name]
+
+
+# ---------------------------------------------------------------------
+# Geometry variation (bond scans, angles)
+# ---------------------------------------------------------------------
+def generate_geometry(name: str, param: float):
+    """
+    Geometry generation wrapper for QPE.
+
+    Calls the VQE geometry generator directly.
+    """
+    return vqe_generate_geometry(name, param)
+
+
+# ---------------------------------------------------------------------
+# Hamiltonian Builder
+# ---------------------------------------------------------------------
+def build_hamiltonian(
+    symbols: list[str],
+    coordinates: np.ndarray,
+    charge: int,
+    basis: str,
+) -> Tuple[qml.Hamiltonian, int]:
+    """
+    Build the molecular Hamiltonian using PennyLane-qchem,
+    with OpenFermion fallback.
+    """
+    try:
+        H, n_qubits = qchem.molecular_hamiltonian(
+            symbols=symbols,
+            coordinates=coordinates,
+            charge=charge,
+            basis=basis,
+        )
+        return H, n_qubits
+
+    except Exception as e_primary:
+        print("⚠️ PennyLane-qchem failed — retrying with OpenFermion backend...")
+
+        try:
+            H, n_qubits = qchem.molecular_hamiltonian(
+                symbols=symbols,
+                coordinates=coordinates,
+                charge=charge,
+                basis=basis,
+                method="openfermion",
+            )
+            return H, n_qubits
+
+        except Exception as e_fallback:
+            raise RuntimeError(
+                "Failed to construct Hamiltonian.\n"
+                f"Primary error:\n  {e_primary}\n"
+                f"OpenFermion fallback error:\n  {e_fallback}\n"
+                "Try installing OpenFermion:\n"
+                "    pip install openfermion openfermionpyscf\n"
+            )

qpe/io_utils.py

@@ -0,0 +1,132 @@
+"""
+qpe/io_utils.py
+================
+Unified result persistence, caching, and filename utilities for QPE.
+
+This version is fully aligned with the VQE I/O stack:
+
+    results/
+      ├── vqe/
+      └── qpe/
+    
+All QPE JSON output files live in: results/qpe/
+
+All PNG figures must be saved through common.plotting.save_plot(),
+which stores everything under: plots/
+
+This file intentionally contains:
+    • No plotting
+    • No PennyLane logic
+    • Only JSON I/O + persistent directory management
+"""
+
+from __future__ import annotations
+import os
+import json
+import hashlib
+from typing import Any, Dict
+
+from vqe_qpe_common.plotting import save_plot, build_filename
+
+
+# ---------------------------------------------------------------------
+# Base Directories (mirrors VQE)
+# ---------------------------------------------------------------------
+BASE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+RESULTS_DIR = os.path.join(BASE_DIR, "results", "qpe")
+
+
+def ensure_dirs() -> None:
+    """Ensure that the QPE results directory exists."""
+    os.makedirs(RESULTS_DIR, exist_ok=True)
+
+
+# ---------------------------------------------------------------------
+# Hashing: repeatable, human-stable, JSON-safe
+# ---------------------------------------------------------------------
+def signature_hash(
+    *,
+    molecule: str,
+    n_ancilla: int,
+    t: float,
+    shots: int | None,
+    noise: Dict[str, float] | None,
+) -> str:
+    """
+    Generate a reproducible hash key for a QPE configuration.
+
+    All important run parameters are included.
+    """
+    key = json.dumps(
+        {
+            "molecule": molecule,
+            "ancilla_qubits": n_ancilla,
+            "time_param": round(float(t), 10),
+            "shots": shots,
+            "noise_params": noise or {},
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:12]
+
+
+def cache_path(molecule: str, key: str) -> str:
+    """Create the canonical JSON file path for a cached QPE result."""
+    ensure_dirs()
+    safe_mol = molecule.replace("+", "plus").replace(" ", "_")
+    return os.path.join(RESULTS_DIR, f"{safe_mol}_QPE_{key}.json")
+
+
+# ---------------------------------------------------------------------
+# JSON Save / Load
+# ---------------------------------------------------------------------
+def save_qpe_result(result: Dict[str, Any]) -> str:
+    """
+    Save a QPE result to JSON using the canonical naming convention.
+
+    Fields that MUST be present in result:
+        molecule, n_ancilla, t, shots, noise
+    """
+    ensure_dirs()
+
+    key = signature_hash(
+        molecule=result["molecule"],
+        n_ancilla=result["n_ancilla"],
+        t=result["t"],
+        shots=result.get("shots", None),
+        noise=result.get("noise", {}),
+    )
+
+    path = cache_path(result["molecule"], key)
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2)
+
+    print(f"💾 Saved QPE result → {path}")
+    return path
+
+
+def load_qpe_result(molecule: str, key: str) -> Dict[str, Any] | None:
+    """
+    Load a cached QPE JSON result if it exists, otherwise return None.
+    """
+    path = cache_path(molecule, key)
+    if os.path.exists(path):
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    return None
+
+
+# ---------------------------------------------------------------------
+# Unified PNG Save Wrapper
+# ---------------------------------------------------------------------
+def save_qpe_plot(filename: str) -> str:
+    """
+    Save a QPE plot using the unified project-wide plotting logic.
+
+    This stores all images under the root-level plots/ directory.
+
+    filename should be produced by build_filename().
+    """
+    return save_plot(filename)

qpe/noise.py

@@ -0,0 +1,47 @@
+"""
+qpe/noise.py
+============
+Noise utility functions for Quantum Phase Estimation (QPE) circuits.
+
+Currently supports:
+  • Depolarizing channel
+  • Amplitude damping channel
+
+Both can be applied together to all wires in a circuit segment.
+"""
+
+from __future__ import annotations
+import pennylane as qml
+from typing import Iterable
+
+def apply_noise_all(
+    wires: Iterable[int],
+    p_dep: float = 0.0,
+    p_amp: float = 0.0,
+) -> None:
+    """Apply depolarizing and/or amplitude damping noise to the given wires.
+
+    This function is intended to be called *inside* a QNode, typically
+    after a unitary operation or ansatz to simulate mixed noise channels.
+
+    Parameters
+    ----------
+    wires : Iterable[int]
+        Wires (qubit indices) on which to apply noise.
+    p_dep : float, optional
+        Depolarizing probability per wire (default = 0.0).
+    p_amp : float, optional
+        Amplitude damping probability per wire (default = 0.0).
+
+    Example
+    -------
+    >>> apply_noise_all([0, 1, 2], p_dep=0.02, p_amp=0.01)
+    """
+    if p_dep <= 0.0 and p_amp <= 0.0:
+        return  # Skip if no noise configured
+
+    for w in wires:
+        if p_dep > 0.0:
+            qml.DepolarizingChannel(p_dep, wires=w)
+        if p_amp > 0.0:
+            qml.AmplitudeDamping(p_amp, wires=w)

qpe/visualize.py

@@ -0,0 +1,212 @@
+"""
+qpe.visualize
+==============
+High-quality plotting utilities for Quantum Phase Estimation (QPE),
+fully unified with the project's global plotting system in
+`common.plotting`.
+
+Provides:
+    • plot_qpe_distribution  – histogram of ancilla measurement outcomes
+    • plot_qpe_sweep         – generic sweep plotting (noise, ancillas, t, etc.)
+
+All plots are saved via:
+    common.plotting.build_filename
+    common.plotting.save_plot
+
+This guarantees:
+    • uniform PNG naming across VQE + QPE
+    • safe molecule names
+    • plots stored in /plots/
+    • consistent DPI / formatting for publication-quality figures
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Any, Sequence, Optional
+
+import matplotlib.pyplot as plt
+
+from vqe_qpe_common.plotting import (
+    build_filename,
+    save_plot,
+    format_molecule_name,
+)
+
+
+# ---------------------------------------------------------------------
+# QPE Probability Distribution Plot
+# ---------------------------------------------------------------------
+def plot_qpe_distribution(
+    result: Dict[str, Any],
+    *,
+    show: bool = True,
+    save: bool = True,
+) -> None:
+    """
+    Plot the ancilla probability distribution from a QPE run.
+
+    Parameters
+    ----------
+    result : dict
+        QPE result dictionary produced by run_qpe().
+    show : bool
+        Display figure window.
+    save : bool
+        Save figure via common plotting system.
+    """
+    probs = result.get("probs", {})
+    if not probs:
+        print("⚠️ No probability data found in QPE result — skipping plot.")
+        return
+
+    molecule = format_molecule_name(result.get("molecule", "QPE"))
+    n_anc = int(result.get("n_ancilla", 0))
+
+    noise = result.get("noise", {})
+    p_dep = float(noise.get("p_dep", 0.0))
+    p_amp = float(noise.get("p_amp", 0.0))
+
+    # Sort by probability descending
+    items = sorted(probs.items(), key=lambda kv: -kv[1])
+    xs = [f"|{b}⟩" for b, _ in items]
+    ys = [float(p) for _, p in items]
+
+    # Figure
+    plt.figure(figsize=(8, 4))
+    plt.bar(xs, ys, alpha=0.85, edgecolor="black")
+
+    plt.xlabel("Ancilla State", fontsize=11)
+    plt.ylabel("Probability", fontsize=11)
+
+    noise_suffix = ""
+    if p_dep > 0 or p_amp > 0:
+        noise_suffix = f" • noise(p_dep={p_dep}, p_amp={p_amp})"
+
+    plt.title(
+        f"{molecule} QPE Distribution ({n_anc} ancilla){noise_suffix}",
+        fontsize=12
+    )
+
+    plt.xticks(rotation=45, ha="right")
+    plt.grid(axis="y", linestyle="--", alpha=0.4)
+    plt.tight_layout()
+
+    if save:
+        fname = build_filename(
+            molecule=molecule,
+            topic="qpe_distribution",
+            extras={
+                "anc": n_anc,
+                "pdep": p_dep,
+                "pamp": p_amp,
+            },
+        )
+        save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()
+
+
+# ---------------------------------------------------------------------
+# Generic QPE Sweep Plot
+# ---------------------------------------------------------------------
+def plot_qpe_sweep(
+    x_values: Sequence[float],
+    y_means: Sequence[float],
+    y_stds: Optional[Sequence[float]] = None,
+    *,
+    molecule: str = "?",
+    sweep_label: str = "Sweep parameter",
+    ylabel: str = "Energy (Ha)",
+    title: str = "QPE Sweep",
+    ref_value: Optional[float] = None,
+    ref_label: str = "Reference",
+    ancilla: Optional[int] = None,
+    noise_params: Optional[Dict[str, float]] = None,
+    show: bool = True,
+    save: bool = True,
+) -> None:
+    """
+    A general-purpose plotting routine for QPE sweeps:
+        • sweep over noise strengths
+        • sweep over t parameter
+        • sweep over number of ancilla qubits
+        • sweep over geometry/bond length (rare for QPE, but possible)
+
+    Parameters
+    ----------
+    x_values : list
+        Parameter values for sweep
+    y_means : list
+        Mean energies or phases
+    y_stds : list, optional
+        Standard deviations
+    molecule : str
+        Molecule label
+    sweep_label : str
+        X-axis label
+    ylabel : str
+        Y-axis label (energy or phase)
+    title : str
+        Plot title
+    ref_value : float, optional
+        Add horizontal reference line
+    ancilla : int, optional
+        Ancilla count for filename metadata
+    noise_params : dict, optional
+        Noise info for filename metadata
+    """
+
+    molecule = format_molecule_name(molecule)
+    p_dep = float((noise_params or {}).get("p_dep", 0.0))
+    p_amp = float((noise_params or {}).get("p_amp", 0.0))
+
+    plt.figure(figsize=(6.5, 4.5))
+
+    if y_stds is not None:
+        plt.errorbar(
+            x_values,
+            y_means,
+            yerr=y_stds,
+            fmt="o-",
+            capsize=4,
+            label="QPE mean ± std",
+        )
+    else:
+        plt.plot(x_values, y_means, "o-", label="QPE mean")
+
+    if ref_value is not None:
+        plt.axhline(
+            ref_value,
+            linestyle="--",
+            color="gray",
+            label=ref_label,
+            alpha=0.8,
+        )
+
+    plt.xlabel(sweep_label)
+    plt.ylabel(ylabel)
+    plt.title(f"{molecule} – {title}")
+    plt.grid(True, linestyle="--", alpha=0.5)
+    plt.legend()
+    plt.tight_layout()
+
+    if save:
+        fname = build_filename(
+            molecule=molecule,
+            topic="qpe_sweep",
+            extras={
+                "anc": ancilla,
+                "pdep": p_dep,
+                "pamp": p_amp,
+                "tag": title.replace(" ", "_").lower(),
+            },
+        )
+        save_plot(fname)
+
+    if show:
+        plt.show()
+    else:
+        plt.close()

vqe/__init__.py

@@ -0,0 +1,118 @@
+"""
+vqe
+---
+A modular Variational Quantum Eigensolver (VQE) and SSVQE toolkit built on PennyLane.
+
+Public API:
+    - run_vqe
+    - run_ssvqe
+    - run_vqe_noise_sweep
+    - run_vqe_optimizer_comparison
+    - run_vqe_ansatz_comparison
+    - run_vqe_multi_seed_noise
+    - run_vqe_geometry_scan
+    - run_vqe_mapping_comparison
+
+    - get_ansatz, init_params, ANSATZES
+    - get_optimizer
+    - build_hamiltonian, generate_geometry
+    - make_run_config_dict, run_signature, save_run_record, ensure_dirs
+
+    - Plotting helpers (visualize.*)
+"""
+
+__version__ = "0.2.0"
+
+# ------------------------------------------------------------------
+# Core VQE APIs
+# ------------------------------------------------------------------
+from .core import (
+    run_vqe,
+    run_vqe_noise_sweep,
+    run_vqe_optimizer_comparison,
+    run_vqe_ansatz_comparison,
+    run_vqe_multi_seed_noise,
+    run_vqe_geometry_scan,
+    run_vqe_mapping_comparison,
+)
+
+# ------------------------------------------------------------------
+# Ansatz registry & utilities
+# ------------------------------------------------------------------
+from .ansatz import get_ansatz, init_params, ANSATZES
+
+# ------------------------------------------------------------------
+# Optimizers
+# ------------------------------------------------------------------
+from .optimizer import get_optimizer
+
+# ------------------------------------------------------------------
+# Hamiltonian & geometry
+# ------------------------------------------------------------------
+from .hamiltonian import build_hamiltonian, generate_geometry
+
+# ------------------------------------------------------------------
+# I/O utilities (config, hashing, results)
+# ------------------------------------------------------------------
+from .io_utils import (
+    make_run_config_dict,
+    run_signature,
+    save_run_record,
+    ensure_dirs,
+)
+
+# ------------------------------------------------------------------
+# Visualization utilities
+# ------------------------------------------------------------------
+from .visualize import (
+    plot_convergence,
+    plot_ssvqe_convergence_multi,
+    plot_optimizer_comparison,
+    plot_ansatz_comparison,
+    plot_noise_statistics,
+)
+
+# ------------------------------------------------------------------
+# SSVQE
+# ------------------------------------------------------------------
+from .ssvqe import run_ssvqe
+
+
+__all__ = [
+    # Core VQE API
+    "run_vqe",
+    "run_vqe_noise_sweep",
+    "run_vqe_optimizer_comparison",
+    "run_vqe_ansatz_comparison",
+    "run_vqe_multi_seed_noise",
+    "run_vqe_geometry_scan",
+    "run_vqe_mapping_comparison",
+
+    # Ansatz tools
+    "get_ansatz",
+    "init_params",
+    "ANSATZES",
+
+    # Optimizers
+    "get_optimizer",
+
+    # Hamiltonian
+    "build_hamiltonian",
+    "generate_geometry",
+
+    # I/O
+    "make_run_config_dict",
+    "run_signature",
+    "save_run_record",
+    "ensure_dirs",
+
+    # SSVQE
+    "run_ssvqe",
+
+    # Visualization
+    "plot_convergence",
+    "plot_optimizer_comparison",
+    "plot_ansatz_comparison",
+    "plot_noise_statistics",
+    "plot_ssvqe_convergence_multi",
+]