dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/native_hf/cartesian.py

@@ -0,0 +1,64 @@
+"""Enumerating the physical (lx,ly,lz) Cartesian components of a shell.
+
+Our integral tensors are shaped (degree+1, degree+1, degree+1, ...) for
+convenience, but only the (lx,ly,lz) triples with lx+ly+lz == degree
+are physical basis functions -- e.g. for a p shell (degree=1) that's
+(1,0,0), (0,1,0), (0,0,1), not e.g. (1,1,0) which the tensor shape
+happens to also have room for.
+"""
+
+import numpy as np
+
+
+def cartesian_powers(degree: int) -> np.ndarray:
+    """Returns an (M, 3) array of (lx,ly,lz) triples with lx+ly+lz == degree,
+    in a fixed canonical order determined by the generator below -- not the
+    common lexicographic convention some other codes use. For p (degree=1)
+    that's px, pz, py, not px, py, pz (confirmed by calling this function
+    directly, not assumed from the shape of the loop); for d (degree=2),
+    xx, xz, xy, zz, yz, yy, not the lexicographic xx, xy, xz, yy, yz, zz.
+    Internally consistent (cartesian_normalization_ratios and every caller
+    in assembly.py use this exact order), but this matters for anything
+    that needs to match a DIFFERENT code's AO ordering (e.g. libcint's) --
+    see native_hf/libcint_bridge.py's per-degree permutation."""
+    return np.array(
+        [(lx, degree - lx - lz, lz) for lx in range(degree, -1, -1) for lz in range(degree - lx, -1, -1)],
+        dtype=np.int32,
+    )
+
+
+def _double_factorial_odd(n: int) -> float:
+    """(2n-1)!! for n >= 0, with the (2*0-1)!! = (-1)!! = 1 convention."""
+    result = 1.0
+    k = 2 * n - 1
+    while k > 1:
+        result *= k
+        k -= 2
+    return result
+
+
+def cartesian_normalization_ratios(degree: int) -> np.ndarray:
+    """Relative normalization of each Cartesian component of a shell of
+    the given degree, relative to the (degree,0,0) component -- 1.0 for
+    every component when degree<=1 (px, py, pz are equivalent by
+    symmetry), but genuinely different starting at degree=2 (e.g. dxy
+    needs a larger normalization constant than dxx, since <dxx|dxx> =
+    3*<dxy|dxy> for the same exponent).
+
+    Standard result for an unnormalized Cartesian Gaussian primitive
+    (x-Rx)^lx (y-Ry)^ly (z-Rz)^lz exp(-a|r-R|^2): its normalization
+    constant is proportional to 1/sqrt((2lx-1)!!(2ly-1)!!(2lz-1)!!), so
+    this ratio -- independent of the exponent, verified numerically
+    against overlap_3d's own self-overlap at several exponents -- is
+    sqrt((2*degree-1)!! / ((2lx-1)!!(2ly-1)!!(2lz-1)!!)).
+
+    Order matches cartesian_powers(degree) exactly, so callers can zip
+    or elementwise-multiply the two directly."""
+    powers = cartesian_powers(degree)
+    reference = _double_factorial_odd(degree)
+    return np.array(
+        [
+            np.sqrt(reference / (_double_factorial_odd(lx) * _double_factorial_odd(ly) * _double_factorial_odd(lz)))
+            for lx, ly, lz in powers
+        ]
+    )

dense_evolution/native_hf/coulomb.py

