fastesp 0.1.0__py3-none-any.whl

fastesp/__init__.py

@@ -0,0 +1,42 @@
+"""fastesp -- exact electrostatic potential from a Gaussian-basis wavefunction.
+
+The electron part of the ESP at a point C is
+
+    V_el(C) = -sum_{mu nu} P_{mu nu} < mu | 1/|r - C| | nu >
+
+evaluated *analytically*: the Gaussian product is expanded in Hermite Gaussians
+(McMurchie-Davidson) and the potential of each Hermite Gaussian is a closed-form
+derivative of the Boys function.  No real-space quadrature is involved, so the
+result is exact to machine precision.
+
+Quick start::
+
+    from fastesp import read_molden, Basis, build_table
+
+    wfn = read_molden("mol.molden.input")
+    basis = Basis(wfn)
+    density = basis.density_matrix_cartesian()
+    table = build_table(wfn, basis, density, points_bohr)
+    esp = table.esp()                      # (n_points,) in Hartree/e
+
+See :mod:`fastesp.cli` (console script ``fastesp``) for the compiled C++/CUDA
+backends, which are orders of magnitude faster on large point sets.
+"""
+from __future__ import annotations
+
+from .basis import Basis, cart_order, overlap_matrix
+from .esp import ESPEngine
+from .ints import boys, primitive_pair_integral
+from .molden import Wavefunction, read_molden
+from .table import (PairTable, basis_payload, build_table, write_basis_payload)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Wavefunction", "read_molden",
+    "Basis", "cart_order", "overlap_matrix",
+    "boys", "primitive_pair_integral",
+    "PairTable", "build_table",
+    "basis_payload", "write_basis_payload",
+    "__version__",
+]

fastesp/basis.py

