dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/qmmm/region.py

@@ -0,0 +1,137 @@
+"""
+Real QM/MM region-partitioning utilities (Dense-Evolution issue #283).
+Validated on Dense-Evolution-Discovery on two molecules (1-hexanol,
+OCC(c1ccccc1)CCC) before promotion here -- see that repo's
+docs/qmmm_utils.md for the full experiment record.
+
+Two real bugs already found and fixed:
+
+1. Hydrogens must always follow their own heavy atom, never be
+   independently BFS-expanded -- doing so spuriously cuts terminal C-H
+   bonds and leaves an empty MM fragment (found on 1-hexanol).
+
+2. A boundary bond that would cut INTO an aromatic ring must instead pull
+   the WHOLE ring into the QM region -- otherwise RDKit's FragmentOnBonds
+   leaves one aromatic atom outside its ring, capped with H, which is not
+   a valid molecule (`AtomKekulizeException: non-ring atom marked
+   aromatic`, found on OCC(c1ccccc1)CCC at radius=2).
+
+Deliberately NOT included here, both real negative results with the full
+record in Dense-Evolution-Discovery's docs/qmmm_bond_order_and_embedding.md:
+
+- An MMFF94 ONIOM-style mechanical correction that originally looked like
+  it halved 1-hexanol's error, but that used a cruder geometry (each
+  fragment independently re-embedded by RDKit instead of sliced from one
+  shared conformer). Once corrected to use the same shared-conformer
+  geometry as everything here, plain truncation is already accurate to
+  <0.2 kcal/mol on every radius tested on two different molecules -- and
+  applying that correction on top makes it WORSE in every single case.
+  The correction was compensating for a geometry artifact of an older
+  embedding choice, not for truncation itself.
+
+- Electrostatic embedding: five different treatments were tried (plain
+  point charge, charge-shifting, Gaussian-smeared over the whole MM
+  region, Gaussian-smeared on just the boundary atom, boundary-atom
+  charge deletion) and every one made the isodesmic-energy error worse
+  than no embedding at all, on the one molecule with a real MM charge to
+  embed. The sign convention was independently verified correct (a
+  minimal He-atom test: E(+1 charge nearby) < E(isolated) < E(-1 charge
+  nearby), exactly as physics requires) -- the failure is not a bug, just
+  genuinely unsolved. Plain truncation remains the right default.
+
+Requires RDKit (the `qmmm` extra: `pip install dense-evolution[qmmm]`).
+"""
+import numpy as np
+from rdkit import Chem
+
+ANGSTROM_TO_BOHR = 1.8897259886
+CH_BOND_BOHR = 1.09 * ANGSTROM_TO_BOHR
+
+
+def partition_qm_mm_region(mol, seed_heavy_atoms, radius):
+    """BFS outward from `seed_heavy_atoms` (a set/list of atom indices)
+    across `radius` heavy-atom hops. Hydrogens always follow their own
+    heavy atom afterward (never independently expanded -- see module
+    docstring). Any boundary bond that would cut into an aromatic ring
+    pulls that whole ring into the QM region first, iterating until
+    stable, before hydrogens are added and the boundary is finalized.
+
+    Returns (qm_atoms: set[int], boundary_pairs: list[(kept_idx, cut_idx)]),
+    one pair per bond crossing the QM/MM boundary, `kept_idx` on the QM
+    side.
+
+    Examples
+    --------
+    >>> from rdkit import Chem
+    >>> from dense_evolution.qmmm import partition_qm_mm_region
+    >>> mol = Chem.AddHs(Chem.MolFromSmiles("OCCCCCC"))
+    >>> qm_atoms, boundary_pairs = partition_qm_mm_region(mol, {0, 1}, radius=1)
+    >>> len(boundary_pairs)
+    1
+    """
+    qm_heavy = set(seed_heavy_atoms)
+    frontier = set(seed_heavy_atoms)
+    for _ in range(radius):
+        new_frontier = set()
+        for idx in frontier:
+            for nbr in mol.GetAtomWithIdx(idx).GetNeighbors():
+                if nbr.GetAtomicNum() > 1 and nbr.GetIdx() not in qm_heavy:
+                    new_frontier.add(nbr.GetIdx())
+        qm_heavy |= new_frontier
+        frontier = new_frontier
+
+    ring_info = mol.GetRingInfo()
+    changed = True
+    while changed:
+        changed = False
+        for bond in mol.GetBonds():
+            if not bond.GetIsAromatic():
+                continue
+            a, b = bond.GetBeginAtomIdx(), bond.GetEndAtomIdx()
+            if (a in qm_heavy) != (b in qm_heavy):
+                for ring in ring_info.AtomRings():
+                    if a in ring or b in ring:
+                        newly = set(ring) - qm_heavy
+                        if newly:
+                            qm_heavy |= newly
+                            changed = True
+
+    qm_atoms = set(qm_heavy)
+    for idx in qm_heavy:
+        for nbr in mol.GetAtomWithIdx(idx).GetNeighbors():
+            if nbr.GetAtomicNum() == 1:
+                qm_atoms.add(nbr.GetIdx())
+
+    raw_boundary = [(b.GetBeginAtomIdx(), b.GetEndAtomIdx()) for b in mol.GetBonds()
+                    if (b.GetBeginAtomIdx() in qm_atoms) != (b.GetEndAtomIdx() in qm_atoms)]
+    boundary_pairs = [(i, j) if i in qm_atoms else (j, i) for i, j in raw_boundary]
+    return qm_atoms, boundary_pairs
+
+
+def sliced_geometry(atomic_numbers, geom_bohr, keep_idx, boundary_pairs):
+    """A coordinate SUBSET of one whole-molecule conformer (never an
+    independently re-embedded fragment -- that would give unrelated 3D
+    structures across fragments, and was the real cause of the MMFF94
+    correction's apparent benefit turning out to be a geometry artifact,
+    see module docstring). Boundary bonds get a capping H placed along
+    the kept->cut bond direction at a standard C-H bond length.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dense_evolution.qmmm import sliced_geometry
+    >>> numbers = [8, 6, 6]
+    >>> geom = np.array([[0.0, 0.0, 0.0], [1.4, 0.0, 0.0], [2.8, 0.0, 0.0]])
+    >>> new_numbers, new_geom = sliced_geometry(numbers, geom, {0, 1}, [(1, 2)])
+    >>> new_numbers
+    [8, 6, 1]
+    """
+    keep_idx = sorted(keep_idx)
+    new_numbers = [atomic_numbers[i] for i in keep_idx]
+    new_geom = [geom_bohr[i] for i in keep_idx]
+    for kept, cut in boundary_pairs:
+        vec = geom_bohr[cut] - geom_bohr[kept]
+        vec = vec / np.linalg.norm(vec)
+        new_geom.append(geom_bohr[kept] + vec * CH_BOND_BOHR)
+        new_numbers.append(1)
+    return new_numbers, np.array(new_geom)

