integral 0.2.0

Native-Rust Gaussian integrals for quantum mechanics (driver + public API).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# integral

Native-Rust Gaussian integrals for quantum chemistry.

`integral` computes the integrals quantum-chemistry methods are built on — overlap,
kinetic energy, nuclear attraction, multipole/dipole, and two-electron repulsion
integrals (ERIs) — over contracted Cartesian and real-spherical Gaussian shells,
in pure, safe, stable Rust with no dependency on external quantum-chemistry
libraries.

[![Crates.io](https://img.shields.io/crates/v/integral.svg)](https://crates.io/crates/integral)
[![Documentation](https://docs.rs/integral/badge.svg)](https://docs.rs/integral)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/nmrtist/integral/blob/main/LICENSE-APACHE)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nmrtist/integral/blob/main/LICENSE-MIT)

## Highlights

integral ships *two* complementary two-electron integral engines behind a measured
dispatch policy:

- an **Obara–Saika / Head-Gordon–Pople (OS/HGP)** engine with specialized,
  per–angular-momentum recurrences — fastest at low angular momentum and high
  contraction; and
- a **Rys-quadrature** engine that stays accurate and compact across *all*
  angular momenta with a very small memory footprint.

A `(angular-momentum, contraction)` policy picks the faster engine per shell
quartet; the two agree to tolerance, so the choice is purely about speed.
One-electron integrals are built from an operator DSL over the position `r` and
momentum `p` operators, and all compile-time specialization and table generation
is done in pure Rust.

The integral algorithms follow standard Gaussian-integral literature and keep
output conventions interoperable with common downstream tooling.

## Quick start

```toml
# Cargo.toml
[dependencies]
integral = "0.2.0"
```

```rust
use integral::{Basis, Shell};

let exps = vec![3.425250914, 0.623913730, 0.168855404];
let coef = vec![0.154328967, 0.535328142, 0.444634542];
let basis = Basis::new(vec![
    Shell::new(0, [0.0, 0.0, 0.0], exps.clone(), coef.clone()).unwrap(),
    Shell::new(0, [0.0, 0.0, 1.4], exps, coef).unwrap(),
]);

let n = basis.nao();
let s = basis.overlap();
let t = basis.kinetic();
let v = basis.nuclear(&[([0.0, 0.0, 0.0], 1.0), ([0.0, 0.0, 1.4], 1.0)]);

let eri = basis.eri();

println!("S01 = {:.6}", s[1]);
println!("T00 = {:.6}", t[0]);
println!("V00 = {:.6}", v[0]);
println!("(00|11) = {:.6}", eri[(0 * n + 0) * n * n + (1 * n + 1)]);
```

Spherical-harmonic output (`2l+1` real components) is opt-in per
shell via `Shell::new_spherical`; Schwarz-screened ERIs via
`basis.eri_screened(tau)`; geometric gradients via `basis.overlap_grad()`,
`basis.eri_grad()`, etc.; and arbitrary one-electron operators via
`basis.int1e(&Operator)`.

## Feature matrix

| Capability | Status | Limit |
|---|---|---|
| Overlap `S`, kinetic `T`, nuclear attraction `V` | ✅ | up to `l = 6` (i shells) |
| Dipole / multipole | ✅ | up to `l = 6` |
| Two-electron ERIs (Coulomb) — OS/HGP **and** Rys engines | ✅ | each shell up to `l = 6` (`l_total` ≤ 24) |
| Measured engine dispatch (`(l_total, contraction)`) | ✅ | — |
| Cartesian output | ✅ (default) | up to `l = 6` |
| Real-spherical (`c2s`) output | ✅ | up to `l = 6` |
| Schwarz (Cauchy–Schwarz) ERI screening | ✅ | error ≤ `τ` (caller-set) |
| Geometric first derivatives (gradients) of `S/T/V/ERI` | ✅ | shells up to `l = 5` (raised to 6) |
| One-electron operator DSL over `r` and `p` | ✅ | dipole, quadrupole, momentum, angular momentum, kinetic, custom |
| C ABI (`integral-sys`) | Minimal | ABI version surface only |
| Parallel dense-ERI seam (`EriBuilder`, call-site threads) | ✅ | safe, no in-crate runtime |

**Threading.** The library is **single-threaded but thread-safe**: integral
builders take `&self` and share no mutable state, so the recommended way to
parallelize is **at the call site**. For the dense ERI tensor, `EriBuilder`
provides a ready-made **parallel seam**: its grain is the canonical bra shell-pair
`(i, j)` (`bra_pairs()`), and `partition()` hands each bra-pair a *disjoint* set of
output rows, so a driver can fill them concurrently into one buffer with no
synchronisation —

```rust
let builder = basis.eri_builder();
let mut out = vec![0.0; builder.output_len()];
let mut tasks = builder.partition(&mut out);
tasks.par_iter_mut().for_each(|t| builder.fill(t)); // rayon lives in the caller
```

The disjointness is owned inside integral (safe `chunks_exact_mut` partitioning, no
`unsafe`); integral itself pulls in **no** threading runtime.

## Validation

integral's correctness is established **from physical and mathematical principles**,
not by requiring users to install reference software:

- **Closed-form analytic checks** — s-Gaussian overlap/kinetic/nuclear/dipole,
  normalization, the Boys function vs `erf`/incomplete-gamma and its recurrence.
- **Exact symmetry & invariance laws** — Hermiticity of one-electron matrices,
  operator-character (anti)symmetry, ERI 8-fold permutational symmetry,
  translational invariance of gradients, gauge/origin operator identities.
- **Three independent in-repo algorithms agreeing** — the OS/HGP and Rys ERI
  engines are cross-checked against each other *and* against an independent
  **McMurchie–Davidson** implementation, to the tight `1e-11` tolerance, across
  the full angular-momentum range.
- **Finite-difference derivative consistency** and numeric invariants (Rys roots
  ∈ (0,1), weights > 0, …).
Every check above runs in plain `cargo test` on Windows, macOS, and Linux with
**no external library**.

## Workspace layout

| Crate | Layer | Role |
|---|---|---|
| [`integral-math`](https://github.com/nmrtist/integral/tree/main/crates/integral-math) | L0 | Boys function, Rys roots/weights, normalization, `c2s` coefficients |
| [`integral-core`](https://github.com/nmrtist/integral/tree/main/crates/integral-core) | L1/L2 | OS one-electron engine, OS/HGP + Rys ERI engines, operator DSL, derivatives |
| [`integral`](https://github.com/nmrtist/integral/tree/main/crates/integral) | L3 | basis/molecule description, drivers, screening, transforms — the public API |
| [`integral-sys`](https://github.com/nmrtist/integral/tree/main/crates/integral-sys) | L3 | `extern "C"` ABI surface |
| [`integral-codegen`](https://github.com/nmrtist/integral/tree/main/crates/integral-codegen) | build | pure-Rust build-time code generation support |

## Safety & MSRV

- `#![forbid(unsafe_code)]` in every crate except `integral-sys` (the FFI surface),
  which uses `#![deny(unsafe_code)]` so each `unsafe` must be an explicit,
  reviewed opt-in with a `// SAFETY:` note.
- Stable Rust only. The crates target a low MSRV (**1.82**) for broad downstream
  compatibility, and are developed on recent stable Rust.

## License

Licensed under Apache-2.0 or MIT.