version 0.3.15

Author: SidRichardsQuantum

.github/workflows/tests.yml

@@ -5,9 +5,28 @@ on:
     branches: ["main"]
   pull_request:
     branches: ["main"]
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+    inputs:
+      python-version:
+        description: "Python version for the full integration job"
+        required: false
+        default: "3.12"
+        type: string
+      pytest-args:
+        description: "pytest arguments for the full integration job"
+        required: false
+        default: "-q -o addopts="
+        type: string
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  test:
+  fast-tests:
+    name: fast tests (${{ matrix.python-version }})
     runs-on: ubuntu-latest
 
     strategy:
@@ -42,6 +61,42 @@ jobs:
           python -m pip --version
           python -m pip freeze | sed -n '1,200p'
 
-      - name: Run tests
+      - name: Run fast tests
         run: |
           pytest -q
+
+  full-tests:
+    name: full integration tests
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+
+    env:
+      PYTHONUTF8: "1"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs['python-version'] || '3.12' }}
+          cache: "pip"
+          cache-dependency-path: |
+            pyproject.toml
+
+      - name: Install package + test deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+          python -m pip install pyscf
+
+      - name: Debug environment
+        run: |
+          python --version
+          python -m pip --version
+          python -m pip freeze | sed -n '1,200p'
+
+      - name: Run full test suite
+        run: |
+          pytest ${{ inputs['pytest-args'] || '-q -o addopts=' }}

CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+No unreleased changes.
+
+---
+
+## [0.3.25] - April 21, 2026
+
 ### Changed
 
 - **Faster default pytest target**
@@ -14,6 +20,29 @@ All notable changes to this project will be documented in this file.
   `pytest -q` runs the fast development suite by default. The full integration
   suite remains available with `pytest -q -o addopts=''`.
 
+- **Split fast and full test CI**
+
+  Updated the tests workflow so pull requests and pushes run the fast pytest
+  matrix, while the full integration suite runs on a scheduled/manual Python
+  3.12 job.
+
+- **Lightweight CLI help startup**
+
+  Made package and CLI public-entrypoint imports lazy so `python -m vqe --help`,
+  `python -m qpe --help`, and `python -m qite --help` avoid importing the
+  PennyLane/OpenFermion stack until a command actually runs.
+
+- **Shared lazy public API exports**
+
+  Added a small shared lazy-export helper and used it across `common`, `vqe`,
+  `qpe`, and `qite` so public imports remain stable without duplicating
+  package-level `__getattr__` boilerplate.
+
+- **Slimmer fast excited-state smoke coverage**
+
+  Split EOM-VQE and EOM-QSE fast tests into single-run smoke checks while
+  keeping the more expensive deterministic rerun checks in the full slow suite.
+
 - **Tightened public API reference**
 
   Reworked the Sphinx API reference into task-oriented sections for primary

README.md

@@ -401,8 +401,8 @@ Variational_Quantum_Eigensolver/
 
 ## Testing
 
-The default pytest target is the fast development suite. Slow chemistry and
-subprocess CLI integration tests are marked separately.
+The default pytest target is the fast development suite. Slow chemistry checks
+and selected subprocess CLI integration tests are marked separately.
 
 ```bash
 pytest -q

USAGE.md

@@ -850,8 +850,9 @@ qite run-qrte --force
 
 ## Testing
 
-The default pytest target runs the fast development suite. Slow chemistry and
-subprocess CLI integration tests are available behind pytest markers.
+The default pytest target runs the fast development suite. Slow chemistry
+checks and selected subprocess CLI integration tests are available behind
+pytest markers.
 
 ```bash
 pytest -q

common/__init__.py

@@ -4,93 +4,79 @@
 
 Shared utilities used across VQE, QPE, and future solvers.
 
