pm3-rs-python 0.2.3__tar.gz → 0.2.5__tar.gz

{pm3_rs_python-0.2.3 → pm3_rs_python-0.2.5}/CHANGELOG.md

@@ -1,6 +1,285 @@
 # Changelog
 
-## 0.2.3 — 2026-09-03
+## 0.2.5
+
+A broad oracle, and the three defects it found.
+
+0.2.4 was validated against a dozen hand-picked molecules. This release compares
+against **189, spanning every element PM3 is parameterized for**, and the answer
+to "does pm3-rs reproduce MOPAC" is now a measurement rather than a belief: all
+189 agree on heat of formation, dipole, net atomic charges and ionization
+potential. Getting there took fixing two real bugs and correcting one assumption
+about what the oracle was.
+
+### Added
+
+- **`tests/data/mopac_oracle.tsv`** — MOPAC v23.2.5's own answers for 189
+  molecules, generated by `tools/oracle/build_oracle_set.py` and read by
+  `tests/mopac_oracle.rs`. Geometries are MOPAC-optimized (so each fixture is a
+  PM3 stationary point) except where there is nothing to optimize — a noble-gas
+  pair has no bound minimum, a Sparkle no valence orbitals — and those rows say so
+  in a `relaxed` column. Coverage is the whole parameter set: main group, the
+  noble gases, the heavy s-block, Zn/Cd/Hg, the fifteen La–Lu Sparkles and MOPAC's
+  `Cb`/`+`/`-`. Francium is the one absentee, because neither code has parameters
+  for it and both refuse it.
+
+  **Agreement: 189 of 189**, worst heat of formation `7.2e-4 kcal/mol`, worst
+  dipole `1.1e-3 D`, worst charge `1.6e-4 e`.
+
+- **`Pm3Options::stability`** ([`ScfStability`]) — an SCF stability search. A
+  converged SCF is one fixed point of an operator that has several, and nothing in
+  a convergence test says it is the ground state. When the frontier gap is small
+  enough that the orbital ordering was in doubt, the molecule is re-solved from
+  deliberately different starting points and the lowest solution kept.
+
+- **`Pm3Options::guess`** ([`ScfGuess`]) — the starting density is now selectable
+  (`Sad`, `Core`, `SymmetryBroken`), because it decides *which* solution is
+  reached and not merely how fast.
+
+- **`Pm3Options::mmok`** — MOPAC's `MMOK` molecular-mechanics amide correction,
+  `K·sin²(O=C–N–H)` per amide hydrogen with `K = 7.1853 kcal/mol`. **Off by
+  default**, unlike MOPAC. Available from Python and the CLI as a `+mmok` suffix
+  on the method (`method="pm3+mmok"`, `--method pm3-d3h4+mmok`). Written over the
+  crate's dual numbers, so its gradient and Hessian contributions come from the
+  same expression and an optimization with it on minimizes what it reports.
+
+### Fixed
+
+- **The SCF converged to excited solutions on seven molecules**, by up to 279
+  kcal/mol, and reported them as converged. `2-butyne` (+279), `ketene` (+204),
+  `C₂F₄` (+166), `C₂Cl₄` (+157), the `O₂` triplet (+135), `NH₂•` (+37) and the
+  methyl radical (+111) each reached a self-consistent state that obeyed the
+  aufbau principle among its own eigenvalues and was not the ground state. Every
+  one of them now agrees with MOPAC.
+
+  Three separate causes, which is why no single change fixed them: DIIS stepping
+  over the fixed point (`2-butyne`, `ketene`), the SAD guess being in the wrong
+  basin (`C₂Cl₄`), and the restricted iteration having no path to the solution at
+  all (`C₂F₄` — reachable only through the unrestricted loop, which converges
+  spin-pure there and so returns a restricted state). The search covers all three
+  by trying them and keeping the lowest.
+
+  It fires on 6 of the 189 and costs nothing on the rest: the frontier gap
+  separates the two populations cleanly (every wrong solution below 4 eV, every
+  first-try-correct one above 5.7), so the trigger is a gap threshold sitting in
+  the empty band between. The whole 189-molecule set solves in under a second.
+
+- **The unrestricted path started from core-Hamiltonian orbitals**, which is the
+  wrong guess. From SAD, the `O₂` triplet and the amino radical land on MOPAC's
+  answer instead of 135 and 37 kcal/mol above it, and the methoxy radical takes a
+  few dozen iterations instead of about 1600.
+
+- **`Pm3Result` gained `scf_paths_tried` and `scf_improvement_ev`**, so a caller
+  can see when the search changed the answer rather than having to infer it.
+
+### Changed
+
+- **MOPAC's default is not PM3, and the oracle now says so.** MOPAC applies `MMOK`
+  unless given `NOMM`, adding a classical amide torsion term after the SCF. It
+  changes no orbital and no total energy, which is what makes it easy to mistake
+  for a discrepancy: acetamide's density, dipole and every eigenvalue agreed with
+  ours to six figures while its heat of formation was 0.66 kcal/mol away. Every
+  row of the oracle is now generated with `NOMM`, so the file is plain PM3.
+
+  Both the form and the constant of the correction were measured against MOPAC
+  rather than copied, by scanning formamide's torsion with `MMOK` and `NOMM` and
+  subtracting; the fit is exact to the digits MOPAC prints.
+
+## 0.2.4
+
+Most of what was broken in 0.2.3 was not the physics but the **surface**: things
+the library could do that no caller could ask for, and one assumption that was
+true at Γ and quietly false everywhere else.
+
+### Fixed
+
+- **A meshed `D(q)` was wrong at `q = 0`** — by 300%, anisotropic on a cubic
+  crystal, and with the *sign* reversed, so a stable structure reported an
+  imaginary optical mode. One substitution made in two places: `P(T) = P(0)`,
+  which **is** Γ sampling (one k-point cannot tell images apart) and is false on a
+  mesh, where `P(0)` is the Brillouin-zone average while `P(T)` decays with `T`.
+  `phased_skeleton` asserted it for the skeleton — the dominant half — and
+  `bare_blocks` asserted it again for the response's exchange term. NaCl `3×3×3`
+  now gives an isotropic `D(0)` agreeing with a central difference of the analytic
+  forces to `1e-4`. Γ sampling is unchanged bit for bit: there the two expressions
+  are the same number.
+
+  The clue had been recorded a release earlier and not used — the error converged
+  smoothly with mesh size, **0% at `1³`** rising to 77% at `7³`. Zero at `1³` is
+  the tell: a `1×1×1` mesh *is* Γ.
+
+- **`native.optimize()` returned no `energy_ev`, and `relax()` no `iterations`
+  or heat of formation.** Reading the docs for one and applying them to the other
+  ended a structure optimization with a `KeyError` from the call that had done the
+  most work. All three optimizers now answer to the same names, held by a
+  table-driven contract test over every native function.
+
+- **`pm3-rs optimize big.xyz --dc 4.8` optimized nothing** and exited 0: the
+  divide-and-conquer branch returned before the command was read. The same held
+  for `frequencies`, `hessian`, `gradient`, `molden`, `ir` and `charges`.
+
+- **Translations and rotations are removed by projection**, not by being small.
+  The rigid-body subspace is discovered from the geometry — 2 rotations for a
+  linear molecule, 0 for an atom — and those modes are **exactly** `0.00 cm⁻¹`.
+  Three different thresholds (`< 50`, `< 100`, `< 300 cm⁻¹`) for the same quantity
+  are gone, as is `SOFT_MODE_FLOOR`.
+
+- **The Γ acoustic sum rule was applied row-wise**, which is not symmetric, and
+  the eigensolver reads one triangle — so the rule that had just been imposed was
+  partly undone and `PeriodicPhonons::hessian` came back non-symmetric. It is a
+  symmetric projection now, and `acoustic_residual_cm` reports the **pre**-projection
+  residual, which is the number worth seeing rather than the one the correction
+  just flattened.
+
+- **`force_tol` was converted the wrong way** in the new CLI and partitioned
+  paths — a gradient scales the opposite way to a length, so the factor is
+  `BOHR_TO_ANGSTROM`. The tolerance was 3.57× looser than asked for, the optimizer
+  stopped early, and it still reported `converged: true`. Now
+  `constants::force_tol_to_au` and `stress_tol_to_au`, with a test that pins the
+  direction.
+
+- **A stalled periodic SCF had no recourse on the Γ path and one rung on the
+  k-point path.** Damping now goes ahead of smearing on both, because its guarantee
+  is stronger: it changes the path and not the equations, and both loops measure
+  convergence against the *undamped* step, so a converged damped run solves what was
+  asked. Silicon on a 3×3×3 mesh is rescued (−145.536995 eV); diamond still fails,
+  because its residual alternates rather than decays and no mixing fraction reaches
+  a symmetry-breaking limit cycle. There is deliberately no third rung: a level
+  shift converges diamond to a *different solution*, which is worse than not
+  converging, so it stays in the diagnosis for the caller to choose.
+
+- **A periodic response returned an incomplete answer for a partially occupied
+  cell, silently.** The occupation factors are the metallic
+  `(f_n − f_m)/(ε_n − ε_m)` form, which makes it look handled; what is missing is
+  the Fermi-level shift, and the sum skips the near-degenerate pairs that carry the
+  Fermi-surface term. It is refused now — keyed on whether the occupations came out
+  **integral**, not on whether smearing was used, so a gapped cell under a small
+  smearing still runs. Same `T·S` certificate the SCF rescue uses.
+
+- Seventeen lines across three files had been committed after a PowerShell cp932
+  round-trip. In `pbc/mod.rs` the casualties were the electrostatics derivation:
+  `√(r² + a)` had lost its root and bracket and `[ W_KO(r) − W_point(r) ]` its
+  minus sign, so a formula read as noise rather than as wrong.
+
+### Added
+
+- **Orbital energies, coefficients and occupations** (`native.orbitals`,
+  `pm3-rs orbitals`, `--coefficients`). Coefficients come with `ao_labels`, and
+  the frontier is taken across both spin channels — a radical's β LUMO sits below
+  its α one.
+- **Phonon eigenvectors.** They were computed and discarded. `modes` (real) at Γ,
+  `modes_real`/`modes_imag` at a wavevector, through `native.phonons` and
+  `PM3.get_phonons`.
+- **`Pm3Options::cphf_max_iter`** and a `cphf_max_iter=` argument on the six
+  Python entry points that run a coupled-perturbed solve. It was two hard-coded
+  `400`s, so a stiff response could only be rescued by editing the crate.
+- **Divide-and-conquer geometry optimization** from the CLI (`--dc` with
+  `optimize`), `native.divide_and_conquer_optimize` and `PM3`.
+- **Molden `[STO]`** (`--sto`, `basis="sto"`) beside the default `[GTO]`, and
+  `--output` to say where the file goes.
+- **`--pbc` in the spelling the reader has in mind**: `1,0,1`, `101`, `xz`,
+  `x,z`, `true,false,true`, `none`.
+- **The periodic optimizer's controls**: `--relax-cell`, `--fixed-cell`,
+  `--max-steps`, `--force-tol`, `--stress-tol`, `--pressure`. `write_xyz` now
+  carries the cell as extended-XYZ `Lattice="..."`, which was silent data loss the
+  moment variable-cell relaxation existed.
+- `--kpts` and `--q` on the CLI; `native.divide_and_conquer_forces`; periodic
+  `hessian` from Python.
+
+### Performance
+
+- **Periodic runs are about 10× faster.** A 48-atom Γ single point went from
+  17.7 s to 1.82 s; the Python test suite from 396 s to 72 s. The numbers are
+  unchanged.
+
+  None of the three optimizations that had been planned were the problem. Measured
+  first, as `examples/born_profile.rs` established: the serial k-point loop was
+  31–45% of a *meshed* run and nothing of a Γ one, the serial Fock build was
+  **0.4%** of an iteration at every size from 6 to 72 atoms, and an optimization
+  step cost 1.6 gradients rather than the up-to-30 the line search was feared to be
+  paying. It was the Ewald sum, at 89–98% of every iteration — and inside that,
+  90.5 s of real space against 2.5 s of reciprocal, so the guess *within* the guess
+  was wrong too.
+
+  The real-space sum evaluated `erfc` and `exp` for every pair inside the cutoff,
+  **twice per iteration**, at distances that do not move while the charges do. The
+  kernel is geometry and now sits in `EwaldContext` beside the phase table. Real
+  space fell 32×. `examples/periodic_profile.rs` and `PM3_GAMMA_PROFILE=1` are the
+  measurement.
+
+- **A Γ-point Hessian is 2.3× faster, and its Ewald phase 210×.** 48 atoms: 51.3 s
+  to 22.8 s, with the Ewald second derivative going from 31.60 s to 0.15 s. Numbers
+  unchanged.
+
+  Profiled first, again, and again it was not the assumption: the coupled-perturbed
+  response — the phase everyone expects to dominate — was 38%, the skeleton rounded
+  to zero, and the Ewald term was 62%. Its inner sum turned out to be a **structure
+  factor written out longhand**: what the site-pair loop accumulates for an atom
+  pair is `Re[S_A S_B*]`, so `O(N_G · N_sites²)` becomes `N_sites` to build the
+  factors plus `N_atoms²` to combine them — and PM3 puts four to five multipole
+  sites on every heavy atom. `examples/hessian_profile.rs` and
+  `PM3_HESSIAN_PROFILE=1` are the measurement. The Hessian is now 96% response,
+  which is where the next look starts.
+
+### Licensing
+
+- **The wheel shipped `LICENSE` alone.** `_native.pyd` has the MOPAC-derived PM3
+  parameter tables compiled into it, so `pip install` distributed Apache-2.0
+  material without the licence text or the attribution. It now carries
+  `THIRD_PARTY_NOTICES.md`, the Apache text and every `NOTICE`.
+- **Nothing recorded the ~60 Rust crates statically linked into the binaries.**
+  `faer`, `rayon`, `pyo3` and their transitive closure are compiled into
+  everything shipped, and MIT asks for the copyright notice to travel with a
+  substantial portion. `third_party/rust-crates/` now carries the index and 524 KB
+  of verbatim texts, generated by `tools/collect_rust_notices.py`.
+
+  Two things the graph turned up: `faer` declares MIT and ships **no MIT text**
+  (what it ships is its own upstream Eigen/LAPACK/SuiteSparse attributions), and
+  `unicode-ident` is `(MIT OR Apache-2.0) **AND** Unicode-3.0` — the only entry
+  where choosing a licence does not settle the question.
+- `tests/attribution.rs` holds all of it to the tree: every linked crate is in the
+  notice, the two distributions agree, no upstream source is tracked, and no file
+  has been through a codepage round-trip.
+
+### Testing
+
+- **Every CLI command against every flag**, mechanically — the matrix that found
+  `--dc` swallowing seven commands. Plus a second layer running each command
+  through the installed console script, where only `energy` had ever been
+  exercised across the Python↔Rust boundary.
+- **All fifteen La–Lu Sparkles against MOPAC** at `1e-5 kcal/mol`, re-run through
+  the executable rather than compared to a stored JSON.
+- `tests/pbc_cubic_identities.rs` has no `#[ignore]`s left, and neither does the
+  suite.
+
+### Known limits
+
+- PM3's transition metals are **Zn, Cd and Hg** and nothing else. `TiO₂`, `SrTiO₃`,
+  `LiCoO₂` and ferrocene are outside the model, not unimplemented. Those three are
+  enough for real organometallic chemistry: `examples/phonon_structures.rs` and
+  `examples/organometallic_bands.rs` cover `Zn(CH₃)₂` and `Hg(CH₃)₂` — linear
+  dialkyls with genuine `M–C` σ bonds — and the `Cd(CN)₂` framework.
+
+- **Phonons must be evaluated at PM3's own geometry, not at the experimental one**,
+  and for ionic solids the two are far apart. A Hessian off a stationary point is
+  not a phonon spectrum, so the experimental lattice constant is the wrong place to
+  ask. At the lattice constant PM3 actually prefers, MgO's spectrum is clean — but
+  that equilibrium sits 12.7% *above* the measured value, and the highest mode comes
+  out at 745 cm⁻¹ against 401 measured.
+
+  For NaCl the energy is still falling at the compressive edge of the range Γ
+  sampling can hold, so PM3 has no bound rocksalt minimum there at all. Neither is
+  a defect in the second-derivative code; PM3 was fitted to molecular heats of
+  formation and never saw a Madelung lattice.
+
+- Where PM3 *is* on firm ground is the molecular chemistry it was fitted to.
+  Dimethylzinc relaxes to a Zn–C bond of 1.924 Å against 1.930 Å measured, and its
+  symmetric Zn–C stretch comes out at 599 cm⁻¹ against ≈615.
+
+- A periodic SCF on some cubic cells with an even Monkhorst–Pack mesh still
+  converges to a mesh-dependent solution; see `docs/pbc.md`.
+
+## 0.2.3
 
 One performance fix, found by running real crystals rather than by reading code,
 and two reporting defects it turned up on the way.
