dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/mps.py

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

dense_evolution/native_hf/__init__.py

@@ -0,0 +1,26 @@
+"""
+Native, JAX-vectorized ab-initio Hartree-Fock engine for Dense-Evolution.
+
+Computes molecular one- and two-electron integrals (overlap, kinetic,
+nuclear attraction, electron repulsion) via the Obara-Saika recursion
+[Obara, Saika, J. Chem. Phys. 84, 3963 (1986)], batched with jax.lax.scan
+so the whole shell-quartet loop compiles to a single XLA program instead
+of looping in the Python interpreter.
+
+This module exists because PennyLane's own differentiable Hartree-Fock
+solver (qml.qchem, method="dhf") builds these same integrals through a
+Python-level loop wrapped in its autograd-tracing numpy layer -- correct,
+but roughly 100x slower than a properly vmap/jit-compiled implementation
+for anything beyond a couple of atoms (profiled on Si2/STO-3G: 482 of
+483 total seconds were spent in that loop). The second-quantization and
+Jordan-Wigner mapping steps that come after the integrals are already
+fast in PennyLane, so this module only replaces the integral/SCF stage
+and hands its output to qml.qchem.observable_hf.fermionic_observable.
+
+Design and algorithm choice were informed by studying lowdanie/hartree-fock-solver
+("slaterform", Apache-2.0) as a reference for how to structure the
+Obara-Saika recursion with jax.lax.scan, and by PennyLane's own white
+paper (Delgado et al., "Differentiable quantum computational chemistry
+with PennyLane", arXiv:2111.09967). No source code from either project
+is copied here.
+"""

dense_evolution/native_hf/_libcint/LICENSE-libcint

@@ -0,0 +1,10 @@
+Copyright (c) 2012, Qiming Sun
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dense_evolution/native_hf/assembly.py

