torchspin 0.3.0__tar.gz → 0.5.0__tar.gz

{torchspin-0.3.0 → torchspin-0.5.0}/CHANGELOG.md

@@ -4,6 +4,378 @@ All notable changes to torchspin will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-10-19
+
+Found by a flavodoxin HYSCORE feasibility study that compared `saffron`
+against MATLAB EasySpin on its own 13C model and got the modulation wrong
+while the raw cosine stayed at 0.99999.  The existing `saffron` suite scored
+agreement with a cosine similarity, which for a pulse-EPR time trace is
+dominated by the DC offset: a HYSCORE trace can have a ~100% wrong modulation
+and still score >0.999.  Every defect below lived in that blind spot.
+
+New oracle: `tests/data/generate_saffron_phase_refs.m` →
+`torchspin/tests/test_saffron_phase_matlab_validation.py` (25 cases, MATLAB
+R2024b), plus a strict `spidyan` amplitude case.  It asserts the **mean-centered** relative L2 error — the modulation
+— as well as the raw error, at tolerances near double-precision roundoff.  All
+26 strict cases, 25 of them fail on 0.4.0 and pass here (the 26th, two-nucleus
+Mims ENDOR, is the one case 0.4.0's hardcoded `EndorMethod=1` got right).  Agreement across the predefined
+2p/3p/4pESEEM, HYSCORE and Mims-ENDOR routes, direct and frequency-binned,
+powder and explicit single crystal, S=1/2 and S=3/2, with and without
+orientation selection and nuclear quadrupole coupling, is now 1e-16 to 1e-14
+rather than "cosine ≥ 0.98".
+
+### Fixed — `saffron` tau phase factor in all four predefined ESEEM/HYSCORE routes
+
+`saffron.m` builds the tau-dependent phase factor as
+`Q_ = exp(-2i*pi*Ea*tau)*exp(-2i*pi*Eb*tau)'`, and MATLAB's `'` is a
+**conjugate** transpose, so element *(i,j)* is `exp(-2i*pi*(Ea_i - Eb_j)*tau)`
+— a *difference* of the two manifold energies.  torchspin formed the outer
+product without conjugating the second factor, giving their *sum*.  The error
+vanishes at `tau = 0`, which is why it survived.
+
+Fixed for `exp_id` 1, 2, 3 and 4 (2pESEEM, 3pESEEM, 4pESEEM, HYSCORE); the
+Mims-ENDOR branch already conjugated correctly.  On the in-repo
+`saffron_HYSCORE.mat` case (tau = 0.08 µs) the mean-centered error against
+MATLAB drops from **112% to roundoff**, while the raw cosine moves only from
+0.999991 to 1.000000.
+
+### Fixed — `saffron` alpha/beta manifold assignment for S=1/2
+
+EasySpin's `Transitions = [1 2]` makes `Ea` the **upper** manifold
+(`<S> = +1/2·n`) and `Eb` the lower.  The S=1/2 fast path had them swapped,
+while torchspin's own S>1/2 path assigned them correctly — an internal
+inconsistency.  Invisible while the nuclear Hamiltonian is linear in **I**
+(the two HYSCORE coherence-transfer pathways then symmetrize the swap away),
+it becomes a 7–33% error as soon as a nuclear quadrupole makes the manifold
+eigenvectors non-trivial.
+
+### Fixed — `saffron` dimension order of the 2D frequency-bin accumulation
+
+`sf_peaks.c` bins a 2D spectrum at `idx = nu1 + nu2*nPoints1`, i.e. dimension
+1 carries `nu1`.  `saffron_peaks.py` computed `idx2 * n_points1 + idx1` into a
+row-major `(n_points1, n_points2)` buffer, which **transposes** the spectrum
+and mis-strides it when the two dimensions differ in length.  Fixed at all
+five 2D increment schemes (11–15, 17).  The binned and direct paths of
+torchspin itself disagreed by 2% before this; a new test asserts they agree,
+which catches this class of bug without any MATLAB reference.
+
+### Fixed — `saffron` `Opt.OriThreshold` reference level under orientation selection
+
+EasySpin takes the pruning threshold from the **unweighted**
+`|<i|SyLab|j>|` maximum and only then multiplies in the excitation amplitude,
+so a narrow `Exp.ExciteWidth` discards more transitions.  torchspin took the
+maximum after excitation weighting and so kept transitions EasySpin drops,
+giving a 75% modulation error for S=3/2 + 14N at `ExciteWidth = 100` MHz.
+Affects S>1/2 with `Exp.ExciteWidth` only.
+
+### Fixed — `saffron` `Opt.Expand` and `Opt.EndorMethod` defaults are conditional in EasySpin
+
+Both were hardcoded to a single value, so the default-argument path silently
+ran a different algorithm than EasySpin:
+
+- `Opt.Expand` defaults to **4 for 1D and 2 for 2D** sequences
+  (`saffron.m:751`); torchspin always used 4, changing the zero-fill of every
+  binned HYSCORE.
+- `Opt.EndorMethod` defaults to **0 for a single SHF nucleus or under
+  `ProductRule`, else 1** (`saffron.m:729`); torchspin always used 1, which
+  selects a different RF-pulse model.  For one nucleus this put the ENDOR
+  amplitude 40% out and changed the lineshape, at cosine 0.996.
+
+Both now accept `None` (the default) to mean EasySpin's rule; an explicit
+integer still overrides it.
+
+### Fixed — `saffron`/`saffron_thyme` treated `Exp.SampleFrame` alone as a single crystal
+
+EasySpin decides sample type from `CrystalSymmetry` or `MolFrame` only
+(`p_sampletype.m:26`): `Exp.SampleFrame` rotates the sample, but a disordered
+powder stays a powder.  `saffron` and `saffron_thyme` also keyed on
+`SampleFrame`, so `SampleFrame` alone silently simulated a **single crystal
+where EasySpin simulates a powder** — a different physical sample, not a
+numerical discrepancy.  `pepper` already had this right; `saffron` now matches
+it.  Code that relied on `SampleFrame` alone to select a crystal must now pass
+`CrystalSymmetry` (e.g. `'P1'`) or `MolFrame`, as EasySpin requires.
+
+### Fixed — `saffron` custom sequences were not divided by their pathway prefactor
+
+For a user-defined sequence (`Exp.Sequence` given as pulses and delays, not a
+predefined name) `saffron.m:1669` divides the signal by the largest surviving
+pathway prefactor.  torchspin omitted this, leaving a custom HYSCORE-style
+sequence a factor of **8** too small.  Shape was unaffected, so the cosine was
+1.000000 and the existing `cosine > 0.95` test passed.  Predefined sequences
+are deliberately *not* renormalized this way, and are unchanged.
+
+### Fixed — `spidyan` complex detection operators were half amplitude
+
+`signalprocessing.m` multiplies a **complex** detection trace (`S+`/`S-`) by
+two when it is demodulated, because the analytic-signal normalization is
+otherwise off by that factor; a purely real or purely imaginary trace (`Sz`) is
+left alone.  torchspin applied the demodulation phase but not the factor, so a
+demodulated `<S+>` channel came out at exactly half EasySpin's amplitude — at
+cosine 1.000000, under a `cosine >= 0.99` assertion.  The `<Sz>` channel in the
+same simulation was already correct, which is why it went unnoticed.
+
+### Audit of the remaining pulse-EPR routes
+
+Prompted by the above, the routes that were scored only by cosine were
+re-checked against fresh MATLAB references with strict metrics.  Now at
+roundoff and covered by tests: custom user sequences (direct and binned),
+`ProductRule` x `TimeDomain` for two nuclei (all four combinations),
+multi-component input with `Sys.weight`, and S=1 systems.
+
+Several apparent discrepancies turned out to be **test-harness** faults rather
+than library faults, and are worth knowing about before trusting an old
+number: `test_3psimple`, `test_4psimple`, `test_hyscore14n`,
+`test_hyscore_ganiso`, `test_mimssimple` and `test_twocomponents` compare
+torchspin's unnormalized output against a MATLAB reference its generator had
+normalized (`y = y/max(abs(y))`), so they sat at a fixed scale factor of 4*pi
+or similar; and `test_saffron_2pESEEM`, `test_saffron_3pESEEM`,
+`test_saffron_HYSCORE_cosine_1d`, `test_S1_*`, `test_S32_HYSCORE`,
+`test_orientation_selective` and `test_customsequence` run with
+`TimeDomain=True` against references generated *without* `Opt.TimeDomain`,
+i.e. they compare direct time evolution against EasySpin's own
+frequency-binned approximation.  Both faults are invisible to a cosine.
+Checked against matched references, the library agrees to roundoff in every
+one of these cases.
+
+Still open, and recorded in `KNOWN_LIMITATIONS.md`:
+
+- `spidyan` multi-spin systems show a small residual that grows linearly
+  through free evolution — a phase drift of order 1e-5 relative — for two
+  coupled electrons (4.7e-3 overall), an electron-nucleus pair (6.4e-5) and
+  S=3/2 (8.8e-6).  Single-electron cases are exact to 1e-13.  Not diagnosed.
+- `saffron` with real pulses returns per-increment transients
+  (`nPoints x nDet x nTime`) where EasySpin returns one detected point per
+  increment, and no simple reduction of those transients recovers EasySpin's
+  trace — the closest is ~3% off after fitting an arbitrary scale.  Treat the
+  real-pulse route as unvalidated; `saffron_thyme` remains without MATLAB
+  cross-validation.
+- `saffron` accepts a predefined `Exp.Sequence` together with real pulses
+  (`Exp.tp`) and silently routes it to the thyme engine; EasySpin rejects that
+  combination outright.  The output is therefore unvalidated.
+- EasySpin's shaped/chirped pulses (`Type`, `trise`, `Frequency`),
+  `Exp.DetWindow`/`DetPhase` and `Opt.SimulationMode` are not implemented in
+  `saffron_thyme`, so EasySpin's own thyme test cases cannot be run against it.
+
+### Note
+
+`saffron` gradients are unaffected in form: a finite-difference check against
+the corrected simulator at nonsymmetric hyperfine values agrees to 1e-10.
+Gradients taken before this release were consistent with the *old*, incorrect
+forward model.
+
+## [0.4.0] — 2026-10-09
+
+Found by fitting a Cu(II) phthalocyanine spectrum (CuPc in ZnPc: S=1/2,
+A∥(Cu) ≈ 647 MHz, four equivalent 14N) — a system that hit every limit of
+`pepper`'s resonance solvers at once.  Every change below is validated against
+EasySpin on MATLAB R2024b through a new 34-case oracle,
+`tests/data/generate_pepper_cupc_refs.m` →
+`torchspin/tests/test_pepper_cupc_matlab_validation.py`, covering all three
+solvers on the same systems plus natural-abundance isotopologues, tilted and
+anisotropic ligand A tensors, nuclear quadrupole coupling, an enlarged exact
+core, and a two-component model.
+
+### Added — `Options.Method='hybrid'` (EasySpin `Opt.Method='hybrid'`)
+
+Exact diagonalization of a core — all electron spins plus the nuclei named in
+the new `Options.HybridCoreNuclei` (1-based, as in EasySpin) — with the
+remaining nuclei shifting and splitting the core lines.  This is the method for
+a large central hyperfine coupling surrounded by small ligand couplings, where
+the exact treatment is unaffordable and perturbation theory is wrong about the
+central coupling.  Cu + 4×14N needs a 648-dimensional Hilbert space exactly,
+which neither code can put in a fit loop; as hybrid the core is 8-dimensional
+and each nitrogen is a 3×3 problem, and the spectrum takes **0.27 s against
+EasySpin's 0.28 s**.
+
+The implementation follows `resfields.m`: the electron spin operators in the
+hyperfine term are replaced by their expectation values in the two core
+eigenstates at the resonance field, and the resulting nuclear sub-Hamiltonian
+is then diagonalized *exactly*, so the quadrupole and nuclear Zeeman terms and
+the nuclear state mixing are not approximated.  Line amplitudes come from the
+Mims overlap matrix |⟨u_r|v_c⟩|², sub-lines below
+`Options.HybridIntThreshold` (0.005, as EasySpin) are dropped, and the nuclei
+are combined by an outer sum of shifts and an outer product of amplitudes.
+Matches EasySpin's hybrid to cosine 0.9998 on every case.
+
+Against the exact `matrix` result hybrid reaches cosine 0.9805 (Cu + 1×14N) and
+0.9740 (Cu + 2×14N).  **EasySpin's own hybrid gives 0.982 and 0.974 on the same
+comparison** — that gap is the method's first-order decoupling, not a port
+defect.  Second-order perturbation theory gives 0.896 and 0.918 on the same
+systems.  See § Pepper in `KNOWN_LIMITATIONS.md` for when to use which.
+
+### Added — `pepper` supports sets of equivalent nuclei
+
+`SpinSystem.n > 1` now works on the `hybrid` and `perturb` paths, which treat
+nuclei one at a time and combine them combinatorially, so a multiplicity is a
+pure saving rather than an obstacle: four equivalent 14N written as `n=[1,4]`
+take 0.30 s instead of 2.0 s and agree with four explicit nitrogens to cosine
+0.99999999.  A set of `n` equivalent nuclei shares one sub-Hamiltonian, so its
+copies are combined once by multiset enumeration — for four 14N that is 495
+combinations instead of 9⁴ = 6561.
+
+The `matrix` path still rejects `n > 1`, since there the nuclei multiply the
+Hilbert space and cannot be collapsed.  EasySpin's `pepper` rejects `n > 1` for
+every method, so this goes beyond it.
+
+### Fixed — `Method='matrix'` crashed on highly degenerate systems
+
+`pepper(Sys, Exp)` on S=1/2 Cu + 4 equivalent 14N aborted with
+`torch._C._LinAlgError: linalg.eigh: (Batch element 5): The algorithm failed to
+converge … too many repeated eigenvalues (error code: 394590)` after 13 s.  One
+matrix out of a batch of 59 complex 648×648 Hermitians: the input is Hermitian
+to 0.0 and finite, but LAPACK's divide-and-conquer driver stalls on the
+hundreds of exactly equal eigenvalue gaps that four identical nuclei produce.
+
+`_linalg.eigh` and `_linalg.eigvalsh` had no error handling, so one bad matrix
+killed the whole orientation batch.  They now retry a rejected batch matrix by
+matrix — the torch routine alone, then NumPy (a different LAPACK build, and
+`zheevr`/`zheev` rather than divide-and-conquer), then a 1e-14 relative diagonal
+perturbation that breaks the exact ties.  Spectra are invariant under unitary
+rotations inside a degenerate subspace, so none of these changes the result
+beyond round-off.  On the autograd path the NumPy detour is skipped, because it
+would silently drop gradients.
+
+### Fixed — `Options.IsoCutoff` had no effect
+
+`expand_components` passed the cutoff as the second positional argument of
+`isotopologues`, which is `n`, so it was silently discarded and pruning always
+used the 1e-4 default.  Affected `pepper` and `garlic`.  No test caught it
+because every test passed `rel_threshold` by keyword.
+
+### Fixed — the perturbation path built a Hamiltonian it never used
+
+`pepper` built the full `H0`/`mux`/`muy`/`muz` operators before dispatching on
+`Options.Method`, but `resfields_perturb_batch` works from the spin system and
+never receives them.  For Cu + 4×14N that is a 648×648 Kronecker product
+costing about 80 % of the run time, repeated for every isotopologue — which is
+why the cost barely depended on `GridSize`.  They are now built on first use.
+Natural-abundance Cu + 4×N at `[91,4]` goes from **2.70 s to 0.41 s**, now
+faster than EasySpin's 0.71 s, with bit-identical output (verified on 14 systems
+spanning both solvers, strain broadening and multi-component input).
+
+### Fixed — `Options.Method` accepted perturbation orders `pepper` cannot run
+
+`'perturb3'`, `'perturb4'` and `'perturb5'` were accepted and silently run as
+second order, and the requested order was never passed to the solver at all, so
+`'perturb1'` also ran second order.  `pepper` now rejects the orders it does not
+implement and forwards the order it does, and the `Options.Method` docstring
+describes the methods per simulator instead of claiming `'perturb'` means fifth
+order everywhere (that is garlic's convention; pepper's `'perturb'` is second
+order, as in EasySpin).
+
+### Fixed — two examples did not compute what they claimed
+
+`examples/solidstate/copper_nitrogens.py` was titled "Four Equivalent 14N
+Ligands" and labelled its plot "4×14N" while simulating **two**, and had dropped
+the `AFrame` tilts that make the four nitrogens inequivalent in the first place.
+It is now the system from the EasySpin original (Buchanan & Dismukes 1987) and
+shows `perturb` against `hybrid`.  `examples/solidstate/matrixperturb.py` ran
+the matrix method twice, labelled one curve "perturb", and carried a comment
+claiming perturbation theory "is not yet exposed as a pepper option in
+torchspin" — untrue since 0.2.x.  It now calls `Method='perturb'`.
+
+### Fixed — concurrent eigendecompositions could corrupt the thread count
+
+`_linalg._pooled` and `pool_map` save, set and restore `torch.set_num_threads`,
+which is process-global.  `esfit` evaluates objective functions in a thread
+pool, so two concurrent batches could interleave and leave the process pinned
+at one intra-op thread for the rest of the session.  Both now hold a lock
+across the critical section.
+
+### Added — `grid_convergence`, to answer whether `Options.GridSize` is enough
+
+The default `GridSize=[19,4]` is badly unconverged for a narrow line on a large
+hyperfine coupling — for the reported Cu(II) case the derivative peak is 3 % out
+at `[19,4]` and still moving 4 % between `[91,4]` and `[361,4]`, in EasySpin
+equally — and a single spectrum gives no hint of it.
+
+`torchspin.grid_convergence(sys, exp, opt)` simulates again on a `refine`×
+finer coarse grid and reports the cosine and amplitude change, with
+`.converged` against tolerances a tenth of the repository's parity bar, and
+`.report()` giving a sentence that names a grid to use.
+
+A heuristic was tried first and deliberately abandoned: comparing the field step
+between knots against the linewidth sounds right, but the SOPHE projection
+integrates analytically over each grid segment, so a large step per knot is
+normal and harmless. That heuristic flagged ~60 simulations in this repository's
+own suite which agree with EasySpin to cosine 0.9999. A check that cries wolf on
+validated-correct cases is worse than none, so the honest version costs a second
+simulation and is opt-in rather than a warning inside `pepper`.
+
+### Fixed — `torchspin.fitgui` now says which extra to install
+
+`FitPanel(...)` failed with a bare `ModuleNotFoundError: No module named
+'ipywidgets'` and no hint that an optional dependency group provides it.  The
+imports now raise an `ImportError` naming the module, what it is needed for, and
+`pip install "torchspin[gui]"`.
+
+The `gui` extra was also incomplete: it omitted `ipython`, which
+`FitPanel.show()` needs, and `cloudpickle`, which the panel's own `n_workers`
+control needs.  Both are now in it, and `ipywidgets` is in `test` and `dev` so
+the four `test_fitgui.py` tests run instead of skipping.
+
+### Fixed — `vary` could put a linewidth or a weight below zero
+
+`vary` becomes `p0 ± vary`, so `Vary.lw = 1` around `lw = 0.54`, or
+`Vary.weight = 0.2` around `weight = 0.001` — both taken from a real fit script
+— handed the optimizer a negative lower bound for a quantity that cannot be
+negative.  In the dict style the field name is known, so the lower bound is now
+clipped at zero for `lw`, `lwpp`, `lwEndor`, `HStrain`, `gStrain`, `AStrain`,
+`DStrain`, `weight`, `tcorr`, `Diff`, `T1` and `T2`, which is what EasySpin's
+`esfit` does (`nonnegFieldNames`).  Explicit `lb`/`ub` are still used exactly as
+given — clipping a bound the user stated would be worse than the problem.
+
+A plain parameter vector carries no field names, so neither `esfit` nor
+`FitSession` can clip there, as in EasySpin; both docstrings now say so and
+point at `lb`/`ub`.
+
+### Fixed — `eprload` units are now documented where they bite
+
+`eprload` returns the abscissa in the file's own units, so a Bruker field axis
+is in **gauss** while the rest of torchspin works in mT.  That is deliberate and
+matches EasySpin, and it was recorded in `KNOWN_LIMITATIONS.md` — but the
+`eprload` docstring said only "Abscissa (magnetic field, time, frequency,
+etc.)", which is where a user actually looks before feeding the axis straight
+into `Experiment.Range`.  The docstring now states the units per format, shows
+the `/ 10` conversion in a worked example, and notes that the file's own unit
+string survives in `params`.
+
+`eprload_info` now prints the unit and, for a gauss axis, that it needs dividing
+by 10 (it also no longer crashes on multi-dimensional data, where `x` is a list
+of axes and `y` can be a list of datasets).
+
+### Documented — derivative amplitude at a turning point is grid-limited
+
+Investigated because it first looked like a parity defect of the exact solver,
+and turned out not to be one.  Comparing Cu + 1×14N by `matrix` against EasySpin
+at `GridSize=[91,4]` gives cosine 0.99948 but amplitude 0.990, and 0.978 at two
+nitrogens — outside the 2 % amplitude convention.  Refining the grid removes it:
+0.9903 → 0.9978 → **1.0010** and cosine 0.99948 → 0.99998 → **1.00000** over
+`[91,4]` → `[181,4]` → `[361,4]`.
+
+Neither code is converged at `[91,4]`: EasySpin's own derivative peak moves
+53.70 → 51.62 → 51.44 across the same refinement, a 4 % change in its own
+answer.  The two are simply unconverged by slightly different amounts.  The
+derivative extremum at a turning point is the most grid-sensitive quantity in a
+powder spectrum, much more so than the integrated intensity.
+
+Absolute intensity agrees throughout, including with nuclei: integrated
+absorption against EasySpin is 578.38/578.38, 559.77/559.90 and 535.49/534.99
+for 0, 1 and 2 nitrogens (0.02–0.09 %), and absorption peak heights agree to
+0.2–0.8 %.  That the integral falls as nuclei are added is real but **EasySpin
+does the same to 0.1 %** — it is the matrix method's transition pre-selection
+dropping weak transitions, and both codes select exactly the same number of
+level pairs (60 and 215).  `hybrid` and `perturb` hold at 578 because they put
+all the nuclear intensity on the core lines.
+
+The two `cupc_*_2N_matrix` cases are kept at `[91,4]` with the amplitude
+tolerance set to the measured grid error, as the regression anchor for this.
+
+### Added — `benchmarks/python/cupc_claims.py`
+
+Reproduces the five reported defects and records the measured before/after
+state, so the performance claims have a ledger rather than an anecdote.
+
 ## [0.3.0] — 2026-10-04
 
 First public release.
@@ -49,7 +421,7 @@ one; none changes any numerical result.
   interrupted=False` with SciPy's message; a stop or interrupt returns the
   best point so far with `interrupted=True`; `n_iterations` is the
   Jacobian-evaluation count (one per trust-region iteration). TRF is an
-  optimisation method, not a CPU-acceleration feature: it runs sequentially;
+  optimization method, not a CPU-acceleration feature: it runs sequentially;
   simulation threading and the population-worker `n_workers` parallelism are
   separate. The default method is unchanged (`simplex`). Parity with a direct
   `scipy.optimize.least_squares` call is tested (`tests/test_esfit_trf.py`).
@@ -71,7 +443,7 @@ one; none changes any numerical result.
   `SpinSystem` built from a template, on the autograd graph when the vector
   requires grad), `simulate`/`simulate_batch` (any differentiable simulator,
   `(N, nPoints)` output, optional spawned pool for no-grad generation),