@@ -0,0 +1,196 @@
+"""Nuclear attraction and electron repulsion integrals.
+
+Both integral types reduce to the same building block: the n-th order
+Hermite Coulomb integral
+
+    V_n(P, C) = K * F_n(p |P-C|^2)
+
+where F_n is the Boys function, P the center of a Gaussian product and
+C either a nuclear position (one-electron case) or the center of a
+second electron pair's product Gaussian (two-electron case). Angular
+momentum on each of up to four centers is then built up from V_n by
+three kinds of linear recursion (Obara-Saika):
+
+  * vertical transfer  -- raises angular momentum on the "bra" center
+    while also shifting the Boys-function order n. This is the only
+    recursion that touches the Boys function directly.
+  * horizontal transfer -- shifts angular momentum from one center to
+    its partner on the same electron (exact via Gaussian product
+    translation, same recursion used for overlap integrals).
+  * electron transfer -- shifts angular momentum from electron 1's
+    pair to electron 2's pair (only needed for the two-electron
+    repulsion integral).
+
+Each recursion has a 2-term memory in its recursion index, so each maps
+onto jax.lax.scan.
+"""
+
+import functools
+
+import jax
+import jax.numpy as jnp
+
+from dense_evolution.native_hf.boys import boys
+from dense_evolution.native_hf.gaussians import GaussianShell3D, product_center, product_prefactor
+
+
+def _hermite_base(order: int, g1: GaussianShell3D, g2: GaussianShell3D, scale: jax.Array, C: jax.Array) -> jax.Array:
+    """V[n,0,0,0] for n = 0..order-1, i.e. the (0,0,0) angular-momentum
+    slice of the Hermite Coulomb integral at every Boys order we'll need."""
+    K = product_prefactor(g1, g2)
+    P = product_center(g1, g2)
+    dist_sq = jnp.sum(jnp.square(P - C))
+    orders = jnp.arange(order)
+    return K * boys(orders, scale * dist_sq)
+
+
+def _vertical_step(scale, p, PA, PC, carry, i):
+    v_prev, v_prev2 = carry
+    v_prev_shift = jnp.roll(v_prev, shift=-1, axis=0)
+    v_prev2_shift = jnp.roll(v_prev2, shift=-1, axis=0)
+
+    v_next = (
+        PA * v_prev
+        - (scale / p) * PC * v_prev_shift
+        + ((i - 1) / (2.0 * p)) * v_prev2
+        - (((i - 1) * scale) / (2.0 * p * p)) * v_prev2_shift
+    )
+    return (v_next, v_prev), v_next
+
+
+def _raise_bra_degree(V0: jax.Array, degree: int, scale: jax.Array, p: jax.Array, A: jax.Array, C: jax.Array, P: jax.Array) -> jax.Array:
+    """Appends a new trailing axis of size `degree` to V0 built via the
+    vertical transfer recursion (one Cartesian direction at a time --
+    call this three times, once per x/y/z, to build a full 3D shell)."""
+    step = functools.partial(_vertical_step, scale, p, P - A, P - C)
+    init = (V0, jnp.zeros_like(V0))
+    _, rest = jax.lax.scan(step, init, jnp.arange(1, degree), unroll=True)
+    return jnp.concatenate((V0[..., None], jnp.moveaxis(rest, 0, -1)), axis=-1)
+
+
+def _hermite_coulomb_tensor(g1: GaussianShell3D, g2: GaussianShell3D, scale: jax.Array, C: jax.Array) -> jax.Array:
+    """The (degree+1)^3 tensor V[ix,iy,iz] = V_0-order Hermite integral
+    with all angular momentum on the bra (g1) side, at Boys order 0."""
+    a, A = jnp.asarray(g1.exponent), jnp.asarray(g1.center)
+    b, B = jnp.asarray(g2.exponent), jnp.asarray(g2.center)
+    p = a + b
+    P = (a * A + b * B) / p
+
+    if g1.degree == 0:
+        return _hermite_base(1, g1, g2, scale, C)[0, None, None, None]
+
+    n = g1.degree + 1
+    V = _hermite_base(3 * n, g1, g2, scale, C)
+    for axis in range(3):
+        V = _raise_bra_degree(V, n, scale, p, A[axis], C[axis], P[axis])
+        if axis < 2:
+            V = V[:-n, ...]
+    return V[0, ...]
+
+
+def _horizontal_step(diff, column, _):
+    shifted = jnp.roll(column, shift=-1)
+    new_column = diff * column + shifted
+    return new_column, new_column
+
+
+def _shift_degree(tensor: jax.Array, axis: int, new_size: int, center_from: jax.Array, center_to: jax.Array) -> jax.Array:
+    """Adds a trailing axis of size new_size to `tensor`, transferring
+    angular momentum from `axis` to it via the (exact) product-Gaussian
+    translation recursion. Used both for same-electron transfers
+    (nuclear attraction, and g1->g2 / g3->g4 in repulsion) and can be
+    reused unmodified for the cross-electron transfer below because the
+    recursion only differs in its coefficients, supplied by the caller."""
+    if new_size <= 1:
+        return tensor[..., None]
+    moved = jnp.moveaxis(tensor, axis, -1)
+    step = functools.partial(_horizontal_step, center_from - center_to)
+    _, rest = jax.lax.scan(step, moved, jnp.arange(1, new_size), unroll=True)
+    combined = jnp.concatenate((moved[..., None], jnp.moveaxis(rest, 0, -1)), axis=-1)
+    return jnp.moveaxis(combined, -2, axis)
+
+
+@jax.jit
+def nuclear_attraction(g1: GaussianShell3D, g2: GaussianShell3D, nucleus: jax.Array) -> jax.Array:
+    """<g1| 1/|r - nucleus| |g2>, shape (L1+1,)*3 + (L2+1,)*3."""
+    a, A = jnp.asarray(g1.exponent), jnp.asarray(g1.center)
+    b, B = jnp.asarray(g2.exponent), jnp.asarray(g2.center)
+    p = a + b
+
+    padded_g1 = GaussianShell3D(degree=g1.degree + g2.degree, exponent=a, center=A)
+    I = (2.0 * jnp.pi / p) * _hermite_coulomb_tensor(padded_g1, g2, p, nucleus)
+
+    for axis in range(3):
+        I = _shift_degree(I, axis, g2.degree + 1, A[axis], B[axis])
+        I = I[(slice(0, g1.degree + 1),) * (axis + 1) + (Ellipsis,)]
+    return I
+
+
+def _electron_transfer_step(p, q, alpha, carry, j):
+    I_prev, I_prev2 = carry
+    I_prev_up = jnp.roll(I_prev, shift=-1, axis=-1)
+    I_prev_down = jnp.pad(I_prev[..., :-1], ((0, 0),) * (I_prev.ndim - 1) + ((1, 0),))
+    idx = jnp.arange(I_prev.shape[-1]).reshape((1,) * (I_prev.ndim - 1) + (-1,))
+
+    I_next = (
+        alpha * I_prev
+        + (idx / (2.0 * q)) * I_prev_down
+        + ((j - 1) / (2.0 * q)) * I_prev2
+        - (p / q) * I_prev_up
+    )
+    return (I_next, I_prev), I_next
+
+
+def _transfer_to_second_electron(tensor: jax.Array, axis: int, new_size: int, exponents, centers) -> jax.Array:
+    if new_size <= 1:
+        return tensor[..., None]
+    a, b, c, d = exponents
+    A, B, C, D = centers
+    p, q = a + b, c + d
+    alpha = -(1.0 / q) * (b * (A - B) + d * (C - D))
+
+    moved = jnp.moveaxis(tensor, axis, -1)
+    step = functools.partial(_electron_transfer_step, p, q, alpha)
+    init = (moved, jnp.zeros_like(moved))
+    _, rest = jax.lax.scan(step, init, jnp.arange(1, new_size), unroll=True)
+    combined = jnp.concatenate((moved[..., None], jnp.moveaxis(rest, 0, -1)), axis=-1)
+    return jnp.moveaxis(combined, -2, axis)
+
+
+@jax.jit
+def electron_repulsion(g1: GaussianShell3D, g2: GaussianShell3D, g3: GaussianShell3D, g4: GaussianShell3D) -> jax.Array:
+    """<g1 g2| 1/r12 |g3 g4>, shape (L1+1,)^3 + (L2+1,)^3 + (L3+1,)^3 + (L4+1,)^3."""
+    a, A = jnp.asarray(g1.exponent), jnp.asarray(g1.center)
+    b, B = jnp.asarray(g2.exponent), jnp.asarray(g2.center)
+    c, C = jnp.asarray(g3.exponent), jnp.asarray(g3.center)
+    d, D = jnp.asarray(g4.exponent), jnp.asarray(g4.center)
+
+    padded_g3 = GaussianShell3D(degree=g3.degree + g4.degree, exponent=c, center=C)
+    padded_g1 = GaussianShell3D(degree=g1.degree + g2.degree + padded_g3.degree, exponent=a, center=A)
+
+    p, q = a + b, c + d
+    scale = (p * q) / (p + q)
+    Q = (c * C + d * D) / q
+    K34 = jnp.exp(-((c * d) / q) * jnp.sum(jnp.square(C - D)))
+    prefactor = 2.0 * jnp.pi ** 2.5 / (p * q * jnp.sqrt(p + q)) * K34
+
+    I = prefactor * _hermite_coulomb_tensor(padded_g1, g2, scale, Q)
+
+    exponents = jnp.array([a, b, c, d])
+    for axis in range(3):
+        I = _transfer_to_second_electron(
+            I, axis, padded_g3.degree + 1, exponents,
+            jnp.array([A[axis], B[axis], C[axis], D[axis]]),
+        )
+        I = I[(slice(0, g1.degree + g2.degree + 1),) * (axis + 1) + (Ellipsis,)]
+
+    for axis in range(3):
+        I = _shift_degree(I, axis, g2.degree + 1, A[axis], B[axis])
+        I = I[(slice(0, g1.degree + 1),) * (axis + 1) + (Ellipsis,)]
+
+    for axis in range(3):
+        I = _shift_degree(I, axis + 3, g4.degree + 1, C[axis], D[axis])
+        I = I[(slice(0, g1.degree + 1),) * 3 + (slice(0, g3.degree + 1),) * (axis + 1) + (Ellipsis,)]
+
+    # axes are currently (g1, g3, g2, g4); reorder to (g1, g2, g3, g4)
+    return jnp.moveaxis(I, [3, 4, 5], [6, 7, 8])

