Home      Spinach

Spinach library

Spinach is a fast (polynomial complexity scaling for liquid state NMR) open-source spin dynamics simulation library that supports NMR, EPR, DNP, MAS, Optimal Control, PHIP, singlet state NMR and other forms of Magnetic Resonance spectroscopy. Spinach history and capabilities are summarized in the 2013 EPR Newsletter.

Version 1.8.3420 (latest version, 31 Aug 2016, documentation)
Version 1.7.2996
Version 1.6.2782
Version 1.5.2440

Please email Ilya Kuprov with any questions, feature requests or systems to simulate. The minimum supported version of Matlab is 2016a (64-bit version) with Parallel Computing Toolbox, Optimisation Toolbox and at least 16 GB of RAM. Spinach supports NVidia Tesla GPUs and large-scale (128+ cores) parallel deployments using Matlab Distributed Computing Server. Protein functionality requires 256 GB of RAM.

New features in version 1.8.3420

  • Major improvements in parallelisation efficency - single-threaded stages have been virtually eliminated from the kernel.
  • Kernel-wide support for NVidia Tesla GPUs; many types of calculations show a factor of ten improvement in speed when the GPU feature is enabled with a Tesla K40 card installed.
  • A revolutionary pseudocontact shift module that can extract the three-dimensional probability density of the paramagnetic centre from the experimental PCS data using a Tikhonov regularisation procedure (collaboration with Liza Suturina).
  • Multiple examples of paramagnetic tag probability density reconstructions from protein PCS data (collaboration with Gunnar Jeschke, Maxim Yulikov, Luca Garbuio, Liza Suturina, Daniel Haussinger and Kaspar Zimmermann).
  • A massively expanded and redesigned optimal control module, featuring quadratically converging regularised Newton-Raphson algorithm and major improvements in the implementation of quasi-Newton methods for both Krotov and GRAPE algorithms (collaboration with David Goodwin).
  • DANTE pulse sequence for fundamental frequency and quadrupolar overtone NMR experiments (collaboration with Marina Carravetta).
  • Magic angle spinning DNP functionality and examples (adapting the code donated by Frederic Mentink-Vigier). Please cite Fred's papers if you are using this functionality and consider adding him as a co-author.
  • Single crystal magic angle spinning functionality and examples (collaboration with Oliver Lafon and Julien Trebosc).
  • Multiple new DEER simulation examples (collaboration with Christiane Timmel, Jeffrey Harmer and Sabine Richert).
  • A bare-bones 3D MRI module using the Fokker-Planck formalism, supporting three-dimensional diffusion and stationary-flow hydrodynamics as well as quantum mechanics and linear chemical kinetics in every voxel. An example of a singlet state flow MRI simulation is provided (collaboration with Ahmed Allami and Giuseppe Pileio)
  • Pulse sequences and multiple examples for CP MAS simulations for fundamental frequency and quadrupolar overtone NMR experiments (collaboration with Marina Carravetta, Maria Concistre and Phil Williamson).
  • Reaction yield detected magnetic resonance module now supports Haberkorn and Jones-Hore recombination kinetics superoperators.
  • Pseudocontact shift fitting module now has the option of cycling through assignment ambiguities and selecting the assignment that yields the best fit.
  • A simple function for the calculation of spectrometer transfer matrix from a stack of waveforms sent to the AWG and a stack of waveforms measured at the sample point in optimal control experiments (collaboration with David Goodwin).
  • S2M and M2S pulse sequences and examples in the singlet state module (collaboration with Giuseppe Pileio and Malcolm Levitt).
  • Ultrafast NMR experiment simulation module now supports diffusion and stationary-flow hydrodynamics.
  • Improved chemical kinetics module and examples of 2D EXSY data fitting (collaboration with Dmitry Shishmarev and Philip Kuchel).
  • A few more examples of Karplus curve extraction from DFT dihedral angle scans in Gaussian (collaboration with Zenawi Welderufael).
  • Tikhonov regularisation L-curve analysis function using a fifth order spline with an option to use either linear or logarithmic coordinates.
  • A few convenience functions for representing Zeeman basis density matrices in spherical tensor basis sets.
  • An option to place unassigned spins into the band between 0 and -1 ppm during protein and nucleic acid NMR data import. This greatly assists with assigning the remaining peaks.
  • ORCA logs and cubes can now be parsed. Gaussian03/09 log parser function now detects error termination.