-  `SpectrumDataset` (seeded on-the-fly samples with resampling, normalisation,
+  `SpectrumDataset` (seeded on-the-fly samples with resampling, normalization,
   noise and baseline), and torch losses (`cosine_loss`, `rmsd`, `normalize`,
   `resample`) so network predictions can be refined through the simulators.
 - `convspec` accepts tensor widths: differentiable ones are routed to the
@@ -98,7 +470,7 @@ one; none changes any numerical result.
 - `pepper_autograd` / `differentiable_spectrum` handle strains (HStrain,
   gStrain, AStrain, DStrain): the per-transition widths from
   `compute_strain_widths_batch` are already torch, and the EasySpin summation
-  branch (facet centres, spread-smoothed widths, bin-integrated Gaussians —
+  branch (facet centers, spread-smoothed widths, bin-integrated Gaussians —
   `gaussian_bins_t`) is now torch too. Forward equals `pepper()` to 2e-12 on
   nitroxide HStrain+gStrain (D2h), axial gStrain (Dinfh), AStrain and S=1
   DStrain cases; gradients vs finite differences of `pepper()` 1e-6–1e-8 for
@@ -125,11 +497,11 @@ one; none changes any numerical result.
   autograd graph for g, A, Q, tcorr/logtcorr and lw/lwpp. Forward unchanged to
   1e-9 (Fremy's salt, nitroxide fast motion, methyl perturb2, frequency sweep,
   Temperature, Harmonic 2, ModAmp); gradients vs finite differences 1e-8
-  (`test_garlic_autograd.py`; the fine accumulation grid is re-discretised with
+  (`test_garlic_autograd.py`; the fine accumulation grid is re-discretized with
   the smallest width, so tcorr finite differences need a step within one
-  discretisation).
+  discretization).
 - `Options.AccumMethod='linear'` (EasySpin `makespec`: a line is split between
-  its two neighbouring bins) is the differentiable form of the default
+  its two neighboring bins) is the differentiable form of the default
   nearest-bin stick spectrum and is selected automatically when the spin
   system carries grad tensors; it differs from nearest-bin binning by the
   sub-bin quantisation only (≈(Δx/2)/σ relative, 1 % for a 0.3 mT Gaussian at
@@ -177,8 +549,8 @@ one; none changes any numerical result.
   pepper 0.9998–1.0000 / 0.999). Training a CNN on their output was training on
   a model that differs from pepper/EasySpin by more than the features to learn.
 - `SpinSystem` keeps tensors that `requires_grad` (no copy) and accepts lists of
-  tensors (`g=[g_tensor]`, `A=[[ax, ay, az]]`), so parameters can be optimised
-  through the regular simulators; `resfields_batch` Boltzmann normalisation is
+  tensors (`g=[g_tensor]`, `A=[[ax, ay, az]]`), so parameters can be optimized
+  through the regular simulators; `resfields_batch` Boltzmann normalization is
   out of place (autograd through `exp`); `hamsymm` detaches before comparing.
 - Not yet differentiable: strains, `ModAmp`, `mwPhase`, ordering,
   photoselection, crystals, frequency sweeps (`pepper_autograd` raises
@@ -263,11 +635,11 @@ notebooks 01–08, benchmark report against MATLAB/EasySpin. Details below.
 ### Changed — performance round 1 (2026-09-02)
 Results are unchanged (MATLAB parity suites and the full test suite green after
 every step; resonance positions within 1e-11 mT of the previous search).
-- `resfields_batch`: one exact diagonalisation per resonance candidate at the
+- `resfields_batch`: one exact diagonalization per resonance candidate at the
   cubic-model root (EasySpin's scheme) with a free Hellmann–Feynman Newton
   correction, instead of three polish evaluations plus a final pass; the
   transition eigenvectors are gathered there and reused for intensities;
-  knot and candidate diagonalisations chunked to ~400 MB; per-orientation
+  knot and candidate diagonalizations chunked to ~400 MB; per-orientation
   reassembly and strain widths as tensor ops (one host sync per call).
 - `torchspin/_linalg.py`: batched `eigh`/`eigvalsh` split over a thread pool of
   single-threaded LAPACK calls (torch loops serially over CPU batches; 21–23×
@@ -294,7 +666,7 @@ every step; resonance positions within 1e-11 mT of the previous search).
   Lanczos/direct/eigen solvers, field-sweep methods, post-convolution nuclei,
   multi-component input; 60-case MATLAB suite (59 at cosine ≥0.999).
 - `pepper`: first-principles absolute intensity (dBdE, nuclear-sublevel
-  sharing, density normalisation) — the empirical scale factors are gone;
+  sharing, density normalization) — the empirical scale factors are gone;
   symmetry-frame fix for tilted axial tensors; level-pair transition
   bookkeeping and EasySpin's strain summation on the interpolated grid;
   Delaunay triangulation, rectified interpolation and projection for the
@@ -335,7 +707,7 @@ every step; resonance positions within 1e-11 mT of the previous search).
 ### Changed — EasySpin parity round 3
 - `cardamom`: field-swept spectra no longer apply `Experiment.Harmonic`
   (EasySpin returns the imaginary FFT of the time-weighted FID); the output
-  scale follows EasySpin's double orientation normalisation; the jump model
+  scale follows EasySpin's double orientation normalization; the jump model
   no longer requires a correlation time.
 - `hamsymm`: principal-value equality at 1e-12 relative (was `torch.allclose`).
 - `FitOptions.lm_delta` default 1e-3 and `lm_gradient_tol` 1e-5 (EasySpin).
@@ -356,8 +728,8 @@ every step; resonance positions within 1e-11 mT of the previous search).
   (sub-increment widths differed by up to 3.7× from the analytic kernel).
 - pepper: resonances were matched across orientations by list index;
   strain widths were evaluated at one field per orientation; slots with