@@ -0,0 +1,304 @@
+"""Assembling full molecular AO integral matrices from contracted shells.
+
+Each pair (or quartet, for repulsion) of shells contributes a block to
+the overall S/T/V matrices (or ERI tensor). We loop over shell
+pairs/quartets in plain Python -- for a minimal basis like STO-3G there
+are only a handful of shells per atom (Si2/STO-3G: 6 shells total), so
+this loop is cheap. The sum over primitives *within* a shell pair/quartet
+and the slicing down to physical Cartesian components both happen
+inside a single jax.jit-compiled call per shell pair/quartet: doing
+that slicing eagerly (one jnp.ndarray.__getitem__ per primitive
+combination) turned out to cost as much per-call dispatch overhead as
+PennyLane's own scalar-at-a-time autograd loop, defeating the purpose,
+so everything from "loop over primitives" to "slice out the physical
+components" is fused into one compiled program per shell pair/quartet
+and only that program's *output* touches eager Python.
+"""
+
+import functools
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+from dense_evolution.native_hf.basis import ContractedShell, n_cartesian_functions
+from dense_evolution.native_hf.cartesian import cartesian_powers, cartesian_normalization_ratios
+from dense_evolution.native_hf.gaussians import GaussianShell3D
+from dense_evolution.native_hf.overlap import overlap_3d
+from dense_evolution.native_hf.kinetic import kinetic_3d
+from dense_evolution.native_hf.coulomb import nuclear_attraction, electron_repulsion
+
+
+@functools.partial(jax.jit, static_argnames=("degree_a", "degree_b", "primitive_fn"))
+def _pair_block(exponents_a, coeffs_a, center_a, degree_a, exponents_b, coeffs_b, center_b, degree_b, primitive_fn, extra=()):
+    """extra: additional *traced* arrays (e.g. nuclear charges/positions)
+    forwarded to primitive_fn unchanged -- traced (not static) so that
+    calling this with a different molecule geometry reuses the same
+    compiled program instead of retracing. primitive_fn must itself be a
+    stable, module-level (not freshly-created-per-call) callable, since
+    it IS a static jit key."""
+    powers_a = jnp.asarray(cartesian_powers(degree_a))
+    powers_b = jnp.asarray(cartesian_powers(degree_b))
+    ratio_a = jnp.asarray(cartesian_normalization_ratios(degree_a))
+    ratio_b = jnp.asarray(cartesian_normalization_ratios(degree_b))
+
+    def one_primitive_pair(ea, ca, eb, cb):
+        ga = GaussianShell3D(degree=degree_a, exponent=ea, center=center_a)
+        gb = GaussianShell3D(degree=degree_b, exponent=eb, center=center_b)
+        full = primitive_fn(ga, gb, *extra)
+        sliced = full[powers_a[:, 0], powers_a[:, 1], powers_a[:, 2]][:, powers_b[:, 0], powers_b[:, 1], powers_b[:, 2]]
+        return ca * cb * sliced
+
+    batched = jax.vmap(
+        jax.vmap(one_primitive_pair, in_axes=(None, None, 0, 0)),
+        in_axes=(0, 0, None, None),
+    )(exponents_a, coeffs_a, exponents_b, coeffs_b)
+    return ratio_a[:, None] * ratio_b[None, :] * jnp.sum(batched, axis=(0, 1))
+
+
+@functools.partial(jax.jit, static_argnames=("degrees", "primitive_fn"))
+def _quartet_block(exponents, coeffs, centers, degrees, primitive_fn):
+    """exponents/coeffs: tuples of 4 arrays (one per shell), centers: tuple
+    of 4 (3,) arrays, degrees: tuple of 4 static ints."""
+    powers = [jnp.asarray(cartesian_powers(d)) for d in degrees]
+    ratios = [jnp.asarray(cartesian_normalization_ratios(d)) for d in degrees]
+
+    def one_quartet(ea, ca, eb, cb, ec, cc, ed, cd):
+        ga = GaussianShell3D(degree=degrees[0], exponent=ea, center=centers[0])
+        gb = GaussianShell3D(degree=degrees[1], exponent=eb, center=centers[1])
+        gc = GaussianShell3D(degree=degrees[2], exponent=ec, center=centers[2])
+        gd = GaussianShell3D(degree=degrees[3], exponent=ed, center=centers[3])
+        full = primitive_fn(ga, gb, gc, gd)
+        sliced = full[powers[0][:, 0], powers[0][:, 1], powers[0][:, 2]]
+        sliced = sliced[:, powers[1][:, 0], powers[1][:, 1], powers[1][:, 2]]
+        sliced = sliced[:, :, powers[2][:, 0], powers[2][:, 1], powers[2][:, 2]]
+        sliced = sliced[:, :, :, powers[3][:, 0], powers[3][:, 1], powers[3][:, 2]]
+        return ca * cb * cc * cd * sliced
+
+    vmapped = one_quartet
+    # vmap outward-in: d, c, b, a -- each adds a leading batch axis.
+    vmapped = jax.vmap(vmapped, in_axes=(None, None, None, None, None, None, 0, 0))
+    vmapped = jax.vmap(vmapped, in_axes=(None, None, None, None, 0, 0, None, None))
+    vmapped = jax.vmap(vmapped, in_axes=(None, None, 0, 0, None, None, None, None))
+    vmapped = jax.vmap(vmapped, in_axes=(0, 0, None, None, None, None, None, None))
+
+    ea, ca, eb, cb, ec, cc, ed, cd = (
+        exponents[0], coeffs[0], exponents[1], coeffs[1],
+        exponents[2], coeffs[2], exponents[3], coeffs[3],
+    )
+    batched = vmapped(ea, ca, eb, cb, ec, cc, ed, cd)
+    summed = jnp.sum(batched, axis=(0, 1, 2, 3))
+    ratio_outer = ratios[0][:, None, None, None] * ratios[1][None, :, None, None] \
+        * ratios[2][None, None, :, None] * ratios[3][None, None, None, :]
+    return ratio_outer * summed
+
+
+_QUARTET_SYMMETRY_PERMS = (
+    (0, 1, 2, 3), (1, 0, 2, 3), (0, 1, 3, 2), (1, 0, 3, 2),
+    (2, 3, 0, 1), (2, 3, 1, 0), (3, 2, 0, 1), (3, 2, 1, 0),
+)
+
+
+def _canonical_quartet_perm(degrees: tuple) -> tuple:
+    """The electron-repulsion integral (ab|cd) is invariant under swapping
+    a<->b, swapping c<->d, and swapping the pair (a,b)<->(c,d) -- the same
+    8-element symmetry build_repulsion_tensor already uses to store one
+    computed block into 8 tensor locations via transpose. Applied here to
+    the OTHER end: _quartet_block's jax.jit cache keys on the exact
+    (a,b,c,d)-ordered `degrees` tuple, so two quartets that are physically
+    the same integral under one of these 8 relabelings still trigger two
+    separate compilations if their degrees arrive in different orders.
+    Picking the lexicographically largest of the 8 relabelings as a fixed
+    canonical form (independent of which one happens to come in) collapses
+    that duplication -- measured on Ne/6-31G*: 35 distinct compiled
+    signatures down to fewer, see native_hf_eri_profile_ne_631gstar.py in
+    Dense-Evolution-Discovery."""
+    best_perm = _QUARTET_SYMMETRY_PERMS[0]
+    best_key = tuple(degrees[i] for i in best_perm)
+    for perm in _QUARTET_SYMMETRY_PERMS[1:]:
+        key = tuple(degrees[i] for i in perm)
+        if key > best_key:
+            best_key = key
+            best_perm = perm
+    return best_perm
+
+
+def _invert_perm(perm: tuple) -> tuple:
+    inv = [0, 0, 0, 0]
+    for i, p in enumerate(perm):
+        inv[p] = i
+    return tuple(inv)
+
+
+def _canonical_quartet_block(exponents, coeffs, centers, degrees, primitive_fn):
+    perm = _canonical_quartet_perm(degrees)
+    if perm == (0, 1, 2, 3):
+        return _quartet_block(exponents, coeffs, centers, degrees, primitive_fn)
+    p_exponents = tuple(exponents[i] for i in perm)
+    p_coeffs = tuple(coeffs[i] for i in perm)
+    p_centers = tuple(centers[i] for i in perm)
+    p_degrees = tuple(degrees[i] for i in perm)
+    block = _quartet_block(p_exponents, p_coeffs, p_centers, p_degrees, primitive_fn)
+    return jnp.transpose(block, _invert_perm(perm))
+
+
+def _shell_offsets(shells: list[ContractedShell]) -> list[int]:
+    offsets, running = [], 0
+    for s in shells:
+        offsets.append(running)
+        running += len(cartesian_powers(s.degree))
+    return offsets
+
+
+def _overlap_primitive(ga, gb):
+    return overlap_3d(ga, gb)
+
+
+def build_overlap_matrix(shells: list[ContractedShell]) -> jax.Array:
+    return _build_two_index(shells, _overlap_primitive)
+
+
+def _core_hamiltonian_primitive(ga, gb, charges, positions):
+    T = kinetic_3d(ga, gb)
+    per_nucleus = jax.vmap(lambda z, r: -z * nuclear_attraction(ga, gb, r))(charges, positions)
+    V = jnp.sum(per_nucleus, axis=0)
+    return -0.5 * T + V
+
+
+def build_core_hamiltonian(shells: list[ContractedShell], nuclear_charges: list[float], nuclear_positions: np.ndarray) -> jax.Array:
+    charges = jnp.asarray(nuclear_charges, dtype=jnp.float64)
+    positions = jnp.asarray(nuclear_positions, dtype=jnp.float64)
+    return _build_two_index(shells, _core_hamiltonian_primitive, extra=(charges, positions))
+
+
+def _build_two_index(shells: list[ContractedShell], primitive_fn, extra=()) -> jax.Array:
+    n = n_cartesian_functions(shells)
+    offsets = _shell_offsets(shells)
+    M = jnp.zeros((n, n))
+    for i, sa in enumerate(shells):
+        for j, sb in enumerate(shells):
+            block = _pair_block(
+                sa.exponents, sa.coefficients, sa.center, sa.degree,
+                sb.exponents, sb.coefficients, sb.center, sb.degree,
+                primitive_fn, extra=extra,
+            )
+            oi, oj = offsets[i], offsets[j]
+            M = M.at[oi : oi + block.shape[0], oj : oj + block.shape[1]].set(block)
+    return M
+
+
+def _pad_primitives(exponents: jax.Array, coeffs: jax.Array, target_n: int) -> tuple:
+    """Pad a shell's primitives up to target_n by repeating its last exponent
+    with coefficient 0 -- contributes exactly zero to the primitive sum (not
+    an approximation), so every shell in a molecule can share one primitive
+    count and _quartet_block's JIT cache stops keying on it. Unlike padding
+    the angular-momentum degree (measured as a regression: it forces cheap,
+    many-primitive low-degree shells through the expensive high-degree
+    recursion), padding primitive count doesn't touch the recursion at all --
+    it only lengthens an already-cheap vmap axis (measured warm-cache cost:
+    0.0001-0.005s regardless of primitive count)."""
+    n = exponents.shape[0]
+    if n == target_n:
+        return exponents, coeffs
+    pad_n = target_n - n
+    exponents = jnp.concatenate([exponents, jnp.full((pad_n,), exponents[-1])])
+    coeffs = jnp.concatenate([coeffs, jnp.zeros(pad_n)])
+    return exponents, coeffs
+
+
+def _schwarz_bound(sa: ContractedShell, sb: ContractedShell, max_primitives: int) -> float:
+    ea, ca = _pad_primitives(sa.exponents, sa.coefficients, max_primitives)
+    eb, cb = _pad_primitives(sb.exponents, sb.coefficients, max_primitives)
+    block = np.array(
+        _canonical_quartet_block(
+            (ea, eb, ea, eb),
+            (ca, cb, ca, cb),
+            (sa.center, sb.center, sa.center, sb.center),
+            (sa.degree, sb.degree, sa.degree, sb.degree),
+            electron_repulsion,
+        )
+    )
+    na, nb = block.shape[0], block.shape[1]
+    diag = np.array([[block[p, q, p, q] for q in range(nb)] for p in range(na)])
+    return float(np.sqrt(np.max(np.abs(diag))))
+
+
+def _shell_pair_schwarz_bounds(shells: list[ContractedShell], max_primitives: int) -> dict:
+    bounds = {}
+    for i, sa in enumerate(shells):
+        for j in range(i + 1):
+            sb = shells[j]
+            q = _schwarz_bound(sa, sb, max_primitives)
+            bounds[(i, j)] = q
+            bounds[(j, i)] = q
+    return bounds
+
+
+def quartet_screening_indices(shells: list[ContractedShell], screening_tol: float = 1e-12) -> list[tuple[int, int, int, int]]:
+    """The (i,j,k,l) shell-index quartets build_repulsion_tensor would
+    compute, decided from Schwarz bounds -- split out so a caller
+    differentiating build_repulsion_tensor w.r.t. nuclear positions can
+    compute this ONCE from a concrete (non-traced) geometry and reuse it.
+
+    Schwarz screening is a discrete, structural decision (which terms
+    exist in the sum at all), not a smooth function of geometry -- Python
+    control flow like `if bound < tol` cannot run on a traced value, the
+    same reason any code with data-dependent sparsity can't be
+    differentiated as a black box. Real differentiable quantum chemistry
+    codes handle this the same way: freeze the sparsity pattern from a
+    concrete evaluation, then differentiate a numerical re-evaluation
+    that reuses that fixed pattern. Passing this list's output back into
+    build_repulsion_tensor's `quartet_indices` argument is that reuse."""
+    max_primitives = max(s.exponents.shape[0] for s in shells)
+    schwarz = _shell_pair_schwarz_bounds(shells, max_primitives)
+    indices = []
+    for i in range(len(shells)):
+        for j in range(i + 1):
+            ij_index = i * (i + 1) // 2 + j
+            for k in range(len(shells)):
+                for l in range(k + 1):
+                    kl_index = k * (k + 1) // 2 + l
+                    if ij_index < kl_index:
+                        continue
+                    if schwarz[(i, j)] * schwarz[(k, l)] < screening_tol:
+                        continue
+                    indices.append((i, j, k, l))
+    return indices
+
+
+def build_repulsion_tensor(
+    shells: list[ContractedShell], screening_tol: float = 1e-12,
+    quartet_indices: list[tuple[int, int, int, int]] = None,
+) -> jax.Array:
+    n = n_cartesian_functions(shells)
+    offsets = _shell_offsets(shells)
+    V = jnp.zeros((n, n, n, n))
+    max_primitives = max(s.exponents.shape[0] for s in shells)
+    if quartet_indices is None:
+        quartet_indices = quartet_screening_indices(shells, screening_tol)
+    for i, j, k, l in quartet_indices:
+        sa, sb, sc, sd = shells[i], shells[j], shells[k], shells[l]
+        ea, ca = _pad_primitives(sa.exponents, sa.coefficients, max_primitives)
+        eb, cb = _pad_primitives(sb.exponents, sb.coefficients, max_primitives)
+        ec, cc = _pad_primitives(sc.exponents, sc.coefficients, max_primitives)
+        ed, cd = _pad_primitives(sd.exponents, sd.coefficients, max_primitives)
+        block = _canonical_quartet_block(
+            (ea, eb, ec, ed),
+            (ca, cb, cc, cd),
+            (sa.center, sb.center, sc.center, sd.center),
+            (sa.degree, sb.degree, sc.degree, sd.degree),
+            electron_repulsion,
+        )
+        oi, oj, ok, ol = offsets[i], offsets[j], offsets[k], offsets[l]
+        for pi, pj, pk, pl, b in (
+            (oi, oj, ok, ol, block),
+            (oj, oi, ok, ol, block.transpose(1, 0, 2, 3)),
+            (oi, oj, ol, ok, block.transpose(0, 1, 3, 2)),
+            (oj, oi, ol, ok, block.transpose(1, 0, 3, 2)),
+            (ok, ol, oi, oj, block.transpose(2, 3, 0, 1)),
+            (ol, ok, oi, oj, block.transpose(3, 2, 0, 1)),
+            (ok, ol, oj, oi, block.transpose(2, 3, 1, 0)),
+            (ol, ok, oj, oi, block.transpose(3, 2, 1, 0)),
+        ):
+            V = V.at[pi : pi + b.shape[0], pj : pj + b.shape[1], pk : pk + b.shape[2], pl : pl + b.shape[3]].set(b)
+    return V

