torchspin 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -4,6 +4,219 @@ 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.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 +262,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 +284,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 +311,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 +338,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 +390,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 +476,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 +507,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 +548,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 +569,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 +670,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 +731,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. -->
+[Unreleased]: https://github.com/follmerlab/torchspin/compare/v0.4.0...HEAD
+[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.4.0}/CITATION.cff

@@ -2,8 +2,8 @@ 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.4.0"
+date-released: "2026-10-09"
 license: MIT
 authors:
   - family-names: "Follmer"

torchspin-0.4.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: torchspin
+Version: 0.4.0
+Summary: Differentiable PyTorch port of EasySpin - EPR/ESR spin Hamiltonian and spectrum simulation
+Author-email: Alec Follmer <ahfollmer@ucdavis.edu>
+Maintainer-email: Alec Follmer <ahfollmer@ucdavis.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/follmerlab/torchspin
+Project-URL: Source, https://github.com/follmerlab/torchspin
+Project-URL: Issues, https://github.com/follmerlab/torchspin/issues
+Project-URL: Upstream (EasySpin), https://easyspin.org
+Keywords: EPR,ESR,spectroscopy,spin-Hamiltonian,pytorch,autograd,magnetic-resonance,quantum,EasySpin,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: torch<3,>=2.0
+Requires-Dist: numpy<3,>=1.23
+Requires-Dist: scipy>=1.10
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: fit
+Requires-Dist: cloudpickle>=2.0; extra == "fit"
+Provides-Extra: gui
+Requires-Dist: ipywidgets>=7.6; extra == "gui"
+Requires-Dist: matplotlib>=3.6; extra == "gui"
+Requires-Dist: ipympl>=0.9; extra == "gui"
+Requires-Dist: ipython>=7; extra == "gui"
+Requires-Dist: cloudpickle>=2.0; extra == "gui"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: matplotlib>=3.6; extra == "test"
+Requires-Dist: cloudpickle>=2.0; extra == "test"
+Requires-Dist: ipywidgets>=7.6; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+Requires-Dist: cloudpickle>=2.0; extra == "dev"
+Requires-Dist: ipywidgets>=7.6; extra == "dev"
+Dynamic: license-file
+
+# torchspin
+
+**Simulate and fit EPR/ESR spectra in Python — differentiable, GPU-capable, and validated against [EasySpin](https://easyspin.org).**
+
+[![PyPI](https://img.shields.io/pypi/v/torchspin)](https://pypi.org/project/torchspin/)
+[![Python](https://img.shields.io/pypi/pyversions/torchspin)](https://pypi.org/project/torchspin/)
+[![Tests](https://github.com/follmerlab/torchspin/actions/workflows/python-tests.yml/badge.svg)](https://github.com/follmerlab/torchspin/actions/workflows/python-tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+
+torchspin reimplements the core physics engine of EasySpin (MATLAB) in
+Python/PyTorch. You get the simulators you already know — `pepper`, `garlic`,
+`chili`, `salt`, `saffron`, `curry`, `cardamom`, `esfit` — with the same units
+and conventions, plus three things MATLAB cannot give you:
+
+- **Gradients.** Spectra are differentiable end to end, so you can fit with
+  gradient descent, propagate uncertainty, or put a simulator inside a neural
+  network.
+- **A Python workflow.** NumPy and torch tensors in and out, no license server,
+  installable with `pip`.
+- **Optional GPU.** `Options(device='cuda')` for batched and gradient-based
+  work.
+
+torchspin is a reimplementation, not a drop-in replacement for every EasySpin
+feature. Before relying on it for published results, read
+[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) — it states per simulator what is
+validated against MATLAB and what is not.
+
+---
+
+## Installation
+
+```bash
+pip install torchspin                 # core
+pip install "torchspin[plot]"         # + matplotlib for the plotting helpers
+pip install "torchspin[gui]"          # + the interactive fitting panel (torchspin.fitgui)
+```
+
+CPU-only PyTorch, to avoid the large CUDA wheels:
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install torchspin
+```
+
+Requires Python 3.10+, PyTorch 2.0+, NumPy 1.23+, SciPy 1.10+.
+
+---
+
+## Quick start
+
+### CW powder spectrum (`pepper`)
+
+```python
+from torchspin import SpinSystem, Experiment, Options, pepper
+
+sys = SpinSystem(
+    S=[0.5],
+    g=[[2.009, 2.006, 2.002]],
+    Nucs=['14N'],
+    A=[[10.0, 10.0, 95.0]],   # MHz
+    lw=[1.0, 0.0],            # Gaussian FWHM (mT)
+)
+exp = Experiment(mwFreq=9.5, Range=[330, 350], nPoints=1024, Harmonic=1)
+B, spec = pepper(sys, exp, Options(GridSize=50))
+```
+
+### Solution EPR (`garlic`)
+
+```python
+from torchspin import SpinSystem, Experiment, garlic
+
+sys = SpinSystem(S=[0.5], g=2.003, Nucs='1H', A=10.0, lw=[0.2, 0.0])
+exp = Experiment(mwFreq=9.5, Range=[336, 342], nPoints=512, Harmonic=1)
+B, spec = garlic(sys, exp)
+```
+
+### Fitting (`esfit`)
+
+```python
+import numpy as np
+from torchspin import esfit, FitOptions
+
+def model(p):
+    sys_mod = SpinSystem(S=[0.5], g=[[p[0], p[1], p[2]]], lw=[1.0, 0.0])
+    _, spc = pepper(sys_mod, exp, Options(GridSize=31, Verbosity=0))
+    return spc.numpy()
+
+result = esfit(
+    data_measured, model,
+    p0=np.array([2.00, 2.10, 2.20]),
+    lb=np.array([1.95, 2.05, 2.15]),
+    ub=np.array([2.05, 2.15, 2.25]),
+    options=FitOptions(method='global', progress='text'),
+)
+print('Best-fit g:', result.pfit)
+```
+
+`progress='text'` prints RMSD, evaluation count and ETA as it runs, and
+interrupting the kernel returns the best fit so far. Population-based methods
+parallelize over processes with `FitOptions(n_workers='auto')`.
+
+### Differentiable spectrum
+
+```python
+import torch
+from torchspin import differentiable_spectrum
+
+g = torch.tensor([2.0, 2.1, 2.2], dtype=torch.float64, requires_grad=True)
+B, spec = differentiable_spectrum(g, mwFreq_GHz=9.5, B_range=(300, 380),
+                                  nPoints=512, lw_mT=1.0)
+loss = ((spec - target_spec) ** 2).sum()
+loss.backward()
+print('dL/dg:', g.grad)
+```
+
+---
+
+## Units and conventions
+
+These match EasySpin, so parameters transfer directly:
+
+| | |
+|---|---|
+| Energy | MHz |
+| Magnetic field | mT |
+| Euler angles | radians, z-y'-z'' **passive** rotation |
+| Basis ordering | m = S, S−1, …, −S (descending) |
+| Default dtype | `torch.complex128` |
+
+---
+
+## What's included
+
+| Category | Modules |
+|----------|---------|
+| CW EPR | `pepper` (powder; `matrix`, `perturb` and `hybrid` resonance solvers, `grid_convergence` to check `GridSize`), `garlic` (solution), `chili` (slow-motion), `salt` (ENDOR) |
+| Pulse EPR | `saffron` (ESEEM/HYSCORE), `spidyan` (arbitrary sequences), `saffron_thyme` (real pulses) |
+| Trajectory | `cardamom` (MD/diffusion/jump), `mdload`, `mdhmm` |
+| Magnetometry | `curry` (susceptibility, magnetization) |
+| Fitting | `esfit` — 10 methods (simplex, L-BFGS-B, Powell, Levenberg–Marquardt, trust-region reflective, grid, Monte Carlo, genetic, swarm, and `global` = swarm + simplex polish); `torchspin.fitgui` interactive panel |
+| Autograd | `differentiable_spectrum`; `pepper`, `garlic`, `salt`, `saffron` and `curry` are differentiable |
+| Machine learning | `torchspin.ml` — parameter packing, batched simulation, datasets, differentiable losses |
+| Data I/O | `eprload` (14 vendor formats), `eprsave` (BES3T), `orca2torchspin` |
+| Batch / GPU | `batch_pepper`, `batch_simulate`; `Options(device='cuda')` |
+
+---
+
+## Tutorials
+
+Start with `01_torchspin_quickstart.ipynb`, then branch to autograd or fitting
+depending on what you need. Full index: [docs/index.md](docs/index.md).
+
+| Notebook | What it covers |
+|---|---|
+| `01_torchspin_quickstart` | Core API: spin systems, Hamiltonians, powder and solution spectra |
+| `02_gpu_and_autograd` | GPU execution and differentiable spectra |
+| `03_spectral_fitting` | Parameter recovery with `esfit` |
+| `04_benchmarks` | Timings against MATLAB/EasySpin |
+| `05_fitting_real_world` | Bad starting guesses, loss landscapes, global vs local search |
+| `06_blue_copper_fitting` | End-to-end Cu(II) case study |
+| `07_easyspin_parity` | Overlays against stored EasySpin references |
+| `08_pepper_playground` | Simulate, add noise, fit with every `esfit` method |
+| `09_fit_gui` | Interactive fitting panel: sliders, live fit, RMSD trace |
+
+They live in `examples/notebooks/`, with scripted equivalents of EasySpin's
+example collection in `examples/{solidstate,liquids,slowmotion,endor,fitting,magnetometry}`.
+
+---
+
+## Accuracy and performance
+
+Every simulator with an EasySpin counterpart is checked against stored MATLAB
+reference output on each commit. Agreement is cosine ≥ 0.999 (most
+0.9999–1.0000) for `pepper`, `garlic`, `salt`, `saffron`, `spidyan` and
+`curry`, with absolute intensities matched where EasySpin defines them.
+`chili` and the stochastic `cardamom` have documented caveats. Details per
+simulator, with the evidence: [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).
+
+On speed, torchspin is competitive rather than uniformly faster. On an audited
+nine-workload comparison it beat EasySpin on six — most strongly on
+slow-motion `chili` (7.3×) and trajectory `cardamom` (2.0×) — and was slower on
+three, including matrix-method Cu(II) powders (0.34×). The GPU path pays off
+for batched and gradient-based work, not for single simulations. Numbers,
+replicates and a per-workload device audit:
+[BENCHMARK_VERIFICATION.md](benchmarks/results/workstation_20260904_verified/BENCHMARK_VERIFICATION.md).
+
+---
+
+## Citation
+
+If you use torchspin in published work, please cite both:
+
+- **EasySpin**, the MATLAB toolbox this port is based on —
+  Stoll, S. & Schweiger, A. *J. Magn. Reson.* **178** (2006) 42–55.
+- **torchspin** — see [CITATION.cff](CITATION.cff).
+
+---
+
+## Contributing
+
+Bug reports, documentation fixes and pull requests are welcome. Development
+install and the test layout are in [CONTRIBUTING.md](CONTRIBUTING.md):
+
+```bash
+git clone https://github.com/follmerlab/torchspin.git
+cd torchspin
+pip install -e ".[dev]"
+pytest -q -m "not slow" -k "not matlab_validation"   # fast pass, ~4 min
+```
+
+The MATLAB reference data ships in the repository but not in the PyPI package,
+so the cross-validation suite only runs from a checkout.
+
+---
+
+## Related
+
+- [EasySpin](https://easyspin.org) — the MATLAB reference implementation
+- [PyTorch](https://pytorch.org) — the autograd engine
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md). torchspin is derived from EasySpin, which is
+also MIT licensed; both copyrights are reproduced there.