symvb 2.0.0__py3-none-any.whl

symvb/system.py

@@ -0,0 +1,354 @@
+"""High-level convenience layer over :class:`~symvb.molecule.Molecule`.
+
+This is a thin, *additive* facade. The low-level symbolic core is unchanged
+and every object it returns (the SymPy ``H``/``S`` matrices, the ground-state
+expression, the structure vectors) stays directly inspectable. The facade
+just removes the boilerplate and the two recurring footguns:
+
+* building the Hamiltonian no longer means three calls plus a hand-combine,
+  and you never scale the two-electron matrix by ``U`` yourself (it already
+  carries the integral name -- doing so silently squares it);
+* expressing a VB structure as a basis vector no longer means re-deriving the
+  fermion sign of the canonical reordering by hand.
+
+Typical use::
+
+    from symvb import System
+    sys = System.ring(6)                       # benzene pi ring, Hubbard U
+    H, S = sys.hamiltonian()                   # 400x400 SymPy matrices
+    E, c = System.from_structures(mol, [cov, ion]).ground_state()
+    w    = sys.weights(groups=...)             # Chirgwin-Coulson weights
+
+Or compose the standalone helpers with a Molecule you built yourself::
+
+    from symvb.system import hamiltonian, ground_state, chirgwin_coulson
+    H, S = hamiltonian(mol, basis)
+    E, c = ground_state(H, S)
+    w    = chirgwin_coulson(c, S)
+"""
+import sympy as sp
+
+from .molecule import Molecule
+from .fixed_psi import FixedPsi, generate_dets
+from .functions import standardize_det
+from .slaterdet import SlaterDet
+
+__all__ = [
+    'System', 'hamiltonian', 'ground_state', 'chirgwin_coulson',
+    'structure_vector',
+]
+
+# reference point for picking the ground root of a symbolic GHEP
+_DEFAULT_REF = {'h': -1, 's': 0, 'U': 1, 'J': 0, 'K': 0, 'M': 0,
+                'h_s': -1, 'h_l': sp.Rational(-3, 10)}
+
+
+def _standardize_full(det_string):
+    """Map ``det_string`` to its ``generate_det_strings``-format twin + sign.
+
+    Returns ``(canonical, sign)`` with ``|det_string> = sign * |canonical>``,
+    where ``canonical`` is the unique basis-format string for the same set of
+    spin-orbitals: alphabetically sorted alpha and beta labels interleaved
+    ``uLuL...`` with the majority-spin extras appended, exactly as
+    :func:`symvb.functions.generate_det_strings` emits it.
+
+    :func:`symvb.functions.standardize_det` alone is not that map: it fixes
+    the spin *pattern* but its pairwise flips can jump a creation operator
+    over same-spin neighbours, permuting the alphabetical order within the
+    alpha/beta blocks (e.g. ``'abcAB' -> 'aAcBb'``, not ``'aAbBc'``), so its
+    output is a valid det string of the same determinant that need not be in
+    the generated basis. Composing it with the within-block label sort of
+    :meth:`symvb.slaterdet.SlaterDet.get_sorted` (spin pattern unchanged),
+    with both fermion signs folded in, gives the true canonical map. A no-op
+    (sign ``+1``) on a string that is already in basis format.
+    """
+    std, flips = standardize_det(det_string)
+    fp = SlaterDet(std).get_sorted()
+    return fp.dets[0].det_string, ((-1) ** flips) * fp.coefs[0]
+
+
+def _det_string(b):
+    """The canonical determinant string of a basis entry (FixedPsi/SlaterDet/str).
+
+    Returned in symvb's standard (interleaved, block-sorted) creation order so
+    that the determinant index this builds agrees with the standardized basis
+    that matrix construction and :func:`structure_vector` use. A no-op on an
+    entry that is already canonical.
+    """
+    if isinstance(b, str):
+        raw = b
+    elif hasattr(b, 'dets'):        # FixedPsi
+        raw = b.dets[0].det_string
+    else:                           # SlaterDet
+        raw = b.det_string
+    return _standardize_full(raw)[0]
+
+
+# --------------------------------------------------------------------------
+# standalone helpers (usable without a System)
+# --------------------------------------------------------------------------
+def hamiltonian(molecule, basis, two_electron=True):
+    """Return ``(H, S)`` over ``basis``, with the two-electron block folded in.
+
+    ``basis`` is a list of ``FixedPsi`` / ``SlaterDet`` / determinant strings.
+    The two-electron block is **always** folded into ``H`` -- under the names
+    declared in ``subst_2e`` when the molecule has them, otherwise under the
+    default ``T_<abcd>`` integral names. The integrals are already inside
+    ``H``; do **not** multiply the two-electron matrix by ``U`` yourself.
+
+    Pass ``two_electron=False`` for an intentionally one-electron model
+    (a Hueckel-level ``H``): this returns the bare ``build_matrix(op='H')``
+    and skips the two-electron build, which dominates the cost on large
+    bases.
+    """
+    H = molecule.build_matrix(basis, op='H')
+    S = molecule.build_matrix(basis, op='S')
+    if two_electron:
+        H = H + molecule.o2_matrix(basis)
+    return H, S
+
+
+def structure_vector(structure, basis_dets):
+    """Expand a VB structure as a column vector over ``basis_dets``.
+
+    ``structure`` is a ``FixedPsi`` (e.g. a Rumer/Heitler-London structure built
+    with ``coupled_pairs``); ``basis_dets`` is the list of determinant strings
+    of the target basis (any creation order). Both sides are brought to the
+    same canonical form: each basis string and each structure determinant is
+    mapped through the full standardization (spin pattern via
+    :func:`symvb.functions.standardize_det`, then within-block label sort),
+    with both fermion signs folded into the coefficient. Alpha-alpha-beta-beta
+    and other non-canonical spin patterns, including the unequal-filling cases
+    where ``standardize_det`` alone leaves the generated basis (e.g. 3 alpha /
+    2 beta hole determinants), are therefore placed correctly. Use this to
+    project a structure onto an explicit determinant basis (e.g. an FCI ground
+    state for weights); to build ``(H, S)`` over the structures themselves,
+    ``hamiltonian`` / ``build_matrix`` now canonicalize internally.
+    """
+    fp = FixedPsi(structure)
+    fp.canonicalize()
+    idx = {}
+    for i, b in enumerate(basis_dets):
+        key, bsign = _standardize_full(b)
+        if key in idx:
+            raise ValueError(
+                "basis determinants %r and %r are the same determinant "
+                "(canonical form %r)" % (basis_dets[idx[key][0]], b, key))
+        idx[key] = (i, bsign)
+    v = sp.zeros(len(basis_dets), 1)
+    for d, c in fp:
+        key, dsign = _standardize_full(d.det_string)
+        if key not in idx:
+            raise ValueError(
+                "structure determinant %r (canonical form %r) is not in the "
+                "target basis" % (d.det_string, key))
+        i, bsign = idx[key]
+        v[i] += dsign * bsign * c
+    return v
+
+
+def chirgwin_coulson(c, S, groups=None, simplify=False):
+    """Chirgwin-Coulson weights of coefficient vector ``c`` under metric ``S``.
+
+    ``w_i = c_i (S c)_i / (c^T S c)`` (the metric makes them sum to one even for
+    non-orthonormal ``c``). If ``groups`` (a list of index lists) is given, the
+    summed weight per group is returned instead. Accepts either SymPy
+    matrices/vectors or NumPy arrays and returns the matching type. ``simplify``
+    is off by default: simplifying raw symbolic weights can be very slow, and
+    it is usually cheaper to substitute numeric values first; pass
+    ``simplify=True`` only for small closed forms.
+    """
+    try:
+        import numpy as np
+        if isinstance(c, np.ndarray):           # numeric path keyed on the coefficient vector
+            c = np.asarray(c, float).ravel()
+            S = np.asarray(S, float)
+            Sc = S @ c
+            w = c * Sc / (c @ Sc)
+            if groups is None:
+                return w
+            return np.array([w[list(g)].sum() for g in groups])
+    except ImportError:
+        pass
+    c = sp.Matrix(c)
+    S = sp.Matrix(S)                            # accept a numpy metric alongside a symbolic c
+    Sc = S * c
+    norm = (c.T * Sc)[0]
+    w = [c[i] * Sc[i] / norm for i in range(c.rows)]
+    if groups is not None:
+        w = [sum(w[i] for i in g) for g in groups]
+    if simplify:
+        w = [sp.simplify(x) for x in w]
+    return sp.Matrix(w)
+
+
+def _ref_subs(H, S, ref):
+    syms = H.free_symbols | S.free_symbols
+    user = {}
+    if ref:
+        for k, val in ref.items():
+            user[sp.Symbol(k) if isinstance(k, str) else k] = val
+    out = {}
+    for sym in syms:
+        if sym in user:
+            out[sym] = user[sym]
+        elif str(sym) in _DEFAULT_REF:
+            out[sym] = _DEFAULT_REF[str(sym)]
+        else:
+            out[sym] = sp.Rational(1, 10)     # neutral nonzero default
+    return out
+
+
+def ground_state(H, S, ref=None, subs=None):
+    """Ground state of ``H c = E S c``.
+
+    **Symbolic** (``subs=None``, default): solves the characteristic polynomial
+    for a SMALL block (2x2, 3x3). Returns ``(E, c)`` as SymPy expressions, ``E``
+    simplified, ``c`` the (un-normalized) ground eigenvector (the metric is
+    applied later by :func:`chirgwin_coulson`, and simplifying an eigenvector
+    full of nested radicals is expensive, so we don't). The ground root is the
+    one numerically lowest at the reference point ``ref`` -- a ``{symbol-or-name:
+    value}`` dict; defaults are ``h=-1, s=0`` and any electron-repulsion integral
+    ``= 1``. The symbolic solve is only practical for a few dimensions.
+
+    **Numeric** (``subs`` given, a substitution dict): the matrices are
+    evaluated and the lowest eigenpair is found with ``scipy.linalg.eigh`` --
+    use this for anything larger, e.g. a full determinant (FCI) basis. Returns
+    ``(E_float, c_ndarray)``.
+    """
+    if subs is not None:
+        import numpy as np
+        from scipy.linalg import eigh as _eigh
+        Hn = np.array(sp.Matrix(H).subs(subs).tolist(), float)
+        Sn = np.array(sp.Matrix(S).subs(subs).tolist(), float)
+        w, v = _eigh(Hn, Sn, subset_by_index=[0, 0])
+        return float(w[0]), v[:, 0]
+    H = sp.Matrix(H)
+    S = sp.Matrix(S)
+    E = sp.Dummy('E')
+    roots = sp.solve((H - E * S).det(), E)
+    if not roots:
+        raise ValueError("det(H - E S) = 0 has no roots solvable in closed form")
+    sub = _ref_subs(H, S, ref)
+    E_gs = min(roots, key=lambda r: float(sp.re(r.subs(sub))))
+    null = (H - E_gs * S).nullspace()
+    if not null:
+        raise ValueError("no eigenvector found for the ground root")
+    return sp.simplify(E_gs), null[0]
+
+
+# --------------------------------------------------------------------------
+# the System facade
+# --------------------------------------------------------------------------
+class System:
+    """A :class:`Molecule` plus a determinant (or structure) basis.
+
+    Construct directly with ``System(molecule, basis)``, from a structure list
+    with ``System.from_structures(molecule, structures)``, or from a topology
+    with ``System.ring(L)`` / ``System.chain(n)``.
+    """
+
+    def __init__(self, molecule, basis, two_electron=True):
+        self.m = molecule
+        self.basis = list(basis)
+        self.det_strings = [_det_string(b) for b in self.basis]
+        self.two_electron = two_electron
+        self._H = None
+        self._S = None
+
+    # ---- constructors ----
+    @classmethod
+    def from_structures(cls, molecule, structures, two_electron=True):
+        """A System whose basis is an explicit list of VB structures."""
+        return cls(molecule, structures, two_electron=two_electron)
+
+    @classmethod
+    def ring(cls, L, n_alpha=None, n_beta=None, hubbard=True,
+             two_electron=True, **kw):
+        """Cyclic ``L``-orbital ring with Hubbard ``U``.
+
+        Defaults to ``floor(L/2)`` electrons of each spin (the Sz=0 reference,
+        e.g. 3 + 3 for benzene). For an ion or an odd ring pass ``n_alpha`` /
+        ``n_beta`` explicitly (the cyclopentadienyl anion is
+        ``System.ring(5, n_alpha=3, n_beta=3)``).
+        """
+        m = Molecule.ring(L, hubbard=hubbard, **kw)
+        na = L // 2 if n_alpha is None else n_alpha
+        nb = na if n_beta is None else n_beta
+        return cls(m, generate_dets(na, nb, L), two_electron=two_electron)
+
+    @classmethod
+    def chain(cls, n, n_alpha=None, n_beta=None, hubbard=True,
+              two_electron=True, **kw):
+        """Linear ``n``-orbital chain with Hubbard ``U``; same filling convention
+        as :meth:`ring` (``floor(n/2)`` electrons of each spin by default)."""
+        m = Molecule.chain(n, hubbard=hubbard, **kw)
+        na = n // 2 if n_alpha is None else n_alpha
+        nb = na if n_beta is None else n_beta
+        return cls(m, generate_dets(na, nb, n), two_electron=two_electron)
+
+    # ---- matrices ----
+    def hamiltonian(self):
+        """``(H, S)`` over the basis (cached). The 2e block is folded into H
+        unless the System was built with ``two_electron=False``."""
+        if self._H is None:
+            self._H, self._S = hamiltonian(self.m, self.basis,
+                                           two_electron=self.two_electron)
+        return self._H, self._S
+
+    @property
+    def H(self):
+        return self.hamiltonian()[0]
+
+    @property
+    def S(self):
+        return self.hamiltonian()[1]
+
+    # ---- VB structures ----
+    def structure_vector(self, structure):
+        """Column vector of ``structure`` over this System's determinant basis."""
+        return structure_vector(structure, self.det_strings)
+
+    # ---- solving ----
+    def ground_state(self, ref=None, subs=None):
+        """``(E, c)`` of the ground state over this basis.
+
+        Symbolic for small bases; pass ``subs`` (a numeric substitution dict) to
+        solve a large/FCI basis numerically with scipy (returns floats/arrays).
+        """
+        H, S = self.hamiltonian()
+        return ground_state(H, S, ref=ref, subs=subs)
+
+    def weights(self, structures=None, groups=None, ref=None, subs=None):
+        """Chirgwin-Coulson weights of the ground state.
+
+        With no ``structures``, weights are per basis function (optionally summed
+        by ``groups``). With ``structures`` (a list of ``FixedPsi``), the ground
+        state is projected onto that (possibly non-orthogonal) structure space
+        and weights are returned per structure, normalized over that space (the
+        composition of the part of the wavefunction the structures span).
+
+        Symbolic by default and only practical for small bases (the ground-state
+        solve is a symbolic characteristic polynomial). For an FCI-sized basis
+        pass ``subs`` (a numeric dict): the ground state is found numerically and
+        the weights come back as a NumPy array.
+        """
+        H, S = self.hamiltonian()
+        E, c = ground_state(H, S, ref=ref, subs=subs)
+        if subs is None:
+            S_eff = S
+        else:
+            import numpy as np
+            S_eff = np.array(sp.Matrix(S).subs(subs).tolist(), float)
+        if structures is None:
+            return chirgwin_coulson(c, S_eff, groups=groups)
+        V = sp.Matrix.hstack(*[self.structure_vector(st) for st in structures])
+        if subs is None:
+            G = V.T * S_eff * V                          # structure-space metric
+            a = G.solve(V.T * S_eff * c)                 # ground state in the structure basis
+        else:
+            import numpy as np
+            Vn = np.array(V, float)
+            G = Vn.T @ S_eff @ Vn
+            a = np.linalg.solve(G, Vn.T @ S_eff @ np.asarray(c, float))
+        return chirgwin_coulson(a, G, groups=groups)

