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.7.2996 (latest version, 10 Jan 2016, documentation)
Version 1.6.2782
Version 1.5.2440
Version 1.4.2114

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

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 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