Spynach

• Python conveniences, no MATLAB licence. Spynach is a pip-installable package that slots into the scientific Python stack: combine it with NumPy, SciPy, fitting and machine-learning libraries or your own code, run it on any machine with nothing to buy or activate, or open the quick-start notebook in the browser, where it installs itself in a click.
• A readable, maintainable kernel. The Spinach algorithms in plain Python with NumPy and SciPy, with the same names and conventions wherever that is possible.
• Verified, not eyeballed. Every ported stage is compared with reference data computed by Spinach itself, with tolerances that are stated and explained.
• Ready for accelerators. The hot loops go through one backend adapter so that a GPU array library can be plugged in; that step is deferred until a target device is chosen.
• Later: a differentiable engine for optimal control and fitting, and possibly a tensor-train backend for chain-like coupling topologies.

• An oracle harness. MATLAB dump scripts write the intermediate results of a Spinach calculation to HDF5 fixtures; parity tests load them and compare the Python results at each stage (oracle/README.md).
• Stage by stage. Spin system, basis, operators, Hamiltonian, propagation, relaxation, contexts, pulse sequences: each lands with its fixtures, tests and documentation before the next starts (roadmap).
• Two formalisms behind one basis abstraction. Dense Zeeman-Hilbert space for small systems, the spherical-tensor Liouville space with state-space restriction (IK-0, IK-1, IK-2) for large liquid-state systems.
• Nothing silently ignored. Any Spinach option that is not yet ported raises an error rather than being dropped.
• Executable documentation. Every guide's code blocks run in the test suite and are rendered into notebooks with their outputs.

Spynach derives from Spinach 2.13, the spin dynamics package of Ilya Kuprov and co-workers, released under the MIT licence. The translation keeps the Spinach attribution and notice in LICENSE, and keeps Spinach's function names, parameter structures and tolerances so that an existing Spinach script maps onto Spynach line by line.

The deliberate differences are small: spin indices are 0-based, product and sum operators are told apart by the type of the first argument, spin system objects are immutable, and time series are 1-D arrays. The guide Coming from Spinach lists, feature by feature, what is the same, what differs and what is not yet ported.

The translation from MATLAB to Python was carried out largely by an AI coding agent working under the direction of Alexej Jerschow, who set the goals and reviewed the results; correctness rests on the test suite against Spinach reference data.

• Coherence transfer pathway selection. ctps, a separate module in the repository (import ctps, no dependency on spynach), ports the CCCP.m and CCCP++ programs: every pathway a sequence allows, weighted by phase cycle, gradients, diffusion and pulses, ranked and drawn in an interactive explorer that steps through the pathways with their factors (guide, notebook).
• Non-ideal pulses and cogwheel search. Each pulse is a perfect 180°, an imperfect 180° or a small-flip-angle pulse, with the leakage of every coherence transfer after J. Chem. Phys. 113, 979 (2000); cogwheel cycles are found by exact integer arithmetic, all winding numbers tested at once, and crusher schemes by the DOTCOPS objective.
• Interactive figures. Plotly figures from every plotting function, FID and time-series plots with no Spinach equivalent, and figure_png for static copies.
• Verification tooling. compare checks any result against a Spinach run; the parity page is regenerated from the test suite; the comparison protocol times and profiles both sides into one report.
• Executable documentation. Guides whose code runs in the tests, notebooks generated with outputs, a Colab quick start, contributed notebooks.

All of it, with an example for each entry, is in the guide Beyond the port.

Python 3.11 or newer. Install from the repository, or clone it and install in editable mode with the docs extra to open the notebooks.

pip install "spynach @ git+https://github.com/ajerschow/spynach.git"

# or, for the notebooks and tests
git clone https://github.com/ajerschow/spynach.git
cd spynach && pip install -e ".[docs,test]"

Two coupled protons at 14.1 T, pulse-acquire, exponential apodisation, two doublets:

import numpy as np
import spynach

spin_system = spynach.create(
    {"isotopes": ["1H", "1H"], "magnet": 14.1},
    {"zeeman": {"scalar": [1.00, 1.10]}, "coupling": {"scalar": [[0, 12.0], [0, 0]]}},
)
spin_system = spynach.basis(spin_system, {"formalism": "zeeman-hilb", "approximation": "none"})
pars = {"spins": ["1H"], "offset": 630, "sweep": 200, "npoints": 1024,
        "rho0": spynach.state(spin_system, "L+", "1H"),
        "coil": spynach.state(spin_system, "L+", "1H")}
fid = spynach.liquid(spin_system, spynach.acquire, pars, "nmr")
fid = spynach.apodisation(fid, [("exp", 6)])
spectrum = np.fft.fftshift(np.fft.fft(fid, 4096))

A caveat for containers: when the CPU quota is below the number of cores the container can see, OpenBLAS oversubscribes the quota and dense LAPACK calls slow down badly. Set OPENBLAS_NUM_THREADS to the quota there; on an ordinary machine nothing needs to be set.

To try the example without installing anything, open it as a notebook that installs Spynach and plots the spectrum:

Each guide is a Markdown document whose code runs in the test suite, and a Jupyter notebook generated from it with its outputs and interactive plots. The notebook links open in nbviewer, which renders the Plotly figures interactively; GitHub's own viewer shows the static copies saved with them.

The documentation index explains how the guides, notebooks and the examples fit together.

The guides run reduced versions of Spinach examples in seconds. The scripts in examples/ are the same calculations at the Spinach size, for side-by-side comparison with MATLAB: each writes its results next to itself and can report the normwise error against a .mat file saved by the Spinach script. Python code contributed by users lives in user_py/ as notebooks saved with their outputs.

The two full-size NOESY scripts and the two contributed scripts are also the cases of the timed parity and timing reports. Contributions to user_py/ keep their author's name in the file and in its README.

The parity suites compare Spynach with Spinach 2.13 fixtures at every stage of a calculation. Of the 540 tests, 323 are fixture comparisons over 45 fixture cases: Liouville-space setup (132), Liouville-space propagation (54), Hilbert-space pulse-acquire (64), anisotropic interactions (25), relaxation (20), scalar relaxation (9), magic angle spinning (16), pulse sequences (3). Comparisons are relative with zero absolute tolerance; the largest measured difference is 8e-11 for quantities compared at 1e-9 (time evolution and FIDs) and 9e-15 for everything compared at 1e-10 or tighter (operators, states, Hamiltonians, propagators). Every case, tolerance and measured difference is listed in docs/parity.md (regenerated from the suite by oracle/parity_summary.py).

Two full-size calculations are run on both sides under a profiler, on the same machine, and summarised in an HTML report with the stage timings, the normwise difference of every saved array, the figures and the profiler tops. The stage timings below are wall clock for each implementation as shipped: Spinach with its parallel pool and multithreaded BLAS, Spynach as a single process with multithreaded BLAS inside dense calls.

Both runs: Apple silicon Mac, 12 cores; MATLAB R2026b with an 11-worker pool; Python 3.12 with NumPy and SciPy on Accelerate. The protocol, including how to add a case, is in comparison/README.md.

Grateful to Claude for the amazing work, and to Ilya for encouragement and for suggesting the catchy name!