New features in version 1.7.2996

  • Detailed documentation wiki site.
  • Standalone Levante-Ernst thermalizer for relaxation superoperators.
  • Major efficiency improvements in the pseudocontact shift module when dealing with non-point unpaired electrons.
  • Floquet theory and Fokker-Planck theory (for single and double rotation solid state NMR) added as kernel contexts.
  • Tensor train matrix by full vector multiplication function added to the tensor train module (collaboration with Sergey Dolgov and Dmitry Savostyanov).
  • A standalone Krylov propagation module with an option to run on GPU.
  • Improved support for NVidia Tesla cards, propagator caching and memory management as well as assorted efficiency improvements and bug fixes throughout the code.
  • Shaped pulse functions in frequency-amplitude-time coordinates using Fokker-Planck formalism, including situations where gradients are present (collaboration with Mohammadali Foroozandeh and Gareth Morris).
  • Three- and four-pulse DEER sequences, pulse-acquire and Davies ENDOR sequence using orientation-selective soft pulses (collaboration with Nurit Manukovsky and Daniella Goldfarb).
  • Time-domain hard-pulse HYSCORE sequence (collaboration with Luke Edwards).
  • Quadrupolar overtone cross-polarization simulation examples (collaboration with Marina Carravetta).
  • Basic 1D, 2D and 3D imaging infrastructure with gradients, diffusion (both finite difference and Fourier derivative operators), flow and quantum mechanical treatment of spin dynamics using Fokker-Planck formalism (collaboration with Jean-Nicolas Dumez).
  • ROESY pulse sequence with ideal spin-lock in the NMR module (collaboration with Christina Thiele, Barbara Odell and Tim Claridge).
  • DNP field scan simulations supporting electrons of any spin, including gadolinium examples (collaboration with Bjorn Corzilius).
  • An efficient gadolinium ZFS parameter distribution integrator (collaboration with Nurit Manukovsky and Daniella Goldfarb).
  • Initial concentrations for the kinetics module can now be specified as input parameters rather than manually in the initial state.
  • Spin system energy level population profiling function.
  • Analytical standard results (in Mathematica) for the relaxation theory module in the example set.

New features in version 1.6.2782

  • BFGS-Krotov and regularized Newton-Raphson GRAPE algorithms in the Optimal Control module (written by David Goodwin). Standalone direct and inverted BFGS and SR1 Hessian update modules.
  • One-angle Lebedev and REPULSION grids, hemisphere and octant subsets for REPULSION grids.
  • Augmented exponential functions for the calculation of matrix exponential derivatives and chained integrals involving matrix exponentials (a collaboration with David Goodwin).
  • Generalized rotating frame transformation module permitting arbitrary order perturbation theory corrections to rotating frame transformations.
  • Chemical kinetics module now supports networks of first order chemical reactions as well as point-to-point coherence fluxes within a fixed spin system.
  • Sparse matrix exponentiation module takes advantage of sparse GPU algebra (NVidia cards only) in the forthcoming Matlab R2015b. An order of magnitude acceleration is observed for some solid state NMR simulations. The module also now uses a hash table based caching algorithm to avoid re-calculation of exponentials of previously encountered matrices. Standalone matrix hashing module added.
  • Interactive 2D spectral integration and slicing functions are now available, along with basic streak removal functionality.
  • Support for double-rotation solid state NMR and double-rotation overtone NMR using Fokker-Planck formalism (collaboration with Marina Carravetta).
  • New spectral fitting examples, including simultaneous multi-spectral fits (collaboration with Bruno Linclau, Giuseppe Pileio and Malcolm Levitt).
  • Symmetry factorization module now supports Hilbert space Hamiltonians.
  • Experimental support for 3D spatial diffusion and triple-axis gradient experiments using direct products of spin and spatial degrees of freedom. Examples of 1D images, 1D diffusion NMR and ultrafast COSY experiments (collaboration with Jean-Nicolas Dumez).
  • Multiple new auxiliary functions that streamline commonly occurring transformations and notation translations.
  • Auxiliary matrix based chemical yield integration algorithm implemented into the Spin Chemistry modules.
  • Out-of-phase ESEEM sequence added to the ESR pulse sequences.