dense_evolution/native_hf/basis.py

@@ -0,0 +1,117 @@
+"""Loading contracted basis-set shells for a molecule.
+
+Basis-set parameters (exponents, contraction coefficients) are fetched
+from the Basis Set Exchange (the `basis_set_exchange` PyPI package,
+data-only, BSD-licensed -- https://www.basissetexchange.org), so this
+module works for any element the basis has data for, not just the
+handful PennyLane's own bundled STO-3G table covers (which stops at
+Ne and is why Silicon needed a hand-written patch earlier in this
+project).
+
+The coefficients BSE reports are for *unnormalized* primitives, so each
+primitive's contraction coefficient must be rescaled by its own L2 norm
+before it can be summed against another shell's primitives. We get that
+norm for free by reusing our own overlap_3d on the primitive against
+itself: N = 1/sqrt(<primitive|primitive>).
+"""
+
+import dataclasses
+
+import basis_set_exchange as bse
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+from dense_evolution.config import ensure_x64
+from dense_evolution.native_hf.cartesian import cartesian_powers
+from dense_evolution.native_hf.gaussians import GaussianShell3D
+from dense_evolution.native_hf.overlap import overlap_3d
+
+
+@dataclasses.dataclass(frozen=True)
+class ContractedShell:
+    """One angular-momentum shell (s, p, ...) of a contracted GTO."""
+
+    atom_index: int
+    center: jax.Array  # shape (3,), atomic units (Bohr)
+    degree: int  # 0 for s, 1 for p, ...
+    exponents: jax.Array  # shape (K,)
+    coefficients: jax.Array  # shape (K,), already primitive-normalized
+
+
+def _primitive_norm(exponent: jax.Array, degree: int) -> jax.Array:
+    """1/sqrt(self-overlap) for the (degree,0,0) Cartesian component,
+    used as the shared reference normalization for every Cartesian
+    component of this shell. For degree<=1 that's already each
+    component's own norm (px, py, pz are equivalent by symmetry). For
+    degree>=2 it is not (dxx and dxy have different norms) --
+    cartesian_normalization_ratios supplies the per-component correction
+    relative to this same (degree,0,0) reference, applied at assembly
+    time in assembly.py rather than here."""
+    g = GaussianShell3D(degree=degree, exponent=exponent, center=jnp.zeros(3))
+    self_overlap = overlap_3d(g, g)[degree, 0, 0, degree, 0, 0]
+    return 1.0 / jnp.sqrt(self_overlap)
+
+
+def _contracted_shell_from_bse(shell: dict, center: jax.Array, atom_index: int) -> list[ContractedShell]:
+    """BSE groups shells like STO-3G's "SP" as one entry with two rows of
+    coefficients (one for the S part, one for the P part) sharing the
+    same exponents; we split those back into separate ContractedShells
+    since our integral code handles one angular momentum at a time."""
+    angular_momenta = shell["angular_momentum"]
+    exponents = jnp.array([float(e) for e in shell["exponents"]])
+
+    shells = []
+    for row, degree in enumerate(angular_momenta):
+        coeffs = jnp.array([float(c) for c in shell["coefficients"][row]])
+        norms = jax.vmap(_primitive_norm, in_axes=(0, None))(exponents, degree)
+        shells.append(
+            ContractedShell(
+                atom_index=atom_index,
+                center=center,
+                degree=degree,
+                exponents=exponents,
+                coefficients=coeffs * norms,
+            )
+        )
+    return shells
+
+
+def load_element_shells(basis_name: str, atomic_number: int, center: jax.Array, atom_index: int) -> list[ContractedShell]:
+    data = bse.get_basis(basis_name, elements=[atomic_number])
+    electron_shells = data["elements"][str(atomic_number)]["electron_shells"]
+
+    if any(s["function_type"] not in ("gto", "gto_cartesian") for s in electron_shells):
+        raise NotImplementedError("Only Cartesian Gaussian basis sets are currently supported.")
+
+    max_degree = max(
+        degree for shell in electron_shells for degree in shell["angular_momentum"]
+    )
+    if max_degree > 2:
+        from basis_set_exchange.lut import element_sym_from_Z
+
+        sym = element_sym_from_Z(atomic_number).capitalize()
+        raise NotImplementedError(
+            f"native_hf's overlap/kinetic/Coulomb integrals only implement s, p and d "
+            f"shells (degree <= 2); {sym} (Z={atomic_number}) needs a degree-{max_degree} "
+            f"shell (f-orbitals or higher) in {basis_name}. Not a silent approximation -- "
+            f"this element genuinely isn't supported by this engine yet."
+        )
+
+    out = []
+    for shell in electron_shells:
+        out.extend(_contracted_shell_from_bse(shell, center, atom_index))
+    return out
+
+
+def build_molecule_shells(atomic_numbers: list[int], geometry_bohr: np.ndarray, basis_name: str) -> list[ContractedShell]:
+    """geometry_bohr: shape (n_atoms, 3), atomic units."""
+    ensure_x64()
+    shells = []
+    for i, (z, r) in enumerate(zip(atomic_numbers, geometry_bohr)):
+        shells.extend(load_element_shells(basis_name, z, jnp.asarray(r), i))
+    return shells
+
+
+def n_cartesian_functions(shells: list[ContractedShell]) -> int:
+    return sum(len(cartesian_powers(s.degree)) for s in shells)