@@ -0,0 +1,303 @@
+"""Cartesian Gaussian basis construction from a MOLDEN wavefunction.
+
+The MOLDEN file stores *spherical* (pure) d/f/g functions when the [5D]/[7F]
+flags are present.  All integrals in this package are written for plain
+Cartesian Gaussians, so every l-shell is re-expressed in its Cartesian span:
+
+    spurious subspace  =  { r^2 * m : m a monomial of degree l-2 }
+
+The pure (l-degenerate) part is the S-orthogonal complement of that subspace,
+and the transformation ``T`` satisfies ``T S T^T = 1``.  Everything below is
+convention independent -- if the MOLDEN functions span the same function space
+(they do: real solid harmonics) the density is reproduced exactly regardless of
+the phase/order convention used by the writer.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+
+from .molden import Shell, Wavefunction
+
+
+# --------------------------------------------------------------------------
+# Cartesian component bookkeeping
+# --------------------------------------------------------------------------
+@lru_cache(maxsize=None)
+def cart_order(l: int) -> tuple[tuple[int, int, int], ...]:
+    """Cartesian components of a shell with angular momentum ``l``.
+
+    Ordering is the standard 'x fastest' one used by most QC codes:
+    (l,0,0), (l-1,1,0), (l-1,0,1), ...
+    """
+    out = []
+    for lx in range(l, -1, -1):
+        for ly in range(l - lx, -1, -1):
+            lz = l - lx - ly
+            out.append((lx, ly, lz))
+    return tuple(out)
+
+
+@lru_cache(maxsize=None)
+def _dfact2(n: int) -> float:
+    """(n)!! for odd n, with (-1)!! = 1."""
+    if n <= 0:
+        return 1.0
+    r = 1.0
+    for k in range(n, 0, -2):
+        r *= k
+    return r
+
+
+def primitive_norm(alpha: float, lx: int, ly: int, lz: int) -> float:
+    """Primitive prefactor used by the MOLDEN/ORCA convention.
+
+    ORCA writes GTO coefficients that already include
+
+        N_s(alpha, l) = (2 alpha/pi)^{3/4} (4 alpha)^{l/2}
+
+    i.e. the radial normalisation *without* the angular (2l-1)!! factor that the
+    fully normalised Cartesian Gaussian carries.  Verified against this very file:
+    the printed coefficient of every single-primitive p/d/f shell equals
+    N_s(alpha, l) to 8 digits.
+    """
+    l = lx + ly + lz
+    return (2.0 * alpha / np.pi) ** 0.75 * (4.0 * alpha) ** (0.5 * l)
+
+
+# --------------------------------------------------------------------------
+# 1D overlap helper (used for same-centre blocks only)
+# --------------------------------------------------------------------------
+def _os1d(a: int, b: int, pa: float, pb: float, p: float) -> float:
+    """int (x-A)^a (x-B)^b exp(-p (x-P)^2) dx  (the sqrt(pi/p) factor excluded)."""
+    s = 0.0
+    for i in range(a + 1):
+        for j in range(b + 1):
+            if (i + j) % 2:
+                continue
+            s += (
+                _binom(a, i) * _binom(b, j)
+                * pa ** (a - i) * pb ** (b - j)
+                * (1.0 / (2.0 * p)) ** ((i + j) / 2.0)
+                * _dfact2(i + j - 1)
+            )
+    return s
+
+
+@lru_cache(maxsize=None)
+def _binom(n: int, k: int) -> float:
+    from math import comb
+    return float(comb(n, k))
+
+
+@lru_cache(maxsize=None)
+def cartesian_overlap_block(l: int) -> np.ndarray:
+    """Overlap of same-exponent MOLDEN-normalised Cartesian Gaussians of degree l.
+
+    With g_i = N_s(alpha,l) m_i exp(-alpha r^2) the block is independent of alpha
+    because N_s^2 * (2 alpha)^{-(l+3/2)} is alpha free; alpha = 1 is used here.
+    """
+    comps = cart_order(l)
+    n = len(comps)
+    p = 2.0
+    pref = primitive_norm(1.0, l, 0, 0) ** 2 * (np.pi / p) ** 1.5
+    s = np.empty((n, n))
+    for i, (ax, ay, az) in enumerate(comps):
+        for j, (bx, by, bz) in enumerate(comps):
+            s[i, j] = pref * (_os1d(ax, bx, 0.0, 0.0, p)
+                              * _os1d(ay, by, 0.0, 0.0, p)
+                              * _os1d(az, bz, 0.0, 0.0, p))
+    return s
+
+
+# Real solid harmonics in MOLDEN ordering m = 0, +1, -1, +2, -2, ...
+# Entries are the coefficients of the degree-l monomials (any common scale per
+# row is irrelevant: the rows are S-normalised below).  The relative signs were
+# read back from this very file: inverting  S_true = (C C^T)^-1  against the
+# Cartesian overlap returns exactly these polynomials.
+_POLY = {
+    2: [{(2, 0, 0): -1, (0, 2, 0): -1, (0, 0, 2): 2},          # 3z^2 - r^2
+        {(1, 0, 1): 1},                                         # xz
+        {(0, 1, 1): 1},                                         # yz
+        {(2, 0, 0): 1, (0, 2, 0): -1},                          # x^2 - y^2
+        {(1, 1, 0): 1}],                                        # xy
+    3: [{(2, 0, 1): -3, (0, 2, 1): -3, (0, 0, 3): 2},           # z(5z^2-3r^2)
+        {(3, 0, 0): -1, (1, 2, 0): -1, (1, 0, 2): 4},           # x(5z^2-r^2)
+        {(2, 1, 0): -1, (0, 3, 0): -1, (0, 1, 2): 4},           # y(5z^2-r^2)
+        {(2, 0, 1): 1, (0, 2, 1): -1},                          # z(x^2-y^2)
+        {(1, 1, 1): 1},                                         # xyz
+        {(3, 0, 0): -1, (1, 2, 0): 3},                          # x(x^2-3y^2)
+        {(2, 1, 0): -3, (0, 3, 0): 1}],                         # y(3x^2-y^2)
+    4: [{(0, 0, 4): 8, (2, 0, 2): -24, (0, 2, 2): -24,
+         (4, 0, 0): 3, (2, 2, 0): 6, (0, 4, 0): 3},             # 35z^4-30z^2r^2+3r^4
+        {(1, 0, 3): 4, (3, 0, 1): -3, (1, 2, 1): -3},           # xz(7z^2-3r^2)
+        {(0, 1, 3): 4, (0, 3, 1): -3, (2, 1, 1): -3},           # yz(7z^2-3r^2)
+        {(2, 0, 2): 6, (0, 2, 2): -6, (4, 0, 0): -1, (0, 4, 0): 1},   # (x^2-y^2)(7z^2-r^2)
+        {(1, 1, 2): 6, (3, 1, 0): -1, (1, 3, 0): -1},           # xy(7z^2-r^2)
+        {(3, 0, 1): 1, (1, 2, 1): -3},                          # xz(x^2-3y^2)
+        {(2, 1, 1): 3, (0, 3, 1): -1},                          # yz(3x^2-y^2)
+        {(4, 0, 0): 1, (2, 2, 0): -6, (0, 4, 0): 1},            # x^4-6x^2y^2+y^4
+        {(3, 1, 0): 1, (1, 3, 0): -1}],                         # xy(x^2-y^2)
+}
+
+
+@lru_cache(maxsize=None)
+def pure_to_cartesian(l: int) -> np.ndarray:
+    """T (2l+1, ncart): rows are the MOLDEN real solid harmonics, S-orthonormal.
+
+    For l <= 1 the Cartesian span is already pure and T is the identity.
+    """
+    comps = cart_order(l)
+    n = len(comps)
+    if l <= 1:
+        return np.eye(n)
+
+    s = cartesian_overlap_block(l)
+    cmap = {c: i for i, c in enumerate(comps)}
+    v = np.zeros((2 * l + 1, n))
+    for r, poly in enumerate(_POLY[l]):
+        for c, val in poly.items():
+            v[r, cmap[c]] = val
+    nrm = np.sqrt(np.einsum("ri,ij,rj->r", v, s, v))
+    return v / nrm[:, None]
+
+
+def _pure_to_cartesian_generic(l: int) -> np.ndarray:
+    """Fallback (not used for l <= 4): S-orthonormal complement of the spurious
+    subspace { r^2 * (monomials of degree l-2) }, arbitrary ordering."""
+    comps = cart_order(l)
+    n = len(comps)
+    if l <= 1:
+        return np.eye(n)
+
+    s = cartesian_overlap_block(l)
+    chol = np.linalg.cholesky(s)
+
+    # spurious vectors: r^2 * (monomials of degree l-2)
+    mons = []
+    lm2 = l - 2
+    for lx in range(lm2, -1, -1):
+        for ly in range(lm2 - lx, -1, -1):
+            lz = lm2 - lx - ly
+            mons.append((lx, ly, lz))
+
+    # coefficient vector of r^2 * x^mx y^my z^mz in the *normalised* Cartesian
+    # basis g_i = N_i * monomial_i * exp(-alpha r^2):  c_i = (monomial coeff)/N_i
+    m = np.zeros((n, len(mons)))
+    for k, (mx, my, mz) in enumerate(mons):
+        for i, (ax, ay, az) in enumerate(comps):
+            for dx, dy, dz in ((2, 0, 0), (0, 2, 0), (0, 0, 2)):
+                if ax == mx + dx and ay == my + dy and az == mz + dz:
+                    m[i, k] += 1.0 / primitive_norm(1.0, ax, ay, az)
+    # NOTE: 1/N_s(1,l) is a common factor per *resulting* component, exactly the
+    # coefficient of r^2*m in the N_s-normalised Cartesian basis.
+    b = chol.T @ m                       # (n, nspur)
+    sv_all, vh = np.linalg.svd(b.T)[1:]  # vh rows = right singular vectors of b^T
+    rank = int((sv_all > 1e-9 * sv_all[0]).sum()) if sv_all.size else 0
+    nn = vh[rank:].T                     # (n, n - rank) orthonormal null space
+    # rows are c = L^{-T} y with y = L^T c; np.linalg.cholesky returns lower L
+    t = (np.linalg.solve(chol.T, nn)).T
+    return t
+
+
+# --------------------------------------------------------------------------
+# Full basis
+# --------------------------------------------------------------------------
+class Basis:
+    """Cartesian Gaussian basis: centres, exponents and contraction coefficients."""
+
+    def __init__(self, wfn: Wavefunction, use_primitive_norm: bool = True):
+        self.wfn = wfn
+        self.use_primitive_norm = use_primitive_norm
+        self.centers: list[np.ndarray] = []
+        self.atoms: list[int] = []
+        self.ang: list[tuple[int, int, int]] = []
+        self.exps: list[np.ndarray] = []
+        self.coefs: list[np.ndarray] = []
+        self.shell_of: list[int] = []
+        self.shells: list[Shell] = []
+
+        for sh in wfn.shells:
+            sh_center = wfn.coords[sh.atom]
+            for (lx, ly, lz) in cart_order(sh.l):
+                # MOLDEN coefficients already carry N_s(alpha,l); the Cartesian
+                # components of a shell therefore share the same radial prefactor.
+                cf = np.asarray(sh.coeffs, dtype=np.float64)
+                self.centers.append(sh_center)
+                self.atoms.append(sh.atom)
+                self.ang.append((lx, ly, lz))
+                self.exps.append(np.asarray(sh.exps))
+                self.coefs.append(cf)
+                self.shell_of.append(len(self.shells))
+            self.shells.append(sh)
+
+        self.n = len(self.centers)
+        self.centers = np.asarray(self.centers)
+        self.atoms = np.asarray(self.atoms, dtype=np.int32)
+        self.ang_arr = np.asarray(self.ang, dtype=np.int32)
+
+    # -- transformation from the stored (spherical) representation ---------
+    def block_transform(self) -> np.ndarray:
+        """(ncart_cart, ncart_sph) matrix mapping stored coefficients to Cartesian.
+
+        Built shell-block by shell-block over the *stored* ordering, where each
+        shell of angular momentum l occupies 2l+1 consecutive functions.
+        """
+        wfn = self.wfn
+        off_sph = 0
+        off_cart = 0
+        blocks = []
+        for sh in wfn.shells:
+            npure = 2 * sh.l + 1
+            ncart = len(cart_order(sh.l))
+            blocks.append((off_sph, off_cart, npure, ncart, sh.l))
+            off_sph += npure
+            off_cart += ncart
+        assert off_cart == self.n, (off_cart, self.n)
+
+        t = np.zeros((off_cart, off_sph))
+        for off_s, off_c, npure, ncart, l in blocks:
+            t[off_c:off_c + ncart, off_s:off_s + npure] = pure_to_cartesian(l).T
+        return t
+
+    def density_matrix_cartesian(self, min_occ: float = 1e-10) -> np.ndarray:
+        wfn = self.wfn
+        occ = wfn.mo_occ > min_occ
+        c = wfn.mo_coeff[:, occ] * np.sqrt(wfn.mo_occ[occ])[None, :]
+        p_sph = c @ c.T
+        t = self.block_transform()
+        return t @ p_sph @ t.T
+
+
+def overlap_matrix(b: Basis) -> np.ndarray:
+    """Full Cartesian overlap matrix (used only for validation)."""
+    n = b.n
+    s = np.zeros((n, n))
+    for i in range(n):
+        ai, bi, ci = b.centers[i]
+        li = b.ang[i]
+        for j in range(i, n):
+            aj, bj, cj = b.centers[j]
+            lj = b.ang[j]
+            d = np.array([ai - aj, bi - bj, ci - cj])
+            ab2 = d @ d
+            tot = 0.0
+            for ea, ca in zip(b.exps[i], b.coefs[i]):
+                for eb, cb in zip(b.exps[j], b.coefs[j]):
+                    p = ea + eb
+                    mu = ea * eb / p
+                    pa = -eb * d / p          # P - A
+                    pb = ea * d / p           # P - B
+                    sx = _os1d(li[0], lj[0], pa[0], pb[0], p)
+                    sy = _os1d(li[1], lj[1], pa[1], pb[1], p)
+                    sz = _os1d(li[2], lj[2], pa[2], pb[2], p)
+                    tot += ca * cb * np.exp(-mu * ab2) * (np.pi / p) ** 1.5 * sx * sy * sz
+            s[i, j] = s[j, i] = tot
+    return s
+
+
+def build_basis(path, use_primitive_norm: bool = True) -> tuple[Wavefunction, Basis]:
+    from .molden import read_molden
+    wfn = read_molden(path)
+    return wfn, Basis(wfn, use_primitive_norm=use_primitive_norm)

fastesp/cli.py

@@ -0,0 +1,326 @@
+"""Command line interface for fastesp.
+
+    fastesp esp WF.molden --points pts_bohr.txt -o esp.txt
+    fastesp build-native            # compile the C++/CUDA backends on demand
+    fastesp selftest                # validate the analytic integrals
+
+``fastesp esp`` picks the fastest backend it can: the CUDA solver if a GPU and
+``nvcc`` are available, else the OpenMP C++ table builder with the NumPy
+evaluator, else the pure NumPy reference.  ``build-native`` compiles both
+backends into a per-user cache directory.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+
+from . import __version__
+from .basis import Basis
+from .molden import read_molden
+from .table import PairTable, basis_payload, build_table, write_basis_payload
+
+NATIVE_DIR = Path(__file__).resolve().parent / "native"
+
+
+# ---------------------------------------------------------------------------
+def cache_dir() -> Path:
+    d = Path(os.environ.get("FASTESP_CACHE",
+                            Path.home() / ".cache" / "fastesp"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _which(name: str) -> str | None:
+    return shutil.which(name)
+
+
+def _nvcc() -> str | None:
+    cand = [os.environ.get("NVCC"), "nvcc", "/usr/local/cuda/bin/nvcc"]
+    for c in cand:
+        if not c:
+            continue
+        p = c if os.sep in c else shutil.which(c)
+        if p and Path(p).exists():
+            return p
+    return None
+
+
+def _src_hash() -> str:
+    h = hashlib.sha256()
+    for f in ("build_pairs.cpp", "esp_gpu.cu"):
+        h.update((NATIVE_DIR / f).read_bytes())
+    return h.hexdigest()[:12]
+
+
+def _default_arch() -> str:
+    return os.environ.get("FASTESP_CUDA_ARCH", "sm_120")
+
+
+def native_paths() -> tuple[Path | None, Path | None]:
+    """(build_pairs, esp_gpu) if already compiled, else (None, None)."""
+    if os.environ.get("FASTESP_NATIVE_DIR"):
+        d = Path(os.environ["FASTESP_NATIVE_DIR"])
+        b, g = d / "build_pairs", d / "esp_gpu"
+        return (b if b.exists() else None), (g if g.exists() else None)
+    d = cache_dir() / f"{_src_hash()}-{_default_arch()}"
+    b, g = d / "build_pairs", d / "esp_gpu"
+    return (b if b.exists() else None), (g if g.exists() else None)
+
+
+def build_native(force: bool = False, arch: str | None = None,
+                 quiet: bool = False) -> tuple[Path | None, Path | None]:
+    arch = arch or _default_arch()
+    out = cache_dir() / f"{_src_hash()}-{arch}"
+    out.mkdir(parents=True, exist_ok=True)
+    cpu, gpu = out / "build_pairs", out / "esp_gpu"
+
+    cxx = _which(os.environ.get("CXX", "g++"))
+    if cxx is None:
+        print("fastesp: no C++ compiler found (set CXX)", file=sys.stderr)
+    elif force or not cpu.exists():
+        for extra in (["-march=native"], []):
+            cmd = [cxx, "-O3", "-fopenmp", *extra, "-o", str(cpu),
+                   str(NATIVE_DIR / "build_pairs.cpp")]
+            if not quiet:
+                print("  " + " ".join(cmd))
+            r = subprocess.run(cmd, capture_output=True, text=True)
+            if r.returncode == 0:
+                break
+            if extra:
+                continue
+            print(r.stderr[-2000:], file=sys.stderr)
+            cpu = None
+    nv = _nvcc()
+    if nv is None:
+        if not quiet:
+            print("fastesp: nvcc not found; GPU backend unavailable", file=sys.stderr)
+    elif force or not gpu.exists():
+        cmd = [nv, "-O3", f"-arch={arch}", "-o", str(gpu), str(NATIVE_DIR / "esp_gpu.cu")]
+        if not quiet:
+            print("  " + " ".join(cmd))
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        if r.returncode != 0:
+            print(r.stderr[-3000:], file=sys.stderr)
+            gpu = None
+    return (cpu if cpu.exists() else None), (gpu if gpu.exists() else None)
+
+
+# ---------------------------------------------------------------------------
+def run_esp(molden: Path, points_file: Path, out_file: Path | None,
+            backend: str = "auto", tol: float = 1e-12, geom: str = "bohr",
+            verbose: bool = True) -> np.ndarray:
+    t0 = time.perf_counter()
+    wfn = read_molden(molden)
+    basis = Basis(wfn)
+    density = basis.density_matrix_cartesian()
+    t_load = time.perf_counter() - t0
+
+    pts = _read_points(points_file, geom)
+    cpu, gpu = native_paths()
+    if backend == "auto":
+        backend = "cuda" if (gpu and _has_gpu()) else ("cpp" if cpu else "numpy")
+    if backend == "cuda" and not gpu:
+        raise SystemExit("fastesp: GPU backend not built; run `fastesp build-native`")
+
+    t_solve_kernel = None
+    t0 = time.perf_counter()
+    if backend == "numpy":
+        table = build_table(wfn, basis, density, pts, tol=tol)
+        t_build = time.perf_counter() - t0
+        t0 = time.perf_counter()
+        esp = table.esp()
+        t_solve = time.perf_counter() - t0
+    else:
+        with tempfile.TemporaryDirectory(prefix="fastesp-") as td:
+            td = Path(td)
+            basis_bin, pairs_bin = td / "basis.bin", td / "pairs.bin"
+            write_basis_payload(basis_bin, basis_payload(wfn, basis, density, pts))
+            r = subprocess.run([str(cpu), str(basis_bin), str(pairs_bin), str(tol)],
+                               capture_output=True, text=True)
+            if r.returncode != 0:
+                raise SystemExit(f"build_pairs failed:\n{r.stderr[-2000:]}")
+            t_build = time.perf_counter() - t0
+            t0 = time.perf_counter()
+            if backend == "cuda":
+                with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as fh:
+                    tmp_out = fh.name
+                reps = int(os.environ.get("FASTESP_REPEATS", "5"))
+                r = subprocess.run([str(gpu), str(pairs_bin), tmp_out,
+                                    "--repeats", str(reps)],
+                                   capture_output=True, text=True)
+                if r.returncode != 0:
+                    raise SystemExit(f"esp_gpu failed:\n{r.stderr[-2000:]}")
+                esp = np.loadtxt(tmp_out, skiprows=1)[:, 3]
+                os.unlink(tmp_out)
+                # the kernel time excludes process start-up (CUDA context setup),
+                # which would otherwise dominate for small point sets
+                t_solve_kernel = min(
+                    float(l.split()[-2]) for l in r.stdout.splitlines()
+                    if l.startswith("run ")) / 1e3
+            else:
+                esp = PairTable.read(pairs_bin).esp()
+                t_solve_kernel = None
+            t_solve = time.perf_counter() - t0
+
+    if verbose:
+        print(f"  backend      : {backend}")
+        print(f"  basis        : {basis.n} Cartesian functions, "
+              f"{len(np.concatenate(basis.exps))} primitives")
+        print(f"  load         : {t_load:8.3f} s")
+        print(f"  pair table   : {t_build:8.4f} s  (point-independent)")
+        if t_solve_kernel is not None:
+            print(f"  ESP kernel   : {t_solve_kernel:8.4f} s")
+            print(f"  ESP incl. process start-up: {t_solve:.4f} s "
+                  f"(CUDA context set-up; amortised when many point sets are run)")
+            tot = t_build + t_solve_kernel
+        else:
+            print(f"  ESP solve    : {t_solve:8.4f} s")
+            tot = t_build + t_solve
+        print(f"  total (excl. load): {tot:.4f} s for {len(pts)} points "
+              f"({1e3 * tot / len(pts):.4f} ms/point)")
+        print(f"  ESP range    : {esp.min() * 27.211386245988:+.4f} .. "
+              f"{esp.max() * 27.211386245988:+.4f} V")
+
+    if out_file:
+        with Path(out_file).open("w") as f:
+            f.write(f"{len(pts)}\n")
+            for (x, y, z), v in zip(pts, esp):
+                f.write(f" {x:20.12f} {y:20.12f} {z:20.12f} {v:22.14e}\n")
+        if verbose:
+            print(f"  wrote        : {out_file}")
+    return esp
+
+
+def _has_gpu() -> bool:
+    try:
+        r = subprocess.run(["nvidia-smi", "-L"], capture_output=True, text=True)
+        return r.returncode == 0 and "GPU" in r.stdout
+    except Exception:
+        return False
+
+
+def _read_points(path: Path, geom: str) -> np.ndarray:
+    txt = Path(path).read_text().splitlines()
+    rows = []
+    for line in txt:
+        f = line.split()
+        if len(f) >= 3:
+            try:
+                rows.append([float(x) for x in f[:3]])
+            except ValueError:
+                continue
+    pts = np.asarray(rows, float)
+    if pts.shape[1] != 3:
+        raise SystemExit(f"fastesp: cannot parse points from {path}")
+    if geom == "angstrom":
+        pts = pts / 0.529177210903
+    return pts
+
+
+# ---------------------------------------------------------------------------
+def selftest(verbose: bool = True) -> int:
+    """Validate the analytic integrals against independent references."""
+    import math
+    from .ints import primitive_pair_integral
+    from numpy.polynomial.legendre import leggauss
+
+    rng = np.random.default_rng(0)
+    worst_ss = 0.0
+    for _ in range(8):
+        A = rng.normal(0, 1, 3); B = A + rng.normal(0, 1, 3); C = rng.normal(0, 3, 3)
+        al = float(np.exp(rng.uniform(-2, 2.5))); be = float(np.exp(rng.uniform(-2, 2.5)))
+        p = al + be; P = (al * A + be * B) / p
+        K = math.exp(-al * be / p * float(((A - B) ** 2).sum()))
+        R = float(np.linalg.norm(C - P))
+        ref = K * (np.pi / p) ** 1.5 * math.erf(np.sqrt(p) * R) / R
+        got = primitive_pair_integral(al, A, (0, 0, 0), be, B, (0, 0, 0), C)
+        worst_ss = max(worst_ss, abs(got - ref) / abs(ref))
+
+    def quad(C, A, la, al, B, lb, be, R=14.0, ngl=240, ncos=220, nphi=440):
+        xs, ws = leggauss(ngl)
+        s = 0.5 * R * (xs + 1.0); wr = 0.5 * R * ws
+        cz, wz = leggauss(ncos)
+        phi = (np.arange(nphi) + 0.5) * (2 * np.pi / nphi); wphi = 2 * np.pi / nphi
+        st = np.sqrt(np.clip(1 - cz ** 2, 0, None))
+        nx = st[None, :, None] * np.cos(phi)[:, None, None] * np.ones((1, 1, 1))
+        ny = st[None, :, None] * np.sin(phi)[:, None, None] * np.ones((1, 1, 1))
+        nz = np.broadcast_to(cz[None, :, None], (nphi, ncos, 1)).copy()
+        ss = s[None, None, :]
+        X, Y, Z = C[0] + ss * nx, C[1] + ss * ny, C[2] + ss * nz
+        rho = ((X - A[0]) ** la[0] * (Y - A[1]) ** la[1] * (Z - A[2]) ** la[2]
+               * np.exp(-al * ((X - A[0]) ** 2 + (Y - A[1]) ** 2 + (Z - A[2]) ** 2))
+               * (X - B[0]) ** lb[0] * (Y - B[1]) ** lb[1] * (Z - B[2]) ** lb[2]
+               * np.exp(-be * ((X - B[0]) ** 2 + (Y - B[1]) ** 2 + (Z - B[2]) ** 2)))
+        return float((rho * ss * wr[None, None, :]
+                      * (wz[None, :, None] * wphi)).sum())
+
+    A = np.array([0.3, -0.4, 0.2]); B = A + np.array([1.1, 0.5, -0.6])
+    C = np.array([0.1, 1.6, 1.1]); al, be = 0.45, 0.72
+    worst = 0.0
+    for la, lb in [((1, 0, 0), (0, 0, 0)), ((2, 0, 0), (0, 1, 0)),
+                   ((1, 1, 0), (0, 0, 1)), ((3, 2, 0), (2, 1, 0)),
+                   ((3, 3, 3), (3, 3, 3))]:
+        ana = primitive_pair_integral(al, A, la, be, B, lb, C)
+        ref = quad(C, A, la, al, B, lb, be)
+        worst = max(worst, abs(ana - ref) / max(abs(ref), 1e-300))
+        if verbose:
+            print(f"  <{la}|1/r|{lb}>  analytic {ana:+.10e}  quadrature {ref:+.10e}"
+                  f"  rel {abs(ana - ref) / max(abs(ref), 1e-300):.1e}")
+    ok = worst_ss < 1e-13 and worst < 1e-11
+    print(f"  s-s vs closed form   worst rel {worst_ss:.1e}")
+    print(f"  general vs quadrature worst rel {worst:.1e}")
+    print("  SELFTEST", "PASS" if ok else "FAIL")
+    return 0 if ok else 1
+
+
+# ---------------------------------------------------------------------------
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser("fastesp", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"fastesp {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("esp", help="electrostatic potential at a set of points")
+    e.add_argument("wavefunction", type=Path, help="MOLDEN file")
+    e.add_argument("--points", type=Path, required=True,
+                   help="text file, one 'x y z' per line (Bohr unless --angstrom)")
+    e.add_argument("-o", "--out", type=Path, default=None)
+    e.add_argument("--backend", choices=["auto", "cuda", "cpp", "numpy"], default="auto")
+    e.add_argument("--tol", type=float, default=1e-12,
+                   help="primitive pair screening threshold in Hartree/e")
+    e.add_argument("--angstrom", action="store_true", help="input points in Angstrom")
+    e.add_argument("-q", "--quiet", action="store_true")
+
+    b = sub.add_parser("build-native", help="compile the C++/CUDA backends")
+    b.add_argument("--arch", default=None, help="CUDA arch, e.g. sm_120")
+    b.add_argument("--force", action="store_true")
+
+    s = sub.add_parser("selftest", help="validate the analytic integrals")
+    s.add_argument("-q", "--quiet", action="store_true")
+
+    a = ap.parse_args(argv)
+    if a.cmd == "esp":
+        run_esp(a.wavefunction, a.points, a.out, backend=a.backend, tol=a.tol,
+                geom="angstrom" if a.angstrom else "bohr", verbose=not a.quiet)
+        return 0
+    if a.cmd == "build-native":
+        cpu, gpu = build_native(force=a.force, arch=a.arch)
+        print(f"  build_pairs: {cpu}")
+        print(f"  esp_gpu    : {gpu}")
+        return 0 if cpu or gpu else 1
+    if a.cmd == "selftest":
+        return selftest(verbose=not a.quiet)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())