New features in version 1.5.2440

  • Improved J-coupling estimation in the protein NMR module (collaboration with Zenawi Welderufael).
  • Native Tensor Train / DMRG module (collaboration with Dmitri Savostyanov and Sergey Dolgov).
  • Explicit numerical gradient and gradient sandwich functions with integration over the sample volume performed using auxiliary matrix methods (collaboration with Luke Edwards).
  • Periodic boundary conditions for the calculation of dipolar couplings in solid state NMR spectroscopy.
  • Two- and three-angle REPULSION grids and an implementation of SHREWD method for spherical integration grid weight assignment (collaboration with Hamid Khan and Malcolm Levitt).
  • Powerful new PCS module, supporting calculation of hyperfine and pseudocontact shifts using point and distributed electron formalisms, as well as extraction of electron probability distributions from experimental PCS data. The module also includes a volumetric plotter function for 3D scalar fields.
  • A streamlined chemical kinetics module, supporting EXSY calculations on whole proteins (collaboration with Joern Werner).
  • Major efficiency improvements in the calculation of Redfield relaxation superoperators, 2D and 3D NMR experiments on proteins.
  • Support for spin-0 particles that makes it convenient to simulate molecules with site-specific isotope substitution.
  • Significant expansion of DEER simulation functionality and several new examples (collaboration with Nurit Manukovsky and Daniella Goldfarb).
  • Examples of spectral fitting using Spinach (collaboration with Bruno Linclau).
  • Examples of quadrupolar overtone NMR simulations using Spinach (collaboration with Marina Carravetta and Phil Williamson).

New features in version 1.4.2114

  • Major efficiency, memory management and parallelization improvements throughout the code, particularly in the protein NMR module.
  • Rotor frame option for the Floquet theory module.
  • Protein J-coupling prediction module, based on graph-theoretical analysis of bonding patterns and a database of Karplus curves.
  • Scalar relaxation of the first kind is now available in the relaxation theory module.
  • Major expansion of the input validation code: all error messages in all functions are now clear and informative.
  • A large number of new example files, including an example simulation illustrating the presence of long-lived states in quadrupolar systems.