dense_evolution/native_hf/boys.py

@@ -0,0 +1,35 @@
+"""The Boys function F_n(x), needed to evaluate any integral involving
+1/r12 (nuclear attraction, electron repulsion) between Gaussians.
+
+    F_n(x) = integral_0^1  t^(2n) exp(-x t^2) dt
+
+which can be written in closed form via the regularized lower incomplete
+gamma function P:
+
+    F_n(x) = Gamma(n + 1/2) * P(n + 1/2, x) / (2 * x^(n + 1/2))
+
+For x -> 0 this formula divides 0/0, so we fall back to the first-order
+Taylor expansion F_n(x) ~= 1/(2n+1) - x/(2n+3), which is accurate to
+better than machine epsilon once x is small enough that no other term
+in the calculation could still be sensitive to it.
+"""
+
+import jax
+import jax.numpy as jnp
+from jax.scipy.special import gammainc, gammaln
+
+_TAYLOR_CUTOFF = 1e-12
+
+
+def boys(n: jax.Array, x: jax.Array) -> jax.Array:
+    """Evaluate F_n(x) elementwise. n and x broadcast against each other."""
+    x = jnp.asarray(x)
+    n = jnp.asarray(n)
+
+    x_safe = jnp.where(x < _TAYLOR_CUTOFF, 1.0, x)
+    log_gamma = gammaln(n + 0.5)
+    closed_form = jnp.exp(log_gamma) * gammainc(n + 0.5, x_safe) / (2.0 * x_safe ** (n + 0.5))
+
+    taylor = 1.0 / (2.0 * n + 1.0) - x / (2.0 * n + 3.0)
+
+    return jnp.where(x < _TAYLOR_CUTOFF, taylor, closed_form)

