Seeded molecules and the transformations the energy must ignore

A metamorphic check runs the code twice on inputs related by a known transformation and compares the answers: rotate a molecule and its energy stays put; stretch every length by 1/lambda and every exponent by lambda^2 and the overlap stays put while the kinetic energy grows by lambda^2. No reference value is needed, so the check can run on inputs nobody has computed before. This module makes those inputs and those transformations.

Seeds. Every generator takes an integer seed and draws from Park-Miller MINSTD (hfz_rng), the same generator as lib/hf/eri_store, so a failure reported as "seed 17" can be rerun as seed 17. The first few draws from a small seed are small (16807 x 1 / 2^31 is 8 × 10⁻⁶), so hfz_state discards three draws before handing the state out.

Random bases. hfz_random_blob(seed, natm, nsh) puts nsh shells on natm atoms: each shell has l from 0 to 3, 1 to 3 primitives with exponents log-uniform in [0.05, 50] and coefficients in [0.2, 1] (hfz_random_basis takes the largest l and primitive count); the atoms sit in a 4-bohr box, at least 1 bohr apart, with charges 1 to 9. The packs travel in the basis blob of lib/hf/integrals (hfz_atoms, hfz_shells, hfz_prims read them back out).

Random molecules. hfz_build makes a molecule out of the atoms of a reference system: each new atom copies the shells of one source atom, so a water STO-3G source gives O and H in STO-3G wherever they are placed. hfz_water_blob(seed, src_at, src_sh, src_pr) perturbs water's geometry (bond lengths 1.6 to 2.0 bohr, angle 95 to 115 degrees); hfz_mol_blob builds H2O, OH, H2O+, H3O+ or OH- by kind, with the same kind of spread.

Transformations.

• hfz_rotation(seed): a random rotation matrix, from a random unit quaternion; hfz_rotate(atoms, R) applies it to every position.
• hfz_translate(atoms, t).
• hfz_perm(seed, n): a random permutation (Fisher-Yates); hfz_permute_atoms and hfz_permute_shells reorder the atoms and put the shells in the new atom order, and hfz_ao_map gives, for each AO of the permuted basis, its index in the original one. The prims pack is not touched: each shell keeps its SH_P0.
• hfz_scale_atoms(atoms, lambda) divides every position by lambda and hfz_scale_prims(prims, lambda) multiplies every exponent by lambda^2. Under the pair, S is unchanged, T is multiplied by lambda^2, V by lambda and every ERI by lambda.

Failures quote their seed. hfz_check(seed, worst, tol) does nothing when worst < tol. Otherwise it prints hfz_seed_failed: [seed, worst, tol] and fails an assertion that reads assert_lt: <seed> >= 0, so the test's FAIL line names the seed.

Used with import hf.fuzz.