New features in version 1.3.1980

  • Zeeman basis set support in Hilbert, Liouville and Fokker-Planck spaces.
  • Experimental support for Tensor Train (aka DMRG, aka MPS) formalism via TT Toolbox (which should be downloaded separately from the developers' web site). This work is a collaboration with Ivan Oseledets, Dmitry Savostyanov and Sergey Dolgov. Hilbert space, Liouville space and Fokker-Planck space simulations are supported.
  • Protein 3D NMR experiments (HNCO, HNCOCA) and 3D contour plotting utility. On sufficiently powerful hardware (256 GB of RAM is a minimum) Spinach can now run liquid-state protein NMR simulations, including Redfield relaxation theory. Ubiquitin is supplied as an example (kindly provided by Griesinger group and BMRB).
  • Floquet theory module, supporting magic angle spinning calculations around a user-specified axis. Two- and three-angle spherical grid averaging options in rotor frame and magnet frame respectively. This module has mostly been developed by Luke Edwards.
  • Infinite order average Hamiltonian theory option (via matrix logarithms) in the average Hamiltonian theory module.
  • Weizmann DNP option in the relaxation theory module (collaboration with Shimon Vega, Akiva Feintuch and Yonatan Hovav).
  • Scalar relaxation of the second kind option in the relaxation superoperator module.
  • Parallel construction of elementary operators and Hamiltonians.
  • Parallel propagation with respect to independently evolving subspaces in the evolution module.
  • Additional spherical quadrature grids: three-angle GSQ set, two-angle icosahedral set.
  • Much faster implementation of the Zero Track Elimination algorithm.
  • Infrastructure and examples for quadrupolar overtone NMR spectroscopy (collaboration with Phil Williamson and Marina Carravetta).
  • Brute force stochastic integration version of Bloch-Redfield-Wangsness theory in the relaxation superoperator module.
  • Import of quadrupolar and spin-rotation tensors from Gaussian03/09 logs.
  • Much richer feedback and reporting throughout the code.
  • Spherical tensor operator norms aligned with mainstream literature conventions.
  • Large number of additional example simulation files.

New features in version 1.2.1437

  • Solid Effect, Cross Effect and Overhauser DNP effect simulation (collaboration with Alexander Karabanov and Walter Kockenberger at Nottingham University). Multiple example files reproducing published literature results.
  • Krotov method and Zhu-Rabitz method as well as several new penalty functionals for the BFGS-GRAPE method in the Optimal Control module. BFGS-GRAPE method now uses an in-house implementation of LBFGS. GRAPE derivatives are now calculated using auxiliary matrix techniques.
  • Lindblad superoperator option and Nottingham DNP option in the relaxation theory module.
  • Average Hamiltonian theory module supporting Waugh and Krylov-Bogolyubov theories up to third order.
  • Spin system trajectory analysis module supporting correlation order, coherence order, spin population and spin participation binning as well as trajectory similarity analysis.
  • Generalized Fokker-Planck modules in the kernel supporting SLE and MAS calculations.
  • Hyperfine tensor and chemical shielding tensor visualization from Gaussian09 GIAO/CSGT log files using ellipsoid plots.
  • GPGPU implementation of the matrix exponential function with an automatic switch-over to CPU processing if the card memory is low.
  • PASADENA, ALTADENA and SABRE parahydrogenation simulation example files.
  • Extra assumption sets for the Hamiltonian superoperator function. 
  • Most Spinach algorithms are now taking full advantage of parallel processing on multicore machines and Matlab clusters.
  • Huge amounts of additional documentation (in the headers) and input validation (in the footers) of each function. Console output has been made more detailed and informative.

New features in version 1.2.1217

  • Stochastic Liouville Equation formalism is now supported for isotropic, axial and rhombic rotational diffusion.
  • Operator generation can now use 'electrons' and 'nuclei' as spin specifications.
  • Powder averages have been abstracted, generalized and parallelized. It is no longer necessary to do powder averaging manually.
  • Spherical averaging grid files now include tessellation information.
  • DEC (“direct expectations via Chebyshev method”) algorithm is now supported in the evolution module.
  • Automatic treatment of dilute isotopes.
  • Tikhonov regularization is now available in the Optimal Control module.
  • DEER (double electron-electron resonance) is now supported as a pulse sequence.
  • Newton series are now supported as a method of matrix exponentiation in the propagator calculation module.
  • Many infrastructure functions have been parallelized and optimized (in both efficiency and memory footprint) for large-scale simulations.
  • Levitt-DiBari thermalization has been implemented into the relaxation theory module.
  • Further examples were added for Spinach modules and procedures as well as extensive documentation in the header of each kernel function and pulse sequence.

Spinach features, version 1.1.1054

  • Provides low-dimensional matrix representations for spin operators in large spin systems and enables time domain simulation of NMR and ESR experiments on systems previously considered too big for any practical calculations. All standard techniques of NMR/ESR simulations remain the same in reduced state spaces, the only difference is smaller matrices. The details of the state space restriction method used by Spinach are presented in this paper.
  • Includes a generalized symmetry module (any number of groups of equivalent spins of any quantum number).
  • Includes Krylov subspace based time propagation functions and on-the-fly dimension reduction tools that operate transparently to the user and ensure rock-bottom CPU and memory requirements in all simulation tasks.
  • Includes a generalized rotation module that outputs the full rotation basis and the associated Wigner functions, returns Liouvillians for user-specified spin system orientations, provides a Lebedev powder integrator and rotational correlation functions for isotropic, axial and rhombic rotational diffusion.
  • Includes a generalized relaxation theory module: complete Redfield superoperators for all known first- and second-rank interactions with all cross-correlations thereof), supporting all types of magnetic resonance spectroscopy: NMR, ESR, DNP, Spin Chemistry, etc. Anisotropic rotational diffusion tensors are supported in full generailty.
  • Includes an analytical derivatives module, supporting derivative superoperators and derivative propagators.
  • Includes an Optimal Control waveform design module using BFGS-GRAPE algorithm with exact gradients. Optimization of broadband pulses, selective pulses and universal rotations is implemented in both Cartesian and phase-amplitude coordinates. For phase-modulated pulses, user-specified amplitude envelopes are available. User-specified waveform basis sets are supported. Template files are included for common Optimal Control optimization tasks.
  • Supports pseudocontact shifts generated by a point paramagnetic metal centre.
  • Includes templates for Overhauser DNP calculations in liquid state and solid effect DNP calculations in solid state using Krylov-Bogolyubov averaging in a reduced state space.
  • Includes functions for multi-grid parallel soft pulses, coherence selection and decoupling.
  • Includes functions for the simulation of magnetochemical experiments (a collaboration with Hannah Hogben and Peter Hore at Oxford).
  • Includes functions for the simulation of common NMR (pulse-acquire, COSY, DQF-COSY, HSQC, CLIP-HSQC, HMQC, HETCOR) and ESR (pulse-acquire, ENDOR, ESEEM) experiments.
  • Includes functions for the simulation of partially aligned systems -- RDCs, residual CSAs and residual quadrupolar interactions are supported in full generality.
