Crate integral 

integral — native-Rust Gaussian integrals for quantum mechanics.

This is the public, Layer-3 crate: basis/molecule description and the one-electron integral drivers (see ARCHITECTURE.md, L3). It exposes overlap, kinetic, nuclear-attraction, and dipole integrals over contracted Cartesian (and real-spherical) Gaussian shells, two ERI engines, geometric first derivatives, and a one-electron operator DSL (Operator / Basis::int1e) over polynomials in the position r and momentum p = −i∇ operators — adding a new 1e integral type is a single Operator declaration, not an engine change.

Quick start

use integral::{Basis, Shell};

// A single normalized s function (one primitive) at the origin.
let s = Shell::new(0, [0.0, 0.0, 0.0], vec![0.8], vec![1.0]).unwrap();
let basis = Basis::new(vec![s]);
let ovlp = basis.overlap();
assert_eq!(ovlp.len(), 1);
assert!((ovlp[0] - 1.0).abs() < 1e-12); // self-overlap of a normalized s = 1

Conventions

• Storage. Dense f64, row-major. Square one-electron matrices are nao × nao with nao = Basis::nao_cart; dipole returns three such matrices [x, y, z].
• Cartesian or spherical. Shells default to Cartesian, with components in integral_math::am ordering (e.g. d: xx, xy, xz, yy, yz, zz). Shell::new_spherical requests the 2l+1 real spherical-harmonic components instead (see ShellKind); a basis may mix the two.
• Normalization. Each primitive is scaled by the shell-level constant N(α, l) (see Shell::primitive_coeff) and the user-supplied contraction coefficients. The Cartesian convention normalizes each monomial so that the stretched component x^l has unit self-overlap (cart_norm); off-axis components such as d_xy therefore have a smaller self-overlap. (This differs from the solid-harmonic Cartesian normalization by a single scalar per shell — 1 for s/p; the relative pattern of components is the same in both.)
• Units. Atomic units (bohr) throughout.

The C ABI lives in the separate integral-sys crate and is stubbed until a later release.

Structs

Basis

An ordered collection of shells defining the atomic-orbital basis.

BraPairFill

One unit of parallel work: the output rows owned by a single canonical bra-pair (i, j), handed out by EriBuilder::partition.

EriBuilder

A reusable plan for assembling the dense (ij|kl) ERI tensor in parallel over canonical bra shell-pairs, with no in-crate threading runtime.

Gradient1e

Per-atom geometric gradient of a one-electron matrix.

GradientEri

Per-atom geometric gradient of the electron-repulsion tensor.

Operator

A one-electron operator: a sum of Terms, polynomial in r and p, with a documented origin for its r factors (the multipole / gauge origin).

OperatorMatrix

The complex matrix of a one-electron operator, stored as separate real and imaginary parts. Both are dense row-major nao × nao (same ordering/strides as the value builders).

ScreeningStats

Outcome of a Schwarz-screened ERI build (Basis::eri_screened).

Shell

A contracted Cartesian Gaussian shell: several primitives sharing a center and angular momentum, combined with contraction coefficients.

Term

One product term of an operator: a real scalar coeff times an ordered product of Factors, applied right-to-left to the ket.

Enums

Engine

Which two-electron engine evaluates an ERI quartet.

Factor

An elementary factor of a one-electron operator product, along a Cartesian axis (0 = x, 1 = y, 2 = z).

IntegralError

Errors returned when constructing or using a Shell / Basis.

ShellKind

Whether a shell’s integrals are returned over Cartesian or real spherical-harmonic components.

Constants

MAX_GRAD_L

Maximum shell angular momentum for which a gradient can be built. The derivative raises the shell to l + 1, which must stay ≤ MAX_L.

Functions

select_engine

Dispatch policy: pick OS/HGP vs Rys from a quartet’s total angular momentum l_total = la+lb+lc+ld and its primitive-quartet contraction_degree (n_prim_a·n_prim_b·n_prim_c·n_prim_d).