dense_evolution/native_hf/differentiable.py

@@ -0,0 +1,53 @@
+"""A differentiable-w.r.t.-nuclear-positions RHF total energy, composed
+from basis.py + assembly.py + scf.py.
+
+Two separate, deliberate pieces make this possible, neither of which is
+a property of any one of those modules alone:
+
+1. Schwarz screening (assembly.py's quartet_screening_indices) is a
+   discrete, structural decision -- which shell quartets exist in the
+   ERI sum at all -- and can't be part of a jax.grad trace (Python
+   control flow can't run on a traced value). It's decided ONCE here,
+   from the reference geometry passed to build_energy_fn, and reused as
+   a fixed structure for every geometry the returned function is later
+   called at.
+
+2. scf.py's iterative convergence search (jax.lax.while_loop) can't be
+   differentiated in reverse mode either -- scf_electronic_energy
+   sidesteps that with the analytic Hartree-Fock gradient (Pople,
+   Krishnan, Schlegel & Binkley, 1979) instead of backpropagating
+   through the loop.
+
+The returned function is only valid near the reference geometry: if the
+nuclei move far enough that a previously-negligible shell-pair
+interaction becomes non-negligible (or vice versa), the frozen
+screening structure is stale and build_energy_fn should be called again
+at the new geometry.
+"""
+
+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, quartet_screening_indices,
+)
+from dense_evolution.native_hf.scf import scf_electronic_energy, nuclear_repulsion_energy
+
+
+def build_energy_fn(
+    atomic_numbers: list[int], nuclear_charges: list[float], n_electrons: int,
+    basis_name: str, reference_geometry_bohr: np.ndarray, screening_tol: float = 1e-12,
+):
+    reference_shells = build_molecule_shells(atomic_numbers, np.asarray(reference_geometry_bohr), basis_name)
+    quartet_indices = quartet_screening_indices(reference_shells, screening_tol)
+
+    def energy_fn(geometry_bohr):
+        shells = build_molecule_shells(atomic_numbers, geometry_bohr, basis_name)
+        S = build_overlap_matrix(shells)
+        H_core = build_core_hamiltonian(shells, nuclear_charges, geometry_bohr)
+        repulsion = build_repulsion_tensor(shells, quartet_indices=quartet_indices)
+        electronic_energy = scf_electronic_energy(S, H_core, repulsion, n_electrons)
+        e_nuc = nuclear_repulsion_energy(nuclear_charges, geometry_bohr)
+        return electronic_energy + e_nuc
+
+    return energy_fn