We are in the process of adding DMRG/MPS functionality, coding up a stochastic Liouville equation module and expanding the library of standard pulse sequences and waveforms. The code is extensively commented and designed to be very readable.

Publications describing Spinach features

D.V. Savostyanov, S.V. Dolgov, J.M. Werner, I. Kuprov, "Exact NMR simulation of protein-size spin systems using tensor train formalism", Physical Review B, 90 (2014) 085139.
G.T.P. Charnock, I. Kuprov, "A partial differential equation for pseudocontact shift", Physical Chemistry Chemical Physics, 16 (2014) 20184-20189. 
L.J. Edwards, D.V. Savostyanov, Z.T. Welderufael, D. Lee, I. Kuprov, "Quantum mechanical NMR simulation algorithm for protein-size spin systems", Journal of Magnetic Resonance, 243 (2014) 107-113.
A. Biternas, G.T.P. Charnock, I. Kuprov, "A standard format and a graphical user interface for spin system specification", Journal of Magnetic Resonance, 240 (2014) 124-131.
I. Kuprov, "Spin system trajectory analysis under optimal control pulses", Journal of Magnetic Resonance, 233 (2013) 107-112.
L.J. Edwards, D.V. Savostyanov, A.A. Nevzorov, M. Concistrè, G. Pileio, I. Kuprov, "Grid-free powder averages: On the applications of the Fokker–Planck equation to solid state NMR", Journal of Magnetic Resonance, 235 (2013) 121-129.
A. Karabanov, A. van der Drift, L.J. Edwards, I Kuprov, W. Köckenberger, "Quantum Mechanical Simulation of Solid Effect Dynamic Nuclear Polarization using Krylov-Bogolyubov time averaging and a Restricted State Space", Physical Chemistry Chemical Physics, 14 (2012) 2658-2668.
L.J. Edwards, I Kuprov, "Parallel density matrix propagation in spin dynamics simulations", Journal of Chemical Physics, 136 (2012) 044108.

