gfn2-rs-python 0.4.5__tar.gz → 0.6.1__tar.gz

gfn2_rs_python-0.6.1/CHANGELOG.md

@@ -0,0 +1,2064 @@
+# Changelog
+
+All notable changes to gfn2-rs. Versions before 0.5.0 had no changelog; the
+0.4.x entries below are reconstructed from release notes that were scattered
+through `docs/` and source comments.
+
+## [0.6.1] - released
+
+### Fixed (licensing) — the binaries now carry the notices they owe
+
+- **The published binaries shipped third-party data with no licence text and no
+  attribution notice.** `_native` (the PyPI wheel) and the CLI executables
+  compile in LGPL-3.0 data (the xtb GFN2 parameter file, the tblite spGFN2 spin
+  constants, the dftd4 reference tables) and Apache-2.0 data (multicharge's
+  EEQ-BC parameters, mctc-lib's element data), and statically link ~50 MIT /
+  Apache-2.0 Rust crates. The wheel's `dist-info/licenses/` held only this
+  project's own GPL `LICENSE`; `THIRD_PARTY_NOTICES.md` did not travel at all;
+  the embedded-data modules *paraphrased* the upstream headers instead of
+  retaining them; and no crate carried any notice anywhere. That is a gap
+  against Apache-2.0 § 4(a) (include the licence) and § 4(b) (retain the
+  attribution notices), LGPL-3.0 § 4 (include the licence), and MIT's
+  requirement to include the notice "in all copies or substantial portions" —
+  a linked binary being a substantial portion.
+
+  What now ships, in **every** channel (wheel `dist-info/licenses/`, crates.io
+  package, source archive) and **embedded in the binaries themselves**:
+
+  - `LICENSES/` — the verbatim texts of GPL-3.0, LGPL-3.0, Apache-2.0,
+    LLVM-exception, MIT, BSD-3-Clause, MPL-2.0, Zlib, Unicode-3.0 and
+    CC-BY-4.0.
+  - `NOTICE` — the upstream licence header of each embedded artefact,
+    **quoted verbatim**, with its pinned commit and method citation.
+  - `THIRD_PARTY_LICENSES_RUST.md` — 630 kB, generated by the new
+    `scripts/collect_rust_licenses.py` from `cargo metadata` and the crate
+    sources: every `LICENSE*` / `COPYING*` / `NOTICE*` / `AUTHORS*` file of all
+    83 resolved crates, verbatim, including `faer`'s `COPYING.EIGEN.MPL2`,
+    `COPYING.LAPACK.BSD` and `COPYING.SUITE_SPARSE.{AMD,COLAMD}.BSD` for its
+    Eigen-, LAPACK- and SuiteSparse-derived kernels. The file records the
+    SHA-256 of the `Cargo.lock` it was generated from.
+  - `pyproject.toml`'s PEP 639 `license-files` now lists all of the above.
+
+  New `--licenses` flag on `gfn2_rs`, `nn_train` and `nn_eval` (and
+  `gfn2_rs.third_party_licenses()` in Python) prints the lot, so an executable
+  or `.pyd` copied out of its package still carries its notices.
+
+  `tests/attribution.rs` (new) pins it: every source file has an SPDX header,
+  every `include_str!`-ed file is named in `NOTICE` and
+  `THIRD_PARTY_NOTICES.md`, every referenced SPDX id has its text in
+  `LICENSES/`, the embedded-data modules quote their upstream header, and the
+  generated crate document matches the current `Cargo.lock` hash — so a
+  dependency bump without regeneration fails the build.
+  `tests/test_wheel_licenses.py` (new) checks the installed wheel's
+  `dist-info/licenses/`.
+
+### Fixed
+
+- **`NnThirdDerivativeMode::Chain`'s rejection named blockers that had already
+  been removed.** The refusal message is the only account of the remaining work
+  a caller ever sees, and it was written when groups (5), (6) and (7) were
+  unbuilt. It kept reporting group (7) as waiting on "a third-order encoder
+  pass: `nn::tape` stops at forward-over-reverse" after `nn::tape` had grown
+  `forward_tangent2` / `backward_with_two_tangents`, and groups (5) and (6) as
+  waiting on raw `M` and `K` tensors that `correction_blocks_with_tangents`
+  supplies. The refusal itself was correct — the tensor is not assembled — but
+  it sent a reader toward finished work.
+
+  The table now carries a state per group (`BUILT, not summed` vs `MISSING`),
+  says group (2) is done for the repulsion family, and enumerates all six
+  chain groups. `chain_mode_refuses_and_names_what_is_missing` pins the
+  built/missing distinction and every group number, so the message cannot go
+  stale silently again. No numerical change: nothing about which groups are
+  summed has moved.
+
+- **The default k-point mesh was Gamma-centred only for even `n`, and an odd
+  grid silently broke the crystal's symmetry.** `mp_coord` produced
+  `i/n - 1/2`. That is the same SET as `i/n` for even `n`, but for odd `n` it
+  is not: `n = 3` gave `{-1/2, -1/6, 1/6}`, which is not a subset of `(1/3)Z`.
+
+  A mesh whose coordinates are not all multiples of `1/n` is not closed under
+  the point group of a lattice whose symmetry operations MIX the primitive
+  reciprocal axes — face-centred cubic is the everyday case — and the symmetry
+  it loses is visible in the answers rather than hidden in a convention.
+  Diamond's triply degenerate Gamma optical mode came out **split**: at
+  `--kgrid 3 3 3` the three modes were 1182.29 / 1315.43 / 1315.43 cm^-1 and at
+  `5 5 5` they were 1268.43 / 1277.81 / 1277.81, a 1 + 2 splitting with no
+  physical cause. The default is now `i/n` folded into `[-1/2, 1/2)`, and the
+  same two grids give **1366.19 x 3** and **1282.00 x 3**; the whole sequence
+  (1595.35, 1366.19, 1300.37, 1282.00, 1276.93 for `n = 2..6`) is now monotone
+  in `n` where it used to zig-zag between the parities.
+
+  Even meshes are unaffected: the set is identical, and
+  `even_meshes_are_the_same_set_as_before_the_fix` pins that. `kpoint_shifted`
+  is untouched and remains the textbook Monkhorst-Pack offset
+  `(2r - n - 1)/(2n)`; for odd `n` it now coincides with the default, so the
+  odd-mesh half-step workaround that `dfpt`'s supercell-fold tests used to need
+  is retired.
+
+  The property, not the formula, is what is pinned:
+  `kpoints::mesh_tests::the_default_mesh_is_closed_under_the_fcc_point_group`
+  rotates every mesh point by two generators of the cubic group and requires it
+  to land back on the mesh modulo a reciprocal lattice vector, and
+  `the_old_default_was_not_closed_for_odd_meshes` keeps the record of what that
+  is protecting against by asserting the old formula's closure held for even
+  `n` only.
+
+- **A wire's SCC was summing `1/r` with a spherical cutoff, and the result
+  jumped with the cutoff rather than converging.** Five dispatches sent a
+  one-axis cell to a truncated direct sum: `Gfn2PbcModel::isotropic_scc_energy`,
+  `gradients::scc_forces_virial`, and — the ones the SCC actually runs
+  through — the shell-resolved kernel, energy and potential in
+  `electronic/scc_common.rs` plus their analytic-gradient counterparts in
+  `native_gradient.rs`. All of them now take the same route a slab does.
+
+  Measured on a tilted HF chain (`a = 6.2` bohr), sweeping `--scc-cutoff`:
+  before, the energy moved by 9.0e-4 Eh and was **discontinuous** — 20/40/60/70
+  bohr converged smoothly while 30/50/80/100/130 jumped by up to 4e-3 Eh,
+  because a spherical cutoff keeps an asymmetric set of images of a sum whose
+  cancellation needs them in pairs. After, the same sweep is monotone with a
+  total spread of 1.4e-5 Eh, and what is left is the short-range
+  `gamma_KO - 1/r` residual, which along one axis converges absolutely.
+
+  The energy is also now **exactly** independent of the vacuum padding: 0.0 Eh
+  difference between 40 and 300 bohr of vacuum, where a 3D Ewald applied to a
+  wire drifts.
+
+- **`--gradients` alone printed no gradient.** It did not imply `--electronic`,
+  so the run fell through to the fixed-charge path and reported a
+  repulsion-only energy with no gradient and no warning — the flag simply did
+  nothing. Every other output flag (`--orbitals`, `--stability`, `--molden`,
+  `--hessian`) already implied it. `--gradients` and `--stress` now do too.
+  Nothing that worked before changes: a caller who passed `--gradients
+  --electronic` is unaffected, and one who passed `--gradients` alone was
+  getting no gradient.
+
+  Found by the new `tests/cli_matrix.rs`, which runs each documented mode
+  combination end to end and asserts the output keys it promises rather than
+  only its exit status — "exit 0" is satisfied by a run that produced nothing.
+  Thirty-three combinations across molecular, periodic and refused cases.
+
+- **The anisotropic-electrostatics slab correction double-counted the
+  charge-charge dipole layer, making every slab energy depend on the vacuum
+  thickness.** A 3D Ewald sum used on a 2D-periodic cell introduces a spurious
+  `2 pi M_n^2 / V` dipole-layer term, which a Yeh-Berkowitz correction removes.
+  The Coulomb path applies that correction with the CHARGE moment `M^q`, and the
+  AES path applied it with the FULL moment `M^q + M^mu` — but the AES Ewald sum
+  deliberately leaves charge-charge to the Coulomb path, so its own artefact is
+  only the cross and dipole-dipole parts. The extra `(M^q)^2` was a term no sum
+  had produced.
+
+  It is proportional to `1/V`, so on a slab it decays only as one over the
+  vacuum thickness. Measured on a water layer in a 12 x 12 bohr cell: the total
+  energy moved 1.4e-4 hartree when the vacuum was doubled from 60 to 120 bohr,
+  and halved with every further doubling instead of settling. After the fix the
+  same sweep from 60 to 480 bohr moves 3.0e-14 hartree. The Coulomb slab sum was
+  already exact (vacuum-independent to 3e-11 at fixed charges); AES was the
+  whole of the drift, confirmed by switching it off.
+
+  `aes::slab_normal_moments` now returns both moments and the correction uses
+  their difference, with the potentials, the gradient/stress and the CPHF
+  potential derivatives all following. Pinned by
+  `physics::slab_energy_is_independent_of_the_vacuum_thickness`, which asserts
+  flatness for the slab and prints how far the same layer treated as a crystal
+  is from flat (2.8e-4 hartree per doubling), so the reason for the separate 2D
+  path is on the record.
+
+  **Any slab or wire energy from an earlier version that included AES is
+  affected**, by an amount set by the vacuum thickness the input happened to
+  use.
+
+- **`lattice_gradient_from_strain_derivative` contracted the wrong index of the
+  inverse cell, and was wrong for every non-orthorhombic cell.** For
+  `cell' = (I + eps) cell` with the atoms at fixed fractional coordinates, the
+  chain rule through `eps = dA A^-1` gives
+  `dE/da_{i,c} = sum_beta S[c][beta] (A^-1)[i][beta]` — the strain derivative
+  contracts with the ROW of `A^-1` belonging to the lattice vector being
+  differentiated. The code used `(A^-1)[beta][i]`, the transpose. `A^-1` is
+  symmetric exactly when the cell is orthorhombic, and every periodic fixture
+  in the test suite is orthorhombic, so nothing caught it; measured on a
+  triclinic cell the error is 4 % on `dE/da_x` of the first lattice vector.
+  The function is public and documented but had no in-tree callers, so no
+  shipped number moves.
+
+  Pinned by `native_gradient::tests::lattice_gradient_conversion_matches_a_model_energy_finite_difference`,
+  which differences a model energy of the cell alone in BOTH parametrisations
+  (strain and lattice vector) so neither side restates the formula, plus two
+  end-to-end tests against the real GFN2 energy on triclinic and orthorhombic
+  cells.
+
+  **Recorded while writing those tests:** the total energy is only
+  *piecewise* smooth in the cell. Image counts are `ceil(cutoff / plane_height)`,
+  so a cell whose plane height divides a cutoff exactly sits on a step of that
+  ceiling. On a `9, 10, 11` bohr cell (`30 / 10` is exactly 3) every derivative
+  touching the `b` axis carried a fixed ~1.5e-7 Eh jump, and its
+  finite-difference error therefore grew as `1/h`: 4.2e-4 at `h = 2e-4`,
+  7.7e-4 at 1e-4, 1.5e-3 at 5e-5. This matters for cell relaxation, not just
+  for tests.
+
+### Added
+
+- **The NN-xTB Hessian and Molden export reached Python and ASE
+  (`gfn2_rs.NnCalculator`, `GFN2RSCalculator.get_hessian` / `export_molden`).**
+
+  The Rust library has had a fully analytic molecular NN Hessian and an
+  overlaid Molden export since the CLI's `--nn-weights` guard was narrowed —
+  `--nn-weights --freq` and `--nn-weights --molden` both work. The Python
+  binding never exposed either, so the ASE calculator refused all four of
+  `get_tda` / `get_td_gradient` / `get_hessian` / `export_molden` with a
+  message that also mis-stated the reason ("The Rust API implements the NN-xTB
+  Hessian and TD gradients"; it implements the Hessian and refuses the TD
+  gradients).
+
+  `NnCalculator` holds a trained model open across calls and exposes
+  `hessian()` — returning `NnHessianResult` with the matrix in both unit
+  systems, the fallback flags and a `source` string — and `export_molden()`,
+  closed shell only. `GFN2RSCalculator.get_hessian` and `export_molden` route
+  through it when `nn_weights` is set; the reference SCC is tightened for the
+  Hessian exactly as the CLI tightens it. Keywords with no NN counterpart
+  (`hessian_mode="fd"`, `relaxed=False`, the `include_*` toggles, `cphf_*`,
+  `hessian_fd_step`) are refused by name rather than silently ignored.
+
+  `get_tda` and `get_td_gradient` still refuse, and the message now says why
+  correctly: the library refuses an excited-state request on an NN-overlaid
+  density too, so it is not a binding gap that a wrapper could close.
+
+- **The PyPI wheel now carries a trained NN-xTB model, and names it
+  (`gfn2_rs.bundled_model_path()`, `gfn2_rs.BUNDLED_MODEL_NAME`).**
+
+  The trained weights are the one runtime input that is not
+  `include_str!`-compiled — `--nn-weights` and `nn_weights=` open a path — so
+  through 0.6.0 a `pip install` could not run the NN-xTB surface at all: no
+  model shipped in the wheel, and the `models/...` spelling in the docs only
+  resolves from a checkout or an unpacked archive. `bundled_model_path()`
+  returns an absolute path inside the installed package, and raises
+  `FileNotFoundError` naming where else to get the file if an installation was
+  built without its package data.
+
+  Mechanically the model exists twice: `models/` for the archive and a
+  byte-identical copy at `python/gfn2_rs/models/` that `maturin` puts inside
+  the wheel. Shipping both copies in the crate would have taken it to 16.4 MiB
+  compressed, past the 10 MiB crates.io accepts without an exemption, so the
+  crate and the sdist carry the package copy and the zip carries `models/`.
+  `tests/attribution.rs` hashes the two and fails if a release refreshes one
+  and forgets the other; `tests/test_bundled_model.py` checks the built wheel,
+  the installed distribution, and that the model loads and moves the energy off
+  plain GFN2. `--nn-weights` gained a load-failure message that says where a
+  model comes from in each channel. Reasoning and sizes in
+  `docs/pip_reachability.md`; the superseded model stays out of the wheel.
+
+- **Analytic third energy derivatives on the NN-xTB PES, staged
+  (`src/nn/third_derivative.rs`, `src/nn/third_repulsion.rs`).** Molecular
+  only, matching `crate::third_derivatives`.
+
+  Because the network's parameters move with the geometry, `d^3E/dR^3` is not
+  the GFN2 tensor at shifted parameters: the chain rule splits it into seven
+  groups (see `docs/nn-xtb.md`). This release assembles group (1)
+  — the fixed-parameter tensor, reachable as
+  `NnThirdDerivativeMode::FrozenParameters` and through
+  `cubic_check --nn-weights` — plus groups (5), (6), (7), and group (2) for
+  the repulsion family. Groups (3) and (4) are FROZEN work, and no other
+  family implements group (2).
+
+  `NnThirdDerivativeMode::Chain`, the assembled tensor, is **REFUSED** with an
+  error naming every missing group. A partial sum is never returned.
+
+  Measured: the frozen-parameter mode captures ~91% of the true third
+  derivative on water with the shipped model (gap 9.2% against the central
+  difference of the exact analytic NN Hessian). Group (7) agrees with the FD
+  of the Hessian's curvature block at 2.3e-10; the repulsion family's group
+  (2) agrees with the FD of that family's Hessian block at 9.8e-9.
+
+  Underneath: `Tape::forward_tangent2` and `Tape::backward_with_two_tangents`
+  (third-order tape passes, 2.7e-11 against FD, and reproducing the existing
+  first- and second-order passes to 1e-12 so the Hessian path provably did not
+  move); `RadialBasis::values_and_three_derivatives`; a constant
+  third-derivative table for the real spherical harmonics;
+  `MaceEncoder::position_gradient_second_tangent` (9.0e-11 against FD of the
+  analytic HVP). `slot_space_to_cartesian_pair` makes the `K` contraction's
+  second factor a parameter while keeping the slot-space accumulation the
+  block is shaped around — pinned BIT-for-BIT against the previous square
+  form.
+
+- **`nn_train --bound clamp|tanh`: a smooth alternative to the paper's hard
+  clamp.** `B(x) = SHIFT_LIMIT tanh(SHIFT_SCALE x / SHIFT_LIMIT)` is analytic,
+  so its first, second and third derivatives are exact everywhere instead of
+  exact only where the clamp is inactive. It agrees with the clamp to third
+  order in a small argument (0.003% at a tenth of the bound, 0.3% at half) and
+  saturates to the same limit.
+
+  Why it matters: at an ACTIVE clamp the true `dB/dx` is `scale` on one side
+  and `0` on the other, so the PES has a kink — the Hessian carries a delta
+  and the third derivative does not exist. No backward convention repairs
+  that. Away from the bound the straight-through convention IS the exact
+  derivative, and `saturation_fraction` (a MAXIMUM over heads, not a fraction
+  of them) below 1.0 means no clamp is active anywhere.
+
+  The choice travels in the `.gfn2nn` header as `shift_bound`; its absence
+  means the clamp, so every previously written model reads back unchanged and
+  a clamp model's header is byte-identical to before. Weights do not transfer
+  between the two bounds once any head approaches the limit.
+
+- `--cphf-tol` / `--cphf-max-iter` on `gfn2_rs` and `hessian_check`, and in
+  the Python/ASE API. The relaxed Hessian is FIRST ORDER in the CPHF
+  solver's residual, so tightening these is how one tells an iterative
+  stopping point from a defect — which is how the k-point Hessian defects
+  below were separated from convergence noise.
+
+- `gfn2_rs --freq` and `--molden` now run on the NN-xTB path, and
+  `nn_eval --per-reaction FILE` writes one TSV row per scored reaction
+  (name, family, species count, reference, per-method errors, `ref_method`,
+  `provenance`) so any grouping can be made without a second evaluation.
+
+- `hessian_mode_used` is now printed by `gfn2_rs --freq` and `hessian_check`,
+  with a `hessian_mode_note` when what ran differs from what was asked for.
+  Until now no surface printed it: `--freq` emitted a hard-coded
+  `mode native-hessian` and a caller could not tell an analytic Hessian from a
+  differenced one.
+
+- MACE, ACE and DimeNet reference citations in `src/nn/mace.rs`,
+  `src/nn/radial.rs` and `src/nn/cg.rs`. The architecture is not this
+  project's; only the reimplementation is, and the source now says whose it
+  is.
+
+- **Exact Coulomb summation for a cell periodic along ONE axis
+  (`src/wire_sum.rs`).** A wire no longer falls back to a truncated direct sum.
+
+  There is no 1D Ewald here because there cannot usefully be one: split `1/r`
+  the Ewald way with a single periodic direction and the reciprocal term is an
+  *incomplete* Bessel function, whose series in the transverse distance
+  alternates with terms of size `(k rho/2)^{2p}/p!` and loses every digit
+  exactly where a wire needs them. So this does not split. It evaluates the
+  lattice sum in closed form, by two expansions that overlap:
+
+  * **near** (`r <= 0.7 L`): the Legendre expansion of each image, summed over
+    the image index, which turns into the Riemann zeta function 窶・    `psi = 1/r + 2 gamma/L + (2/L) sum_{k even} zeta(k+1) P_k(z/r) (r/L)^k`;
+  * **far**: Poisson summation along the wire 窶・    `psi = (2/L) ln(2L/rho) + (4/L) sum_m K_0(2 pi m rho/L) cos(2 pi m z/L)`.
+
+  Every individual term of a 1D Coulomb sum diverges logarithmically; what is
+  subtracted is one constant, the same for every pair, so it cancels exactly
+  for a neutral cell. A charged wire has no finite Coulomb energy at all, and
+  **is refused by name** 窶・not even with `--charged-pbc background`, because
+  the other two axes are vacuum and a background confined to the cell does not
+  remove the divergence.
+
+  Each piece is checked against something that did not build it: `K_0`/`K_1`
+  against the Wronskian `I_0 K_1 + I_1 K_0 = 1/x` (worst residual 1e-14 over
+  `x` in [0.1, 60]), zeta against its closed forms, the near expansion against
+  `psi(0, L/2) = (2/L)(gamma + 2 ln 2)` derived from the digamma function, the
+  two expansions against each other across their whole overlap, the whole
+  function against a brute-force sum over a million images, and the assembled
+  energy against the **exact 1D Madelung constant `2 ln 2`** (agreement to
+  1e-13 relative). Forces and the full 3x3 strain derivative match finite
+  differences in every component; the period derivative comes from Euler's
+  homogeneity relation rather than a third series.
+
+- **Cell relaxation: `--opt-cell fixed|volume|full`.** The L-BFGS optimizer now
+  steps in six strain parameters alongside the atomic coordinates, so a
+  periodic structure can relax its cell. `full` frees shape and volume,
+  `volume` frees the shape and holds the volume *exactly* (not to first order
+  in the strain: the deformation is rescaled by `det(I + eps)^(-1/3)`, measured
+  to preserve the volume to 1.5e-16 relative), `fixed` is the default and the
+  behaviour every earlier version had.
+
+  Only strains between periodic axes are free, so a slab relaxes in its plane
+  and never along the vacuum, and `--opt-cell volume` on a slab is refused by
+  name — a slab's cell volume is whatever vacuum thickness the input chose, so
+  holding it fixed constrains nothing physical.
+
+  The strain gradient is `V sigma F^-T`, which is the place a transposed
+  contraction changes nothing on a cubic cell and everything on a triclinic
+  one, so it is verified against a central finite difference of the energy the
+  same code produces, component by component over all `3N + 6` parameters, on a
+  triclinic cell at non-zero strain: 8.6e-7 for `full`, 4.0e-7 for `volume`.
+  `physics::cell_relaxation_finds_the_same_wire_lattice_constant_from_either_side`
+  relaxes a hydrogen wire from 4.2 and from 2.6 bohr and requires the same
+  answer (3.19370 against 3.19365, and the same energy to 8e-9 Eh).
+
+  Convergence needs BOTH the force and the free stress components below their
+  tolerances (`--opt-stress-tol`, default 1e-6 Eh/bohr^3); the per-iteration
+  line and the trace TSV carry `stress_max` and `volume_bohr3`.
+
+  The fixed-cell path is unchanged **bit for bit** —
+  `physics::fixed_cell_optimization_is_unchanged_by_the_cell_parameter_space`
+  compares the two trajectories by `f64::to_bits`.
+
+- **Orbital energies and the frontier: `--orbitals`, `--orbital-coefficients`.**
+  The SCC always produced orbital energies and occupations; nothing reported
+  them. `ElectronicResult::frontier_orbitals()` now locates the HOMO, the LUMO
+  and the gap per spin channel, and the CLI, the Python bindings
+  (`result.homo_lumo_gap_ev`, `result.orbital_energies_hartree`, ...) and the
+  ASE calculator (`get_orbital_energies()`, `get_homo_lumo()`) expose them.
+
+  Three things the definition has to get right, each pinned:
+  - occupations are fractional at any non-zero electronic temperature, so the
+    split is a threshold at half the channel capacity, and
+    `integral_occupations` says whether that was a formality or a judgement
+    call;
+  - a doublet's singly occupied orbital sits at exactly half capacity in the
+    spin-summed channel and is the HOMO, not the LUMO — with a tolerance,
+    because a finite-temperature fill lands it a few parts in 1e9 short;
+  - on a k-point run the gap is the FUNDAMENTAL one, taken across the whole
+    Brillouin zone, and `gap_is_indirect` says when the two ends sit at
+    different k-points.
+
+  Refused on the divide-and-conquer path, whose pooled subsystem eigenvalues
+  are not bands of one Hamiltonian.
+
+- **SCC convergence diagnosis: `scc_verdict`, `scc_class`, `--scc-trace`,
+  `--scc-preset`, `--kerker-beta`.** `ElectronicResult::scc_residual_history`
+  records the residual of every iteration on every driver, and
+  `ResidualMonitor` reads the ratios back as one of three verdicts —
+  *converging*, *sloshing* (over-correcting) or *stiff* (converging at a rate
+  that will not arrive). The last two matter because their remedies are
+  opposites: damping a stiff iteration makes it creep more slowly.
+
+  On a stiff verdict the CLI takes the remedy the ladder cannot express before
+  walking the ladder: `anneal_electronic_temperature` converges at four times
+  the requested electronic temperature and halves its way back down, ending at
+  exactly the requested value — measured against a direct solve, 3.6e-15 Eh at
+  300 K.
+
+  `classify_from_frontier` labels a solution insulator or metallic (gap below
+  0.02 Eh, or fractional occupations), `--scc-preset auto|insulator|metal`
+  selects the matching settings, and `auto` resolves itself by measuring the
+  first solve rather than guessing before one exists.
+
+  `--kerker-beta` implements the charge-space analogue of plane-wave Kerker
+  mixing, damping each eigenmode of the shell Coulomb kernel by
+  `1/(1 + beta lambda)` (verified eigenmode by eigenmode). It is **off by
+  default and measured not to help**: on the metallic fixtures it ranges from
+  neutral to harmful, and on the one hard case that converged without it, it
+  stops it converging. `docs/measurements.md` records why — the
+  instability is in the self-consistent MULTIPOLE response, not the charge
+  response, so a charge-space filter cannot reach it.
+
+- **`docs/measurements.md`**, the periodic-SCC census: every shipped
+  periodic example at three electronic temperatures and both accelerators, plus
+  a half-filled hydrogen chain and a polar HF chain. The finding, stated as a
+  2x2 rather than a guess: a metal fails only with self-consistent multipoles
+  AND zero electronic temperature, and any symmetry breaking at all — 1e-8 bohr
+  is enough, about what an angstrom-to-bohr conversion costs — is enough to
+  trigger it.
+
+- **`docs/pip_reachability.md`**, an audit of what survives each distribution
+  channel. Two things are reached by path rather than compiled in (the NN
+  trainer's default dataset and the Ln-xTB parameter generator), and both now
+  name the source repository in their error and their `--help`.
+
+  The wheel was built and every entry listed rather than inferred from the
+  configuration: all ten `LICENSES/*.txt`, `LICENSE`, `NOTICE`,
+  `THIRD_PARTY_NOTICES.md` and `THIRD_PARTY_LICENSES_RUST.md` are in
+  `dist-info/licenses/` (784 kB of a 3.84 MB wheel), and the training records,
+  the root `nnxtb_model.gfn2nn`, `.pdb` symbols and `__pycache__` are not.
+  `tests/test_wheel_licenses.py` now derives its required list from the
+  repository's own `LICENSES/` directory instead of a hand-written one, checks
+  a built `.whl` as well as the installed distribution, and requires each
+  licence entry to be non-empty — an empty file satisfies a file-list check and
+  no licence.
+
+  `docs/` is deliberately **not** in the wheel: 421 kB with no licence text in
+  it, and a wheel is a runtime artefact. The three runtime messages that named
+  a `docs/` file now say it lives in the source repository, and a test pins the
+  decision so including them later has to be deliberate.
+
+### Performance
+
+Measured on a 480-atom water cluster (`--electronic --gradients`) profiled with
+`GFN2_PROFILE=1`, against the same binary before each change.
+
+- **The DIIS error vector cost twice the matrix multiplications it needed.**
+  `F P S - S P F` was built from two triple products. `F`, `P` and `S` are all
+  symmetric, so `(F P S)^T = S P F`: the second product was recomputing the
+  transpose of the first. One triple product now serves both, in the new
+  `scc_accel::commutator_fps_minus_spf`, which the orthonormal, AO and
+  long-range-corrected paths all share.
+
+  `electronic.scf.fock_accel` fell from 4417 ms to 3134 ms (**-29%**, six
+  `O(n^3)` products down to four) and the whole run from 22.0 s to 19.5 s
+  (**-11%**). The error is now *exactly* antisymmetric, where the two-product
+  form was antisymmetric only to rounding.
+
+- **The 2D neutral-difference Ewald matrix ran a full slab Ewald once per
+  column.** `nat` system clones, `nat` neighbour-list builds and `nat`
+  reciprocal sums, where one of each suffices: the 3D part is the geometry
+  matrix the 3D arm already uses, and the Yeh–Berkowitz correction is **rank
+  one** (`(4 pi/V) z_i z_j`) and needs no Ewald at all. That removes a factor of
+  `nat` from the real-space and cloning cost of every slab SCC setup.
+  `the_slab_neutral_difference_matrix_matches_the_column_by_column_form` pins
+  the new build against the definition it replaced, for every reference atom, on
+  a skewed cell.
+
+- **The 1D neutral-difference matrix is built the same way**, in one pass over
+  the pairs rather than one potential evaluation per column.
+
+Not changed, and recorded because they are what a profile points at next on this
+system: the D4 three-body term is 34% of the run and is a genuine `O(N^3)`
+triple sum for any cluster smaller than its 40 bohr cutoff (already the dftd4
+value); the dense diagonalization is 23% and inherently cubic; and the DIIS
+history holds three matrices per entry where only the Fock matrices are needed
+for the extrapolation — at 12 entries and 960 basis functions that is 266 MB of
+the run's 475 MB peak, and the densities and errors are consumed only through
+scalars that could be accumulated when an entry is pushed.
+
+### Known limitations
+
+- **This bundled NN-xTB model is still worse than plain GFN2 on non-covalent
+  interactions and conformer energies.** A limitation of the trained model, not
+  of the method.
+
+  The v0.6.1 retrain uses `--energy-normalization wtmad2`, which exists to fix
+  one cause: the v0.6.0 model trained on an unweighted squared kcal/mol loss, so
+  high-energy subsets took the whole gradient budget. It **reduces the effect
+  without removing it** — the aggregate and the large-error families improve
+  against the v0.6.0 model, while `s22`, `s66`, `aconf` and `sconf` stay above
+  plain GFN2's own error.
+
+  The other cause is what this schema lets the network reach on dispersion. The
+  learnable D4 surface is four **element-independent** globals (`a1`, `a2`,
+  `s8`, `s9`), all of which *were* trained here; the C6 coefficients come from
+  the dftd4 reference tables and none of those is learnable, so the model can
+  only rescale dispersion uniformly. The one element-resolved handle on the
+  neighbouring physics, `atom.dpol` (the AES dipole polarizability), was
+  **dropped from this run** because it had saturated at ~0.99 of its clamp in
+  the v0.6.0 model. Restoring it with a wider clamp, and giving D4 an
+  element-resolved head, is where the next run goes.
+
+  **How much that costs depends on what you are computing**, and the guidance
+  is calibrated against each family's own energy scale rather than against the
+  MAE alone (v0.6.0 model, default fallback; the `median |ref|` column is a
+  property of the dataset):
+
+  | family | median \|ref\| | GFN2 | model | model, as % of ref |
+  | --- | ---: | ---: | ---: | ---: |
+  | W4-11 atomization | 280.8 | 120.73 | 37.06 | **13%** |
+  | MOR41 | 34.2 | 14.07 | 7.60 | **22%** |
+  | S22 | 4.54 | 0.77 | 1.26 | 28% |
+  | S66 | 4.19 | 0.73 | 1.41 | 34% |
+  | SCONF | 5.54 | 1.64 | 2.45 | 44% |
+  | ACONF | **1.30** | 0.19 | 1.26 | **97%** |
+
+  So: use it for atomization and transition-metal reaction energies; on S22 /
+  S66-scale interaction energies it is usable at roughly double the relative
+  error of plain GFN2; and **do not use it for conformer energy differences of
+  order 1 kcal/mol** (ACONF and anything like it), where its error is 97% of the
+  median energy difference — the error is the signal. Only that last case earns
+  a flat prohibition, and it earns it because of the scale of the question, not
+  because the MAE is large.
+
+  **Gradients are a separate question and do not follow the energies.** On the
+  16 `zero_force` structures the model's residual force at the reference
+  geometry has a median of 1.00e-2 Eh/bohr against plain GFN2's 5.62e-3 (RMS
+  1.03e-2 against 9.06e-3), and it is the better of the two on 6 of 16. The
+  direction matches the energies — it improves what GFN2 handles worst and
+  worsens what it handles best — with more scatter. With `n = 16`, all small
+  closed-shell first- and second-row molecules, that is not a verdict on forces
+  in general; against reference forces on the 217-structure held-out set the
+  model's force RMS does improve through training. For force-driven work
+  (optimization, MD, vibrations) pick on the case rather than assuming the
+  energy improvement carries over. Not a defect in the derivative code: the NN
+  gradient is finite-difference verified molecular and periodic, closed- and
+  open-shell, smeared and not.
+
+  Written into `models/README.md` and `docs/whats-new-0.6.1.md` as a
+  limitation rather than withheld or described as a measurement caveat. The
+  NN-xTB path remains experimental and opt-in.
+
+- **A metallic cell at zero electronic temperature does not converge** on a
+  k-mesh. Measured, diagnosed as the self-consistent multipole response rather
+  than charge sloshing, and documented in `docs/measurements.md`. The
+  remedy is the finite electronic temperature the physics wants anyway, which
+  the shipped 300 K default provides.
+
+
+- **No viewer has rendered a Molden file from this code.** The AO basis and the
+  spherical-d convention are verified numerically (the overlap round trip, and
+  the five d functions against the standard real solid harmonics to 1e-12);
+  nobody has opened one in Multiwfn or Avogadro.
+
+- **DFPT supports metals.** A Fermi-smeared (fractionally occupied) reference
+  at `q != 0` was refused by name — *"The Mermin (fractional) response at
+  q != 0 is not implemented"* — and the module additionally overwrote whatever
+  occupations the SCF produced with a `T = 0` filling by band index, behind a
+  hard `1e-6` Eh frontier-gap gate. Now:
+
+  - both point sets are filled from the Fermi-Dirac distribution at the SCF's
+    **own** chemical potential (new
+    `occupations::occupations_at_fixed_fermi_level`). `k + q` is off the mesh,
+    and re-bisecting `mu` from its own spectrum would put the two halves of
+    every band pair in different equilibria;
+  - the band-pair difference quotients take their analytic `df/deps` limits at
+    a degeneracy (reusing the Mermin CPHF's own
+    `weight_difference_quotient`), which is what makes a gapless frontier well
+    posed: `e_r - e_p -> 0` is accompanied by `f_r - f_p -> 0`, because both
+    are the same smooth function of the energy;
+  - the frontier-gap gate applies to `T = 0` references only, and is reported
+    rather than enforced for smeared ones;
+  - integer-occupation references keep the exact `T = 0` algebra, unchanged, so
+    no gapped result moves.
+
+  **No chemical-potential shift belongs at `q != 0`, and that is exact rather
+  than an approximation:** a displacement wave of wavevector `q != 0` has no
+  `(k, k)` matrix element, so the first-order eigenvalue shift vanishes, and
+  with it the occupation response and the particle-number condition that would
+  fix `mu^x`. The Fermi-surface physics enters entirely through the `df/deps`
+  limit. At `q = 0` the force constants *are* the relaxed Hessian, which routes
+  smeared references to the crate's Mermin CPHF on its own.
+
+  Validated by `q_tests::smeared_reference_matches_the_supercell_fold` against
+  the exact `2 x 1 x 1` supercell fold — an independent route, since the
+  supercell's relaxed Hessian goes through the Mermin CPHF and never through
+  the `q`-point solver. On a reference whose worst occupation sits 0.518 away
+  from 0 or 2, the two agree to **3.7e-8 on a scale of 1.6e-1** (2.3e-7
+  relative).
+
+- **`src/vibrations.rs`: one vibrational analysis, shared by `--freq`, the
+  NN-xTB frequency loss and the DFPT Gamma path.** The mass-weighted Hessian is
+  now diagonalised INSIDE an orthonormal basis of the rigid-body subspace's
+  orthogonal complement, so exactly `3N - n` internal modes come out and there
+  is no selection step at all.
+
+  This removes two defects that had drifted apart in two copies of the same
+  algorithm. `nn/freq_modes.rs` projected with `P = I - sum q q^T`, diagonalised
+  the full `3N x 3N` matrix and then **discarded the `n` eigenpairs of smallest
+  `|lambda|`** — i.e. it assumed the smallest-magnitude modes were the
+  projected ones, which fails for a flat internal mode or a mis-decided rank.
+  The CLI's copy did **no selection at all** and printed all `3N` values, so the
+  ~6 projected residues were listed as vibrations; on the non-stationary water
+  of `tests/physics.rs` that meant reporting `imaginary_modes 1` for a
+  −150.66 cm⁻¹ value that is a *rotation*, not a saddle direction.
+
+  Which rigid motions are zero modes is now decided by periodic
+  dimensionality: 3 translations always; rotations only about an axis parallel
+  to every periodic lattice vector. A molecule keeps 3 (2 linear, 0 for one
+  atom), a **1D wire keeps one** (`3N - 4`, or `3N - 3` when every atom lies on
+  the wire axis), and a **2D slab keeps none** (`3N - 3`, same as a crystal) —
+  rotating the home cell about a slab normal does not rotate its images. The
+  linearity decision uses the same collinearity predicate as the dataset
+  loader, so the trainer's mode count agrees with its reference count by
+  construction. The wavenumber constant `5140.4848`, previously written out in
+  three places, has one definition, checked against CODATA.
+
+- **A second oracle: 216 single points against tblite 0.6.0 and xtb**, with
+  non-equilibrium geometries, in `tests/oracle_tblite.rs`. 54 molecules from H
+  to Hf, each at its constructed geometry (textbook bond lengths, already off
+  any GFN2 minimum) and at three further geometries displaced by 0.06, 0.13 and
+  0.24 Angstrom RMS. The geometries are generated by
+  `scripts/make_tblite_oracle.py` from internal coordinates written in that
+  script, so the set carries no benchmark-database provenance, and they are
+  stored **with** the energies: a reference energy without the structure it
+  belongs to pins nothing.
+
+  | comparison | n | median | worst |
+  | --- | ---: | ---: | ---: |
+  | tblite vs xtb (the oracle's own spread) | 216 | 2.5e-9 | 2.0e-8 |
+  | this crate vs tblite, excluding titanium halides | 207 | 3.9e-9 | 1.7e-6 |
+
+  **What it found** (details and an all-element sweep in
+  `docs/measurements.md`): nine titanium-halide references are off by 5 to 24
+  Eh, and it is not the Hamiltonian. With `--scf-accel charge` this crate
+  reproduces tblite on all nine to 5.3e-7 Eh; with the DEFAULT Fock-space
+  ADIIS→CDIIS accelerator the SCC converges — reporting `scf_converged true` —
+  onto a different self-consistent solution with a titanium Mulliken charge of
+  −6.44 on an atom that has four valence electrons. GFN2's third-order term
+  goes as `Γ³q³` and so is unbounded below for `q < 0`; titanium's
+  `GAM3 = 1.767` is the deepest such well in its neighbourhood (Sc 0.50,
+  V 0.90, Zr 0.70), which is why titanium is the element that falls in. The
+  spurious solution is degenerate at the frontier: its occupations come out
+  fractional at 300 K, so `--tda` refuses it outright, while the physical
+  solution has a lowest TDA excitation of +0.101 Eh. Both halves are pinned by
+  the test, so neither a regression nor a silent fix can pass unnoticed.
+
+- **Phonon and normal-mode eigenvectors.** `dfpt::modes_from_dynamical_matrix`
+  and `dfpt::phonon_modes_dfpt` return the mass-weighted eigenvectors next to
+  the wavenumbers, complex away from Gamma (the realification's upper half is
+  the real part and its lower half the imaginary one), with
+  `PhononModes::cartesian_displacements` for the `M^{-1/2}`-scaled pattern.
+  `frequencies_from_dynamical_matrix` now delegates to it and is bit-identical.
+  New CLI flag `--modes` prints, per mode, the unit-norm Cartesian displacement
+  pattern; with `--qpoint` it prints both parts, because the phase between
+  neighbouring cells is physical. Pinned by `D z = lambda z` and Hermitian
+  orthonormality at Gamma and at `q = 1/2`.
+
+- `--qpoint QX QY QZ` on the CLI: phonon frequencies at one fractional
+  wavevector through the DFPT module, alongside the Gamma analysis.
+- `dfpt::frequencies_from_force_constants` with `AcousticProjection`, and
+  `dfpt::enforce_acoustic_sum_rule`. The latter delivers exact row sums and
+  **reports** the asymmetry it cannot remove rather than iterating towards a
+  fixed point that does not exist: the on-site correction is symmetric only
+  when the row-sum block is, and neither re-symmetrising nor symmetrising the
+  correction converges.
+
+- **SCC convergence: a stability test, a ladder that fixes what it rejects, and
+  a new default starting point.** The tblite oracle above showed the SCC
+  converging, and reporting success, onto solutions several Hartree from the
+  answer. Three changes, all measured:
+
+  - **`ElectronicOptions::initial_guess` defaults to `InitialGuess::Eeq`.**
+    Both reference programs start from a superposition of atomic densities;
+    this crate started from `q = 0`, which is the wrong basin for a polar
+    reference and is when a `q^3` term unbounded below can be overshot into.
+    `InitialGuess::Zero` reproduces the old behaviour. Measured: converged
+    energies do not move (water 2.7e-9 from tblite, benzene 1.7e-6, methanol
+    2.6e-9, unchanged), and on its own this does NOT fix titanium.
+  - **`electronic::scc_charge_curvature` and a CLI ladder that uses it.** The
+    on-site curvature `eta_s + 2 gamma3_s q_s` is positive at a minimum in the
+    charges and negative at a maximum; it costs one multiply per shell. It
+    separates the two titanium tetrachloride solutions cleanly (-0.472 against
+    +0.308) and stays between +0.25 and +0.43 on healthy molecules. The CLI now
+    tests every converged answer with it, and when the answer fails, re-solves
+    the same equations on progressively more damped rungs
+    (`electronic::apply_scc_rung`, shared with the NN trainer), from both the
+    EEQ and the zero guess, and finally at charge tolerances relaxed to 1e-7
+    and 1e-6. The rung, the guess and any relaxed tolerance are reported;
+    `--no-scc-ladder` turns it off. Measured against tblite: TiCl4 4.98 →
+    5.3e-7 Eh, WH2 18.7 → 1.3e-8, CrH2 2.6e-2 → 5.4e-8, IrH 2.9e-1 → 6.1e-9,
+    AsF 2.8e-2 → 6.8e-10.
+  - **`--scc-search`** walks the whole ladder even when the first answer passes
+    and keeps the LOWEST acceptable solution, for references with more than one
+    stable SCC solution: TcH 5.9e-2 → 9.6e-9, GeH2 9.3e-3 → 2.5e-8. On two
+    further probes it confirms this crate is already in the DEEPER minimum and
+    tblite is not.
+
+- **`--stability` and `src/stability.rs`: stability analysis of a converged
+  solution.** Three questions, cheapest first: is it a minimum in the charges
+  (the curvature above), is the frontier gap open (fractional occupations at
+  300 K mean it collapsed), and is it a minimum in the orbital rotations. The
+  last is the DFT/HF analysis proper, the lowest eigenvalue of the electronic
+  Hessian, read off the Tamm-Dancoff spectrum the crate already computes: the
+  singlet channel for internal stability, the triplet channel for external
+  (restricted-to-unrestricted) stability. A channel that cannot run reports
+  why rather than failing, because "this reference has no frontier gap" is an
+  answer.
+
+- **Open-shell coverage against tblite, at both levels.** Occupation-only
+  (`-u N --no-spinpol` against `--spin N`) and spin-polarized (`-u N` against
+  `--spin N --spin-polarized`), 344 odd-electron probes each. Split by whether
+  this crate's SCC converged, the occupation-only path agrees to a median
+  6.9e-9 and the spin-polarized path to 3.5e-9. The finding is that the
+  spin-polarized SCC misses its charge tolerance on 218 of 344 probes, against
+  28 of 344 for the occupation-only path: a convergence gap, not a physics
+  one. Recorded in `docs/measurements.md`.
+
+### Changed (BREAKING)
+
+- **`Cargo.toml`'s package list is now an `include` WHITELIST, not an
+  `exclude` blacklist — and the blacklist was leaking.** Measured with
+  `cargo package --list` before the change: the crates.io package carried a
+  locally built `_native.cp314-win_amd64.pyd` (11.8 MB — one Python ABI and
+  one OS, inside a *source* package), its `.pdb`, three `__pycache__` entries,
+  the root `nnxtb_model.gfn2nn` and seven optimizer scratch files. **21.3 MB**
+  of it. There is no git repository here, so `cargo package` has no
+  `.gitignore` to consult and an exclude list has to anticipate every artefact
+  the working tree can grow; this one had not.
+
+  Inverting the list dropped exactly those 15 files and nothing else, verified
+  by diffing `cargo package --list` across the change. `tests/` now ships in
+  the crate as well, so the suite (including `attribution.rs`, whose inputs
+  are all whitelisted) runs from an unpacked published crate.
+  `scripts/make_release_zip.py` is a whitelist for the same reason, and its
+  archive is unchanged file-for-file. `pyproject.toml` keeps only the two
+  wheel-payload entries; the sdist is governed by the Cargo whitelist, checked
+  by building one.
+
+- **`nn_train --dataset` is REQUIRED and has no default.** Training data is
+  supplied by the caller. A default would name a path most callers do not
+  have, and would let a run silently pick up whatever happened to sit there.
+  The refusal names the flag and points at `docs/nn-xtb.md`, which now
+  carries the `.gfn2ds` format and a worked training procedure. The four
+  corpus tests in `src/nn/dataset.rs` take their directory from
+  `GFN2_NN_DATASET` and print `SKIPPED` when it is unset.
+
+- **`PeriodicDimensionality::OneD` carries its periodic axis**, the way `TwoD`
+  already carried its non-periodic one: `OneD { periodic_axis: usize }`. Matches
+  on the bare variant need `OneD { .. }`. It also retires two `expect()`s in
+  `vibrations.rs` that were re-deriving the axis from the lattice.
+
+- **`ko_ewald::warn_one_dimensional_electrostatics_once` is gone.** It warned
+  that a wire's electrostatics were a truncated sum; they are not any more. A
+  no-op stub was rejected on purpose — it would read as a warning still watching
+  for something.
+
+- `--freq` prints the `3N - n` **internal** modes, not all `3N`, with new
+  `n_projected_translations`, `n_projected_rotations` and `n_internal_modes`
+  lines. `imaginary_modes` counts every `f < 0` — the old `-10 cm^-1`
+  threshold existed to hide projected residues, which no longer occur, so it
+  now only hid real saddles.
+- **`nn_train --dataset` is now REQUIRED and has no default.** Training data is
+  supplied by the caller; a default would name a path most callers do not have,
+  and would let a run silently pick up whatever happened to sit there. The
+  refusal names the flag and points at `docs/nn-xtb.md`, which now carries
+  the `.gfn2ds` format and a worked training procedure. The four corpus tests in
+  `src/nn/dataset.rs` take their directory from `GFN2_NN_DATASET` and print
+  `SKIPPED` when it is unset. NN-xTB training records are excluded from the
+  source archive as well as from the crates.io and PyPI packages, so they are
+  distributed in no channel at all.
+- `scripts/make_release_zip.py` gains `--lf` (LF endings, no BOM, working tree
+  untouched).
+- **`--gradients` and `--stress` now imply `--electronic`.** They did not, and
+  a run with either alone printed no gradient at all; see *Fixed* above.
+  Nothing that produced output before changes.
+- **The default SCC starting guess is the EEQ-BC charges**
+  (`InitialGuess::Eeq`), matching what xtb and tblite do. `InitialGuess::Zero`
+  reproduces the pre-0.6.1 path. Measured: this alone does not change any
+  converged energy in the oracle suite, but it is the right basin to start a
+  polar reference from.
+- **`--opt-cell volume` is refused on a slab or a wire**, by name: the cell
+  volume of a partially periodic cell is set by the vacuum thickness the input
+  chose, so constraining it constrains nothing physical.
+- **Slab and wire stress components touching a non-periodic axis are reported
+  as zero**, in the CLI, the Python bindings and the ASE calculator alike.
+  `unmasked_stress_hartree_per_bohr3` has the raw tensor. An ASE
+  `FrechetCellFilter` on a slab therefore no longer relaxes the vacuum.
+
+## [0.6.0] - released
+
+### Removed (BREAKING)
+
+- **The Ln-xTB lanthanide parameters are no longer distributed**, in any channel.
+  Removed: `data/param_lnxtb.txt` (and with it the `include_str!`, the
+  `BUNDLED_LNXTB_OVERLAY_TEXT` public constant and its `lib.rs` re-export),
+  `data/lnxtb_reference_bondlengths.tsv`, `examples/lnxtb/` (50 `.xyz` files),
+  and `tests/lnxtb.rs`.
+
+  **Why.** The values come from the Supporting Information of a subscription
+  article. Wiley's Online Library terms of use state that users "shall not have
+  the right to incorporate any material from the Electronic Products into any
+  institutional or other repository", and v0.6.0 publishes to GitHub, crates.io
+  and PyPI - three repositories, distributing continuously. That is a contract
+  term, and attribution does not cure a contract term; only not distributing
+  does. The earlier assessment (`docs/lnxtb_licensing.md`) recommended keeping
+  the data with stronger attribution, and that was right for its premise: the
+  deliverable then was a zip handed to one person. The premise changed, so the
+  conclusion did. Nothing about the copyright analysis changed - it still rates
+  every copyright theory as very low, and Wiley has no copyright standing in
+  Supporting Information at all (its CTA excludes SI from the assignment; the
+  author retains it).
+
+  **Migration.** `scripts/extract_lnxtb_params.py` (new) builds the parameter
+  file from your own copy of the Supporting Information. This is a transcription
+  step, not a reimplementation: SI Table S62 already prints the parameters in
+  exactly the xtb `$Z=` syntax, as extractable text. Verified to reproduce the
+  previous hand transcription exactly - 15 blocks, 300 values, `identical`.
+
+  ```bash
+  python scripts/extract_lnxtb_params.py --si jcc70321-sup-0002-datas2.pdf -o param_lnxtb.txt
+  gfn2_rs --xyz NdF3.xyz --electronic --ln-xtb-param param_lnxtb.txt --charge 0 -u 2
+  ```
+
+  **API changes.** `Gfn2Parameters::bundled_lnxtb_overlay()` is gone;
+  `apply_lnxtb_overlay()` now takes `Option<&str>` and resolves
+  `--ln-xtb-param PATH` > `GFN2_LNXTB_PARAM` > **error**, mirroring the existing
+  `--spin-param` precedent. There is deliberately no fallback to plain GFN2: a
+  silent fallback returns a converged result that looks like Ln-xTB and is not.
+  New CLI flag `--ln-xtb-param FILE`; new Python kwarg `ln_xtb_param=`.
+
+  **What this costs, stated plainly.** `tests/lnxtb.rs` validated all 15
+  lanthanides against the SI energies (13 of 15 at 1e-7..1e-9 Eh; Pr/Sm are a
+  documented parameter-set instability) and the LnF3 bond lengths. Every one of
+  its seven tests loaded an SI geometry, so none survive the fixtures. Those
+  measurements are recorded in the docs but are no longer re-runnable from this
+  repository. The overlay *wiring* is still regression-tested, on a synthetic
+  two-element parameter block (`src/params.rs`), because parsing the `5d6s6p`
+  shell shape and replacing exactly the listed elements do not depend on which
+  numbers arrive; and `src/electronic/tests.rs` keeps a lanthanide SCC test on
+  the bundled GFN2 block.
+
+  The SI also tabulates a separate Ce(VI) re-optimization for the `Ln-xTB*`
+  method. The extractor reports it and can select it with `--ce6`; the previous
+  bundled file silently contained only the Ln-xTB Ce block.
+
+### Fixed
+
+- **`nn_train --checkpoint-every` wrote nothing under `--select-by holdout`.**
+  The checkpoint block only fired `if let Some(w) = &best_weights`, and
+  `best_weights` is populated by the training-loss branch (`!select_by_holdout`)
+  or by a holdout evaluation. With holdout selection the first evaluation is at
+  `--holdout-every` epochs, so `--checkpoint-every 10 --holdout-every 25` ran the
+  checkpoint block at epochs 9 and 19 and silently wrote no file. Caught on a
+  live 100-epoch run: 13 epochs (7.3 h) in, no `.gfn2nn` existed.
+  The wording ("save the best model every N epochs") is not violated -- there is
+  no "best" yet -- but the effect is a long run's first hours having no crash
+  protection and nothing saying so.
+
+  Now the block falls back to the CURRENT weights when no selected best exists,
+  so `--checkpoint-every` always produces a resumable file, and a startup line
+  states when the first *selected* checkpoint will appear. Selection semantics
+  are unchanged: the final save still ships `best_weights` when they exist.
+
+- **Ewald splitting-parameter independence is now enforced, not just hoped for.**
+  `physics::ewald_splitting_parameter_independence` had been `#[ignore]`d since
+  it was written -- first as a known failure, then as "partially fixed" -- and
+  the skip reason claimed the SCF total still drifted by 8.1e-3 Eh. Running it
+  as part of a sweep of every ignored test showed that it PASSES, and by a wide
+  margin: 2.7e-15 Eh spread (5.3e-16 relative) over alpha = 0.16 .. 0.32
+  bohr^-1, reproducible to every printed digit. The regularized `G = 0` term
+  for the `r^-3` Klopman-Ohno tail had closed the defect; nobody noticed because
+  the test stayed disabled. It is now enabled, which makes alpha independence a
+  standing guard over the whole periodic electrostatic assembly (isotropic SCC,
+  AES and D4 at once) instead of a disabled note, and the Known-issues entry
+  claiming otherwise has been withdrawn.
+
+  Sweep result for the record: all **42** ignored library tests pass
+  (`cargo test --release --lib -- --ignored --test-threads=1`, 303 s). The
+  remaining disabled tests are the two documented in Known issues
+  (`oracle_mindless03_metastable_reference`, the spin-polarized Mermin
+  identity), which fail for the reasons recorded there.
+
+- **The standalone periodic multipole-Ewald tool computed the charge-quadrupole
+  channel with the sign inverted.** `multipole.rs` kept a private
+  `QTHETA_COEFF = -1/3` and used the ONE constant for both the real-space pair
+  kernel and the reciprocal-space structure factor. Those two spaces genuinely
+  need opposite signs -- Poisson summation flips this channel, which is why
+  `aes.rs` carries `AES_QTHETA_COEFF` (`+1/3`) and `AES_RECIP_QTHETA_SIGN`
+  separately -- so the shared constant was right for the reciprocal sum and
+  wrong for the real-space one.
+
+  **Scope: `gfn2_rs --multipoles FILE` on a PERIODIC system only.** The
+  molecular branch of that flag goes through `aes::direct_aes_potentials` and
+  was always correct, and the SCF, gradient, Hessian, third-derivative and
+  NN-xTB paths all import the shared constants, so none of them were affected.
+
+  Found by a mechanical sweep for constants defined in more than one module,
+  looking for the pattern that produced an earlier defect of exactly this kind
+  (a private duplicate of this same constant with a flipped sign inverted the
+  frozen q-theta Hessian block, ~9e-3 Eh/bohr^2, recorded above
+  `AES_QTHETA_COEFF`). This copy had no test at all: `multipole.rs` contained a
+  single test, for an unrelated projection convention.
+
+  The fix imports the shared constants instead of re-deriving them, and names
+  the two spaces separately (`QTHETA_COEFF`, `RECIP_QTHETA_COEFF`) so one cannot
+  silently serve both again. `standalone_multipole_kernel_agrees_with_the_scf_aes_sign`
+  now pins all three channels against `aes::direct_aes_potentials`, comparing
+  the unscreened real-space kernels rather than Ewald totals -- the AES damping
+  factors are strictly positive, so they cannot change a sign, which makes this
+  a decomposition-free oracle. Measured after the fix, the standalone/SCF
+  magnitude ratio is 1.2461 for q-theta and 1.2460 for mu-mu, i.e. exactly the
+  shared `f5` damping factor, with matching signs.
+
+- **The two `nn_train` fast-route fallbacks now name the structure and the
+  reason.** Both discarded the route's error (`Err(_)`) and announced themselves
+  once, globally, as "some frequency/force structures are outside the domain" —
+  naming neither how many, nor which, nor why. On an eleven-hour run that is the
+  difference between a one-structure nuisance and half the set on the slow
+  route, and the slow route is the trainer's dominant cost.
+
+  Both messages had also gone **stale against the code they described**: the
+  frequency one listed "molecular references" among the causes when it is
+  PERIODIC references that are rejected, and the force one still claimed "closed
+  shell" after the open-shell adjoint landed. Printing the route's own error
+  cannot drift that way. Reported once per structure, since the route is
+  re-decided on every item and an unconditional message would repeat the whole
+  list once per epoch.
+
+- **Per-item notes now reach `--log`, not just stderr.** The epoch line already
+  followed the rule that anything which removed data from the gradient belongs
+  in the log rather than the stderr stream; the notes that say where the epoch's
+  TIME went did not, and they are just as unrecoverable once an eleven-hour
+  run's console scrollback has rolled. `EpochMetrics` gained `messages`, and the
+  CLI writes them above the epoch line they belong to.
+
+- `nn_train`'s slow-item warning now names the item. It previously reported only
+  that something had taken minutes, which on a 550-item epoch left no way to
+  tell which structures — or even which KIND of item — accounted for the time.
+
+- **Every `#[allow(dead_code)]` in `src/` now either states why or is gone.**
+  `rustc` emits no warnings (verified over `--all-targets --all-features` with
+  the crate fully recompiled, which includes `src/python.rs` — the normal test
+  gate never compiles it), but fourteen suppressions were standing between that
+  clean output and the truth. Nine already carried a reason. The other five:
+
+  - `hessian::response`: two private routines removed —
+    `scalar_derivative_direct_pulay_hessian_kpoints` and
+    `scc_shell_response_gradient_fd`, with the four imports they alone used. No
+    caller anywhere in the crate, tests included. An FD oracle that no test
+    drives is not an oracle; it is unexercised code rotting against the routine
+    it was written to check.
+  - `hessian::response::scc_response_potential_ground_density_gradient`: kept,
+    with the reason added — it is dead in a lib build and live in a test one,
+    where it is the partner-FD arbiter for the shell response.
+  - `cphf::BlochCartesianCphfHessianResult`: the `allow` moved from the STRUCT
+    to the two fields that are actually test-only
+    (`orbital_shell_charge_responses`, `metric_shell_charge_responses`). A
+    struct-level suppression also hides every field added later; the other nine
+    fields here are live.
+  - `third_derivatives::classical::CnThirdData::blocks`: the `allow` was stale
+    and inert — the field IS read, by `finalize_d4`, for
+    `sum_p f_p d^3 CN_p / dR^3`. Removed the attribute and documented the
+    reader, so the field no longer reads as abandoned.
+
+  The remaining ~113 `#[allow(clippy::too_many_arguments)]` and
+  `#[allow(clippy::type_complexity)]` are left alone deliberately: both lints
+  are in `clippy::complexity`, which `Cargo.toml` already sets to `allow`
+  crate-wide, so they are inert today — but they are the defence if that
+  setting is ever tightened.
+
+### Documentation
+
+- `docs/README.md` (new): an index. Seven documents, 345 KB, and nothing said
+  which to open — or which are maintained against the code (the two API
+  references) versus dated records of one investigation (everything else).
+- `docs/nn-xtb.md`: the **Results** and **Tried and rejected** sections
+  were unfilled `<!-- -->` template placeholders in a document whose first
+  paragraph says "start here before optimizing anything in this module". Both
+  are now written from the measured record, including the two refuted
+  hypotheses above and the parallel-scaling diagnosis, and the header points a
+  reader at the refutations first.
+- The v0.5.0 engineering notes (retired from `docs/` in v0.6.1): status corrected from
+  `[0.5.0] - in progress` to `released`.
+- `docs/measurements.md`: says explicitly that its absolute times are only
+  comparable within its own series.
+
+### Added
+
+- **`dfpt`: self-consistent linear response at a wavevector — the dynamical
+  matrix `D(q)`.** New public module with `force_constants_at_q`,
+  `dynamical_matrix_dfpt`, `frequencies_dfpt` and
+  `frequencies_from_dynamical_matrix`, plus `DfptOptions` for the
+  coupled-perturbed controls.
+
+  **`q = 0` is exact by construction.** The `q = 0` force constants ARE the
+  relaxed analytic Hessian, so that path routes to `compute_hessian` rather
+  than reimplementing it — a second implementation could only disagree, and a
+  bit-identity test pins them together.
+
+  **A non-zero `q` runs a periodic CPHF on the PRIMITIVE cell** (`dfpt::solver`
+  and its submodules), and reproduces the exact supercell fold at commensurate
+  `q` having shared no code with it beyond the SCF and the pair integrals:
+
+  | reference | mesh | `q` | oracle | `max |C_DFPT - C_supercell|` | scale |
+  |---|---|---|---|---|---|
+  | H2 lattice (5 bohr period) | `[2,1,1]` | 1/2 | 2x1x1 | `6.8e-11` | 0.315 |
+  | H2 lattice | `[3,1,1]` shifted | 1/3 | 3x1x1 | `1.5e-10` | 0.311 |
+  | LiH lattice (polar) | `[2,1,1]` | 1/2 | 2x1x1 | `3.8e-15` | 0.037 |
+
+  with `|C(q) - C(0)| = 2.7e-2` / `7.6e-3` on the H2 lattice, so the tests
+  cannot pass on a `C(q)` that dropped the phase. The whole `q`-machinery run
+  AT `q = 0` lands on `compute_hessian` to `5.0e-14` (acoustic sum rule
+  `1.7e-16`); `C(q)` is Hermitian to `1.3e-17` before the final symmetrization
+  and `C(-q) = C(q)*` to `7.8e-18` at `q = 1/4`; an incommensurate `q = 0.31`
+  gives real branches that move by `12 cm^-1` over `dq = 0.01`.
+
+  How it is built, and what pins each part (`dfpt::q_tests`):
+
+  * **Bands at `k + q`** from the converged Fock, by the same builder that
+    rebuilds the mesh bands (`electronic::closed_shell_scf_points_at`), so a
+    commensurate `q` lands on a mesh point's own bands. Integer occupations and
+    a clear frontier gap over the union of both point sets are REQUIRED
+    (linear response is not the right object at a degeneracy).
+  * **The bare perturbation** is the `q = 0` Bloch derivative-matrix walk with
+    one phase changed — `e^{i(k+q).T}` on the ket-centre contribution, since
+    the ket atom sits in cell `T` and moves with that phase — including the
+    coordination-number chain, whose site-resolved `dCN_a/du_c^(q)` follows
+    the same bra/ket rule. Pinned at `q = 0` element for element against
+    `cphf::bloch_cartesian_ao_derivative_matrices` (`3.3e-16`).
+  * **The IES kernel at `q`** (`dfpt::kernel`): Klopman–Ohno residual with
+    `e^{iq.L}`, and the `1/r` and `r^-3` Ewald sums over `G + q`. At `q != 0`
+    there is nothing to regularise — the `G = 0` members are finite and are
+    exactly the supercell's `G_s = q` vectors. Pinned by finite differences of
+    its own value (gradient and Hessian, `~7e-11`), by independence of the
+    Ewald splitting parameter (`5.5e-12`, after removing the same-site `L = 0`
+    smooth-term Hessian that the real-space sum excludes — the α scan found
+    that at `9.4e-3` while value and gradient already agreed to `1e-12`), and by
+    the fold of the supercell's own shell kernel (`2.3e-15`).
+  * **The response** is the unified band-pair quotient
+    `D_pr = [(f_r - f_p) V_pr - (f_r e_r - f_p e_p) S_pr]/(e_r - e_p)` on
+    `(k+q, k)` blocks, which carries the resonant, the antiresonant (bra at
+    `k+q`) and the occupied-metric (`-f S_pr`, closed form) terms at once; the
+    shell-space self-consistency is a dense direct solve `(I - chi K(q)) dq =
+    source`, so there is no mixing to stall.
+  * **The skeleton** is every fixed-density block phased term by term with one
+    rule (`e^{iq.(cell_Y - cell_X)}` per ordered pair of cluster sites):
+    repulsion (`q = 0`: `0.0`; folds: `2e-16`), the fixed-charge shell IES
+    written as `delta_ab sum_c q q H_0 - q q H_q` (`1e-15`), and the direct
+    Pulay/CN block (`3e-16` at `q = 0`, `9e-16` folded at `q = 1/3`).
+
+  **Refused BY NAME, never answered with a number missing a term:** D4 and AES
+  (no phased kernels yet), 1D/2D cells (no phased Ewald there), spin-polarized,
+  open-shell and Fermi-smeared references, time-reversal-folded meshes, a
+  molecule, a `q` along a non-periodic axis, and nonsense solver controls. A
+  `q` that is a reciprocal-lattice vector IS Gamma and takes the Gamma path.
+  `DfptResult` now reports which route ran (`DfptRoute`), the frontier gap,
+  the pre-symmetrization Hermiticity residual and the shell-space residual, so
+  a comparison can assert what it compared. `frequencies_from_dynamical_matrix`
+  diagonalises a complex Hermitian `D(q)` through its realification.
+
+  **A mesh premise worth stating.** An `n`-fold supercell at Gamma folds the
+  primitive points `{0, 1/n, ...}`; this crate's unshifted Monkhorst–Pack mesh
+  (`i/n - 1/2`) is that set for even `n` but NOT for odd `n` (`[3,1,1]` is
+  `{1/2, +-1/6}`, the fold of the supercell's zone-boundary point), where
+  `kpoint_shifted = true` restores it. The first `q = 1/3` comparison missed by
+  `1.6e-3` for exactly that reason, and with the Gamma-centred mesh the
+  residual is `1.5e-10`. The probe that states the premise as a test had to be
+  written twice: closure of the mesh under `k -> k + 1/n` is NOT it (every
+  equispaced mesh is closed under its own spacing — the first probe asserted
+  otherwise and was refuted); the criterion is that every mesh coordinate be a
+  multiple of `1/n`.
+
+  `LongRange::Off` drops the `G = 0` members at `q != 0`. Measured: it changes
+  `C(1/2)` on the non-polar H2 lattice by `1.7e-6`, and it leaves a
+  splitting-DEPENDENT kernel (those members are what balance the real-space
+  sums), so it is a diagnostic at the shipped splitting, not a second kernel.
+
+  **`force_constants_at_commensurate_q` gives `C(q)` at any `q` a supercell can
+  represent.** It is NOT DFPT and does not claim to be — it costs a supercell,
+  which is the cost DFPT exists to avoid — but it is exact, and it is the
+  oracle the `q != 0` DFPT path is measured against. The transform is
+  `C(q) = sum_L Phi_ab(L) e^{iq.L}`, read off a supercell's Gamma Hessian.
+  Paired with `dynamical_matrix_from_force_constants` it reaches wavenumbers
+  through the same mass weighting the `q = 0` path uses.
+
+  Pinned by four identities rather than by one comparison: the `q = 0` fold of a
+  2x1x1 supercell reproduces the primitive cell's force constants **on a
+  `[2,1,1]` k-mesh** to `1.9e-16` (the supercell/k-mesh equivalence — comparing
+  against the primitive GAMMA Hessian instead is off by `1.9e-5`, which is the
+  physical gap between the two samplings, and getting that wrong is the easiest
+  way to "verify" a broken replication order); `C(q)` is Hermitian to `3.5e-18`
+  and `C(-q) = C(q)*` exactly; an incommensurate `q` is refused; and an isolated
+  molecule in a 12-bohr cell shows FLAT dispersion, its zone-boundary
+  frequencies within `0.13 cm^-1` of Gamma — with a lower bound on that shift
+  too, so the test cannot pass on a `C(q)` that dropped the phase.
+
+  Note for readers coming from a DFT code: GFN2 has no exact exchange, so two of
+  the three complications a Hartree-Fock or hybrid DFPT carries — a non-local
+  `J - K` kernel, and `sum_T |T|^-1` diverging at Gamma — do not arise. GFN2's
+  kernel is the isotropic IES gamma, the third-order onsite term, AES and the
+  D4 charge response, all charge-channel.
+
+- **The open-shell analytic Hessian now covers PERIODIC references on a k-point
+  mesh.** `cphf::spin_bloch`'s two-channel solver — which existed for the
+  k-point TD gradient — now also returns the per-k AO density and
+  energy-weighted responses, and those feed the same
+  `hessian::cphf_bloch::bloch_cphf_response_hessian` the closed-shell mesh uses.
+  Acceptance: H3 (uhf = 1) in a 12-bohr cell at kgrid [2,1,1] against the
+  central FD of the analytic gradient, `3.2e-7`, beside a closed-shell H3+
+  control on the same cell at `7.1e-9`.
+
+  Three things had to be fixed to get there, each of which the acceptance test
+  found rather than a code review:
+
+  * `bloch_response_density` leaves `energy_weighted` at ZERO on the
+    integer-occupation path (only the Mermin builder fills it), so every dW
+    piece has to be assembled explicitly. `add_bloch_response_fock_energy_weighted`
+    also hard-wires the isotropic-CHARGE convention; the spin fold is the same
+    object at `+`/`-` per channel, so it is now split out as
+    `add_bloch_shell_potential_energy_weighted`.
+  * The occupied-metric fold reads the COMMON `h^x`, but a channel's `h^x` also
+    carries the frozen reference spin fold `+/- 1/2 (V+V) S^x`, which
+    `spin_bloch` applied only to the right-hand side. Invisible while nothing
+    read `energy_weighted`; wrong as soon as something did.
+  * Two guards refused the reference for reasons that did not survive reading
+    the code: `hessian_pulay`'s k-point direct-Pulay walk takes every density
+    through `KPointGradientBands::pair_contraction`, which already sums the
+    channels, and `hessian::compute_hessian`'s open-shell branch shadowed the
+    non-Gamma branch entirely, making the new route dead.
+
+  **A diagnosis worth keeping.** The first acceptance geometry was a
+  near-equilateral H3 — the textbook Jahn-Teller system — whose alpha
+  SOMO/LUMO are degenerate. Linear response is not the right object at a
+  degeneracy: the CPHF denominator `eps_a - eps_i` collapses, the response
+  block came out at `9.4`, and the Hessian missed the FD by `1.2e-3`. Nothing
+  pointed at it except the geometry. A response-coefficient scan, a
+  frozen-coefficient scan, and tightening the CPHF from `1e-8` to `1e-14` at
+  4000 iterations all left the residual at exactly `1.181e-3`; the solver's own
+  charge response matched the SCF finite difference to ~7e-8 relative; and the
+  `ao_responses` reduced BIT-IDENTICALLY to the closed-shell solver's on a
+  split closed-shell reference. Distorting the geometry moved the response
+  block to `0.079` and the residual to `3.2e-7`. `open_shell_kpoint_hessian_response_scale_scan`
+  (ignored) reproduces every one of those probes.
+
+  Spin-POLARIZED meshes stay on FD, for a named missing piece: the three
+  fixed-orbital spin blocks in Bloch form. They all carry `W` or `V = W m` and
+  so vanish for UHF, which is why the UHF path is complete without them.
+
+- **The open-shell analytic Hessian now covers Fermi-SMEARED references.** A
+  two-channel Mermin CPHF (`cphf::spin_gamma`) sits beside the occupied-virtual
+  amplitude solver, and the entry points pick between them on the occupations
+  themselves. Three separate hard guards - the `hessian` dispatcher, the plain
+  GFN2 `hessian::spin_response` assembly and the NN `nn::hessian_analytic`
+  response folds - all bottomed out in the same amplitude parameterisation, so
+  fixing it at the root lifted all three at once.
+
+  **Why it matters.** Of the 720 frequency structures in the training corpus, 108
+  are open shell, and the small radical diatomics (CaBr, GaO, NSe) smear their
+  degenerate pi levels straight into the old `1e-6` integer guard. Those
+  structures were paying the semi-numerical route every epoch.
+
+  Two conventions are load-bearing and both were read off the code rather than
+  assumed:
+
+  * The existing Fermi-Dirac occupation derivative is written for SPATIAL
+    orbitals, `f in [0, 2]`; a spin channel holds `f in [0, 1]` and its
+    derivative is `-f(1-f)/kT`, exactly TWICE the spatial one at the same
+    physical filling. The two are now one expression, `-f(n-f)/(n kT)`, selected
+    by the new `OccupationScale`, and the closed-shell path is bit-identical.
+  * Alpha and beta each conserve their OWN electron count
+    (`occupations::spin_resolved_occupations` fills them from two independent
+    Fermi levels), so the chemical-potential shift enforcing
+    `sum_p f_p^x = 0` is per channel. The channels couple through the charge and
+    spin kernels, never through a shared `mu^x`.
+
+  Self-consistency is solved densely in the `(dq, dm)` shell space - one
+  geometry-fixed `2 nshell` coupling matrix, one solve per perturbation - which
+  is the closed-shell finite-temperature recipe with the magnetisation channel
+  added. AES stays outside it, converged by the same damped outer loop the
+  closed-shell path uses.
+
+  Acceptance: the full relaxed Hessian of a smeared OH radical (all terms) vs
+  the central FD of the analytic gradient, UHF and spin-polarized. Note that the
+  per-channel conservation test is deliberately NOT the magnitude check - a
+  uniform factor of two cancels out of both `mu^x` and `sum_p f_p^x = 0`, so
+  only a real second derivative can catch the wrong occupation scale.
+
+- **The NN force-loss analytic adjoint now accepts open-shell references.** Both
+  of its response solves route through the coupled two-channel spin CPHF, the
+  same `nn::hessian_analytic::open_shell_response_folds` the analytic NN Hessian
+  uses (generalised here to take the parameter perturbations directly, so the
+  Hessian can pass `3N` of them and the adjoint the single `J_w` direction it
+  actually needs). The family blocks need no spin work: every implemented head
+  couples to a spin-summed quantity.
+
+  Until now an open-shell force structure fell back to the double finite
+  difference every epoch, and the guard's stated reason - "the same carve-out
+  the analytic NN Hessian documents" - had outlived that carve-out by a release.
+
+  Acceptance runs on TWO open-shell references, integer (H2O+) and Fermi-smeared
+  (OH), against the same Richardson-extrapolated double FD the closed-shell path
+  answers to. One is not enough for the reason this project already recorded:
+  the broken closed-shell wiring passed H2O+ by accident while missing 5.6% of
+  CH2's correction blocks.
+
+  **A real defect surfaced here, in the AES self-consistency tolerance.** At the
+  `1e-8` copied from the closed-shell loop, the smeared case sat three decades
+  above every other reference (`2.4e-8` against `1.7e-11`). A step scan settled
+  what it was: FLAT from `5e-4` to `4e-3`, so neither `1/h` oracle noise nor
+  `h^2` truncation, so a systematic error on the analytic side. At `1e-12` the
+  residual is `1.3e-10` and the scan shows the expected noise-floor/truncation
+  shape. The closed-shell loop keeps `1e-8` only because its own FD oracle
+  floors out around there. Running the loop out is now an explicit error rather
+  than a silently unconverged response.
+
+- `nn_train --drop-heads A,B`: remove heads from the learned schema by full name
+  (`global.gam3p`, `atom.rcov`, ...) before the network is built.
+
+  **Why.** A head that keeps hitting its `ClampSte` bound is a hard error for
+  every item that touches it - deliberately, since a saturated STE gradient no
+  longer matches the true derivative and the forces would not belong to the PES.
+  In the v0.6.0 training run one head, `global.gam3p`, accounted for *all* 31
+  saturation errors, and the plateau backoff chased it from `1e-4` down to
+  `1.25e-5` before the guard's own "not rising" branch recognised that the clamp
+  bound, not the step size, was binding. Dropping the head trains the remaining
+  38 at full step size instead of paying that tax every epoch. Combines with
+  `--init-model`, which matches tensors by name and never asks the checkpoint
+  for a head the reduced schema does not have, so a run can resume from a full-
+  schema checkpoint with no loss of the other heads' learned state.
+
+  A name that is not in the schema is an **error**. `LearnSchema::without_heads`
+  ignores unknown names by design, so an unvalidated typo would train the full
+  schema while the log claimed the head was dropped - indistinguishable from a
+  run that did what was asked. The removal is also recorded in the model
+  header's `provenance` line, not only implied by the absent `head =` entry.
+
+### Changed
+
+- **The NN-xTB out-of-domain guard no longer substitutes plain GFN2 on head
+  saturation.** `NnFallbackPolicy` gained a [`FallbackMode`]: `Invalid` (the new
+  default) substitutes only when the shifted parameters are UNUSABLE — a
+  physical floor rejects them (`zeta < 0.05`, `GAM`/`REPA`), or the overlay
+  breaks an SCC that plain GFN2 converges. `Extrapolation` restores the old
+  behaviour; `Off` is what training uses.
+
+  Saturation evidence is still produced, on the new
+  `NnEvaluation::extrapolation_warning`, so the guard trades a wrong
+  substitution for a report rather than for silence.
+
+  **Why.** The old trigger conflated two different things. A saturated head
+  gives a shift that is TRUNCATED but still correctly directed, which beats
+  `Delta-p = 0`; genuine out-of-domain input gives a shift whose DIRECTION is
+  arbitrary. Measured on the v0.6.0 training checkpoint, acting on saturation
+  lost on four of seven benchmark families and won on one, and cost 44.640
+  against 7.608 kcal/mol over all 2226 reactions. The structures it rejected
+  were ordinary in-training-set ones (`force_ethanol_rmd17_*`, `sconf_*`).
+
+- **A reaction energy is now computed with ONE treatment for all its species.**
+  The guard is a per-STRUCTURE decision while a reaction energy is a DIFFERENCE
+  of structures, so rejecting some species and not others differenced a
+  corrected energy against an uncorrected one — producing errors larger than
+  either method alone (S66 1.369 -> 43.998 kcal/mol, against plain GFN2's own
+  0.734 on the same 62 reactions, with a 1648 kcal/mol outlier neither method
+  can produce). `nn_eval` now reports the whole reaction from the baseline if
+  the guard rejected any species.
+
+- `--nn-fallback` accepts `off | on | invalid | extrapolation` (`on` is
+  `invalid`). New `--nn-element-coverage on|off`.
+
+### Added
+
+- **`nn_train --energy-normalization none|wtmad2`.** `wtmad2` scales each
+  reaction-energy RESIDUAL by `mean|E_ref| over all reactions / mean|E_ref| over
+  its subset` — the GMTKN55 WTMAD-2 weighting, and the metric the NN-xTB paper
+  reports its GMTKN55 result in.
+
+  Without it the 52 subsets enter a SQUARED kcal/mol loss with mean reference
+  energies from 0.580 (RG18) to 568.7 (W4-17), a factor of 980, so the
+  atomization sets take the gradient budget and a sub-kcal error on a weakly
+  bound complex is invisible. That is measurable in the trained model: against
+  plain GFN2 it wins on every subset whose own error is large (W4-17 190.3 ->
+  43.6, W4-11 120.7 -> 37.6) and loses on every subset whose error is small
+  (RG18 0.112 -> 0.398, ACONF 0.194 -> 1.677, S66x8 0.591 -> 1.174), crossing
+  over at a plain-GFN2 MAE of 2-3 kcal/mol.
+
+  The scale multiplies the residual, not the loss, so the Huber knee sits at the
+  same RELATIVE error for every subset. Reported holdout MAE stays in kcal/mol
+  — the option changes what the loss weighs, never what the metric measures.
+  Default `none`, which is what every run up to v0.6.0 used.
+
+- **`train_elements` in the `.gfn2nn` header**, and
+  `NnCalculator::train_elements`. The trainer records the atomic numbers of its
+  TRAIN split (not the whole dataset: a held-out structure contributed no
+  gradient), and an evaluation falls back when asked about an element the model
+  never saw. The key is optional on read, so no `FORMAT_VERSION` bump — an older
+  build skips it into `unknown_keys`. A model that does not record it cannot be
+  checked and is skipped rather than passed.
+
+- **`rmd17_conformers.gfn2ds`** (515 reactions) and
+  `scripts/rmd17_relative_energies.py` that generates it. `forces*.gfn2ds`
+  carries 2150 structures that fed ONLY the force loss; for frames of the same
+  molecule the reference energy DIFFERENCE is a pure conformational energy, and
+  the format already expresses one — as a `$reaction`. No new geometry: the 516
+  ethanol frames were matched to `rmd17_ethanol.npz` on coordinates (516/516, a
+  worst deviation of exactly 0.0) and paired consecutively. Same PBE/def2-SVP
+  level as the forces already in those records.
+
+- **Published packages no longer carry the NN-xTB training dataset.**
+  `Cargo.toml` gained an `exclude` (mirrored in `pyproject.toml`) covering
+  the training-records directory and `tests/**`. The dataset is 11 MB and is read at run
+  time by path rather than compiled in, so excluding it costs the published
+  crate no functionality. It stays in the repository, where the trainer
+  and the dataset tests use it. `cargo package --list` now ships two `data/`
+  files, both `include_str!`-compiled and both explicitly GPL-compatible.
+- `src/nn/dataset.rs`: the four tests that load the bundled dataset now print
+  `SKIPPED` with a reason and return when no corpus is available, instead
+  of panicking. They run in full in the repository, so the release gate is
+  unaffected; this only matters when running `cargo test` from a published sdist.
+- `THIRD_PARTY_NOTICES.md` gained a preamble stating that **bundled third-party
+  data keeps its own licence and is not covered by this project's GPL grant**,
+  with a per-artefact table naming which rows are and are not. GPL-3.0 § 5
+  requires the covered work to be licensed as a whole under the GPL, so shipping
+  non-relicensable material inside it without saying so would purport to grant
+  rights nobody here holds. The project's own `docs/lnxtb_licensing.md` § 4 had
+  identified this; the notices had not yet followed.
+
+### Performance
+
+- **The encoder second-order pass is now parallel over its `3N` direction
+  columns** (`nn::hessian_analytic::encoder_jacobian_and_curvature`). On a
+  profiled epoch this one scope was **81% of `nn::analytic_hessian`** and the
+  largest single scope in the trainer, at up to 23.7 s in ONE call — and it was
+  a plain serial loop, in a file that contained no `rayon` at all.
+
+  Measured on an identical workload (same 24 items, same seed, same weights,
+  `RAYON_NUM_THREADS=3`):
+
+  | scope | before | after |
+  |---|---|---|
+  | `nn::encoder_second_order` | 49,121 ms | **29,075 ms** (−41%) |
+  | `nn::analytic_hessian` | 60,402 ms | **40,054 ms** (−34%) |
+  | largest single call | 23,661 ms | **14,147 ms** (−40%) |
+
+  The unchanged scopes in the same runs moved by −11% to +18% (`nn::evaluate`,
+  `nn::frozen_head_gradients`, `nn::train_compute_structure`,
+  `nn::force_adjoint_param_grads`), which is the load noise of measuring on a
+  machine that is also training; −41% sits outside that band.
+
+  This matters more than the percentage suggests. The trainer parallelizes over
+  ITEMS and an epoch ends when its LAST item does, so a lone slow frequency
+  structure leaves the machine idling on one thread while it finishes — the
+  epoch's wall time is bounded below by exactly this loop, and the measurement
+  above was taken with only 3 threads to spread it over.
+
+  **Bit-identical, by construction.** Every column reads only shared immutable
+  state (the tape, the encoder graph, the constant adjoint seeds) and produces
+  only its own Jacobian column and its own column of the curvature; `Tape` is a
+  plain `Vec<Node>` with no interior mutability and all three of its traversals
+  take `&self`; neither `nn::tape` nor `nn::mace` uses rayon, so no inner
+  reduction order can shift. Columns are collected in index order and no sum is
+  reassociated.
+
+- **Two performance hypotheses were measured and REFUTED**, recorded here
+  because both are the obvious thing to try again:
+
+  1. *"Frequency items are slow because they fall back to the semi-numerical
+     Hessian; the analytic route is the fast one."* On 15 real structures across
+     four size bands (6, 10, 15 and 20 atoms) the two routes are within noise of
+     each other — speedups 0.7×–1.7×, **mean 1.13×, with no size trend**. The
+     analytic route buys about 10%, not the `6N`-versus-`O(1)` win the shape of
+     the two algorithms suggests, because it pays `3N` parameter-direction
+     responses of its own. The six largest frequency structures were also all
+     closed-shell and all already on the analytic route, so the smeared/
+     open-shell work did not move this population at all.
+  2. *"Force items are slow because the double FD pays `6N` displaced SCCs."*
+     It does not: the force loss differentiates along ONE direction `w`, so the
+     double FD is **two** displaced evaluations regardless of `N`. Measured
+     through the production `run_item` path, the analytic adjoint is **9×
+     slower** at 27 atoms (49.4 s vs 5.3 s) and 3.4× slower at 9 atoms — and it
+     gets worse with size. `FORCE_ANALYTIC_STATE`'s cached decision to keep the
+     double FD is correct, and increasingly correct as structures grow.
+
+  Both censuses are kept as ignored tests, so the numbers can be re-taken rather
+  than re-argued: `tests/nn_freq_route_cost.rs` and
+  `nn::train::tests::force_route_cost_census`.
+
+- **`global.kdiff` is a dead head: it costs 25,217 learnable scalars (2.5% of
+  the model) to produce a provably-zero output.** Recommend adding it to
+  `--drop-heads` on the next training run; the accuracy cost is exactly zero.
+
+  `kdiff` is the paper's `k_pol`, read ONLY by the non-valence arms of
+  `scc_common::h0_scaling`. `basis.rs` sets `is_valence = !seen_l[l]`, so a
+  shell is non-valence only when its atom carries an earlier shell of the same
+  angular momentum — and **no GFN2 element does**, verified across all 86 in the
+  bundled parameters. Those arms are dead code for every system, `dE/d kdiff` is
+  identically zero, and the head's zero-initialized final layer can never move.
+
+  Three independent measurements agree, on the 32-epoch checkpoint of the live
+  run: the head's output is exactly `0.000000` over 400 sampled structures; its
+  `w3` and `b3` are the only bit-zero final layer among 35 heads (every other
+  head's `w3` reached `7.2e-2`–`4.3e-1`); and the structural argument above.
+  `nn::param_grad`'s `d_shell_global_gradients_match_full_scf_fd` already stated
+  this in a comment — nothing checked it, so the premise is now pinned by
+  `every_gfn2_element_has_distinct_shell_momenta`, which fails loudly if a
+  parameter set ever makes `kdiff` live.
+
+- New diagnostics for the trainer's head stack, both ignored, both reading a
+  checkpoint without disturbing a running trainer: `nn_head_saturation_census`
+  resolves the epoch line's single `sat` number to a per-head maximum with the
+  element and structure that reach it, and `nn_head_final_layer_census` reports
+  which heads never left their zero init. The `sat` monitor is the right alarm
+  and the wrong diagnosis — it says a head is pressing its clamp without saying
+  which, so the only responses available were guesswork or nothing.
+
+- **The shift bound uses ONE global RMS scale per head, which is wrong for any
+  parameter whose per-element values span orders of magnitude.** `Δp_a =
+  B(x_a) × scale`, with `B` clamped to `[−0.5, 0.5]` and `scale` the RMS of
+  that parameter over all 86 elements (`LearnSchema::denorm_scales`). Measured
+  as `0.5 × RMS` against the smallest non-zero baseline: **DPOL 128.9× (Rh),
+  QPOL 96.0× (Pb), GAM3 43.1× (La), REPB 20.4× (He)** — four of six atom-wise
+  families. `GAM` (1.6×) and `REPA` (1.2×) are fine.
+
+  For the common organic elements the DPOL bound permits ±0.11× of baseline on
+  F, ±0.16× on H, ±0.18× on O — but **±2.20× on carbon**, whose baseline
+  (−0.4117) is an order below the RMS. Carbon is also the most abundant
+  training element and dominates the force loss, so the head with the most data
+  and the loosest effective bound is the one that saturated. The `gam3` clamp
+  saturation seen earlier in v0.6.0 training has the same root cause.
+
+  **The obvious fix makes it worse.** Scaling by each element's own `|p0|`
+  tightens carbon's bound 4.4× (0.9047 → 0.2059) against a network that wants
+  `|Δp| ≈ 0.896`, so it pins the head harder. It corrects the physical size of
+  the shift and does nothing for the saturation, because `NnFallbackPolicy`
+  keys on head-output saturation, not on the parameter. The two are separate
+  defects and were conflated once here before being measured.
+
+- `nn_eval` gained **`--nn-fallback on|off`** (default `on`), matching
+  `gfn2_rs --nn-fallback`. `nn_train` evaluates with the policy DISABLED, so
+  for a saturated model the training log's holdout MAE and `nn_eval`'s were
+  different quantities with no way to compute one from the other. Verified on
+  the same 223 held-out reactions: `off` reproduces the training log exactly
+  (**9.053 kcal/mol**, plain GFN2 20.081), `on` gives **48.543** because 990 of
+  6391 structures fall back to plain GFN2 and a reaction then differences a
+  corrected energy against an uncorrected one. The gap is the saturation
+  damage, and the rejected structures are ordinary in-training-set ones
+  (`force_ethanol_rmd17_*`, `sconf_*`) — the guard is misfiring, not catching
+  unseen chemistry.
+
+## [0.5.0] - released
+
+Two documents accompanied this entry when v0.5.0 shipped: a feature-by-feature
+walkthrough, and engineering notes keeping the full development record — the
+per-defect forensics, the evidence chains and every measured residual — that
+this summary condenses. Both were retired from `docs/` in v0.6.1 to cut a
+documentation set that had grown to 17 files; this entry is what remains of
+them. The one part not derivable from the code — where the NN-xTB
+implementation deliberately departs from the paper it is based on — was carried
+forward and is in `docs/nn-xtb.md`.
+
+### Highlights
+
+- The **analytic Hessian is exact and is now the default**, for closed-shell,
+  open-shell and spin-polarized references alike; five independent defects that
+  had been masking each other were root-caused and fixed.
+- **Every production finite difference is gone** from the energy/gradient/Hessian
+  path: AES and D4 potential derivatives, the NN-xTB parameter gradients
+  (including the basis-moving Slater exponents) and all 22 learnable globals now
+  have closed forms.
+- **TD-GFN2 excited-state gradients are exact** on the Gamma, k-point and
+  open-shell paths, AES included — the k-point path was ~7.5e-2 Eh/bohr wrong
+  and hidden behind a 1e-1 test tolerance.
+- **NN-xTB is end to end**: periodic evaluation and forces, excited-state
+  gradients, a frequency (Hessian) loss, an out-of-domain fallback, parameter
+  distillation, and a training set grown from 46 to 264 reactions plus 96
+  structures carrying real reference forces.
+- **Divide-and-conquer SCC** gained analytic gradients (molecular,
+  Gamma-periodic and k-point meshes — the Bloch driver runs a per-k DC step
+  with one global Fermi level), the fixed-partition analytic stress (Gamma and
+  k-point; the frozen-partition strain FD matches to ~1.4e-9 Eh/Bohr³) and a
+  CLI/Python surface — with a measured, honest verdict on what it does and does
+  not make linear.
+- **Analytic third derivatives** (molecular only, by design) are complete for
+  molecular systems: classical, fixed-density electronic, the full 2n+1 CPHF
+  response cross terms, the D4 charge response and the AES block (frozen and
+  response) — water 8.681e-10 / water dimer 3.334e-9 Eh/bohr^3 against the
+  five-point FD of the relaxed analytic Hessian. Retrievable as `dense`,
+  `block` or `vec` from Rust, `cubic_check` and Python. The D4 **three-body
+  (ATM) charge response** landed too, so nothing in the module is staged and
+  `include_d4` no longer contracts for `enable_d4_atm = false`.
+
+### Method and correctness
+
+- **SCC convergence.** New default accelerator: Fock-space ADIIS -> CDIIS
+  (`--scf-accel`, `scf_accelerator=`), same fixed points as the legacy
+  charge-space path (1e-15..1e-13 Eh) in roughly half the iterations (water
+  dimer 29 -> 12, ferrocene 32 -> 15, PrF3 300 -> 64), with a divergence guard
+  that hands pathological cases back to the legacy path. Gamma and Bloch;
+  spin-polarized and LC keep the legacy accelerators.
+- **Parameters.** `param_gfn2-xtb.txt` is bundled and used by default
+  (resolution order `--param` > `GFN2_XTB_PARAM` > bundled). The experimental
+  **Ln-xTB** lanthanide overlay (`--ln-xtb`) reproduces the reference total
+  energies to 1e-7..1e-9 Eh across the series; Pr/Sm halides have a documented
+  parameter-side instability. `docs/lnxtb_licensing.md` records the licensing
+  assessment for the bundled SI-derived data.
+- **xtb oracle validation.** 18 geometries and 170 reference values transcribed
+  from the xtb unit tests; water energy components agree to 1e-11..1e-13 Eh and
+  the analytic gradient is FD-exact to 2.9e-10 Eh/bohr.
+- **Analytic Hessian.** `HessianMode::{Analytic, SemiNumerical, FiniteDifference}`
+  with `Analytic` the default and `HessianResult::mode_used` reporting what
+  actually ran (also exposed to Python/ASE). All terms on, against the central
+  FD of the analytic gradient: water 5.9e-8, CO2 3.7e-7, NH3 6.7e-8, H2 Gamma
+  cell 7.6e-9, H2 k-grid [2,1,1] 7.6e-9 Eh/bohr^2. Open-shell UHF 6.6e-8 and
+  spin-polarized 6.5e-8 via a new coupled two-channel spin CPHF.
+- **Spin derivatives completed.** The spin-polarized gradient was missing the
+  Mulliken-Pulay overlap chain of `E_spin = 1/2 m^T W m` (1.8e-4 -> 1.2e-9
+  Eh/bohr), and spin-polarized **stress** now works (its virial agrees with the
+  frozen-density strain FD to ~9 significant digits).
+- **TD-GFN2 excited-state gradients.** Gamma with full AES (~1e-9 vs energy FD);
+  k-point rebuilt on the direct method (singlet 3.3e-8, triplet with AES
+  3.8e-8, replacing a ~7.5e-2 error); open-shell rebuilt likewise (1.5e-11
+  without AES, 1.2e-11 with).
+- **Analytic third derivatives** (`compute_third_derivatives`, `cubic_check`),
+  **molecular only by design**: classical repulsion 4.9e-12 and D4 pair+ATM
+  ~3e-15, electronic fixed-density H2 4.5e-13 / water 2.1e-13, against the
+  five-point FD of the analytic Hessian. The **2n+1 CPHF response cross
+  terms** are implemented for SCC-only references (IES gamma +
+  third/fourth-order onsite + H0 CN chains; `include_response`): the full
+  relaxed `E^xyz` matches the five-point FD of the relaxed analytic Hessian
+  at the FD floor — H2 3.3e-11, water 1.8e-11 Eh/bohr^3 — with every CPHF
+  convention pinned by four dedicated response tests
+  (`third_derivatives::cphf3`). The **D4 charge-response cross terms** are
+  implemented too (`include_d4`), on new third-order D4 charge machinery
+  (`d3zeta`, mixed q/CN reference weights): water reaches 1.2e-10 against the
+  D4-relaxed Hessian FD with the two-body pair term. The **frozen-multipole AES
+  block** (`include_aes`, `third_derivatives::aes3`) is the exact third
+  derivative of the energy `aes_frozen_multipole_hessian` is the second
+  derivative of — damped multipole kernels plus the logistic damping-radius
+  CN chain in a `Local3<5>` jet, composed by the general multivariate chain
+  formula — and matches that Hessian's five-point FD at the rounding floor
+  (water 4.7e-13, water dimer 7.2e-13 Eh/bohr^3). The **AES moment-RESPONSE
+  cross terms** (`third_derivatives::aes_response3`: CAMM Pulay folds of the
+  second and third moment-integral derivatives, the AES kernel against one and
+  two multipole responses, the second density variation against the AES
+  response Fock, and the onsite-polarization channel) complete the relaxed
+  tensor. With everything on, the analytic `E^xyz` matches the five-point FD of
+  the relaxed analytic Hessian at **water 8.681e-10** and **water dimer
+  3.334e-9** Eh/bohr^3 (gate 1e-6). The **DFT-D4 three-body (ATM) charge
+  response** completes the module: the ATM energy is `W(geometry) x C9` with
+  `C9 = sqrt(C6_ij C6_ik C6_jk)` the only charge-dependent factor, so its
+  whole charge response is a third-order jet of `C9` in the six variables
+  `(q_i, q_j, q_k, covCN_i, covCN_j, covCN_k)` (built from the log
+  derivatives of the three pair `C6`s) contracted with the geometric factor
+  and its first two Cartesian derivatives — the `V^{yz}` / `K^x` / `K'`
+  classes the pair term already had, deposited through per-atom accumulators
+  so the per-triple work stays O(1) in the atom count. `include_d4` therefore
+  no longer contracts for `enable_d4_atm = false`, and with the three-body
+  term on the tensor reaches **water 1.789e-11** and **water dimer 9.844e-9**
+  Eh/bohr^3 against the D4-relaxed Hessian FD. Because the GFN2 damping makes
+  the three-body term small, the acceptance is backed by two sensitivity
+  guards: the `C9` jet against its own step-halved finite differences, and
+  the full dimer comparison rerun with `s9` scaled by 1e4 — four decades of
+  amplification of the three-body classes alone, which leaves the residual at
+  the FD floor (9.728e-10).
+- **Third-derivative output forms** (`ThirdDerivativeRequest`): the tensor can
+  now be retrieved as `dense`, `block` or `vec`, all three accumulating into the
+  *same* sink so they agree to round-off where they overlap
+  (`dense[a][b][c] == block(c)[(a,b)] == vec(e_c)[(a,b)]`, pinned by
+  `third_derivatives::tests`; the block/vec pair is bit-identical).
+  `ThirdDerivativeResult::dense_tensor()` materializes the plain row-major
+  `3N x 3N x 3N` buffer so callers never hand-compute `third_index`;
+  `ThirdDerivativeRequest::block(coords)` returns the symmetric `3N x 3N` slices
+  `M^(c)_ab = E_abc` a cubic-force-field / anharmonic consumer wants, without
+  ever materializing `3N^3`; `vec` (the `ModeContractions` variant, now also
+  reachable as `ThirdDerivativeRequest::vec`) stays the primary large-system
+  API. Only `dense` is capped (`3N <= 150`) and its error now quotes the actual
+  byte cost of both stores. The molecular-only, closed-shell and
+  integer-occupation guards are identical for every form. Wired through
+  `compute_third_derivatives`, `cubic_check` (`--form dense|block|vec`,
+  `--block-coords`, `--vectors FILE`, `--compare-forms`, `--no-fd`, and `--out`
+  now writes the selected form) and the new Python
+  `Gfn2NativeCalculator.third_derivatives(...)` / `ThirdDerivativeResult`.
+- **Fully-analytic NN-xTB Hessian** (`nn::hessian_analytic`, molecular): the
+  complete Eq. 25 assembly with no finite differences — fixed-parameter CPHF
+  Hessian, the encoder Jacobian and its forward-over-reverse curvature term,
+  and the SCC mixed / parameter-parameter blocks. The `n_theta` CPHF solves
+  the parameter-parameter block would need collapse to **3N** by solving one
+  parameter-direction response per Cartesian direction
+  (`cphf::solve_gamma_parameter_cphf_response`, which shares the geometric
+  solver's operator and differs only in its right-hand side). Head families
+  land one at a time behind an explicit guard — a schema containing an
+  unimplemented head is REJECTED, never silently approximated. Covered so
+  far: repulsion (`repa`, `repb`, `kexp`), the whole H0 band set (`lev`,
+  `kcn`, `poly`, `en`, `enscale`, the six Wolfsberg scalings), the whole
+  charge-kernel set (`gam`, `lpar`, `gam3`, `third`, the four `gam3*`
+  globals, `alphaj`) and the DFT-D4 globals (`a1`, `a2`, `s8`, `s9`). Every
+  family is accepted against the Richardson extrapolation of the
+  semi-numerical reference at two step sizes, with a measured sensitivity
+  guard proving the correction blocks are large enough for the test to mean
+  anything; all sit at the reference's ~2-4e-9 floor.
+- **Divide-and-conquer SCC** (experimental): energy path plus analytic
+  gradients for molecular AND Gamma-periodic references (single subsystem
+  matches the exact gradient to ~1e-16; saturated buffers reach the ~1e-9 FD
+  floor; the truncated-buffer partition-boundary residual is quantified rather
+  than hidden). k-point and stress are explicit errors.
+- **Physics validation suite** (`tests/physics.rs`): translation/rotation
+  invariance, gradient and Hessian sum rules, k-grid <-> supercell consistency,
+  size consistency, charge conservation and spin electron counts, each asserting
+  a stated tolerance and printing its measured residual.
+
+### NN-xTB (experimental throughout)
+
+- **The analytic NN Hessian now covers the shipped schema head for head.**
+  `atom.rcov` was the last gap, and it is the only head that reaches the energy
+  through an INTERMEDIATE variable rather than through a factor of some term:
+  it is the CN counting radius, so it moves the coordination number, and the
+  coordination number has exactly two consumers - the H0 onsite level
+  `h = hdiag - 0.1 kcn CN eV` and the AES damping radius `R(CN)`. (The D4 covCN
+  is not one of them; it keeps its own frozen radii by design.)
+
+  Routing it as an EFFECTIVE CN TANGENT is what made the families tractable.
+  The band family adds it to the per-shell onsite tangent it already builds for
+  `lev` and `kcn`; the AES family carries it as a sixth radius axis, which its
+  `RadiusJet` was already able to serve because `arg = CN - vcn - shift` makes
+  `d/dCN == -d/dvcn` an identity to all orders. Everything CN-mediated then
+  falls out of machinery that was already there and already tested, and only
+  the two terms that differentiate `CN` ITSELF are folded separately against
+  the CN adjoint: `d2CN/dR drcov` in the mixed block and `d2CN/drcov2` in the
+  theta-theta block. One structural consequence: `h` is bilinear in the pair
+  `(kcn, CN)`, so putting a parameter inside `CN` gives the band family's level
+  factor a frozen second-parameter derivative it never had - a `kcn x rcov`
+  corner that is identically zero unless both heads are in the schema.
+
+  Verified against two INDEPENDENT references, because one convention can look
+  right on its own: a Richardson-extrapolated finite difference of the exact NN
+  gradient (the true PES) reaches 1.5e-11 for `rcov` alone, 1.5e-11 with
+  `shell.kcn`, 1.8e-11 with the AES radius heads - against correction blocks of
+  1e-4, so seven orders of relative accuracy; and a double finite difference of
+  the head gradients through the force adjoint, which shares every family
+  block, reaches 1.0e-10 and 1.1e-10 relative. The AES family's block-level
+  test gained a fifth per-atom slot for it and holds at 5e-10 relative.
+
+  Consequences elsewhere: `tests/physics.rs` no longer has to drop `atom.rcov`
+  from the Hessian fixtures, and the force adjoint covers the whole schema too
+  (it shares `IMPLEMENTED_HEADS` precisely so a head cannot be covered by one
+  assembly and not the other). Molecular references only, the same carve-out
+  the AES and Slater-exponent families make - a periodic self-image pair has
+  `rc = 2 rcov` and its radius chain doubles, which is refused rather than
+  guessed.
+
+- **Model and derivatives.** Periodic evaluation and **periodic forces**
+  (1.9e-9 Eh/bohr vs the FD of the NN energy); excited-state gradients
+  (`NnCalculator::tda_gradient`, 1.1e-8); encoder Hessian-vector products and
+  the semi-numerical NN Hessian; the learnable set extended with `atom.en` and
+  `shell.third`; analytic `dE/dp` for every class including the basis-moving
+  Slater exponents and all 22 globals.
+- **Training.** The frequency (Hessian) loss completes the paper's Eq. 26 (its
+  mode-projected adjoint matches a per-parameter FD to a relative 8e-5);
+  `--init-model` warm starts, `--select-by holdout` stops shipping past the
+  generalization optimum, and an SCC convergence ladder plus a saturation guard
+  keep long runs alive.
+- **Training robustness** (each item measured against a real failure before it
+  was built): the frequency loss now uses the **fully-analytic NN Hessian**
+  behind a self-verifying switch — the first in-domain frequency item of a run
+  computes both routes and compares (closed-shell probe first; 108 of the 720
+  frequency structures are open shell and fall back PER STRUCTURE, not per
+  run); **Huber loss** (`--huber-delta`, default 10 in sqrt-normalized-loss
+  units) bounds one sample's gradient influence without a cliff, replacing the
+  hard per-item cap that false-positived on a legitimate hard sample at 1.86e2
+  (`--max-sample-loss` remains, disabled, as a loud diagnostic; non-finite item
+  losses are always dropped); the physical parameter floors (Slater, GAM, REPA)
+  are now **clamps** mirroring the head outputs' own `ClampSte` bound — counted
+  and announced via `overlay_clamp_events()`, never silent — instead of hard
+  errors that killed a whole structure over one shell; a structure whose SCC
+  ladder fails **3 consecutive epochs is quarantined** for the rest of the run
+  by name (one diverging reference had cost 304 s per epoch, every epoch);
+  `--max-items` draws a deterministic stratified subsample (~3:3:1 ratio,
+  element coverage first) for bounded runs; and the epoch line reports
+  `SKIPPED` / `OUTLIER` / `QUARANTINED` / `PCLAMP` counters so a run that is
+  quietly training on less than it thinks is visible at a glance.
+- **Dataset.** 106 structures / 46 reactions -> 555 / 264 -> **6391 / 2227**
+  (the bulk expansion to the mandated >= 5000 items at
+  energy : force : frequency ~ 3 : 3 : 1): 47 further GMTKN55 subsets, the
+  S66x8/S22x5/NBC10/HBC6 dissociation curves, the W4-17 extension, the
+  remaining MOR41 reactions, the BOTNet force families grown to **2150
+  structures with reference force vectors**, and **720 harmonic-frequency
+  structures** (292 CCSD(T)/cc-pVTZ + 412 B3LYP/6-31G* CCCBDB cohorts with
+  same-level geometries + the 16 legacy records). Every record carries
+  provenance; every reaction re-balances through the loader; all counts are
+  pinned by tests. Trainer support for the scale: `--batch-size` concurrent
+  batching and `--freq-per-epoch` deterministic frequency-item rotation.
+- **Deployment.** An out-of-domain **fallback** rejects the learned correction
+  and runs plain GFN2 (`--nn-fallback`), and **parameter distillation**
+  (`nn_eval --distill-params`) projects a trained model onto a static GFN2
+  parameter file — recovering 40-57% of the reaction-energy gain but degrading
+  forces below stock GFN2, which is reported rather than smoothed over.
+
+### Interfaces, packaging and build
+
+- **NN-xTB reaches ASE.** `GFN2RSCalculator(nn_weights="model.gfn2nn")` puts
+  the learned surface behind the ordinary ASE properties, so an optimizer or an
+  MD run needs no other change; the forces are exact for that surface (the
+  correction's own geometry dependence is differentiated, not frozen), so a
+  relaxation converges to a real stationary point of it. `nn_fallback` arms the
+  out-of-domain guard and its verdict is reported in `results` alongside the
+  plain-GFN2 baseline energy and the head saturation.
+
+  What it does NOT cover, it now refuses. `get_tda`, `get_td_gradient`,
+  `get_hessian` and `export_molden` run through `Gfn2NativeCalculator`, which
+  never sees the overlay, so with `nn_weights` set they raise instead of
+  handing back GFN2 derivatives for an NN-xTB energy - a mismatch between an
+  energy surface and its derivatives is far harder to notice than an error.
+  Periodic input, stress, and `spin_polarized`/`dc`/`experimental_corrections`
+  raise for the same reason. `tests/test_python_api.py` pins both halves: that
+  every guard fires before the weight file is even opened, and that a
+  calculator without `nn_weights` is completely unaffected.
+
+- **Freely specifiable NN-xTB training data**: `--dataset` (both `nn_train` and
+  `nn_eval`) is now **repeatable** and accepts a `.gfn2ds` file or a directory
+  of them in any mix, all loading into one dataset with one structure-name
+  namespace (`Dataset::load_paths`; `Dataset::load_dir` unchanged).
+- **Deterministic batched NN-xTB training** (`--batch-size`,
+  `TrainConfig::batch_size`): the items of a batch are evaluated concurrently
+  and their MEAN gradient taken as one optimizer step, with results reduced in
+  item order — bit-reproducible for any batch size, and `1` (the default)
+  reproduces the historical per-item stepping exactly. The read-only passes
+  (pre-normalization, holdout metrics) are parallelized the same way. Measured
+  on the bundled S66 subset (tiny preset, 2 epochs end to end): 92.7 s at
+  batch 1 vs 30.3 s at batch 8. This is the throughput path toward the
+  100k-item training target.
+- **Training learning-rate floor**: `min_lr` now defaults to `1e-5` and floors
+  EVERY reduction (plateau scheduler and saturation backoffs — the plateau
+  path previously ignored it); the per-item saturation backoff is rate-limited
+  by the same cooldown as the epoch-end guard. Together these close the
+  failure mode where one hard-saturating structure halved the learning rate
+  every epoch until the run could no longer move (measured collapse to 1e-9).
+- CLI/Python/ASE wiring for the SCF accelerator, Hessian mode, Ln-xTB, DC,
+  k-point TRS folding, Molden export and the NN paths; three console scripts
+  (`gfn2-rs`, `gfn2-nn-train`, `gfn2-nn-eval`); ASE energy semantics unified on
+  the Mermin energy GFN2-xTB actually reports.
+- Wavefunction export in Molden format (verified by reconstructing the overlap
+  matrix from the written file alone to 2e-13).
+
+### Fixed
+
+- **Two eV -> Hartree constants** were in use: the SCF converted the CN
+  self-energy shift with the CODATA value while every derivative path used the
+  legacy xtb constant GFN2 was parametrized against, so the derivatives were
+  differentiating a slightly different H0 than the SCF built.
+- **Radii-table unit conversion** used CODATA where xtb uses the legacy Bohr
+  radius (~1e-7 offset in coordination numbers and the CN-dependent H0).
+- **Five analytic-Hessian defects** that partially cancelled: a missing CN chain
+  rule in the CPHF right-hand side, a half-weight mixed CN cross term, an
+  inverted AES charge-quadrupole sign, a wrongly-dropped frozen-multipole AES
+  block, and a spurious factor of 2 in the Bloch CN response fold.
+- **The CN cross term was screened on the wrong quantity.** An `|S| <= 1e-18`
+  gate also discarded a term proportional to the overlap GRADIENT, which is
+  ordinary for an s-p pair whose overlap vanishes by symmetry: 3.3e-6 Eh/bohr^2
+  on a water dimer, now 1.19e-8 (the FD floor).
+- **The learnable radii were read from the frozen tables in six derivative
+  walks.** A per-atom radius reaches the physics only through the
+  `Gfn2Parameters` accessors (`poly_radius_for_atom`, `cn_radius_for_atom`,
+  ...); six places called `data_tables::atomic_radius_bohr` /
+  `covalent_radius_d3_bohr` directly instead, so with a non-zero radius shift
+  they differentiated a slightly different H0 than the energy built. The
+  visible symptom was in the ANALYTIC `dE/dp` of eight *other* head classes:
+  the frozen-orbital head gradients disagreed with the fully re-converged SCF
+  finite difference by 0.01-1% for `atom.en`, `shell.lev`, `shell.kcn`,
+  `shell.poly`, `shell.exp`, `global.ks`, `global.kp` and `global.enscale`,
+  while the radius heads themselves looked correct (they take the frozen-FD
+  route, which recomputes everything consistently). Fixed in
+  `nn::param_grad`, `native_gradient::shell_poly_factor_derivative`,
+  `nn::hessian_analytic`, `nn::hessian_exp_family`,
+  `third_derivatives::response3` and `third_derivatives::h0_pref3` (new
+  `cn_third_derivatives_with_radii`); the DFT-D4 covalent CN keeps its own
+  frozen table by design. All 41 variational probes now agree.
+  The force loss reaches the four radius heads only through the double finite
+  difference (the analytic force adjoint's documented coverage gap), and that
+  composition had no test at all - it now has one.
+- **The r^-3 Klopman-Ohno Ewald tail** gained its regularized `G = 0` term; that
+  kernel is now independent of the Ewald splitting parameter (see Known issues
+  for what remains).
+- **The reciprocal-space AES charge-quadrupole potential missed the
+  Poisson-summation sign.** The Ewald AES energy stores
+  `AES_RECIP_QTHETA_SIGN * AES_QTHETA_COEFF = -1/3` in its structure factor,
+  but the conjugate quadrupole potential block still used `+1/3`, making the
+  reciprocal quadrupole potential the negative of the variational derivative
+  of the energy (~1e-4 on periodic water; it also broke the Hellmann-Feynman
+  property the divide-and-conquer periodic gradients rely on). The analytic
+  potential-derivative mirror now reads the production constants directly so
+  the two can no longer drift apart.
+- **The streamed D4 ATM group builder duplicated groups across workers.** The
+  parallel three-body build splits the flattened (center, neighbor) work list
+  mid-center, and each worker emitted its own partial `(i, j, k)` groups; in a
+  small cell with many images the duplication scaled with the worker count and
+  broke the `<= nat^3` distinct-group bound the cache gate had been promised
+  (644 groups for a 6-atom cell). The join now merges partials by key.
+- **The training saturation guard could not do its job**: it answered a state
+  variable with a rate control and drove the learning rate to zero without
+  reducing saturation (measured: 0.912 pinned while the LR fell 1e-4 -> 6e-9).
+  It is now rate-limited and fires only while saturation is rising.
+- **The ASE calculator ignored the atoms it was attached to.** `atoms.calc =
+  GFN2RSCalculator(...)` followed by `get_tda`, `get_td_gradient`, `get_hessian`
+  or `export_molden` with no atoms argument — the form the docs show — raised
+  `RuntimeError: no ASE Atoms object supplied or attached` unless a single point
+  had happened to run first, because ASE attaches through a `set_atoms` hook the
+  base `Calculator` does not define. The attachment is now kept live and
+  separate from `self.atoms` (ASE's copy of the last calculated geometry), so a
+  geometry moved in place is picked up rather than silently reused.
+- Numerous smaller wiring fixes: ASE `scf_accelerator` forwarding, Python
+  `mode_used`, `nn_eval` SCF-convergence enforcement, DC front-end defaults.
+- **The open-shell analytic NN Hessian is now exact** instead of guarded off.
+  The Eq. 25 correction blocks' two response solves previously used the
+  closed-shell CPHF space, which silently dropped the (doubly -> singly
+  occupied) beta rotations — up to 25% of the correction on CH while H2O+ was
+  accidentally right. Both solves now run the coupled two-channel spin CPHF
+  (geometric totals plus the new relaxed spin parameter CPHF). Accepted at
+  2.0e-12 (CH2 triplet) / 6.3e-12 (H2O+) against the Richardson-extrapolated
+  semi-numerical reference, and the spin machinery pushed through a
+  closed-shell reference reproduces the closed-shell correction blocks to
+  9e-14. Fractional (smeared) channel occupations still error loudly and fall
+  back per structure in the trainer.
+
+### Performance
+
+
+- **Two scaling-order reductions in the Hessian assembly.** Both replace a
+  quantity recomputed inside a doubly-nested `ndim x ndim` loop with one
+  computed once, so the cost falls by a factor of the system size rather than
+  by a constant.
+  - `nn::hessian_analytic`: the frozen theta-theta block recomputed four
+    loop-invariant shell sums for every `(a, b)` pair. One of them, the
+    third-order `q^T G q` contraction, is a full `nshell^2` double sum with no
+    dependence on either loop index at all, which made an `O(N^2)` block cost
+    `O(N^4)`. All four are now hoisted; two become `nshell`-length vectors,
+    one an `ndim x nshell` table, one a scalar.
+  - `hessian::direct`: the k-point AES frozen block ran
+    `aes_multipole_cross_energy` - three Ewald sums - once per matrix element,
+    `3 ndim^2` Ewald evaluations in total. The AES energy is a quadratic form
+    in the moments and its potentials are that form applied to a moment set,
+    so `E(a+b) - E(a) - E(b) = a . (T b)`: the block now builds `ndim`
+    potential sets and contracts, `O(N^3)` instead of `O(N^4)`.
+  - The contraction has one trap worth recording, because the first two
+    attempts at it were wrong. `AesPotentials::finish` pushes the quadrupoles
+    through `gfn2_traceless`, so the potentials are `dE/dM_raw` - gradients in
+    the ten-component RAW AO moment basis - while callers hold projected CAMM
+    moments. Pairing them directly is off by the `3/2` that projection applies
+    on the quadrupole slots, and against the Ewald reference that reads as a
+    plausible "off by about two", which invites fitting a constant instead of
+    finding the basis mismatch. The fix contracts the traceless pre-image
+    `(2/3) theta` instead. `hessian::tests::aes_potential_contract` now pins
+    each premise separately - the energy is homogeneous of degree two and
+    satisfies Euler's theorem, the potential map is linear, every one of the
+    ten slots matches a finite difference of the energy with respect to the
+    raw component (this is the test that *names* the basis), and
+    `gfn2_traceless` is self-adjoint with `(2/3) theta` as its pre-image - so
+    a future change cannot re-introduce a convention error that only an
+    aggregate comparison would have to catch.
+- **Concurrent evaluation no longer spawns OS threads per structure, and no
+  longer nests its own parallelism.** The library parallelizes at two levels:
+  inside one calculation (AO pair blocks, Pulay walkers, CPHF columns, D4
+  triples) and — for callers with many independent calculations, above all the
+  NN trainer — across whole structures. Two defects made the second level
+  fight the first. `electronic::scc_common::precompute_ao_image_integral_pairs`
+  used `std::thread::scope`, spawning up to 16 fresh OS threads *per
+  structure* (the gate trips at 64 directed pairs, so at roughly eight atoms);
+  thread creation and teardown take process-wide locks in the OS, so
+  concurrent callers serialized on them, and four workers meant 64 threads
+  competing for 8 physical cores. All 25 such sites across the crate - the
+  integral pre-pass, both Pulay walkers, the Gamma and Bloch CPHF right-hand
+  sides and solves, the CPHF and finite-difference Hessian column loops, the
+  k-point SCF map, and the four D4 pair/ATM evaluators - now use rayon's
+  persistent pool through the shared `defaults::map_chunks` /
+  `map_index_chunks` helpers. The chunking is unchanged and rayon's `collect`
+  preserves input order, so the floating-point summation order - and every
+  result - is bit-identical; the index tags and sorts the scoped version
+  needed to restore order are simply gone.
+  Separately, `defaults::run_inner_sections_serially` makes an inner parallel
+  section run serially when the caller is already on a rayon worker: nesting
+  adds no parallelism, since both levels draw on one pool. A calculation
+  driven from the CLI or the Python bindings is not on a pool thread and keeps
+  the inner parallelism it always had. Measured on the trainer's
+  pre-normalization pass (full dataset, four threads): the frequency phase
+  fell from 869.5 s to 372.9 s. `native_gradient::PULAY_FORCE_SERIAL` was a
+  hand-rolled version of the same idea for one call site; it still applies and
+  is now the special case of a general rule.
+- **Process-global locks are out of the per-SCC-iteration path.** `std::env::var`
+  takes a process-wide lock (a critical section around the environment block
+  on Windows) and allocates; `fourth_order_coefficient` read `GFN2_FOURTH_ORDER_C`
+  on every call from the third-order energy and potential, and the AES
+  component masks and D4 thread controls did likewise. The D4 pair/ATM
+  geometry memos and the C6 pair tables were `Mutex<HashMap>`s consulted per
+  structure — and with a shared eight-entry cap, concurrent workers holding
+  different structures evicted each other's entries and then paid the lock to
+  rebuild them. All are now read once per thread (`defaults::cached_env`,
+  thread-local memos in front of the shared C6 table), and
+  `available_parallelism` — a syscall — is cached rather than called per
+  calculation. The lattice image-offset and reciprocal-vector lists got the
+  same treatment.
+- **The trainer's SCC-iteration cost was dominated by measurement distortion
+  and lock convoys, both gone.** `profile::event` printed a line per call from
+  inside the per-iteration D4 scope, serializing every rayon worker on the
+  stderr lock and billing the wait to the enclosing scope (the "98.6% of SCC
+  is D4" reading); events now aggregate into the profile report. The real
+  per-iteration waste — covCN re-derivation, two geometry-cache mutexes and
+  nat(nat+1)/2 C6-table mutex acquisitions per iteration, plus per-call OS
+  thread spawns in the pair/ATM evaluators — is hoisted into a per-structure
+  `D4ScfContext` built once before each SCC loop (Gamma, spin-polarized and
+  k-point paths), bit-identically. Measured on the profiled trainer slice:
+  the SCC iteration mean fell 93.1 -> 32.7 ms and the D4 share 91.7 -> 2.2 ms.
+- **The NN gradient no longer re-runs the SCC.** The evaluation's converged
+  state is fed straight into the gradient assembly
+  (`native_analytic_gradient_with_electronic`) whenever its tolerance meets
+  the gradient's 1e-10 stationarity cap; the trainer now evaluates at that
+  tolerance by construction, so one gradient-grade SCC per item replaces the
+  historical pair (~9 s of re-converged SCC per training gradient, and half
+  the SCCs of every semi-numerical NN Hessian column).
+- **The fixed-parameter analytic Hessian is 5.0x faster at 24 atoms**
+  (11.03 s -> 2.22 s; scaling exponent 3.38 -> ~2.9): three per-column AO
+  walks rebuilt every moment-integral derivative for every column and were 95%
+  of the assembly; they are now precomputed once. The `O(nocc^2 nao^2)` metric
+  folds became matmuls (same sums re-associated; fingerprints agree to 15-17
+  significant digits).
+- **The NN analytic Hessian reuses the fixed-p Hessian's own Gamma CPHF
+  response** for its geometric context instead of re-solving the identical
+  3N-column system (~25-30% of the assembly).
+- **The force-loss adjoint has an exact analytic route** replacing the double
+  finite difference, verified per family to ~5e-11 relative (Richardson) with
+  a rigid-translation pin. Measured today it is 7.5-12.6x SLOWER than the
+  double FD (the mixed second derivative needs Hessian-cost objects), so a
+  self-verifying switch computes both once per run, checks agreement, times
+  them and keeps the faster route — the moment the analytic route's cost work
+  lands it flips on its own, with no config change.
+
+- **The periodic total energy still depends on the Ewald splitting parameter.**
+  After the `r^-3` `G = 0` fix the residual drift is 8.1e-3 Eh in the isotropic
+  SCC channel and 7.7e-4 Eh in AES (water in a 14 bohr cube, alpha 0.16..0.32).
+  `tests/physics.rs::ewald_splitting_parameter_independence` is `#[ignore]`d and
+  documents it; relative energies at fixed cell and fixed Ewald settings are
+  unaffected.
+- **Periodic third derivatives are out of scope by design** (not deferred), as
+  are k-point NN-xTB gradients and DC gradients under a k-point mesh or strain.
+- **DC is not linear scaling overall.** It removes the cubic eigensolve
+  (`lowdin_solve` N^2.95 -> `dc_density_step` N^1.59, 4.93x faster at 768
+  atoms with `--no-d4-atm`), but H/S construction, the SCC kernel, AES and
+  the exact Ewald electrostatics remain full-system on every iteration, so
+  total wall time scales N^1.68 vs N^2.64. With D4 ATM on (the default) the
+  streamed three-body term dominates the DC run (73% at 768 atoms, ~N^2.9)
+  and the gap narrows to N^2.39 vs N^2.43 (1.92x at 768). At 1536 atoms the
+  per-SCC-iteration cost holds N^1.33; the N^2.37 total is inflated by SCC
+  convergence (43 iterations vs 19 at 768). See `docs/measurements.md`.
+- **The NN fallback does not detect a confidently-wrong model.** On reaction
+  families the shipped model never saw, the network was 4x worse than plain
+  GFN2 and the fallback fired on 0 of 555 structures. Its triggers are
+  out-of-domain proxies; `used_fallback == false` is not a quality guarantee.
+- Everything NN-xTB, DC, Ln-xTB and third-derivative related is marked
+  experimental and may change.
+### Known issues
+
+- **The EEQ-BC analytic Hessian carries a ~5e-6 residual.** With
+  `d4_eeqbc = true` AND D4 on, the relaxed analytic Hessian differs from a
+  finite difference of its own gradient by 3.8e-6 (water) / 5.1e-6 (dimer)
+  Eh/bohr^2, where every other charge source reaches ~5e-9. The pieces that
+  could plausibly explain it have each been proven exact instead: the EEQ-BC
+  charge curvature to 5.7e-13, the whole dispersion side (fixed-charge block
+  plus all three chain blocks) to 6.2e-16 against the FD of the exact D4 force,
+  and that force bit-identical (3.6e-18) to what `native_analytic_gradient`
+  adds for this charge source. It survives every combination of the four
+  SCC/D4 decoupling flags, is not a symmetrization artefact, and reproduces
+  with no finite difference at all as `H(D4 on) - H(D4 off) != [fixed block +
+  chain]`. Gated at 1e-5 in `eeqbc_d4_analytic_relaxed_hessian_matches_
+  gradient_fd_*` at the MEASURED floor, to be tightened to 1e-6 when closed.
+  `hessian_mode = "fd"` is the escape hatch and is still honoured for this
+  charge source.
+- ~~**The periodic total energy still drifts with the Ewald splitting
+  parameter.**~~ **Not an open issue — withdrawn after measurement.** This
+  entry was written from the `#[ignore]` reason on
+  `physics::ewald_splitting_parameter_independence`, which described the state
+  at some earlier point in v0.5.0 development and had gone stale while the test
+  stayed disabled. Re-run, the test **passes**: sweeping alpha over
+  0.16 .. 0.32 bohr^-1 on water in a 14 bohr cube with both series converged,
+  the SCC total energy agrees to **2.7e-15 Eh** (5.3e-16 relative, reproducible
+  exactly across runs) — machine precision, not the 8.1e-3 Eh the stale note
+  claimed. The regularized `G = 0` term for the `r^-3` Klopman-Ohno tail
+  (`ko_ewald::r3_ewald_g0_e1`) closed it. The test is now **enabled**, so the
+  invariance is a standing regression guard over the whole periodic
+  electrostatic stack rather than a disabled note. See the Fixed section.
+
+- **`mindless03` no longer reproduces its xtb oracle reference.** That system
+  has several self-consistent SCC solutions and the reference is a *metastable*
+  one: xtb generated it at `acc = 1.0` (charge convergence 1e-4 e), stopping
+  before the iteration left that basin. Converging to 1e-9 lands 6.8e-2 Eh
+  ABOVE the reference; raising the iteration budget to 2000 lands 4.4 Eh BELOW
+  it; converging first at xtb's own 1e-4 and warm-starting the tight solve
+  reproduces the 6.8e-2 result exactly, so this iteration does not pass through
+  the reference basin at all. A binary built before the NN-xTB radius-class work
+  passes the case, so basin selection changed during v0.5.0 development - but
+  the energy functional is not implicated: the other six oracle sets still pass
+  at their own tight floors (water agrees to 1e-11..1e-13 on every component)
+  and the analytic gradient stays FD-exact to 3e-10. Kept visible as the
+  `#[ignore]`d `oracle_mindless03_metastable_reference`, with the full
+  measurement record in its doc comment.
+- **The Mermin `dF/dT = -S` identity is not verified on the spin-polarized
+  path.** The O2 triplet fixture does not converge in 3000 iterations at the
+  test's settings - the spin driver still uses the legacy charge-space
+  accelerator, since ADIIS -> CDIIS was extended to the Gamma and Bloch drivers
+  only. With a decaying level shift it converges, but the identity then holds
+  to just 6.4e-4 with the raw differences plateauing rather than falling as
+  `h^2`, which is the signature of converging to a fixed point of the shifted
+  Hamiltonian. The entropy bookkeeping itself is correct (the spin path sums
+  the alpha and beta channel entropies separately). Closed-shell Gamma and the
+  metallic k-point path verify to 1.3e-8 and 4.1e-13 respectively. Kept as the
+  `#[ignore]`d `..._spin_polarized` test.
+
+
+## [0.4.5]
+- No release notes were recorded in-tree for this version.
+
+## [0.4.4]
+- Shipped the MOR41-fit uniform-optimum `experimental_corrections` preset
+  (`range_separation.rs`; `--experimental-corrections`).
+
+## [0.4.3]
+- DIIS error vector switched to the orthonormalised commutator
+  `X^T (FPS - SPF) X`; a 22-atom stall case dropped from 2129 to 92
+  iterations.
+
+## [0.4.2]
+- LC SCF robustness: damped-mixing DIIS fallback, DIIS restart on residual
+  growth, automatic virtual level shift (fixes CO).
+
+## [0.4.1]
+- EEQ-BC CG indefinite-block fix (H2/I2 homonuclear diatomics) via LU
+  fallback on the bordered KKT system.
+
+## [0.4.0]
+- Finite electronic temperature (Mermin free energy) for the OFX/LC path;
+  `param_deriv` experimental option-knob finite-difference targets.
+
+## [0.3.0]
+- Range-separation scope bound `OMEGA_MAX_SUPPORTED = 1.0`.