dense_evolution/native_hf/gaussians.py

@@ -0,0 +1,79 @@
+"""Primitive Gaussian shells and the Gaussian product theorem.
+
+A primitive Gaussian of angular momentum degree L centered at R with
+exponent a is, in 3D:
+
+    G(r) = (x-Rx)^lx (y-Ry)^ly (z-Rz)^lz * exp(-a |r-R|^2)
+
+We only ever need the *maximum* degree L for a shell (s: L=0, p: L=1,
+...) because the recursions below build every (lx,ly,lz) with
+lx+ly+lz <= L in one shot, so a shell is fully described by (L, a, R).
+"""
+
+import dataclasses
+
+import jax
+import jax.numpy as jnp
+from jax.tree_util import register_pytree_node_class
+
+
+@register_pytree_node_class
+@dataclasses.dataclass
+class GaussianShell1D:
+    """A single Cartesian component (x, y, or z) of a Gaussian shell."""
+
+    degree: int
+    exponent: jax.Array  # shape ()
+    center: jax.Array  # shape ()
+
+    def tree_flatten(self):
+        return (self.exponent, self.center), self.degree
+
+    @classmethod
+    def tree_unflatten(cls, degree, children):
+        exponent, center = children
+        return cls(degree=degree, exponent=exponent, center=center)
+
+
+@register_pytree_node_class
+@dataclasses.dataclass
+class GaussianShell3D:
+    """A 3D Gaussian shell: one exponent/center, all (lx,ly,lz) with
+    lx+ly+lz <= degree implicitly represented."""
+
+    degree: int
+    exponent: jax.Array  # shape ()
+    center: jax.Array  # shape (3,)
+
+    def tree_flatten(self):
+        return (self.exponent, self.center), self.degree
+
+    @classmethod
+    def tree_unflatten(cls, degree, children):
+        exponent, center = children
+        return cls(degree=degree, exponent=exponent, center=center)
+
+    def component(self, axis: int) -> GaussianShell1D:
+        return GaussianShell1D(
+            degree=self.degree,
+            exponent=self.exponent,
+            center=jnp.asarray(self.center)[axis],
+        )
+
+
+def product_center(g1: GaussianShell3D, g2: GaussianShell3D) -> jax.Array:
+    """The center P of the Gaussian obtained by multiplying two Gaussians
+    (Gaussian product theorem): P = (a*A + b*B) / (a+b)."""
+    a, b = jnp.asarray(g1.exponent), jnp.asarray(g2.exponent)
+    A, B = jnp.asarray(g1.center), jnp.asarray(g2.center)
+    return (a * A + b * B) / (a + b)
+
+
+def product_prefactor(g1: GaussianShell3D, g2: GaussianShell3D) -> jax.Array:
+    """The scalar prefactor K = exp(-mu |A-B|^2), mu = a*b/(a+b), that the
+    product of two Gaussians picks up (everything else about the product
+    is folded into the recursions below)."""
+    a, b = jnp.asarray(g1.exponent), jnp.asarray(g2.exponent)
+    diff = jnp.asarray(g1.center) - jnp.asarray(g2.center)
+    mu = (a * b) / (a + b)
+    return jnp.exp(-mu * jnp.dot(diff, diff))