G.T.P. Charnock, M. Krzystyniak, I. Kuprov, "Molecular structure refinement by direct fitting of atomic coordinates to experimental ESR spectra", Journal of Magnetic Resonance, 216 (2012) 62-68.
H.J. Hogben, P.J. Hore, I. Kuprov, "Multiple decoherence-free states in multi-spin systems", Journal of Magnetic Resonance, 211 (2011) 217-220.
A. Karabanov, I. Kuprov, G.T.P. Charnock, A. van der Drift, L.J. Edwards, W. Köckenberger, "On the accuracy of the state space restriction approximation for spin dynamics simulations", Journal of Chemical Physics, 135 (2011) 084106.
P. de Fouquieres, S.G. Schirmer, S.J. Glaser, I. Kuprov, "Second order gradient ascent pulse engineering", Journal of Magnetic Resonance, 212 (2011) 412-417.
M. Krzystyniak, L.J. Edwards, I. Kuprov, "Destination state screening of active spaces in spin dynamics simulations", Journal of Magnetic Resonance, 210 (2011) 228-232. 
H.J. Hogben, M. Krzystyniak, G.T.P. Charnock, P.J. Hore, I. Kuprov, "Spinach - a software library for simulation of spin dynamics in large spin systems", Journal of Magnetic Resonance, 208 (2011) 179-194.
I. Kuprov, "Diagonalization-free implementation of spin relaxation theory for large spin systems", Journal of Magnetic Resonance, 209 (2011) 31-38.
H.J. Hogben, P.J. Hore, I. Kuprov, Strategies for state space restriction in densely coupled spin systems with applications to spin chemistry, Journal of Chemical Physics, 132 (2010), 174101.
R. Raj, I. Kuprov, K. Pervushin, Benchmarking NMR experiments: a relational database of protein pulse sequences, Journal of Magnetic Resonance, 203 (2010), 129-137.

I. Kuprov, C.T. Rodgers, Derivatives of spin dynamics simulations, Journal of Chemical Physics, 131 (2009) 234108.

I. Kuprov, Polynomially scaling spin dynamics II: further state space compression using Krylov subspace techniques and zero track elimination, Journal of Magnetic Resonance 195 (2008) 45-51.

I. Kuprov, N. Wagner-Rundell, P.J. Hore, Polynomially scaling spin dynamics simulation algorithm based on adaptive state space restriction, Journal of Magnetic Resonance 189 (2007) 241-250.
I. Kuprov, N. Wagner-Rundell, P.J. Hore, Bloch-Redfield-Wangsness theory engine implementation using symbolic processing software, Journal of Magnetic Resonance 184 (2007) 196-206.
The full index of our recent publications is located here.
The authors are very grateful to Mark Butler, Jean-Nicolas Dumez, Lyndon Emsley, Jack Freed, Steffen Glaser, Jeff Harmer, Paul Hodgkinson, Alexej Jerschow, Alexander Karabanov, Walter Köckenberger, Christiane Koch, Malcolm Levitt, Frederic Mentink-Vigier, Niels Chr. Nielsen, Konstantin Pervushin, Chris Rodgers, Sophie Schirmer, Thomas Schulte-Herbrüggen, Stefan Stoll, Zdenek Tosner and Shimon Vega for many useful discussions and feedback. The project is funded by the EPSRC (EP/F065205/1, EP/H003789/1).


see the forum for technical support, FAQs, feature requests and general discussions