dense_evolution/native_hf/bridge.py

@@ -0,0 +1,112 @@
+"""Bridge from our native Hartree-Fock result to a PennyLane qubit Hamiltonian.
+
+The expensive part (Hartree-Fock: integrals + SCF, everything in this
+package) is entirely ours. Second quantization and the Jordan-Wigner
+mapping are cheap (profiled at under 2 seconds even for Si2 -- see
+dense_evolution/native_hf/__init__.py's module docstring) and PennyLane
+already does them well via public functions, so we call those directly
+instead of reimplementing them.
+"""
+
+import numpy as np
+
+from dense_evolution.native_hf.basis import build_molecule_shells
+from dense_evolution.native_hf.assembly import build_overlap_matrix, build_core_hamiltonian, build_repulsion_tensor
+from dense_evolution.native_hf.scf import run_scf, HFResult
+
+# pennylane is installed in this test suite's own environment, so the
+# except branch below (and the `if qml is None` check further down) is
+# only exercised by tests/unit/test_imports.py, which blocks pennylane
+# in a separate subprocess -- invisible to same-process coverage, so
+# excluded rather than chased with an artificial same-process test.
+try:
+    import pennylane as qml
+    import pennylane.qchem.observable_hf as _pl_observable
+except ModuleNotFoundError:  # pragma: no cover
+    qml = None
+    _pl_observable = None
+
+_BOHR_PER_ANGSTROM = 1.0 / 0.52917721067
+
+
+def _ao_to_mo(H_core: np.ndarray, repulsion: np.ndarray, C: np.ndarray):
+    one = np.einsum("qr,rs,st->qt", C.T, H_core, C)
+    two = np.swapaxes(
+        np.einsum("ab,cd,bdeg,ef,gh->acfh", C.T, C.T, repulsion, C, C),
+        1, 3,
+    )
+    return one, two
+
+
+def _apply_active_space(core_constant: float, one: np.ndarray, two: np.ndarray, core_idx, active_idx):
+    for i in core_idx:
+        core_constant = core_constant + 2 * one[i][i]
+        for j in core_idx:
+            core_constant = core_constant + 2 * two[i][j][j][i] - two[i][j][i][j]
+
+    for p in active_idx:
+        for q in active_idx:
+            for i in core_idx:
+                delta = np.zeros(one.shape)
+                delta[p, q] = 1.0
+                one = one + (2 * two[i][p][q][i] - two[i][p][i][q]) * delta
+
+    one_active = one[np.ix_(active_idx, active_idx)]
+    two_active = two[np.ix_(active_idx, active_idx, active_idx, active_idx)]
+    return core_constant, one_active, two_active
+
+
+def build_qubit_hamiltonian(
+    atomic_numbers: list[int],
+    geometry_angstrom: np.ndarray,
+    n_electrons: int,
+    active_electrons: int = None,
+    active_orbitals: int = None,
+    basis_name: str = "sto-3g",
+    cutoff: float = 1e-12,
+) -> tuple["qml.Hamiltonian", int, HFResult]:
+    """Runs native Hartree-Fock, then hands the result to PennyLane for
+    second quantization + Jordan-Wigner mapping.
+
+    Returns:
+        tuple[qml.Hamiltonian, int, HFResult]: the mapped qubit
+        Hamiltonian, the qubit count, and the native HFResult -- the
+        latter useful for e.g. reporting the SCF energy alongside the
+        post-mapping ground-state energy.
+    """
+    if qml is None:  # pragma: no cover -- see the try/except above
+        raise ModuleNotFoundError(
+            "build_qubit_hamiltonian requires pennylane. "
+            "Install it with: pip install dense-evolution[pennylane]"
+        )
+
+    geometry_bohr = np.asarray(geometry_angstrom) * _BOHR_PER_ANGSTROM
+    shells = build_molecule_shells(atomic_numbers, geometry_bohr, basis_name)
+
+    S = build_overlap_matrix(shells)
+    H_core = build_core_hamiltonian(shells, [float(z) for z in atomic_numbers], geometry_bohr)
+    repulsion = build_repulsion_tensor(shells)
+
+    hf_result = run_scf(S, H_core, repulsion, n_electrons, [float(z) for z in atomic_numbers], geometry_bohr)
+
+    one, two = _ao_to_mo(H_core, repulsion, hf_result.orbital_coefficients)
+    n_orbitals = one.shape[0]
+
+    if active_electrons is None and active_orbitals is None:
+        core_idx, active_idx = [], list(range(n_orbitals))
+    else:
+        core_idx, active_idx = qml.qchem.active_space(
+            n_electrons, n_orbitals, active_electrons=active_electrons, active_orbitals=active_orbitals
+        )
+
+    core_constant, one_active, two_active = _apply_active_space(
+        hf_result.nuclear_repulsion_energy, one, two, core_idx, active_idx
+    )
+
+    fermi_op = _pl_observable.fermionic_observable(
+        np.array([core_constant]), one_active, two_active, cutoff
+    )
+    qubit_hamiltonian = qml.jordan_wigner(fermi_op)
+    n_qubits = 2 * len(active_idx)
+
+    return qubit_hamiltonian, n_qubits, hf_result