symvb/test_det_conventions.py

@@ -0,0 +1,292 @@
+"""Determinant-convention consistency between standardize_det and the
+generate_dets/generate_det_strings basis.
+
+standardize_det fixes the spin *pattern* (uLuL... + majority-spin tail) but
+its pairwise flips can permute the alphabetical order within the alpha/beta
+blocks, so on unequal-filling (and beta-block-leading) determinants its output
+string need not be a member of the generated basis (e.g. 'abcAB' -> 'aAcBb',
+not 'aAbBc'). Its output convention is load-bearing in matrix construction and
+must not change; the *lookup* side (symvb.system.structure_vector) therefore
+standardizes both the basis strings and the structure determinants through the
+full canonical map (spin pattern + within-block sort, fermion signs folded).
+These tests pin the census of the mismatch, the fixed lookup at every affected
+filling, sign correctness against an independent inversion-parity reference,
+and exact no-regression on previously-working columns.
+"""
+import string
+import unittest
+from itertools import combinations
+
+import numpy as np
+import sympy as sp
+
+from symvb import FixedPsi, Molecule
+from symvb.fixed_psi import generate_dets
+from symvb.functions import generate_det_strings, standardize_det
+from symvb.system import _standardize_full, hamiltonian, structure_vector
+
+FILLINGS = [(2, 1, 4), (2, 2, 3), (2, 2, 4), (3, 2, 4), (3, 2, 6), (3, 3, 6)]
+
+# dets (with alphabetically sorted alpha and beta blocks, i.e. exactly the
+# strings FixedPsi.canonicalize can emit) whose bare standardize_det output
+# is NOT in generate_det_strings(Na, Nb, Norb)
+KNOWN_MISS_COUNTS = {(2, 1, 4): 0, (2, 2, 3): 9, (2, 2, 4): 36,
+                     (3, 2, 4): 48, (3, 2, 6): 600, (3, 3, 6): 2800}
+
+
+def _canonicalized_space(Na, Nb, Norb):
+    """All det strings with sorted alpha block and sorted beta block, over all
+    C(Na+Nb, Na) spin patterns: the input space structure_vector feeds into
+    the standardization after FixedPsi.canonicalize()."""
+    lo = string.ascii_lowercase[:Norb]
+    up = string.ascii_uppercase[:Norb]
+    out = []
+    for a in combinations(lo, Na):
+        for b in combinations(up, Nb):
+            for pos in combinations(range(Na + Nb), Na):
+                s = [''] * (Na + Nb)
+                ia = ib = 0
+                for i in range(Na + Nb):
+                    if i in pos:
+                        s[i] = a[ia]
+                        ia += 1
+                    else:
+                        s[i] = b[ib]
+                        ib += 1
+                out.append(''.join(s))
+    return out
+
+
+def _ref_canonical(det_string, basis_by_soset):
+    """Independent reference: the basis string over the same spin-orbital set
+    and the inversion parity of the permutation relating the two creation
+    orders."""
+    so = [(c.lower(), 0 if c.islower() else 1) for c in det_string]
+    tgt = basis_by_soset[frozenset(so)]
+    tso = [(c.lower(), 0 if c.islower() else 1) for c in tgt]
+    pos = {v: i for i, v in enumerate(tso)}
+    idx = [pos[v] for v in so]
+    inv = sum(1 for i in range(len(idx)) for j in range(i + 1, len(idx))
+              if idx[i] > idx[j])
+    return tgt, (-1) ** inv
+
+
+def _soset_index(basis):
+    return {frozenset((c.lower(), 0 if c.islower() else 1) for c in b): b
+            for b in basis}
+
+
+def _old_structure_vector(structure, basis_dets):
+    """The pre-fix structure_vector algorithm (bare standardize_det lookup),
+    kept here as the no-regression reference on fillings where it worked."""
+    fp = FixedPsi(structure)
+    fp.canonicalize()
+    idx = {d: i for i, d in enumerate(basis_dets)}
+    v = sp.zeros(len(basis_dets), 1)
+    for d, c in fp:
+        std, flips = standardize_det(d.det_string)
+        if std not in idx:
+            raise ValueError(std)
+        v[idx[std]] += (-1) ** flips * c
+    return v
+
+
+class TestFillingCensus(unittest.TestCase):
+    def test_standardize_det_miss_counts(self):
+        # pin the characterization: standardize_det's output leaves the
+        # generated basis exactly this often, per filling, over the
+        # canonicalized (sorted-block) input space; it is a no-op on the
+        # basis strings themselves.
+        for Na, Nb, Norb in FILLINGS:
+            basis = set(generate_det_strings(Na, Nb, Norb))
+            for b in basis:
+                self.assertEqual(standardize_det(b), (b, 0))
+            miss = sum(1 for d in _canonicalized_space(Na, Nb, Norb)
+                       if standardize_det(d)[0] not in basis)
+            self.assertEqual(miss, KNOWN_MISS_COUNTS[(Na, Nb, Norb)],
+                             msg=f"filling ({Na},{Nb},{Norb})")
+
+    def test_full_standardization_lands_in_basis_with_correct_sign(self):
+        # the fixed lookup map: every canonicalized-space det lands ON the
+        # basis, with the sign of the independent inversion-parity reference
+        for Na, Nb, Norb in FILLINGS:
+            basis = generate_det_strings(Na, Nb, Norb)
+            bset = set(basis)
+            ref_idx = _soset_index(basis)
+            for d in _canonicalized_space(Na, Nb, Norb):
+                key, sgn = _standardize_full(d)
+                self.assertIn(key, bset,
+                              msg=f"({Na},{Nb},{Norb}): {d!r} -> {key!r}")
+                self.assertEqual((key, sgn), _ref_canonical(d, ref_idx),
+                                 msg=f"({Na},{Nb},{Norb}): {d!r}")
+
+    def test_structure_vector_lookup_succeeds_at_all_fillings(self):
+        # end-to-end: structure_vector places every sampled det (including
+        # the ones bare standardize_det mishandles) at the right position
+        # with the right sign, and never raises
+        for Na, Nb, Norb in FILLINGS:
+            basis = generate_det_strings(Na, Nb, Norb)
+            ref_idx = _soset_index(basis)
+            space = _canonicalized_space(Na, Nb, Norb)
+            bset = set(basis)
+            missing = [d for d in space if standardize_det(d)[0] not in bset]
+            step = max(1, len(space) // 20)
+            sample = space[::step] + missing[::max(1, len(missing) // 20)]
+            for d in sample:
+                v = structure_vector(FixedPsi(d), basis)
+                key, sgn = _ref_canonical(d, ref_idx)
+                nz = {basis[i]: v[i] for i in range(len(basis)) if v[i] != 0}
+                self.assertEqual(nz, {key: sgn},
+                                 msg=f"({Na},{Nb},{Norb}): {d!r}")
+
+    def test_outside_basis_raises_named_valueerror(self):
+        basis = generate_det_strings(2, 1, 4)      # orbitals a..d only
+        with self.assertRaises(ValueError) as cm:
+            structure_vector(FixedPsi('aEb'), basis)
+        self.assertIn('aEb', str(cm.exception))
+
+    def test_duplicate_basis_det_raises(self):
+        # 'abA' is the same determinant as 'aAb' in a different creation order
+        with self.assertRaises(ValueError):
+            structure_vector(FixedPsi('aAb'), ['aAb', 'abA'])
+
+
+class TestHoleBasisRoundTrip326(unittest.TestCase):
+    """(H2)3+ sigma-hole diabatics on the (3,2,6) basis: structure_vector must
+    reproduce the low-level to_standard mapping that
+    examples/h2h2h2_plus_diabatic.py hand-rolls (positions AND signs)."""
+
+    ORBS = 'abcdef'
+    PAIRS = [('a', 'b'), ('c', 'd'), ('e', 'f')]
+
+    def _to_standard(self, det_string):
+        # replicated from examples/h2h2h2_plus_diabatic.py
+        so_list = [2 * self.ORBS.index(c.lower()) + (0 if c.islower() else 1)
+                   for c in det_string]
+        if len(set(so_list)) != len(so_list):
+            return None, 0
+        alphas = sorted(c for c in det_string if c.islower())
+        betas = sorted(c for c in det_string if c.isupper())
+        std = ''
+        na, nb = len(alphas), len(betas)
+        for i in range(min(na, nb)):
+            std += alphas[i] + betas[i]
+        std += ''.join(alphas[nb:]) + ''.join(betas[na:])
+        target = [2 * self.ORBS.index(c.lower()) + (0 if c.islower() else 1)
+                  for c in std]
+        pos = {v: i for i, v in enumerate(target)}
+        idx = [pos[v] for v in so_list]
+        inv = sum(1 for i in range(len(idx)) for j in range(i + 1, len(idx))
+                  if idx[i] > idx[j])
+        return std, (-1 if inv % 2 else 1)
+
+    def _hole_raws(self, hole_pair):
+        hole_atoms = self.PAIRS[hole_pair]
+        full_idx = [i for i in range(3) if i != hole_pair]
+        f0, f1 = self.PAIRS[full_idx[0]], self.PAIRS[full_idx[1]]
+        return [h_a + f0a + f0b.upper() + f1a + f1b.upper()
+                for h_a in hole_atoms
+                for f0a in f0 for f0b in f0
+                for f1a in f1 for f1b in f1]
+
+    def test_hole_diabatics_match_to_standard_route(self):
+        basis = generate_det_strings(3, 2, 6)
+        ds_to_idx = {d: i for i, d in enumerate(basis)}
+        cols = []
+        n_outside = 0
+        for hp in range(3):
+            raws = self._hole_raws(hp)
+            self.assertEqual(len(raws), 32)
+            n_outside += sum(1 for r in raws
+                             if standardize_det(r)[0] not in ds_to_idx)
+            v_ref = np.zeros(len(basis))
+            for raw in raws:
+                std, sgn = self._to_standard(raw)
+                self.assertIsNotNone(std)
+                v_ref[ds_to_idx[std]] += sgn
+            fp = FixedPsi()
+            for raw in raws:
+                fp.add_str_det(raw, coef=1)
+            v = np.array(structure_vector(fp, basis), float).ravel()
+            self.assertTrue(np.array_equal(v, v_ref), msg=f"hole {hp}")
+            cols.append(v)
+        # the audited mismatch: 64 of the 96 raw hole dets are exactly the
+        # strings the pre-fix lookup raised on
+        self.assertEqual(n_outside, 64)
+        # the three diabatics are orthonormal at s = 0 (norm^2 = 32 raw dets
+        # collapsing pairwise onto 32 basis dets of unit coefficient)
+        Phi = np.column_stack(cols)
+        self.assertTrue(np.allclose(Phi.T @ Phi / 32.0, np.eye(3),
+                                    atol=1e-14))
+
+
+class TestNoRegression(unittest.TestCase):
+    """Columns the pre-fix code produced correctly must be reproduced exactly."""
+
+    def test_223_longbond_column_exact(self):
+        # the (2,2,3) long-bond column pinned by TestStructureVector in
+        # test_system.py, and the full old-vs-new comparison on all three
+        # allyl Rumer structures
+        basis = [p.dets[0].det_string for p in generate_dets(2, 2, 3)]
+        structs = [FixedPsi('aBcC', coupled_pairs=[(0, 1)]),
+                   FixedPsi('aAbC', coupled_pairs=[(2, 3)]),
+                   FixedPsi('abBC', coupled_pairs=[(0, 3)])]
+        for st in structs:
+            self.assertEqual(structure_vector(st, basis),
+                             _old_structure_vector(st, basis))
+        v = structure_vector(structs[2], basis)
+        nz = {basis[i]: v[i] for i in range(len(basis)) if v[i] != 0}
+        self.assertEqual(nz, {'aBbC': -1, 'bAcB': -1})
+
+    def test_214_hole_columns_exact(self):
+        # (2,1,4) is a filling where bare standardize_det never leaves the
+        # basis (census count 0), so the old algorithm was fully correct
+        # there; the new lookup must agree determinant-for-determinant
+        basis = [p.dets[0].det_string for p in generate_dets(2, 1, 4)]
+        hole0 = FixedPsi()
+        for ha in 'ab':
+            for fa in 'cd':
+                for fb in 'CD':
+                    hole0.add_str_det(ha + fa + fb, coef=1)
+        hole1 = FixedPsi()
+        for ha in 'cd':
+            for fa in 'ab':
+                for fb in 'AB':
+                    hole1.add_str_det(fa + fb + ha, coef=1)
+        for st in [hole0, hole1, FixedPsi('acC'), FixedPsi('aCc')]:
+            self.assertEqual(structure_vector(st, basis),
+                             _old_structure_vector(st, basis))
+
+
+class TestProjectionConsistency(unittest.TestCase):
+    def test_vthv_matches_direct_hamiltonian_unequal_filling(self):
+        # (H2)2+ dimer, Na=2/Nb=1/4 orbitals: projecting the FCI (H, S)
+        # through structure_vector columns must equal (H, S) built directly
+        # over the structures
+        m = Molecule(zero_ii=True, interacting_orbs=['ab', 'cd', 'bc'],
+                     subst={'h': ('H_ab', 'H_cd'), 't': ('H_bc',),
+                            's': ('S_ab', 'S_cd'), 'sg': ('S_bc',)},
+                     subst_2e={'U': ('1111',)}, max_2e_centers=1)
+        dets = generate_dets(2, 1, 4)
+        strs = [p.dets[0].det_string for p in dets]
+        hole0 = FixedPsi()
+        for ha in 'ab':
+            for fa in 'cd':
+                for fb in 'CD':
+                    hole0.add_str_det(ha + fa + fb, coef=1)
+        hole1 = FixedPsi()
+        for ha in 'cd':
+            for fa in 'ab':
+                for fb in 'AB':
+                    hole1.add_str_det(fa + fb + ha, coef=1)
+        structs = [hole0, hole1]
+
+        Hfci, Sfci = hamiltonian(m, dets)
+        V = sp.Matrix.hstack(*[structure_vector(st, strs) for st in structs])
+        H_dir, S_dir = hamiltonian(m, structs)
+        self.assertTrue(sp.simplify(V.T * Hfci * V - H_dir).is_zero_matrix)
+        self.assertTrue(sp.simplify(V.T * Sfci * V - S_dir).is_zero_matrix)
+
+
+if __name__ == '__main__':
+    unittest.main()