@@ -45,7 +324,7 @@ and two reporting defects it turned up on the way.
 - `cargo fmt` across the tree: 0.2.2 shipped 26 files that rustfmt disagreed
   with, all of them new or edited in that release.
 
-## 0.2.2 — 2026-09-03
+## 0.2.2
 
 The response properties a dynamical matrix was already most of the way to, and a
 Berry phase to check them from outside. The largest fix is none of those: a
@@ -189,7 +468,7 @@ removing the intra-atomic `dd` moment the phase omits (`PM3_BORN_NO_DD=1`)
 collapses that to `1.9e-4`. The two formalisms agree on everything except one
 identified physical term.
 
-## 0.2.1 — 2026-09-01
+## 0.2.1
 
 Phonons everywhere the Γ point already worked, an external electric field, and
 the wavefunction outputs that go with it. Three defects that had shipped in
@@ -377,7 +656,7 @@ test that could have caught them ran.
   existed. A test now compares every stub signature against the extension, and
   another asserts `pm3_rs.native` can pass every argument the extension accepts.
 
-## 0.2.0 — 2026-08-27
+## 0.2.0
 
 Periodic boundary conditions. Molecular results are unchanged except for one
 bug fix, noted below.

{pm3_rs_python-0.2.3 → pm3_rs_python-0.2.5}/Cargo.lock

