Spinach library
Spinach is a fast (polynomial complexity scaling for liquid state NMR) opensource 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.
Downloads:
Version 2.1.4400 (latest version, 5 Jan 2018, documentation)
Version 2.0.4198
Version 1.10.4104
Version 1.9.3608
Please email Ilya Kuprov with any questions, feature requests or systems to simulate. The minimum supported version of Matlab is 2017b (64bit version) with Parallel Computing Toolbox, Optimisation Toolbox and at least 8 GB of RAM. Spinach supports NVidia Tesla GPUs and largescale (128+ cores) parallel deployments using Matlab Distributed Computing Server. Protein functionality requires 64 GB of RAM.
New features in version 2.1.4400
 Much faster symmetry treatment, particularly in systems with multiple nonAbelian symmetry groups.
 Kernelwide support for spherical rank 1 interactions (such as antisymmetric CSA), including relaxation theory.
 Kernelwide support for high spherical rank zerofield splitting, including relaxation theory.
 Polyadic representation option for large Kronecker products  many operations may be carried out without opening them.
 PRESS, DWI, EPI, and DPFGSE pulse sequences and examples in the MRI module (collaboration with Ahmed Allami).
 TROSY relaxation theory examples.
 An option to add magnetisation pumping (e.g. CIDNP or SABRE) terms to the relaxation superoperator.
 Arbitrary pulse timing grids, major improvements in parallel efficiency, and ensemble control options in the Optimal Control module.
 A huge amount of additional documentation.
Version 2.0.4145
 Bug fixes, stability and documentation improvements.
New features in version 1.10.4104
 Expanded spatially encoded NMR and MRI module (collaboration with Ahmed Allami, Mohammadali Foroozandeh, Maria Grazia Concilio, Gareth Morris, Marta Brucka, Damien Jeannerat, Ludmilla Guduff, and JeanNicolas Dumez):
 Chirp pulse functions (unidirectional and saltire).
 Gradient operators now take chemical shifts into account.
 Arbitrary distributions of diffusion tensors in 3D.
 Arbitrary stationary flow fields in 3D.
 Simultaneous treatment of diffusion, hydrodynamics, chemical kinetics and quantum mechanical spin dynamics / relaxation theory using FokkerPlanck formalism.
 PSYCHE, UFCOSY, UFDOSY, UFCOSYDOSY and other ultrafast / pure shift NMR pulse sequences.
 Multiple new MRI pulse sequences, phantoms and examples: SPIRAL, EPI, diffusion, etc.
 Expanded paramagnetic NMR module (collaboration with Liza Suturina, Steven Worswick, Lewis Mills, David Parker, Michele Vonci, Kevin Mason, Nick Chilton, Eric McInnes, and Carlos Geraldes):
 Automatic treatment of PCS and Curie relaxation (second rank) when a magnetic susceptibility tensor is specified.
 Giant spin Hamiltonian support and the associated functionality (Stevens operators, relaxation theory, Wigner 3j and 6j symbols, conversion between gtensors and susceptibility tensors, effective gtensor calculation for Kramers doublets).
 Poisson solver option in lanthanide probability density reconstruction from PCS data.
 A standalone module for scalar relaxation within Redfield theory.
 Various optimisations, parallel efficiency, numerical stability and memory efficiency improvements:
 Asynchronous parallel calculation path for the Redfield superoperator.
 Diskbased generation option for Hamiltonians with dimension in excess of 100 million.
 Fast linear solver options in frequency domain detection experiments.
 Aggressive memory recycling across the kernel.
 Careful handling of very low spin temperatures.
 Improved diagnostic output at run time.
 More consistent unit handling.
 Different chemical compartments can now have different rotational correlation times within Redfield theory.
 Expanded and redesigned Optimal Control module, including an interface to Bruker XEPR Python libraries (David Goodwin's PhD thesis).
 Several new zero and ultralow field NMR pulse sequences (collaboration with Dima Budker and John Blanchard).
 Multiple new pulse sequences and examples in all areas of magnetic resonance.
New features in version 1.9.3608
 Improved MRI and spatially encoded NMR infrastructure, supporting anisotropic 3D diffusion and stationary flow hydrodynamics at the same time as quantum mechanical spin dynamics, relaxation theory and chemical kinetics in every voxel. Ultrafast NMR pulse sequences (UFCOSY, UFDOSY, 3D UFCOSYDOSY) are provided as examples (collaboration with Ahmed Allami, Ludmilla Guduff and JeanNicolas Dumez). Arbitrary 3D profiles are now supported for the relaxation superoperator, the initial condition and the detection state. The module uses the FokkerPlanck formalism.
 The kernel now supports the giant spin Hamiltonian model up to an arbitrary spherical rank, as well as calculation of molar magnetization at thermal equilibrium, susceptibility tensor estimation from a gtensor, and the calculation of residual anisotropic chemical shifts under partial magnetic alignment. Point electron model function for pseudocontact shifts now supports averaging over structural ensembles (collaboration with Liza Suturina).
 Dipolar interactions calculated from cartesian coordinates now take into account Zeeman interaction amplitude and anisotropy (collaboration with Liza Suturina).
 The basis set selection now has an option to include only the zeroquantum states on a particular group of spins.
 DEER calculations now have a switch to include or exclude the flipflop terms from the interelectron dipolar interaction Hamiltonian (collaboration with Nurit Manukovsky and Daniella Goldfarb).
 Karplus curve fitter function now returns standard deviations.
 An example PBS submission script is provided for running Spinach on PCS clusters.
 Spin system import from SpinXML files is now supported.
 3D surface plotting utility for cylindrical coordinates.
 Major convenience and usability improvements in the Optimal Control module (collaboration with David Goodwin).
 Major performance and memory efficiency improvements across the kernel.
New features in version 1.8.3420
 Major improvements in parallelisation efficency  singlethreaded stages have been virtually eliminated from the kernel.
 Kernelwide 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 threedimensional 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 NewtonRaphson algorithm and major improvements in the implementation of quasiNewton 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 MentinkVigier). Please cite Fred's papers if you are using this functionality and consider adding him as a coauthor.
 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 barebones 3D MRI module using the FokkerPlanck formalism, supporting threedimensional diffusion and stationaryflow 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 JonesHore 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 stationaryflow 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 Lcurve 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 LevanteErnst thermalizer for relaxation superoperators.
 Major efficiency improvements in the pseudocontact shift module when dealing with nonpoint unpaired electrons.
 Floquet theory and FokkerPlanck 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 frequencyamplitudetime coordinates using FokkerPlanck formalism, including situations where gradients are present (collaboration with Mohammadali Foroozandeh and
Gareth Morris).
 Three and fourpulse DEER sequences, pulseacquire and Davies ENDOR sequence using orientationselective soft pulses (collaboration with Nurit Manukovsky and Daniella Goldfarb).
 Timedomain hardpulse HYSCORE sequence (collaboration with Luke Edwards).
 Quadrupolar overtone crosspolarization 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 FokkerPlanck formalism (collaboration with JeanNicolas Dumez).
 ROESY pulse sequence with ideal spinlock 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
 BFGSKrotov and regularized NewtonRaphson GRAPE algorithms in the Optimal Control module (written by David Goodwin). Standalone direct and inverted BFGS and SR1 Hessian update modules.
 Oneangle 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 pointtopoint 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 recalculation 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 doublerotation solid state NMR and doublerotation overtone NMR using FokkerPlanck formalism (collaboration with Marina Carravetta).
 New spectral fitting examples, including simultaneous multispectral 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 tripleaxis 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 JeanNicolas 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.
 Outofphase ESEEM sequence added to the ESR pulse sequences.
