dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/qec.py

@@ -0,0 +1,20 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.physics.qec as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.qec import pauli_commutes, compute_syndrome, erasure_aware_decode`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.physics.qec directly in new code.
+"""
+from dense_evolution.physics.qec import (
+    pauli_commutes, compute_syndrome, erasure_aware_decode, pymatching_decode,
+    blind_minimum_weight_decode, decode_with_erasure_fallback,
+    counts_in_intervals_dimension, nearest_coset_decode, erasure_ml_decode,
+    peeling_decode, union_find_decode, matching_erasure_decode,
+    estimate_edge_probabilities_from_detection_events,
+)
+
+__all__ = [
+    'pauli_commutes', 'compute_syndrome', 'erasure_aware_decode', 'pymatching_decode',
+    'blind_minimum_weight_decode', 'decode_with_erasure_fallback',
+    'counts_in_intervals_dimension', 'nearest_coset_decode', 'erasure_ml_decode', 'peeling_decode', 'union_find_decode', 'matching_erasure_decode',
+    'estimate_edge_probabilities_from_detection_events',
+]

dense_evolution/qft.py

@@ -0,0 +1,9 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.circuits.qft as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.qft import qft`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.circuits.qft directly in new code.
+"""
+from dense_evolution.circuits.qft import qft
+
+__all__ = ['qft']

dense_evolution/qmmm/__init__.py

@@ -0,0 +1,13 @@
+from .forces import (
+    ATOMIC_MASSES_AMU, compute_hellmann_feynman_forces, md_step, run_md_trajectory,
+    MIN_NUCLEAR_DISTANCE_ANGSTROM, ACCEL_CONVERSION,
+)
+from .region import partition_qm_mm_region, sliced_geometry, ANGSTROM_TO_BOHR, CH_BOND_BOHR
+from .propagation import propagate_relevance
+
+__all__ = [
+    "ATOMIC_MASSES_AMU", "compute_hellmann_feynman_forces", "md_step", "run_md_trajectory",
+    "MIN_NUCLEAR_DISTANCE_ANGSTROM", "ACCEL_CONVERSION",
+    "partition_qm_mm_region", "sliced_geometry", "ANGSTROM_TO_BOHR", "CH_BOND_BOHR",
+    "propagate_relevance",
+]

dense_evolution/qmmm/ase_bridge.py

@@ -0,0 +1,97 @@
+"""
+ASE Calculator bridge for dense_evolution.native_hf (issue #288).
+
+Motivation: QM/MM point 5's basis-flexibility test (Dense-Evolution-
+Discovery, docs/qmmm_bond_order_and_embedding.md) needed a richer basis
+(6-31G*) to test a real hypothesis about STO-3G's rigidity -- native_hf
+already supports arbitrary basis names via `build_energy_fn`'s own
+`basis_name` string parameter (nothing was actually hardcoded at the
+library level; the QM/MM scripts' own `BASIS = "sto-3g"` constants were
+just a script-level convenience). What native_hf does NOT give for free
+is interop with the wider Python computational-chemistry ecosystem (ASE
+Atoms objects, ASE's own optimizers/MD drivers, other engines' Atoms
+representations) -- this bridge is exactly that interop layer, not a new
+basis-set capability.
+
+Requires ASE (the `ase` extra: pip install dense-evolution[ase]).
+"""
+import numpy as np
+
+HARTREE_TO_EV = 27.211386245988  # CODATA, matches this project's own use of scipy.constants elsewhere (dense_evolution.qmmm.forces.ACCEL_CONVERSION)
+ANGSTROM_TO_BOHR = 1.8897259886
+
+
+def _import_ase_calculator():
+    try:
+        from ase.calculators.calculator import Calculator, all_changes
+    except ImportError as exc:
+        raise ImportError(
+            "dense_evolution.qmmm.ase_bridge needs ASE, an optional dependency "
+            "(pip install dense-evolution[ase]); it is not installed."
+        ) from exc
+    return Calculator, all_changes
+
+
+class DenseEvolutionCalculator:
+    """An ASE Calculator backed by dense_evolution.native_hf's own
+    differentiable RHF energy (build_energy_fn) -- real Obara-Saika
+    integrals and SCF, not a stub. `basis_name` is a plain string, passed
+    straight through to native_hf (e.g. "sto-3g", "6-31g*", any basis
+    basis_set_exchange has data for).
+
+    ASE units: eV, Angstrom (this class converts from native_hf's own
+    Hartree/Bohr at the boundary; everything inside native_hf itself
+    stays atomic units).
+
+    Only `energy` is implemented -- native_hf's forces come from
+    dense_evolution.qmmm.forces.compute_hellmann_feynman_forces (a
+    separate, already-real Hellmann-Feynman implementation with its own
+    finite-difference derivative and its own molecule-catalog-shaped
+    calling convention); this bridge does not reimplement or wrap that
+    here.
+
+    Examples
+    --------
+    >>> from ase import Atoms
+    >>> from dense_evolution.qmmm.ase_bridge import DenseEvolutionCalculator
+    >>> h2 = Atoms('H2', positions=[[0, 0, 0], [0, 0, 0.7414]])
+    >>> h2.calc = DenseEvolutionCalculator(atomic_numbers=[1, 1], nuclear_charges=[1.0, 1.0],
+    ...                                    n_electrons=2, basis_name="sto-3g")
+    >>> round(h2.get_potential_energy(), 2)
+    -30.39
+    """
+
+    implemented_properties = ["energy"]
+
+    def __new__(cls, atomic_numbers, nuclear_charges, n_electrons, basis_name):
+        Calculator, all_changes = _import_ase_calculator()
+
+        class _Impl(Calculator):
+            implemented_properties = ["energy"]
+
+            def __init__(self):
+                super().__init__()
+                self._atomic_numbers = atomic_numbers
+                self._nuclear_charges = nuclear_charges
+                self._n_electrons = n_electrons
+                self._basis_name = basis_name
+                self._energy_fn = None
+                self._reference_geometry_bohr = None
+
+            def calculate(self, atoms=None, properties=("energy",), system_changes=all_changes):
+                super().calculate(atoms, properties, system_changes)
+                from dense_evolution.config import ensure_x64
+                from dense_evolution.native_hf.differentiable import build_energy_fn
+                ensure_x64()
+
+                geometry_bohr = np.asarray(atoms.get_positions()) * ANGSTROM_TO_BOHR
+                if self._energy_fn is None or "numbers" in system_changes:
+                    self._reference_geometry_bohr = geometry_bohr
+                    self._energy_fn = build_energy_fn(
+                        self._atomic_numbers, self._nuclear_charges, self._n_electrons,
+                        self._basis_name, self._reference_geometry_bohr,
+                    )
+                energy_hartree = float(self._energy_fn(geometry_bohr))
+                self.results["energy"] = energy_hartree * HARTREE_TO_EV
+
+        return _Impl()

dense_evolution/qmmm/forces.py

@@ -0,0 +1,388 @@
+"""
+Real Hellmann-Feynman nuclear forces and a real Velocity-Verlet MD step
+for this project's real molecule catalog -- no fabricated geometry,
+charges, or Hamiltonian anywhere.
+
+Forces are F = -dE/dR (E = <psi|H(R)|psi>, psi held fixed -- the
+Hellmann-Feynman theorem exactly), with H(R) this project's own real
+Hamiltonian at geometry R (dashboard_core.hamiltonians.
+build_molecular_hamiltonian -- the same real Hartree-Fock/Jordan-Wigner
+pipeline already used throughout dashboard_core, not a separate one built
+for this module). The derivative itself is a real central finite
+difference (step verified converged: h=0.001 and h=0.0005 Angstrom agree
+to 4 significant figures against H2), not PennyLane's autograd through
+the full qchem pipeline.
+
+An earlier version used qml.grad to differentiate PennyLane's
+"dhf"-method Hamiltonian directly -- mathematically the more elegant
+exact-derivative approach, and it worked locally, but failed identically
+on both Ubuntu and macOS CI runners with the exact same PennyLane
+version (0.45.1) that passed locally on Windows: `TypeError: unsupported
+operand type(s) for +: 'NotImplementedType' and 'NotImplementedType'`, a
+signature of autograd hitting an operation its VJP system doesn't
+support, apparently platform-dependent inside PennyLane/autograd's own
+internals. Rather than depend on that fragile cross-platform behavior,
+this module differentiates numerically instead, reusing the same dense
+Hamiltonian construction already verified elsewhere in this codebase.
+
+An even earlier version tried adding an external classical point-charge
+potential directly to the post-Jordan-Wigner dense Hamiltonian (mirroring
+legacy/dash.py's QMMMForceEngine). That shape-mismatched (the JW matrix
+indexes many-body qubit basis states, not one row per atom) and was
+dropped for the same direct-differentiation idea, minus the fragile
+autograd dependency.
+
+Verified 2026-08-05 against H2: force ~0.0154 Hartree/Angstrom at the
+real equilibrium bond length (0.7414 A, small residual expected since
+the electronic state is evaluated at fixed geometry -- clamped-nucleus
+Hellmann-Feynman, not a fully relaxed force), rising sharply and
+correctly signed as a restoring force at a stretched 1.2 A bond.
+
+Moved here from dashboard_core/qmmm.py (previously the only "qmmm" code
+in this project, doing full-QM Hellmann-Feynman forces on a small fixed
+molecule catalog -- no MM region, no partitioning) so this module lives
+in the library alongside region.py/propagation.py (real QM/MM region
+partitioning and embedding, Dense-Evolution issue #283) instead of being
+buried inside the dashboard tool. dashboard_core.qmmm now re-exports
+these names for backward compatibility -- the dashboard code did not
+change.
+"""
+import numpy as np
+from scipy import constants as _c
+
+__all__ = [
+    'ATOMIC_MASSES_AMU', 'compute_hellmann_feynman_forces', 'md_step', 'run_md_trajectory',
+    'MIN_NUCLEAR_DISTANCE_ANGSTROM', 'ACCEL_CONVERSION',
+]
+
+
+def _import_dashboard_hamiltonians():
+    # Lazy, not module-level: dense_evolution.qmmm is walked by
+    # test_imports.py::test_all_submodules_importable_with_only_base_dependencies,
+    # which must succeed with ONLY dense_evolution's own base dependencies
+    # installed. dashboard_core is a separate, heavier, optional tool (its
+    # own 'dashboard' extra: streamlit, qiskit, pennylane, ...) built ON
+    # TOP of this library -- the core library must never require it just
+    # to be imported. A real bug found in CI: an earlier version of this
+    # module imported dashboard_core.hamiltonians at module level, so
+    # merely importing dense_evolution.qmmm (even for region.py/
+    # propagation.py, which need neither dashboard_core nor this
+    # function) forced a dashboard_core import and broke that test.
+    try:
+        from dashboard_core.hamiltonians import MOLECULE_CATALOG, build_molecular_hamiltonian
+    except ImportError as exc:
+        raise ImportError(
+            "dense_evolution.qmmm.forces's Hellmann-Feynman/MD functions need "
+            "dashboard_core (the 'dashboard' extra: pip install dense-evolution[dashboard]); "
+            "it is not installed."
+        ) from exc
+    return MOLECULE_CATALOG, build_molecular_hamiltonian
+
+
+# A plain physical-safety-floor constant (0.3 A -- shorter than any real
+# covalent bond dashboard_core's molecule catalog could ever produce),
+# not something that needs dashboard_core's dynamic Hamiltonian
+# machinery -- kept as a real, always-available module-level constant
+# here (must stay numerically in sync with
+# dashboard_core.hamiltonians.MIN_NUCLEAR_DISTANCE_ANGSTROM, which is
+# itself just this same literal).
+MIN_NUCLEAR_DISTANCE_ANGSTROM = 0.3
+
+# MIN_NUCLEAR_DISTANCE_ANGSTROM itself lives in hamiltonians.py now (prog.txt,
+# dashboard_core audit point 1d) -- this module already imports several
+# other names from there (see above), so importing this one too is not
+# circular; it was previously redefined here under a comment reasoning
+# the opposite (that importing it WOULD be circular), which had the
+# import direction backwards. Real MD safety floor, not a fabricated
+# number: shorter than any real covalent bond this project's molecule
+# catalog could ever produce (H2's own equilibrium is 0.7414 A) --
+# run_md_trajectory checks new positions against this after every
+# Velocity-Verlet step, since Hartree-Fock at a near-collided geometry
+# (the failure mode a too-large dt_fs drives light atoms like H toward)
+# diverges rather than raising a clear error, making the actual cause
+# hard to diagnose from the resulting crash. md_step itself stays a
+# bare, unchecked F=ma primitive -- the check belongs at
+# run_md_trajectory's real-simulation boundary, not the mechanical
+# formula (tests exercise md_step directly with synthetic, not
+# physically meaningful, starting positions).
+
+
+def _assert_no_nuclear_collision(positions, step, dt_fs):
+    """Raises RuntimeError if any two atoms in `positions` (n_atoms, 3)
+    are closer than MIN_NUCLEAR_DISTANCE_ANGSTROM -- see that constant's
+    comment for why. A no-op for a single atom (nothing to compare)."""
+    if positions.shape[0] < 2:
+        return
+    diffs = positions[:, None, :] - positions[None, :, :]
+    dists = np.linalg.norm(diffs, axis=-1)
+    np.fill_diagonal(dists, np.inf)
+    min_dist = float(dists.min())
+    if min_dist < MIN_NUCLEAR_DISTANCE_ANGSTROM:
+        raise RuntimeError(
+            f"MD trajectory diverged: two atoms are {min_dist:.4f} A apart at step "
+            f"{step + 1} (below the {MIN_NUCLEAR_DISTANCE_ANGSTROM} A safety floor -- "
+            f"no real covalent bond in this catalog is that short). This almost always "
+            f"means dt_fs={dt_fs} is too large for the forces involved -- light atoms "
+            f"like H accelerate sharply and overshoot in a single step. Try a smaller "
+            f"dt_fs before rerunning."
+        )
+
+# Real standard atomic weights (amu) for the elements this project's real
+# molecule catalog actually uses (H2, HeH+, H3+, LiH, H2O) -- only what's
+# needed, not the full periodic table, so nothing here is an unverified
+# guess for an element no catalog molecule contains.
+ATOMIC_MASSES_AMU = {'H': 1.008, 'He': 4.0026, 'Li': 6.94, 'O': 16.00, 'Si': 28.085}
+
+# a [Angstrom/fs^2] = ACCEL_CONVERSION * F[Hartree/Angstrom] / mass[amu]
+# -- derived from CODATA (scipy.constants), verified 2026-08-05:
+# (hartree_J / angstrom_m) / amu_kg * fs_s**2 / angstrom_m = 0.262550...
+ACCEL_CONVERSION = (
+    (_c.physical_constants['Hartree energy'][0] / 1e-10)
+    / _c.physical_constants['atomic mass constant'][0]
+    * (1e-15 ** 2) / 1e-10
+)
+
+
+def _reference_ground_state(symbols, geometry, charge, mapping, active_electrons=None, active_orbitals=None):
+    """Real ground-state eigenvector of the molecule's real Hamiltonian at
+    the given geometry, via build_molecular_hamiltonian -- the same
+    construction dashboard_core.hamiltonians' own energy/VQE panels use,
+    with its own native_hf fallback for elements outside PennyLane's
+    bundled STO-3G table (e.g. Si). Not part of the differentiable path
+    -- this is evaluated once at a fixed geometry to get a real
+    electronic state, then held fixed while forces are computed at
+    (possibly different) geometries, exactly as the Hellmann-Feynman
+    theorem requires.
+
+    BUG FIX (prog.txt, dashboard_core audit point 3a): this used to call
+    qml.qchem.Molecule/molecular_hamiltonian directly instead of going
+    through build_molecular_hamiltonian, so any molecule needing the
+    native_hf fallback (Si2 is in MOLECULE_CATALOG precisely because it
+    needs it) crashed here with PennyLane's own "basis set data is not
+    available for Si" error -- even though the rest of this module
+    (energy_at, below) already used the fallback-aware path and would
+    otherwise have worked."""
+    _MOLECULE_CATALOG, build_molecular_hamiltonian = _import_dashboard_hamiltonians()
+    h_matrix, n_qubits = build_molecular_hamiltonian(
+        symbols, geometry, charge, mapping, active_electrons, active_orbitals)
+    eigvals, eigvecs = np.linalg.eigh(h_matrix)
+    return eigvecs[:, 0], float(eigvals[0]), n_qubits
+
+
+def compute_hellmann_feynman_forces(name: str, statevector=None, mapping: str = "jordan_wigner",
+                                     geometry=None, fd_step_angstrom: float = 0.001):
+    """Real Hellmann-Feynman forces (Hartree/Angstrom) on every nucleus of
+    MOLECULE_CATALOG[name]: F = -d<psi|H(R)|psi>/dR, with H(R) this
+    project's own real Hamiltonian (build_molecular_hamiltonian) and psi
+    held fixed. The derivative is a real central finite difference
+    (fd_step_angstrom, default 0.001 A -- verified converged against
+    0.0005 A to 4 significant figures for H2), not automatic
+    differentiation (see module docstring for why). statevector defaults
+    to the molecule's own real Hartree-Fock ground state (computed at its
+    catalog geometry) -- pass a VQE-converged state instead to get forces
+    evaluated on that state. geometry defaults to the catalog's own
+    equilibrium geometry -- an MD loop moving the nuclei must pass its
+    own current positions here at each step, or every step evaluates the
+    same fixed catalog geometry again (the actual bug this parameter was
+    added to fix: run_md_trajectory originally never passed its own
+    updated positions back in here).
+
+    Cost (prog.txt, dashboard_core audit point 4a): the central-difference
+    derivative evaluates energy_at 6*n_atoms+1 times (H2's 2 atoms -> 13
+    Hamiltonian builds per call, each at a genuinely different geometry).
+    This looks like it should be cacheable -- build_molecular_hamiltonian
+    already caches by exact geometry -- but it isn't in practice: every
+    one of the 13 geometries differs by fd_step_angstrom, so every call
+    is a cache miss. Measured directly on H2 (dhf/PennyLane path) before
+    deciding not to add a "cache the Pauli-term basis" layer here: HF +
+    fermion-to-qubit mapping took 0.130s, Pauli-term extraction 0.0005s,
+    dense matrix assembly 0.0031s -- the Hartree-Fock solve itself is
+    96%+ of the cost, not the bookkeeping after it, so caching the
+    Pauli-term structure would save a few percent at best, not the
+    6*n_atoms multiplier prog.txt's framing suggests. A real geometry
+    change requires a real HF re-solve regardless of how its output gets
+    packaged afterward -- see the module docstring's own account of why
+    analytic differentiation (which WOULD avoid re-solving HF this many
+    times) was tried and dropped for a real cross-platform PennyLane/
+    autograd bug, not reattempted here.
+
+    Parameters
+    ----------
+    name : str
+        A key from `MOLECULE_CATALOG` (e.g. one of `list(MOLECULE_CATALOG)`
+        -- these are descriptive strings like `"H2 (Idrogeno) - R = 0.7414
+        A [equilibrio reale]"`, not bare element symbols like `"H2"`).
+    statevector, mapping, geometry, fd_step_angstrom : see description above.
+
+    Returns
+    -------
+    dict
+        `name`, `symbols`, `energy_hartree`, `positions_angstrom`,
+        `forces_hartree_per_angstrom`, `force_norm`.
+
+    Examples
+    --------
+    >>> from dense_evolution.qmmm import compute_hellmann_feynman_forces
+    >>> from dashboard_core.hamiltonians import MOLECULE_CATALOG
+    >>> h2 = [k for k in MOLECULE_CATALOG if k.startswith("H2 ")][0]
+    >>> result = compute_hellmann_feynman_forces(h2)
+    >>> round(result['energy_hartree'], 4)
+    -1.1373
+    >>> 0.01 < result['force_norm'] < 0.02  # small residual at equilibrium, not exactly zero
+    True
+    """
+    MOLECULE_CATALOG, build_molecular_hamiltonian = _import_dashboard_hamiltonians()
+    if name not in MOLECULE_CATALOG:
+        raise ValueError(f"unknown molecule {name!r}; available: {sorted(MOLECULE_CATALOG)}")
+    spec = MOLECULE_CATALOG[name]
+    symbols = spec["symbols"]
+    if geometry is None:
+        geometry = spec["geometry"]() if callable(spec["geometry"]) else spec["geometry"]
+    charge = spec["charge"]
+    # BUG FIX (prog.txt, dashboard_core audit point 3a): these two were
+    # never read from spec at all, so any catalog entry needing active-
+    # space reduction (Si2 is the reason it's in MOLECULE_CATALOG) built
+    # the FULL Hamiltonian instead of the reduced one here -- for Si2
+    # specifically, 36 qubits instead of the intended 8, which
+    # SafeMemoryGuard correctly refuses to allocate. Both
+    # _reference_ground_state and energy_at below need these to build
+    # the same, correctly-reduced Hamiltonian this molecule's other
+    # dashboard panels (VQE, energy scan) already use.
+    active_electrons = spec.get("active_electrons")
+    active_orbitals = spec.get("active_orbitals")
+
+    unknown = [s for s in symbols if s not in ATOMIC_MASSES_AMU]
+    if unknown:
+        raise ValueError(f"no real atomic mass on file for {unknown} -- add to "
+                          f"ATOMIC_MASSES_AMU before using this molecule here")
+
+    if statevector is None:
+        statevector, _gs_energy, _n_qubits = _reference_ground_state(
+            symbols, geometry, charge, mapping, active_electrons, active_orbitals)
+    sv = np.asarray(statevector, dtype=np.complex128)
+    geometry = np.asarray(geometry, dtype=np.float64)
+
+    def energy_at(geom):
+        h_matrix, _n_qubits = build_molecular_hamiltonian(
+            symbols, geom, charge, mapping, active_electrons, active_orbitals)
+        return float(np.real(np.vdot(sv, h_matrix @ sv)))
+
+    energy = energy_at(geometry)
+    forces = np.zeros_like(geometry)
+    h = fd_step_angstrom
+    for i in range(geometry.shape[0]):
+        for j in range(3):
+            geom_plus = geometry.copy()
+            geom_plus[i, j] += h
+            geom_minus = geometry.copy()
+            geom_minus[i, j] -= h
+            forces[i, j] = -(energy_at(geom_plus) - energy_at(geom_minus)) / (2 * h)
+
+    return {
+        "name": name,
+        "symbols": symbols,
+        "energy_hartree": energy,
+        "positions_angstrom": geometry.tolist(),
+        "forces_hartree_per_angstrom": forces.tolist(),
+        "force_norm": float(np.linalg.norm(forces)),
+    }
+
+
+def md_step(positions_angstrom, velocities_angstrom_per_fs, forces_hartree_per_angstrom,
+            symbols, dt_fs: float = 0.5):
+    """One real Velocity-Verlet half-step (v(t+dt/2) = v(t) + a(t)*dt/2,
+    r(t+dt) = r(t) + v(t+dt/2)*dt) using the real Hellmann-Feynman forces
+    above and each atom's real atomic mass -- ordinary classical Newtonian
+    mechanics (F=ma), nothing invented. Positions in Angstrom, velocities
+    in Angstrom/fs, forces in Hartree/Angstrom, dt in femtoseconds.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dense_evolution.qmmm import md_step
+    >>> positions = np.array([[0, 0, 0.0], [0, 0, 0.7414]])   # H2 at equilibrium
+    >>> velocities = np.zeros_like(positions)
+    >>> forces = np.array([[0, 0, 0.0109], [0, 0, -0.0109]])  # restoring force, pulling atoms together
+    >>> new_pos, new_vel, accel = md_step(positions, velocities, forces, ['H', 'H'], dt_fs=0.5)
+    >>> bool(new_pos[1, 2] < 0.7414)  # the second atom moved toward the first
+    True
+    """
+    positions = np.asarray(positions_angstrom, dtype=np.float64)
+    velocities = np.asarray(velocities_angstrom_per_fs, dtype=np.float64)
+    forces = np.asarray(forces_hartree_per_angstrom, dtype=np.float64)
+    masses = np.array([ATOMIC_MASSES_AMU[s] for s in symbols], dtype=np.float64)
+
+    accel = ACCEL_CONVERSION * forces / masses[:, None]
+    velocities_half = velocities + 0.5 * accel * dt_fs
+    positions_new = positions + velocities_half * dt_fs
+    return positions_new, velocities_half, accel
+
+
+def run_md_trajectory(name: str, n_steps: int, dt_fs: float = 0.5, mapping: str = "jordan_wigner",
+                       recompute_electronic_state: bool = False, fd_step_angstrom: float = 0.001):
+    """Real, minimal ab-initio-forces MD trajectory: at each step, real
+    Hellmann-Feynman forces (compute_hellmann_feynman_forces) move the
+    real nuclear positions/velocities via real Velocity-Verlet (md_step).
+    Starts from rest (zero initial velocities) at the catalog's real
+    equilibrium geometry.
+
+    fd_step_angstrom: forwarded to compute_hellmann_feynman_forces at
+    every step -- previously not exposed here at all, silently using
+    that function's own default (0.001 A) with no way for a caller to
+    ask for a different finite-difference step (e.g. a molecule with an
+    unusually steep energy landscape, where the default step size isn't
+    the one already verified converged for H2).
+
+    recompute_electronic_state=False (default) holds the electronic state
+    fixed at the initial Hartree-Fock reference through the whole
+    trajectory -- forces stay exact only close to the starting geometry
+    (a real, explicitly-stated approximation, not a fabricated one).
+    True ab-initio MD (re-solving Hartree-Fock at every step's new
+    geometry) is available by setting this True, at real, substantial
+    extra cost per step.
+
+    Examples
+    --------
+    >>> from dense_evolution.qmmm import run_md_trajectory
+    >>> from dashboard_core.hamiltonians import MOLECULE_CATALOG
+    >>> h2 = [k for k in MOLECULE_CATALOG if k.startswith("H2 ")][0]
+    >>> traj = run_md_trajectory(h2, n_steps=3, dt_fs=0.5)
+    >>> traj['step']
+    [0, 1, 2]
+    >>> len(traj['force_norm'])
+    3
+    """
+    MOLECULE_CATALOG, _build_molecular_hamiltonian = _import_dashboard_hamiltonians()
+    if name not in MOLECULE_CATALOG:
+        raise ValueError(f"unknown molecule {name!r}; available: {sorted(MOLECULE_CATALOG)}")
+    spec = MOLECULE_CATALOG[name]
+    symbols = spec["symbols"]
+    geometry = spec["geometry"]() if callable(spec["geometry"]) else spec["geometry"]
+    charge = spec["charge"]
+    active_electrons = spec.get("active_electrons")
+    active_orbitals = spec.get("active_orbitals")
+
+    statevector, _gs_energy, _n_qubits = _reference_ground_state(
+        symbols, geometry, charge, mapping, active_electrons, active_orbitals)
+    positions = np.asarray(geometry, dtype=np.float64)
+    velocities = np.zeros_like(positions)
+
+    trajectory = {"step": [], "time_fs": [], "positions_angstrom": [], "energy_hartree": [], "force_norm": []}
+    for step in range(n_steps):
+        result = compute_hellmann_feynman_forces(name, statevector, mapping=mapping, geometry=positions,
+                                                  fd_step_angstrom=fd_step_angstrom)
+        forces = np.asarray(result["forces_hartree_per_angstrom"])
+        trajectory["step"].append(step)
+        trajectory["time_fs"].append(step * dt_fs)
+        trajectory["positions_angstrom"].append(positions.tolist())
+        trajectory["energy_hartree"].append(result["energy_hartree"])
+        trajectory["force_norm"].append(result["force_norm"])
+
+        positions, velocities, _accel = md_step(positions, velocities, forces, symbols, dt_fs=dt_fs)
+        _assert_no_nuclear_collision(positions, step, dt_fs)
+
+        if recompute_electronic_state:
+            statevector, _gs_energy, _n_qubits = _reference_ground_state(
+                symbols, positions, charge, mapping, active_electrons, active_orbitals)
+
+    return trajectory

dense_evolution/qmmm/propagation.py

@@ -0,0 +1,80 @@
+"""
+Diffuse2Seg-derived relevance propagation, for QM/MM region selection
+weighted by a real chemical affinity (Mayer/Wiberg bond order) instead of
+a fixed hop-count radius.
+"""
+import numpy as np
+
+
+def propagate_relevance(affinity, seed_idx, n_nodes, p=1.6, lam=1e-5, tau_prop=1e-4, max_iter=500):
+    """Algorithm 1 of Hummer, Sicking, Huger & Gottschalk 2026
+    (arXiv:2609.06491, "Diffuse2Seg", Sec. 3.4/A.1), read directly from
+    the paper and implemented verbatim.
+
+    Non-linear p-Laplacian graph-regularized smoothing (Elmoataz et al.
+    2008), solved by Gauss-Jacobi iteration: propagates a one-hot seed
+    vector over any node-affinity graph `affinity` (self-attention in the
+    original paper; Mayer/Wiberg bond order in Dense-Evolution-Discovery's
+    QM/MM experiments) into a soft relevance map that stays smooth within
+    high-affinity regions and is throttled across low-affinity (edge)
+    ones. `p`, `lam`, `tau_prop` are the paper's own final values
+    (Sec. 4.2).
+
+    Measured, not assumed (Dense-Evolution-Discovery's
+    qmmm_diffuse2seg_propagation_lambda_sweep.py, on the real Mayer
+    bond-order graph of a branched-aromatic molecule,
+    OCC(c1ccccc1)CCC): at the paper's own lam=1e-5 -- tuned for a dense
+    grid of prompts later merged together, not a single isolated seed --
+    a stronger real bond (aromatic ring, bond order 1.412) actually
+    propagates LESS relevance than a weaker one (alkyl chain, bond order
+    0.991), the opposite of the naive expectation. The ratio crosses 1.0
+    only around lam~0.5-1, and only reaches a large expected-direction
+    differentiation (ratio 1.49) at lam=10, two orders of magnitude above
+    the paper's own calibrated value. This is reported as the real,
+    measured lam-dependence of this algorithm in a single-seed molecular
+    setting, distinct from the many-prompt image setting it was designed
+    and calibrated for -- `lam` is not silently retuned to whatever value
+    looks best.
+
+    Degenerate-case handling: at any node i where g_i = sqrt(sum_j
+    A_ij(f_j-f_i)^2) is exactly 0 (every affinity-neighbor already equals
+    f_i), the formula's g_i^(p-2) term diverges for p<2. An earlier
+    version clamped g_i away from 0 with an epsilon -- the same category
+    of shortcut already rejected elsewhere in this project for degenerate
+    eigenvalues (see dense_evolution.physics.spectral, Kato's divided-
+    difference formula) in favor of the real mathematical limit. Worked
+    out directly here: as g_i -> 0, every A_ij-connected f_j equals f_i
+    by definition of g_i=0, so the g_i^(p-2)-weighted terms in both the
+    numerator and denominator of the update come to dominate and cancel
+    to exactly f_i -- i.e. a node already consistent with its whole
+    affinity-neighborhood is unchanged by an edge-preserving smoothing
+    step, exactly as expected. Implemented as an explicit special case
+    below, not an epsilon.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dense_evolution.qmmm import propagate_relevance
+    >>> affinity = np.array([[0, 1.0, 0], [1.0, 0, 1.0], [0, 1.0, 0]])
+    >>> rel = propagate_relevance(affinity, [0], 3, lam=1.0)
+    >>> bool(rel[0] > rel[1] > rel[2])
+    True
+    """
+    f0 = np.zeros(n_nodes)
+    f0[seed_idx] = 1.0
+    f = f0.copy()
+    for _ in range(max_iter):
+        diff = f[None, :] - f[:, None]
+        g = np.sqrt(np.sum(affinity * diff ** 2, axis=1))
+        degenerate = g == 0.0
+        gp = np.zeros_like(g)
+        gp[~degenerate] = g[~degenerate] ** (p - 2)
+        gamma = affinity * (gp[:, None] + gp[None, :])
+        numerator = lam * f0 + (gamma * f[None, :]).sum(axis=1)
+        denominator = lam + gamma.sum(axis=1)
+        f_new = np.where(degenerate, f, numerator / denominator)
+        if np.sum((f_new - f) ** 2) <= tau_prop:
+            f = f_new
+            break
+        f = f_new
+    return f