@@ -653,7 +653,7 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
 [[package]]
 name = "pm3-rs"
-version = "0.2.3"
+version = "0.2.5"
 dependencies = [
  "faer",
  "pyo3",

{pm3_rs_python-0.2.3 → pm3_rs_python-0.2.5}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pm3-rs"
-version = "0.2.3"
+version = "0.2.5"
 edition = "2021"
 license = "GPL-3.0-or-later"
 authors = ["ss0832"]

{pm3_rs_python-0.2.3 → pm3_rs_python-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pm3-rs-python
-Version: 0.2.3
+Version: 0.2.5
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Rust
@@ -19,6 +19,15 @@ Requires-Dist: numpy>=1.21
 Requires-Dist: ase>=3.22 ; extra == 'ase'
 Provides-Extra: ase
 License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: third_party/README.md
+License-File: third_party/mopac/LICENSE
+License-File: third_party/dftd3/NOTICE
+License-File: third_party/h_bonds4/NOTICE
+License-File: third_party/mopac/NOTICE
+License-File: third_party/pyseqm/NOTICE
+License-File: third_party/rust-crates/NOTICE
+License-File: third_party/rust-crates/LICENSES.txt
 Summary: PM3 semiempirical method with periodic boundary conditions, divide-and-conquer, a Python-native API and an ASE calculator
 Keywords: chemistry,computational-chemistry,quantum-chemistry,semiempirical,pm3,nddo,mopac,ase,periodic-boundary-conditions,dft
 Author: ss0832

pm3_rs_python-0.2.5/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,115 @@
+# Third-party notices
+
+`pm3-rs` is GPL-3.0-or-later. This document records the provenance of its
+scientific parameters and reference algorithms, with the citations.
+
+**[`third_party/README.md`](third_party/README.md) is the index**: one table
+saying, for each upstream project, what `pm3-rs` takes from it, under which
+license, and which files here hold the terms. Each `third_party/<name>/NOTICE`
+records the same for that project in detail. Start there if the question is
+"what is owed to whom"; this file is the bibliography.
+
+No third-party source code is vendored in this repository. What crosses the
+boundary is published numeric parameters and published working equations.
+
+That is true of the *repository*. It is not true of the **binaries**: the Rust
+dependency graph is statically linked into `_native.pyd` and the `pm3-rs`
+command, so around sixty crates are compiled into everything this project ships.
+They are recorded separately in
+[`third_party/rust-crates/NOTICE`](third_party/rust-crates/NOTICE), with the
+verbatim texts in `LICENSES.txt` beside it, because the obligation they carry is
+a different one: MIT asks for the copyright notice to travel with the binary,
+not for a citation in a bibliography. See "Rust dependencies" below.
+
+## PM3
+
+The PM3 model is described by:
+
+- J. J. P. Stewart, "Optimization of parameters for semiempirical methods I.
+  Method", *J. Comput. Chem.* **10**, 209-220 (1989),
+  DOI 10.1002/jcc.540100208.
+- J. J. P. Stewart, "Optimization of parameters for semiempirical methods II.
+  Applications", *J. Comput. Chem.* **10**, 221-264 (1989),
+  DOI 10.1002/jcc.540100209.
+
+The machine-readable PM3 tables under `src/data/` are generated by
+`tools/extract_pm3_params.py` from open-source MOPAC v23.2.5:
+
+- repository: https://github.com/openmopac/mopac, tag `v23.2.5`
+- license: Apache-2.0, retained at `third_party/mopac/LICENSE`
+- input files: `parameters_for_PM3_C.F90`,
+  `parameters_for_PM3_Sparkles_C.F90`, `alpb_and_xfac_pm3.F90`, and
+  `parameters_C.F90`
+
+The extracted data include element parameters, per-element Gaussian terms,
+PM3 pair factors, shell/reference-atom data, La-Lu Sparkles, and MOPAC special
+atom codes. MOPAC is also used as the executable oracle for plain PM3.
+
+The Rust implementation follows the MOPAC reference equations for derived
+multipoles, one- and two-center NDDO integrals, PM3 core-core repulsion, SCF
+bookkeeping, and special zero-orbital cores. The implementation is original
+Rust code; no MOPAC Fortran source is redistributed.
+
+MOPAC contributes in three distinct roles — redistributed parameter data,
+followed-but-not-copied equations, and a build-time oracle that never ships —
+which carry different obligations. [`third_party/mopac/NOTICE`](third_party/mopac/NOTICE)
+separates them and names the upstream file behind each.
+
+## D3, H4, and X corrections
+
+- D3: S. Grimme, J. Antony, S. Ehrlich, and H. Krieg, *J. Chem. Phys.*
+  **132**, 154104 (2010). Embedded C6/radius tables were extracted from the
+  Apache-2.0 MOPAC implementation; see `third_party/dftd3/NOTICE`.
+- PM3-D3: the zero-damping constants `s6=1`, `s8=0.612`, `rs6=1.345`,
+  `rs8=1`, `alpha6=14`, and `alpha8=16` are verified against the public MOPAC
+  5.022mn `anad3.f` implementation distributed by the University of Minnesota.
+- D3H4: J. Rezac and P. Hobza, *J. Chem. Theory Comput.* **8**, 141-151
+  (2012), DOI 10.1021/ct200751e. PM3-specific D3/H4/H-H coefficients follow
+  the authors' public implementation and Cuby interface parameter table; see
+  `third_party/h_bonds4/NOTICE`.
+- X: J. Rezac and P. Hobza, *Chem. Phys. Lett.* **506**, 286-289 (2011),
+  DOI 10.1016/j.cplett.2011.03.009. Parameters follow MOPAC
+  `corrections/disp_DnX.F90`.
+
+## PySEQM
+
+The closed-form s/p two-center integral and rotation kernels in
+`src/integrals.rs` and `src/overlap.rs` follow the reference equations
+implemented by PySEQM:
+
+- https://github.com/lanl/PYSEQM
+- G. Zhou et al., *J. Chem. Theory Comput.* **16**, 4951 (2020)
+- BSD-3-Clause; see `third_party/pyseqm/NOTICE`
+
+## Rust dependencies
+
+Everything above concerns *scientific* provenance — parameters and equations —
+and none of it is code that ships. The Rust crates are the opposite case: no
+science crosses from them, and all of their code does.
+
+`faer` (linear algebra), `rayon` (parallelism) and `pyo3` (the Python bindings)
+are the three direct dependencies; with their transitive closure that is around
+sixty crates, statically linked into `_native.pyd` and the `pm3-rs` executable.
+Most are MIT, which requires the copyright notice and the permission notice to
+be included in "all copies or substantial portions of the Software" — which a
+static binary is. A handful carry other terms: `atomic-wait` is BSD-2-Clause,
+`bytemuck` offers Zlib, `target-lexicon` is Apache-2.0 with the LLVM exception,
+and `unicode-ident` is `(MIT OR Apache-2.0) AND Unicode-3.0`, where the `AND`
+means the Unicode terms apply on top rather than as an alternative.
+
+- index, with the SPDX expression and files found per crate:
+  [`third_party/rust-crates/NOTICE`](third_party/rust-crates/NOTICE)
+- the verbatim texts, with their copyright lines:
+  `third_party/rust-crates/LICENSES.txt`
+- regenerate with `python tools/collect_rust_notices.py` after changing a
+  dependency; `tests/attribution.rs` fails if the graph and the index disagree
+
+`faer` additionally carries upstream attributions of its own — Eigen (MPL-2.0),
+LAPACK and SuiteSparse (BSD) — which are reproduced in `LICENSES.txt` along with
+everything else, rather than being left one level up the chain.
+
+Apache-2.0 and BSD-3-Clause are compatible with GPL-3.0-or-later for this use,
+as are MIT, BSD-2-Clause, Zlib, MPL-2.0 and Apache-2.0-WITH-LLVM-exception; the
+compatibility is one-way, and this project is the GPL end of it. Numeric
+scientific parameter values are retained with provenance regardless of their
+copyright status.

{pm3_rs_python-0.2.3 → pm3_rs_python-0.2.5}/docs/pbc.md

@@ -461,6 +461,46 @@ each image's displacement scaled by its own `e^{iq·T}`, validated by folding a
 hydrogen-bonded chain onto its own doubled cell. The Γ-point analytic Hessian
 reaches 1D and 2D the same way, its Ewald block being the phased sum at `q = 0`.
 
+## A meshed `D(q)` was wrong at `q = 0`, and is fixed in 0.2.4
+
+Through 0.2.3, `dynamical_matrix_on_mesh` / `phonons(..., kpts=...)` / `--kpts`
+with `--q` returned a badly wrong answer at `q = 0`. Measured on rocksalt NaCl at
+its experimental lattice constant, `3×3×3` mesh, in eV/Ų:
+
+| | `D_xx` | `D_yy` | `D_zz` |
+|---|---:|---:|---:|
+| central difference of the analytic forces | +2.16 | +2.16 | +2.16 |
+| `dynamical_matrix_on_mesh`, 0.2.3 | **−4.61** | **−1.28** | **−1.28** |
+| `dynamical_matrix_on_mesh`, 0.2.4 | +2.16 | +2.16 | +2.16 |
+
+Three things had been wrong at once — the magnitude, the isotropy a cubic crystal
+must have, and the *sign*, which reported an imaginary optical mode for a
+structure that is a minimum.
+
+**The cause was one substitution made in two places.** `P(T) = P(0)` — one density
+matrix serving every lattice image — *is* Γ sampling: a single k-point cannot tell
+images apart, so it holds there by construction. On a mesh it is false, because
+`P(0)` becomes the Brillouin-zone average while `P(T)` decays with `T`.
+
+- `phased_skeleton` passed one density matrix to `pair_block` for every image. The
+  skeleton is the larger half of `D(q)`, so a meshed run built its dominant term
+  from the wrong density.
+- `bare_blocks` read `exchange_scale · P^σ(0)` for the exchange part of each bare
+  perturbation, where the response needs `P^σ(T)`. `SpinChannel::p_images` already
+  carried the right thing under both samplings; nothing was reading it.
+
+Both now read the per-image density. Γ sampling is unchanged, bit for bit: at Γ
+the two expressions are the same number.
+
+The clue that identified it had been recorded for a release and not used — the
+error converged smoothly with mesh size, 0% at `1³` rising to 77% at `7³`. Zero at
+`1³` is the tell: a `1×1×1` mesh *is* Γ, where the substitution is exactly true.
+
+`tests/pbc_cubic_identities.rs` holds both identities on a mesh, and
+`pbc::dfpt::tests::the_meshed_skeleton_is_where_the_cubic_symmetry_breaks` runs
+the skeleton without the response under both samplings — a separation no public
+entry point offers, and what made the second occurrence findable.
+
 ## Response properties
 
 Everything in this section is a contraction of the same first-order density the
@@ -597,10 +637,40 @@ so it is known rather than discovered:
   level shifts to 5 eV, and at a thousand iterations. Two eV of smearing does converge — to a
   *different* solution 200 eV away.
 
-  The chemical potential is what gives it away: it swings by an electronvolt every iteration as
-  occupations flip. An even Γ-centred mesh on a cubic cell puts every one of its points on a
-  zone-boundary symmetry point, where bands meet; a Fermi level inside a degenerate manifold has
-  no stable filling to find, and the bisection reassigns it each pass.
+  The chemical potential is what gives it away: it swings by an electronvolt every iteration. An
+  even Γ-centred mesh on a cubic cell puts every one of its points on a zone-boundary symmetry
+  point, where bands meet.
+
+  > **The mechanism above is now measured, and the "occupations flip" half of it is wrong.**
+  > `PM3_KSCF_TRACE=1` reports the occupation-flip count and the per-atom populations alongside
+  > the residual. On the **primitive** two-atom cell at 5.64 Å with a `2×2×2` mesh, the flip count
+  > is **zero at every iteration** — the occupations never change sides — while a full **1.1
+  > electrons** move between Na and Cl each pass and `μ` follows across twelve electronvolts. It
+  > is charge sloshing, not a Fermi level trapped in a degenerate manifold; the charge moves first
+  > and `μ` follows it. That cell also *recovers*, converging unaided to `−341.786 eV`.
+  >
+  > **And converging is not the point.** The primitive cell on a `2×2×2` mesh converges, cleanly,
+  > to a state with **−2.10 electrons of charge on the sodium**, where every mesh from `3³` to
+  > `7³` puts `+0.16` to `+0.24` there and agrees on the energy to 0.06 eV. A sodium that has
+  > gained two electrons is not a chemical result, and nothing in the energy, the residual or the
+  > `converged` flag says so. `KpointResult::charge_swing` does: the even mesh swings **1.44
+  > electrons** on its way there against the odd mesh's 0.29. **Check it, and check the charges.**
+  >
+  > **It is not a mixing problem, and three standard remedies say so.** A deeper Pulay history
+  > (8 → 24) moves diamond's residual from `3.72e-5` to `3.41e-5`; Kerker preconditioning of the
+  > atomic-charge channel makes NaCl's sloshing *worse* (1.44 → 2.56 electrons of swing); handing
+  > damping over to the accelerator, as the Γ path does, converges diamond and silicon and breaks
+  > four k-point identities. What the Kerker experiment showed instead is the actual shape of the
+  > problem: **three different mixers reach three different converged solutions on the same cell
+  > and mesh** — `−341.79`, `−366.34` and `−379.22 eV`, with `−2.10`, `−4.35` and `−4.94`
+  > electrons on the sodium — while every odd mesh agrees on `−327.45` and `+0.17`. The
+  > fixed-point map has several attractors at that sampling and the mixer picks among them. No
+  > preconditioner fixes that. Use an odd mesh, and check `charge_swing`.
+  >
+  > The conventional-cell failure `tests/crystals.rs` pins is a different system and has not been
+  > re-measured with the trace. Run it before repeating the explanation above.
+  > `examples/scf_hardening.rs` has the ladder, and a failed SCF now carries its own diagnosis in
+  > the error rather than only a residual.
 
   Odd meshes do not sit on those points. `3×3×3` converges in eighteen iterations, and the answer
   is right: energies agree to 0.02 eV and charges to 0.02 electrons across `3×3×3`, `4×4×4` and