New features in version 1.5.2440
 Improved Jcoupling 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 threeangle 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 spin0 particles that makes it convenient to simulate molecules with sitespecific 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 Jcoupling prediction module, based on graphtheoretical 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 longlived states in quadrupolar systems.
New features in version 1.3.1980
 Zeeman basis set support in Hilbert, Liouville and FokkerPlanck 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 FokkerPlanck 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 liquidstate 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 userspecified axis. Two and threeangle 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: threeangle GSQ set, twoangle 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 BlochRedfieldWangsness theory in the relaxation superoperator module.
 Import of quadrupolar and spinrotation 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 ZhuRabitz method as well as several new penalty functionals for the BFGSGRAPE method in the Optimal Control module. BFGSGRAPE method now uses an inhouse 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 KrylovBogolyubov 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 FokkerPlanck 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 switchover 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 electronelectron 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 largescale simulations.
 LevittDiBari
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 lowdimensional 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 onthefly dimension reduction tools that operate transparently to the user and ensure rockbottom 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 userspecified 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 secondrank interactions with all crosscorrelations 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 BFGSGRAPE algorithm with exact gradients. Optimization of broadband pulses, selective pulses and universal rotations is implemented in both Cartesian and phaseamplitude coordinates. For phasemodulated pulses, userspecified amplitude envelopes are available. Userspecified 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 KrylovBogolyubov averaging in a reduced state space.
 Includes functions for multigrid 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 (pulseacquire, COSY, DQFCOSY, HSQC, CLIPHSQC, HMQC, HETCOR) and ESR (pulseacquire, 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
Acknowledgements
The authors are very grateful to Mark Butler, JeanNicolas Dumez, Lyndon Emsley, Jack Freed, Steffen Glaser, Jeff Harmer, Paul Hodgkinson, Alexej Jerschow, Alexander Karabanov, Walter Köckenberger, Christiane Koch, Malcolm Levitt, Frederic MentinkVigier, Niels Chr. Nielsen, Konstantin Pervushin, Chris Rodgers, Sophie Schirmer, Thomas SchulteHerbrü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).
