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. It exposes overlap, kinetic, nuclear-attraction, dipole, and spin-free scalar-relativistic pVp (Basis::pvp / Basis::pvp_charges) 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 crate::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.

Re-exports

pub use operator::Factor;

pub use operator::Operator;

pub use operator::Term;

Modules

engine

Layer 1 (integral engines) + Layer 2 (operator/derivative layer).

math

Layer 0 shared numerical primitives.

Structs

Basis

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

Bra3cFill

One unit of parallel 3-center work: the (μ, ν) output rows owned by a single canonical bra-pair (i, j), handed out by Eri3cBuilder::partition. Distinct tasks borrow disjoint regions of the same buffer, so a driver may fill them across threads with no synchronisation (Eri3cBuilder::fill).

BraPairFill

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

Ecp

Semilocal ECP on one atom: U(r) = U_L(r) + Σ_{l<L} Σ_m |lm⟩ (U_l(r) − U_L(r)) ⟨lm|.

EcpPrimitive

One radial primitive d · r^(n−2) · exp(−ζ r²) of an ECP expansion (n ∈ {0, 1, 2, ...}).

Eri3cBuilder

A reusable plan for assembling the dense 3-center tensor (ij|P) — row-major [nao, nao, naux], P fastest — in parallel over canonical bra shell-pairs of the main basis, with no in-crate threading runtime.

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.

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.

Enums

Engine

Which two-electron engine evaluates an ERI quartet.

EriKernel

The two-electron interaction operator an ERI family is evaluated over.

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_ECP_GRAD_L

Maximum AO angular momentum supported by Basis::ecp_grad_contract (l ≤ 5, s…h — heavy-element QZ basis sets carry h functions on the ECP atom; the derivative raises the differentiated shell to l + 1 = 6 = MAX_L, which stays inside the engines’ validated range). Validated by the finite-difference gradient tests through h.

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 bra/ket half-momenta ne = la+lb, nf = lc+ld (so l_total = ne+nf) and its primitive-quartet contraction_degree (n_prim_a·n_prim_b·n_prim_c·n_prim_d).