dense_evolution/random_circuit.py

@@ -0,0 +1,15 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.circuits.random_circuit as part of fixing the module/
+function name collision (dense_evolution.qft/random_circuit each had a
+function sharing its own module's name -- any code importing the flat
+submodule path directly clobbered the package's re-exported function
+attribute with the module object, e.g. `TypeError: 'module' object is
+not callable`; see prog.txt). Kept so
+`from dense_evolution.random_circuit import random_circuit` (used by
+external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.circuits.random_circuit directly
+in new code.
+"""
+from dense_evolution.circuits.random_circuit import random_circuit
+
+__all__ = ['random_circuit']

dense_evolution/registry.py

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

dense_evolution/simulator.py

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

dense_evolution/solvers/__init__.py

@@ -0,0 +1,19 @@
+"""Solvers subpackage: algorithms built on top of the backends
+(VQE/autodiff gradients, tight-binding solvers)."""
+from .autodiff import circuit_to_energy_fn
+from .harrison_tb import (
+    ELEMENTS, ETA, HBAR2_OVER_M_EV_ANG2,
+    hopping_integral, sp3_bond_block, sp3_dimer_hamiltonian, zincblende_hamiltonian,
+)
+from .vhd_tb import (
+    Material, MATERIALS, sp3s_star_hamiltonian, direct_gap_at_gamma,
+    band_extrema_along_path,
+)
+
+__all__ = [
+    "circuit_to_energy_fn",
+    "ELEMENTS", "ETA", "HBAR2_OVER_M_EV_ANG2",
+    "hopping_integral", "sp3_bond_block", "sp3_dimer_hamiltonian", "zincblende_hamiltonian",
+    "Material", "MATERIALS", "sp3s_star_hamiltonian", "direct_gap_at_gamma",
+    "band_extrema_along_path",
+]

dense_evolution/solvers/autodiff.py

@@ -0,0 +1,169 @@
+from typing import Callable, Optional, Tuple
+
+from ..circuits.parser import QASMCircuit
+from ..circuits.gates import GATE_IDS
+from ..circuits.compiler import QuantumTranspiler
+from ..circuits.registry import HAS_JAX, NoiseModel, NoiseSpec
+from ..config import ensure_x64
+
+if HAS_JAX:
+    import jax
+    import jax.numpy as jnp
+    from ..circuits.compiler import _compile_and_run_circuit_jit
+else:
+    jnp = None
+
+
+#: gates that receive a value from theta — must match the n_params count
+#: below exactly, or theta's allocation order desyncs from the template's
+#: injection order. Kept identical to dashboard_core's own list (same
+#: engine, one source of truth).
+_PARAMETRIC_GATES = ('rx', 'ry', 'rz', 'u1', 'p', 'cp', 'crz')
+_TWO_QUBIT_GATES = ('cx', 'cy', 'cz', 'cp', 'crz', 'swap')
+
+
+def _require_jax():
+    if not HAS_JAX:
+        raise ImportError(
+            "circuit_to_energy_fn requires JAX. "
+            "Install it with: pip install dense-evolution[jax]")
+    ensure_x64()  # this template is always complex128 -- see config.py
+
+
+def _build_template(circuit: QASMCircuit, n_qubits: int) -> "jnp.ndarray":
+    """Builds the (n_ops, 4) float64 [g_id, q1, q2, sentinel] template that
+    the energy function injects theta into (-1.0 in the param slot for
+    gates whose value comes from theta, patched in via jnp.where inside a
+    jax.lax.scan, never a Python float() — that would sever the JAX trace).
+
+    Structural pass only: build (name, *qubits) tuples (no param values —
+    QuantumTranspiler.transpile only inspects gate name/qubit-count, for
+    ccx/swap decomposition), transpile once, then look up g_id per gate and
+    mark parametric slots with the sentinel. ccx/toffoli decomposes into
+    non-parametric gates only, so this never desyncs theta's order.
+
+    circuit.ops qubits are always plain ints here (QASMCircuit is the
+    package's own interchange type, produced by QASMParser.parse and by
+    the Qiskit/PennyLane interop bridge alike) — no defensive unwrapping
+    of framework-specific qubit/wire objects needed.
+    """
+    tuples = []
+    for op in circuit.ops:
+        name = str(op['name']).lower().strip()
+        qubits = [int(q) for q in op.get('qubits', [])]
+        if not qubits or any(q >= n_qubits for q in qubits):
+            continue
+        tuples.append((name, *qubits))
+
+    target = QuantumTranspiler.transpile(tuples)
+
+    rows = []
+    for cmd in target:
+        name = cmd[0].lower()
+        if name not in GATE_IDS:
+            # BUG FIX: used to `continue` here, silently dropping the
+            # gate from the traced circuit -- a typo'd or unsupported
+            # gate name (e.g. 'u2'/'u3', multi-parameter gates this
+            # template's single-param-per-row [g_id, q1, q2, sentinel]
+            # shape can't represent -- see gates.py's PARAMETRIC_GATES)
+            # gave a silently WRONG energy/gradient instead of an error.
+            raise ValueError(
+                f"circuit_to_energy_fn: gate '{name}' has no GATE_IDS "
+                f"entry, so it can't be represented in this JIT template "
+                f"and would otherwise be silently dropped from the "
+                f"traced circuit. Multi-parameter gates like 'u2'/'u3' "
+                f"aren't supported here (this template carries one "
+                f"parameter per row) -- decompose them into rx/ry/rz/cx "
+                f"first, or use DenseSVSimulator.run_circuit (the eager "
+                f"path) instead, which does support them directly.")
+        g_id = float(GATE_IDS[name])
+        qubits = cmd[1:]
+        sentinel = -1.0 if name in _PARAMETRIC_GATES else 0.0
+        if name in _TWO_QUBIT_GATES and len(qubits) >= 2:
+            rows.append([g_id, float(qubits[0]), float(qubits[1]), sentinel])
+        elif qubits:
+            rows.append([g_id, float(qubits[0]), 0.0, sentinel])
+
+    if not rows:
+        return jnp.empty((0, 4), dtype=jnp.float64)
+    return jnp.array(rows, dtype=jnp.float64)
+
+
+def circuit_to_energy_fn(
+    circuit: QASMCircuit, n_qubits: int
+) -> Tuple[Callable, int]:
+    """
+    Convert a QASMCircuit into a JAX-differentiable energy function.
+
+    circuit : QASMCircuit — from QASMParser.parse(qasm), or from the
+              Qiskit/PennyLane interop bridge (from_qiskit/from_pennylane).
+
+    Returns (energy_fn, n_params):
+      energy_fn(theta, h_matrix, stato_zero=None, noise=None) ->
+      (energy, statevector) is a pure JAX function, differentiable w.r.t.
+      theta via jax.grad / jax.value_and_grad(energy_fn, argnums=0,
+      has_aux=True). stato_zero defaults to |0...0> if not given.
+      n_params is the number of parametric gates in the circuit, in the
+      same order theta is injected — build theta as an array of that
+      length.
+
+      noise, when given, is a registry.NoiseSpec (a JAX PyTree) applied
+      to the statevector right after the circuit and before the energy
+      expectation value is computed — natively inside the same traced
+      computation as theta, not as an external step the caller has to
+      splice in around energy_fn themselves. Because NoiseSpec carries
+      its own jax_key as a pytree leaf, the whole thing stays
+      jit/grad/vmap-composable with no OS-entropy fallback and no
+      external key-management workaround:
+
+          noise = NoiseSpec(model='depolarizing', p=0.05,
+                             jax_key=jax.random.PRNGKey(0))
+          energy, sv = energy_fn(theta, h_matrix, noise=noise)
+
+    This is the same engine dashboard_core.py's real VQE gradient uses
+    internally (verified against finite differences, ~1e-11 agreement) —
+    exposed here as public API so it's reachable without reading
+    dashboard_core.py, and so circuits imported via from_qiskit/
+    from_pennylane (which are NOT differentiable on their own — see
+    run_pennylane_circuit's docstring) have a real way to become
+    differentiable instead of just a documented dead end.
+    """
+    _require_jax()
+    template = _build_template(circuit, n_qubits)
+    n_params = sum(1 for op in circuit.ops
+                   if str(op['name']).lower().strip() in _PARAMETRIC_GATES)
+
+    def energy_fn(theta, h_matrix, stato_zero: Optional["jnp.ndarray"] = None,
+                  noise: Optional["NoiseSpec"] = None):
+        if stato_zero is None:
+            stato_zero = jnp.zeros(2 ** n_qubits, dtype=jnp.complex128).at[0].set(1.0)
+
+        if n_params == 0:
+            # No parametric gates -> no sentinel (-1.0) rows in template, so
+            # patch_and_apply below would never take its is_param branch.
+            # Skip the scan entirely rather than index into an empty theta
+            # array during tracing (n_params is a static Python int, fixed
+            # at circuit_to_energy_fn() call time, so this branch is
+            # resolved before any tracing happens — not a jax.lax.cond).
+            sv = _compile_and_run_circuit_jit(stato_zero, template)
+        else:
+            def patch_and_apply(carry, op):
+                idx = carry
+                is_param = op[3] == -1.0
+                final_p = jnp.where(is_param, theta[idx], op[3])
+                next_idx = jnp.where(is_param, idx + jnp.int32(1), idx)
+                return next_idx, jnp.array([op[0], op[1], op[2], final_p], dtype=jnp.float64)
+
+            _, patched_ops = jax.lax.scan(patch_and_apply, jnp.int32(0), template)
+            sv = _compile_and_run_circuit_jit(stato_zero, patched_ops)
+
+        if noise is not None:
+            sv = NoiseModel.apply_to_sv(
+                sv, n_qubits, model=noise.model, p=noise.p,
+                jax_key=noise.jax_key, qubits=list(noise.qubits) if noise.qubits is not None else None,
+            )
+
+        energy = jnp.real(jnp.vdot(sv, h_matrix @ sv))
+        return energy, sv
+
+    return energy_fn, n_params

dense_evolution/solvers/harrison_tb.py

@@ -0,0 +1,189 @@
+"""
+Harrison empirical tight-binding parameters -- builds an sp3 tight-binding
+Hamiltonian for a cluster of real atoms directly from published atomic term
+values and the universal bond-scaling law, with no SCF/DFT and no external
+quantum-chemistry dependency (PySCF, OpenFermion).
+
+Source: Walter A. Harrison, "Electronic Structure and the Properties of
+Solids" (Dover reprint). Atomic term values (ELEMENTS) and the universal
+eta coefficients (ETA) below are transcribed from that book's Solid State
+Table, cross-checked against the numbers in jarvist/HarrisonSolidStateTable.jl
+(github.com/jarvist/HarrisonSolidStateTable.jl), a Julia implementation of
+the same table. Only elements with both an s and a p term value in that
+table are included here (the "simple atom" sp3 entries Harrison uses for
+tetrahedral semiconductors); d-block entries are left out since Harrison's
+own table flags them "not well checked".
+
+Sign convention: ELEMENTS stores true orbital energies (negative, eV --
+bound states below vacuum), i.e. the negative of the magnitudes printed in
+Harrison's table.
+
+Two-center bond integrals follow Harrison's universal scaling law:
+    V_ll'm = eta_ll'm * hbar^2 / (m_e * d^2)
+with d the bond length in Angstrom and hbar^2/m_e = 7.62 eV*Angstrom^2 (the
+standard constant quoted alongside this law). eta_ssσ/spσ/ppσ/ppπ are
+dimensionless and materials-independent -- the same four numbers apply to
+every element pair.
+
+Slater-Koster sp3 matrix elements (sp3_bond_block) follow the standard
+1954 Slater-Koster table for an (s, px, py, pz) basis.
+
+zincblende_hamiltonian builds the periodic Bloch Hamiltonian for a
+two-atom zinc-blende basis (nearest-neighbor sp3, 4 bonds per atom) --
+validated against real GaAs (a=5.6533 Angstrom): computed direct gap
+at Gamma is 2.91 eV vs. the experimental 1.42 eV, roughly 2x too
+large. This is a known, documented limitation of Harrison's universal
+(materials-independent) parameter set on polar/ionic compound
+semiconductors -- not a bug here -- since it uses no per-material
+fitting and omits d-orbitals. Useful as a fast, dependency-free
+qualitative estimate; not a substitute for this project's DFT-derived
+GaAs parameters where quantitative accuracy matters.
+"""
+import numpy as np
+
+__all__ = [
+    'ELEMENTS', 'ETA', 'HBAR2_OVER_M_EV_ANG2',
+    'hopping_integral', 'sp3_bond_block', 'sp3_dimer_hamiltonian',
+    'zincblende_hamiltonian',
+]
+
+# name -> (Z, eps_s [eV], eps_p [eV], atomic mass [amu])
+# Values transcribed from Harrison's Solid State Table (magnitudes in the
+# book are positive "term values"; stored here as negative orbital energies).
+ELEMENTS = {
+    'Be': dict(Z=4,  eps_s=-8.17,  eps_p=-4.14,  mass=9.01),
+    'B':  dict(Z=5,  eps_s=-12.54, eps_p=-6.64,  mass=10.81),
+    'C':  dict(Z=6,  eps_s=-17.52, eps_p=-8.97,  mass=12.01),
+    'N':  dict(Z=7,  eps_s=-23.04, eps_p=-11.47, mass=14.01),
+    'O':  dict(Z=8,  eps_s=-29.14, eps_p=-14.13, mass=16.00),
+    'Mg': dict(Z=12, eps_s=-6.86,  eps_p=-2.99,  mass=24.31),
+    'Si': dict(Z=14, eps_s=-13.55, eps_p=-6.52,  mass=28.09),
+    'P':  dict(Z=15, eps_s=-17.10, eps_p=-8.33,  mass=30.97),
+    'S':  dict(Z=16, eps_s=-20.80, eps_p=-10.27, mass=32.06),
+    'Cu': dict(Z=29, eps_s=-6.92,  eps_p=-1.83,  mass=63.54),
+    'Zn': dict(Z=30, eps_s=-8.40,  eps_p=-3.38,  mass=65.37),
+    'Ga': dict(Z=31, eps_s=-11.37, eps_p=-4.90,  mass=69.82),
+    'Ge': dict(Z=32, eps_s=-14.38, eps_p=-6.36,  mass=72.59),
+    'As': dict(Z=33, eps_s=-17.33, eps_p=-7.91,  mass=74.92),
+    'Se': dict(Z=34, eps_s=-20.32, eps_p=-9.53,  mass=78.96),
+    'Sn': dict(Z=50, eps_s=-12.50, eps_p=-5.94,  mass=118.7),
+    'I':  dict(Z=53, eps_s=-19.42, eps_p=-9.97,  mass=126.9),
+    'Pb': dict(Z=82, eps_s=-12.07, eps_p=-5.77,  mass=207.2),
+}
+
+# Universal Harrison interatomic matrix element coefficients (dimensionless),
+# from the Dover reprint's "top right table". Materials-independent.
+ETA = dict(ss_sigma=-1.40, sp_sigma=1.84, pp_sigma=3.24, pp_pi=-0.81)
+
+# hbar^2 / m_e in eV*Angstrom^2, the constant in Harrison's d^-2 scaling law.
+HBAR2_OVER_M_EV_ANG2 = 7.62
+
+
+def hopping_integral(eta, d_angstrom):
+    """V_ll'm = eta * hbar^2/(m_e d^2) [eV], for bond length d in Angstrom."""
+    if d_angstrom <= 0:
+        raise ValueError(f"bond length must be positive, got {d_angstrom}")
+    return eta * HBAR2_OVER_M_EV_ANG2 / d_angstrom ** 2
+
+
+def sp3_bond_block(l, m, n, d_angstrom, eta=ETA):
+    """
+    4x4 Slater-Koster hopping block <A, {s,px,py,pz}| H |B, {s,px,py,pz}>
+    for a bond from atom A to atom B along direction cosines (l, m, n)
+    (unit vector, l^2+m^2+n^2 = 1) and bond length d_angstrom.
+
+    Basis order: s, px, py, pz. Standard Slater-Koster (1954) table.
+    """
+    norm = l * l + m * m + n * n
+    if not np.isclose(norm, 1.0, atol=1e-6):
+        raise ValueError(f"(l, m, n) must be a unit vector, got norm={norm}")
+
+    Vssσ = hopping_integral(eta['ss_sigma'], d_angstrom)
+    Vspσ = hopping_integral(eta['sp_sigma'], d_angstrom)
+    Vppσ = hopping_integral(eta['pp_sigma'], d_angstrom)
+    Vppπ = hopping_integral(eta['pp_pi'], d_angstrom)
+
+    block = np.zeros((4, 4), dtype=np.complex128)
+    block[0, 0] = Vssσ
+    block[0, 1], block[0, 2], block[0, 3] = l * Vspσ, m * Vspσ, n * Vspσ
+    block[1, 0], block[2, 0], block[3, 0] = -l * Vspσ, -m * Vspσ, -n * Vspσ
+
+    block[1, 1] = l * l * Vppσ + (1 - l * l) * Vppπ
+    block[2, 2] = m * m * Vppσ + (1 - m * m) * Vppπ
+    block[3, 3] = n * n * Vppσ + (1 - n * n) * Vppπ
+
+    block[1, 2] = block[2, 1] = l * m * (Vppσ - Vppπ)
+    block[2, 3] = block[3, 2] = m * n * (Vppσ - Vppπ)
+    block[1, 3] = block[3, 1] = l * n * (Vppσ - Vppπ)
+    return block
+
+
+def sp3_dimer_hamiltonian(element_a, element_b, bond_length_angstrom,
+                           direction=(0.0, 0.0, 1.0), eta=ETA):
+    """
+    8x8 sp3 tight-binding Hamiltonian for a 2-atom A-B cluster (one bond),
+    basis order [A:s,px,py,pz, B:s,px,py,pz]. On-site blocks are each
+    atom's diagonal (eps_s, eps_p, eps_p, eps_p); the A-B off-diagonal
+    block is sp3_bond_block along `direction` (unit vector, default: bond
+    along z), Hermitian-conjugated into the B-A block.
+
+    This is a minimal, directly checkable sanity case (bonding/antibonding
+    sp3 splitting), not a periodic-solid band structure.
+    """
+    for name in (element_a, element_b):
+        if name not in ELEMENTS:
+            raise ValueError(f"no Harrison sp term values for element {name!r}; "
+                              f"available: {sorted(ELEMENTS)}")
+    l, m, n = direction
+    a, b = ELEMENTS[element_a], ELEMENTS[element_b]
+
+    H = np.zeros((8, 8), dtype=np.complex128)
+    H[0, 0] = a['eps_s']
+    H[1, 1] = H[2, 2] = H[3, 3] = a['eps_p']
+    H[4, 4] = b['eps_s']
+    H[5, 5] = H[6, 6] = H[7, 7] = b['eps_p']
+
+    hop = sp3_bond_block(l, m, n, bond_length_angstrom, eta=eta)
+    H[0:4, 4:8] = hop
+    H[4:8, 0:4] = hop.conj().T
+    return H
+
+
+def zincblende_hamiltonian(k, cation, anion, lattice_constant_angstrom, eta=ETA):
+    """
+    8x8 Bloch Hamiltonian for a zinc-blende crystal's two-atom basis
+    (cation at (0,0,0), anion at (1/4,1/4,1/4) of the conventional cubic
+    cell), sp3 nearest-neighbor tight-binding, at crystal momentum k
+    (Cartesian, 1/Angstrom -- e.g. Gamma=(0,0,0)).
+
+    Basis order [cation:s,px,py,pz, anion:s,px,py,pz]. The four
+    cation->anion nearest-neighbor bonds are the standard zinc-blende
+    tetrahedral set (lattice_constant/4)*(1,1,1), (1,-1,-1), (-1,1,-1),
+    (-1,-1,1); each contributes sp3_bond_block(...) weighted by its
+    Bloch phase exp(i k . d), summed into the off-diagonal block.
+    """
+    for name in (cation, anion):
+        if name not in ELEMENTS:
+            raise ValueError(f"no Harrison sp term values for element {name!r}; "
+                              f"available: {sorted(ELEMENTS)}")
+    k = np.asarray(k, dtype=float)
+    d_vectors = (lattice_constant_angstrom / 4) * np.array([
+        [1, 1, 1], [1, -1, -1], [-1, 1, -1], [-1, -1, 1],
+    ], dtype=float)
+    bond_length = np.linalg.norm(d_vectors[0])
+
+    T = np.zeros((4, 4), dtype=np.complex128)
+    for d in d_vectors:
+        l, m, n = d / bond_length
+        phase = np.exp(1j * np.dot(k, d))
+        T += phase * sp3_bond_block(l, m, n, bond_length, eta=eta)
+
+    c, a = ELEMENTS[cation], ELEMENTS[anion]
+    H = np.zeros((8, 8), dtype=np.complex128)
+    H[0, 0] = c['eps_s']
+    H[1, 1] = H[2, 2] = H[3, 3] = c['eps_p']
+    H[4, 4] = a['eps_s']
+    H[5, 5] = H[6, 6] = H[7, 7] = a['eps_p']
+    H[0:4, 4:8] = T
+    H[4:8, 0:4] = T.conj().T
+    return H