dense_evolution/native_hf/kinetic.py

@@ -0,0 +1,52 @@
+"""Kinetic energy integrals, obtained from overlap integrals for free.
+
+The second derivative of a Gaussian (x-B)^j exp(-b(x-B)^2) with respect
+to its own center reduces to a combination of Gaussians of degree j-2,
+j and j+2, which gives kinetic integrals as a fixed linear combination
+of overlap integrals evaluated at a boosted degree:
+
+    T[i,j] = j(j-1) S[i,j-2] - 2b(2j+1) S[i,j] + 4b^2 S[i,j+2]
+
+T here is <i| d^2/dx^2 |j>; the physical kinetic energy operator is
+-1/2 (d^2/dx^2 + d^2/dy^2 + d^2/dz^2), so callers must negate and halve
+the sum of the three Cartesian terms.
+"""
+
+import jax
+import jax.numpy as jnp
+
+from dense_evolution.native_hf.gaussians import GaussianShell3D
+from dense_evolution.native_hf.overlap import overlap_1d
+
+
+def _kinetic_1d_from_overlap(S: jax.Array, b: jax.Array) -> jax.Array:
+    """S has shape (n_i, n_j) with n_j >= 3 (degree-boosted). Returns the
+    kinetic matrix of shape (n_i, n_j - 2)."""
+    n_j_out = S.shape[1] - 2
+    j = jnp.arange(n_j_out)[None, :]
+
+    term_down = jnp.pad(j[:, 2:] * (j[:, 2:] - 1) * S[:, :-4], ((0, 0), (2, 0))) if n_j_out > 2 else jnp.zeros((S.shape[0], n_j_out))
+    term_same = -2.0 * b * (2.0 * j + 1.0) * S[:, :-2]
+    term_up = 4.0 * b * b * S[:, 2:]
+
+    return term_down + term_same + term_up
+
+
+@jax.jit
+def kinetic_3d(g1: GaussianShell3D, g2: GaussianShell3D) -> jax.Array:
+    """<g1| d^2/dx^2 + d^2/dy^2 + d^2/dz^2 |g2>, shape matching overlap_3d.
+
+    Multiply by -0.5 to get the physical kinetic-energy matrix elements.
+    """
+    b = jnp.asarray(g2.exponent)
+    g2_boosted = GaussianShell3D(degree=g2.degree + 2, exponent=g2.exponent, center=g2.center)
+
+    S = [overlap_1d(g1.component(d), g2_boosted.component(d)) for d in range(3)]
+    T = [_kinetic_1d_from_overlap(S[d], b) for d in range(3)]
+    S_trim = [s[:, :-2] for s in S]
+
+    term_x = jnp.einsum("ad,be,cf->abcdef", T[0], S_trim[1], S_trim[2])
+    term_y = jnp.einsum("ad,be,cf->abcdef", S_trim[0], T[1], S_trim[2])
+    term_z = jnp.einsum("ad,be,cf->abcdef", S_trim[0], S_trim[1], T[2])
+
+    return term_x + term_y + term_z