-This subpackage contains:
-    • common.molecules   — canonical molecule registry
-    • common.geometry    — unified geometry generators (bond/angle scans)
-    • common.hamiltonian — single source of truth for Hamiltonian construction
-    • 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.
+The public exports are resolved lazily so importing high-level packages for
+metadata or CLI help does not also import the quantum chemistry stack.
 """
 
 from __future__ import annotations
 
 from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from typing import Any
 
 from . import mpl_env as _mpl_env  # noqa: F401
+from .lazy import LazyExports, list_exports, load_export
 
 try:
     __version__ = _pkg_version("vqe-pennylane")
 except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0"
 
 
-# Molecule data + helpers
-from .molecules import MOLECULES, get_molecule_config  # noqa: F401, E402
-
-# Geometry (bond length, angle scans, parametrized coordinates)
-from .geometry import generate_geometry  # noqa: F401, E402
-
-# Hamiltonian construction (PennyLane + OpenFermion fallback)
-from .hamiltonian import (  # noqa: F401, E402
-    build_hamiltonian,
-    get_exact_spectrum,
-    summarize_registry_coverage,
-)
-from .benchmarks import (  # noqa: F401, E402
-    analyze_qpe_result,
-    exact_ground_energy_for_problem,
-    ionization_energy_panel,
-    qpe_branch_candidates,
-    qpe_calibration_plan,
-    summarize_problem,
-    summary_stats,
-    timed_call,
-)
-from .metrics import compute_fidelity  # noqa: F401, E402
-from .problem import ResolvedProblem, resolve_problem  # noqa: F401, E402
-
-# Molecule visualization
-from .molecule_viz import (
-    plot_molecule,
-    infer_bonds,
-    infer_angles_from_bonds,
-)  # noqa: F401, E402
-
-# Plotting utilities shared across VQE + QPE
-from .plotting import build_filename, save_plot  # noqa: F401, E402
-from .naming import format_molecule_name, format_token  # noqa: F401, E402
-
-__all__ = [
+_EXPORTS: LazyExports = {
     # Molecules
-    "MOLECULES",
-    "get_molecule_config",
+    "MOLECULES": ("common.molecules", "MOLECULES"),
+    "get_molecule_config": ("common.molecules", "get_molecule_config"),
     # Geometry
-    "generate_geometry",
+    "generate_geometry": ("common.geometry", "generate_geometry"),
     # Hamiltonian
-    "build_hamiltonian",
-    "get_exact_spectrum",
-    "summarize_registry_coverage",
-    "timed_call",
-    "summary_stats",
-    "qpe_branch_candidates",
-    "analyze_qpe_result",
-    "qpe_calibration_plan",
-    "exact_ground_energy_for_problem",
-    "ionization_energy_panel",
-    "summarize_problem",
-    "compute_fidelity",
-    "ResolvedProblem",
-    "resolve_problem",
+    "build_hamiltonian": ("common.hamiltonian", "build_hamiltonian"),
+    "get_exact_spectrum": ("common.hamiltonian", "get_exact_spectrum"),
+    "summarize_registry_coverage": (
+        "common.hamiltonian",
+        "summarize_registry_coverage",
+    ),
+    # Benchmarks/helpers
+    "timed_call": ("common.benchmarks", "timed_call"),
+    "summary_stats": ("common.benchmarks", "summary_stats"),
+    "qpe_branch_candidates": ("common.benchmarks", "qpe_branch_candidates"),
+    "analyze_qpe_result": ("common.benchmarks", "analyze_qpe_result"),
+    "qpe_calibration_plan": ("common.benchmarks", "qpe_calibration_plan"),
+    "exact_ground_energy_for_problem": (
+        "common.benchmarks",
+        "exact_ground_energy_for_problem",
+    ),
+    "ionization_energy_panel": ("common.benchmarks", "ionization_energy_panel"),
+    "summarize_problem": ("common.benchmarks", "summarize_problem"),
+    "compute_fidelity": ("common.metrics", "compute_fidelity"),
+    "ResolvedProblem": ("common.problem", "ResolvedProblem"),
+    "resolve_problem": ("common.problem", "resolve_problem"),
     # Plotting
-    "build_filename",
-    "save_plot",
-    "format_molecule_name",
-    "format_token",
+    "build_filename": ("common.plotting", "build_filename"),
+    "save_plot": ("common.plotting", "save_plot"),
+    "format_molecule_name": ("common.naming", "format_molecule_name"),
+    "format_token": ("common.naming", "format_token"),
     # Molecule visualization
-    "plot_molecule",
-    "infer_bonds",
-    "infer_angles_from_bonds",
+    "plot_molecule": ("common.molecule_viz", "plot_molecule"),
+    "infer_bonds": ("common.molecule_viz", "infer_bonds"),
+    "infer_angles_from_bonds": ("common.molecule_viz", "infer_angles_from_bonds"),
+}
+
+__all__ = [
+    "__version__",
+    *_EXPORTS.keys(),
 ]
+
+
+def __getattr__(name: str) -> Any:
+    return load_export(
+        package_name=__name__,
+        package_globals=globals(),
+        exports=_EXPORTS,
+        name=name,
+    )
+
+
+def __dir__() -> list[str]:
+    import sys
+
+    return list_exports(sys.modules[__name__], _EXPORTS)

common/lazy.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+LazyExports = dict[str, tuple[str, str]]
+
+
+def load_export(
+    *,
+    package_name: str,
+    package_globals: dict[str, Any],
+    exports: LazyExports,
+    name: str,
+) -> Any:
+    """Resolve and memoize a lazily exported package attribute."""
+    try:
+        module_name, attr_name = exports[name]
+    except KeyError as exc:
+        raise AttributeError(
+            f"module {package_name!r} has no attribute {name!r}"
+        ) from exc
+
+    value = getattr(import_module(module_name), attr_name)
+    package_globals[name] = value
+    return value
+
+
+def list_exports(module: ModuleType, exports: LazyExports) -> list[str]:
+    """Return names exposed by a package module plus its lazy exports."""
+    return sorted(set(vars(module)) | set(exports))