-  missing resonances were filled from neighbours; isotropic systems and
-  frequency sweeps had wrong normalisation/units; single components ignored
+  missing resonances were filled from neighbors; isotropic systems and
+  frequency sweeps had wrong normalization/units; single components ignored
   `Sys.weight`.
 
 ### Added — EasySpin port completion (2026-09-01)
@@ -457,7 +829,7 @@ every step; resonance positions within 1e-11 mT of the previous search).
 - `TestAutoTargetAndGlobal` and `TestSimplexExploration` regression tests
   in `tests/test_esfit.py` (6 new tests total).
 - `benchmarks/PERFORMANCE_SUMMARY.md` and `benchmarks/RUNLOG_2026-04-20.md`
-  (development records, not distributed; their results are summarised in
+  (development records, not distributed; their results are summarized in
   `benchmarks/results/BENCHMARK_REPORT.md` and embedded in
   `benchmarks/analysis/make_manuscript_figures.py`)
   — performance and accuracy summary (MATLAB parity
@@ -518,5 +890,8 @@ ported to Python/PyTorch with 1820+ passing tests.
 - Euler angles: radians, z-y'-z'' passive rotation
 - Default dtype: `torch.complex128`
 
-[Unreleased]: https://github.com/follmerlab/torchspin/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/follmerlab/torchspin/releases/tag/v0.1.0
+<!-- 0.3.0 was the first public release and the history before it was squashed,
+     so v0.1.0-v0.2.2 have no tags in this repository to link to. -->
+[0.5.0]: https://github.com/follmerlab/torchspin/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/follmerlab/torchspin/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/follmerlab/torchspin/releases/tag/v0.3.0

{torchspin-0.3.0 → torchspin-0.5.0}/CITATION.cff

@@ -2,15 +2,22 @@ cff-version: 1.2.0
 message: "If you use torchspin in your research, please cite both torchspin and the upstream EasySpin paper."
 title: "torchspin: Differentiable PyTorch port of EasySpin for EPR spectroscopy"
 type: software
-version: "0.3.0"
-date-released: "2026-10-04"
+version: "0.5.0"
+date-released: "2026-10-19"
 license: MIT
 authors:
   - family-names: "Follmer"
     given-names: "Alec"
     email: "ahfollmer@ucdavis.edu"
 repository-code: "https://github.com/follmerlab/torchspin"
-url: "https://github.com/follmerlab/torchspin"
+preferred-citation:
+  type: article
+  authors:
+    - family-names: "Follmer"
+      given-names: "A. H."
+  title: "TorchSpin: Differentiable Electron Paramagnetic Resonance Simulation in PyTorch"
+  journal: "arXiv preprint arXiv:2610.18924"
+  year: 2026
 keywords:
   - "EPR"
   - "ESR"
@@ -18,9 +25,9 @@ keywords:
   - "spin-Hamiltonian"
   - "pytorch"
   - "autograd"
+  - "differentiable simulation"
   - "magnetic resonance"
   - "EasySpin"
-
 references:
   - type: article
     title: "EasySpin, a comprehensive software package for spectral simulation and analysis in EPR"