dense_evolution/native_hf/libcint_bridge.py

@@ -0,0 +1,167 @@
+"""libcint bridge for native_hf's one- and two-electron integrals.
+
+native_hf's own build_repulsion_tensor (assembly.py) computes the ERI
+tensor via JAX-jitted Obara-Saika recursions -- correct, differentiable,
+but pays a JIT-compilation tax on mixed-angular-momentum bases (~532s on
+Ne/6-31G* even after the primitive-count-padding fix), and its one-electron
+assembly ran out of memory during XLA compilation for a 4-heavy-atom
+molecule at 6-31G* on a Kaggle CPU kernel. libcint (Sun, J. Comput. Chem.
+36, 1664 (2015), BSD-2) computes the identical integrals with C kernels
+compiled once, ahead of time.
+
+libcint is linked statically, together with csrc/cint_driver.c, into one
+shared library shipped inside the platform wheels of dense-evolution
+(dense_evolution/native_hf/_libcint/, built by
+.github/scripts/build-libcint.sh in .github/workflows/libcint.yml) and
+called through ctypes, with the atm/bas/env arrays built here from
+native_hf's own ContractedShell list. The driver loops over shell blocks
+in C (8-fold ERI symmetry, int2e_optimizer) and writes every integral
+already rescaled and in native_hf's AO order. A source install has no
+bundled library: run build-libcint.sh and point DENSE_EVOLUTION_LIBCINT at
+the resulting file.
+
+Shells are passed to libcint in native_hf's own order, so AO blocks line
+up shell by shell. Two convention differences remain inside each shell,
+confirmed empirically on Ne/6-31G*:
+  - Cartesian component order: libcint orders px,py,pz and
+    xx,xy,xz,yy,yz,zz; native_hf's cartesian_powers orders px,pz,py and
+    xx,xz,xy,zz,yz,yy.
+  - Normalization: libcint's raw Cartesian d components are not unit
+    self-overlap (xx/yy/zz vs. xy/xz/yz differ by exactly a factor of 3).
+    native_hf's primitive-normalized coefficients differ from libcint's
+    radial convention by a per-shell constant too. Both are removed by a
+    per-AO rescale computed from libcint's own overlap diagonal at call
+    time, exact for whatever exponent/element/degree is in play.
+Degrees above 2 raise NotImplementedError (native_hf itself caps at 2).
+"""
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from dense_evolution.native_hf.basis import build_molecule_shells
+from dense_evolution.native_hf.cartesian import cartesian_powers
+
+_LIBCINT_CARTESIAN_ORDER = {
+    0: [(0, 0, 0)],
+    1: [(1, 0, 0), (0, 1, 0), (0, 0, 1)],
+    2: [(2, 0, 0), (1, 1, 0), (1, 0, 1), (0, 2, 0), (0, 1, 1), (0, 0, 2)],
+}
+_LIB_NAMES = {"win32": "libdecint.dll", "darwin": "libdecint.dylib"}
+_PTR_ENV_START = 20
+_POINT_NUC = 1
+_KINDS = {"ovlp": 0, "kin": 1, "nuc": 2}
+_lib = None
+
+
+def load_libcint() -> ctypes.CDLL:
+    """The bundled libcint + driver shared library (or DENSE_EVOLUTION_LIBCINT's),
+    loaded once; ImportError if neither exists."""
+    global _lib
+    if _lib is not None:
+        return _lib
+    path = os.environ.get("DENSE_EVOLUTION_LIBCINT") or str(
+        Path(__file__).with_name("_libcint") / _LIB_NAMES.get(sys.platform, "libdecint.so")
+    )
+    if not os.path.isfile(path):
+        raise ImportError(
+            f"native_hf.libcint_bridge needs the bundled libcint library, expected at {path}. "
+            "It ships inside the dense-evolution wheels for Windows, macOS and Linux "
+            "(pip install dense-evolution); for a source install, run "
+            ".github/scripts/build-libcint.sh and set DENSE_EVOLUTION_LIBCINT to the library file."
+        )
+    lib = ctypes.CDLL(path)
+    tail = [ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p, ctypes.c_int, ctypes.c_void_p]
+    lib.de_int1e.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_int] + [ctypes.c_void_p] * 3 + tail
+    lib.de_int1e.restype = None
+    lib.de_int2e.argtypes = [ctypes.c_void_p, ctypes.c_int] + [ctypes.c_void_p] * 3 + tail
+    lib.de_int2e.restype = None
+    _lib = lib
+    return lib
+
+
+def _permutation_libcint_to_native_hf(degree: int) -> np.ndarray:
+    """perm such that native_hf_ordered[i] == libcint_ordered[perm[i]]."""
+    if degree not in _LIBCINT_CARTESIAN_ORDER:
+        raise NotImplementedError(
+            f"libcint_bridge only has a verified AO-order mapping for degree <= 2; "
+            f"degree={degree} would need the same empirical check first, not an "
+            f"assumed extension of the pattern."
+        )
+    native_order = [tuple(int(x) for x in p) for p in cartesian_powers(degree)]
+    libcint_order = _LIBCINT_CARTESIAN_ORDER[degree]
+    return np.array([libcint_order.index(p) for p in native_order])
+
+
+class _Cint:
+    """atm/bas/env arrays for one molecule plus per-shell AO offsets, the
+    native_hf AO permutation, evaluated by the C driver."""
+
+    def __init__(self, atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str):
+        self.lib = load_libcint()
+        shells = build_molecule_shells(atomic_numbers, geometry_bohr, basis_name)
+        env = [0.0] * _PTR_ENV_START
+        atm, bas = [], []
+        for z, r in zip(atomic_numbers, np.asarray(geometry_bohr, dtype=float)):
+            atm.append([int(z), len(env), _POINT_NUC, len(env) + 3, 0, 0])
+            env.extend([r[0], r[1], r[2], 0.0])
+        for s in shells:
+            e = np.asarray(s.exponents, dtype=float)
+            c = np.asarray(s.coefficients, dtype=float)
+            bas.append([s.atom_index, s.degree, e.shape[0], 1, 0, len(env), len(env) + e.shape[0], 0])
+            env.extend(e)
+            env.extend(c)
+        self.atm = np.ascontiguousarray(atm, dtype=np.int32)
+        self.bas = np.ascontiguousarray(bas, dtype=np.int32)
+        self.env = np.ascontiguousarray(env, dtype=np.float64)
+        self.sizes = [len(cartesian_powers(s.degree)) for s in shells]
+        self.offsets = np.concatenate([[0], np.cumsum(self.sizes)]).astype(int)
+        self.n = int(self.offsets[-1])
+        self.perm = np.concatenate(
+            [o + _permutation_libcint_to_native_hf(s.degree) for o, s in zip(self.offsets, shells)]
+        )
+        self.ao_loc = np.ascontiguousarray(self.offsets, dtype=np.int32)
+        self.pos = np.ascontiguousarray(np.argsort(self.perm), dtype=np.int32)
+
+    def _tail(self):
+        return (self.atm.ctypes.data, self.atm.shape[0], self.bas.ctypes.data, self.bas.shape[0], self.env.ctypes.data)
+
+    def one(self, kind: str, r: np.ndarray, pos: np.ndarray) -> np.ndarray:
+        out = np.empty((self.n, self.n))
+        r = np.ascontiguousarray(r, dtype=np.float64)
+        self.lib.de_int1e(_KINDS[kind], out.ctypes.data, self.n, self.ao_loc.ctypes.data, r.ctypes.data, pos.ctypes.data, *self._tail())
+        return out
+
+    def rescale(self) -> np.ndarray:
+        S = self.one("ovlp", np.ones(self.n), np.arange(self.n, dtype=np.int32))
+        return 1.0 / np.sqrt(np.diag(S))
+
+    def two(self, r: np.ndarray) -> np.ndarray:
+        out = np.empty((self.n,) * 4)
+        self.lib.de_int2e(out.ctypes.data, self.n, self.ao_loc.ctypes.data, r.ctypes.data, self.pos.ctypes.data, *self._tail())
+        return out
+
+
+def build_overlap_and_core_hamiltonian_libcint(
+    atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str
+) -> tuple[np.ndarray, np.ndarray]:
+    """Same contract as assembly.build_overlap_matrix + build_core_hamiltonian
+    combined, computed via libcint. Returns (S, H_core) in native_hf's own AO
+    ordering/normalization, ready for scf.run_scf alongside
+    build_repulsion_tensor_libcint's output."""
+    c = _Cint(atomic_numbers, geometry_bohr, basis_name)
+    r = c.rescale()
+    return c.one("ovlp", r, c.pos), c.one("kin", r, c.pos) + c.one("nuc", r, c.pos)
+
+
+def build_repulsion_tensor_libcint(atomic_numbers: list, geometry_bohr: np.ndarray, basis_name: str) -> np.ndarray:
+    """Same contract as assembly.build_repulsion_tensor, computed via libcint
+    with 8-fold permutational symmetry; takes (atomic_numbers, geometry_bohr,
+    basis_name) rather than a shells list.
+
+    geometry_bohr: shape (n_atoms, 3), atomic units, same convention as
+    build_molecule_shells."""
+    c = _Cint(atomic_numbers, geometry_bohr, basis_name)
+    return c.two(c.rescale())