spinach - cornell university · spinach is not a black box – it is an open-source matlab library...

Tutorial lecturePracticalities of Spinach

Spinach syntax and functionality, protein simulation specifics, relaxation theory options, computer hardware considerations.

Ilya Kuprov, University of Southampton, June 2014

"Pray, Mr Babbage, if you put into themachine wrong figures, will the rightanswers come out?“

Members of UK Parliament,to Charles Babbage, in 1860

Magnetic resonance simulation flowchart

Spinach is not a black box – it is an open-source Matlab library of infrastructure functions.

Gather spin system, instrument and experiment parameters

Generate spin Hamiltonian

Generate relaxation superoperator

Generate thermal equilibrium state

Thermalize rlxn superoperator

Generate exponential propagator

If you are using Spinach,this is the only thing youwould need to do manually.

Obtain system trajectoryProject out the

observables

What you need to provide

N.B.: DFT calculations for heavy metals and large aromatic systems require considerable skill.

Z NN EN EE MWˆ ˆ ˆ ˆ ˆ ˆH H H H H H

Zeeman interactions

inter-nuclear and quadrupolar interactions

electron-nuclearinteractions

inter-electron interactionsand zero-field splitting

microwave and radiofrequency terms

Z 0 E 0 N

ˆ ˆˆ k k k k

k k

H B E B N A A

Zeeman interactions: chemical shielding tensors fornuclei and g-tensors for electrons.Where to get: from the literature or from quantumchemistry packages (Gaussian, CASTEP, ORCA, etc.).

GIAO DFT B3LYP/cc-pVTZ or similar is generallyaccurate for small CHNO molecules.


N.B.: despite the common “scalar coupling” moniker, J-coupling is actually a tensor too.


Zeeman interactions





Inter-nuclear interactions: J-couplings, nuclear quadrupolar interactions, inter-nuclear dipolar interactions.Where to get: literature or DFT for J-coupling and NQI. Dipolar couplings are mostconveniently extracted from Cartesian coordinates of the spins.

,NN NN Q

20 N N5

ˆ ˆ ˆ ˆˆ 2

ˆ ˆ ˆ ˆ3( )( ) ( )4

j k kj k k k

j k k

j k

j jk jk k jk j kj k jk

H J N N N N

N r r N r N Nr

A


N.B.: “anisotropic hyperfine” and “electron-nuclear dipolar” interactions are the same thing.


Zeeman interactions





Electron-nuclear interactions: isotropic (aka Fermicontact) and anisotropic hyperfine couplings.Where to get: literature or DFT (requires specialized basissets). For remote electron-nuclear pairs (10 Angstroms ormore), Cartesian coordinates.

,EN EN

,

ˆ ˆˆ j kj k

j kH E N A

Note the strong directionality of some HFC tensors.


N.B.: the practical accuracy of DFT for exchange coupling and particularly ZFS is very low.


Zeeman interactions





Inter-electron interactions: exchange interaction, zero field splitting, inter-electrondipolar interactions.Where to get: literature or DFT for exchange coupling and ZFS. Dipolar couplingsare most conveniently extracted from Cartesian coordinates of the spins.

,EE EE ZFS

20 E E5

ˆ ˆ ˆ ˆˆ 2

ˆ ˆ ˆ ˆ3( )( ) ( )4

j k kj k k k

j k k

j k

j jk jk k jk j kj k jk

H J E E E E

E r r E r E Er

A


N.B.: the direction of the B1 field in most MAS experiments is parallel to the spinning axis.


Zeeman interactions





Microwave and radiofrequency terms:amplitude coefficients in front of the LXand LY terms in the Hamiltonian.Where to get: from the pulse calibrationcurves of the instrument. The RF/MWpower (in Hz) is equal to the reciprocalwidth of the 360-degree pulse.

(K.R. Thurber, A. Potapov, W.-M. Yau, R. Tycko)

MW MW MW Xˆ ˆcos k k

kH t a E

Spinach architecture

N.B.: most functions are parallelized and would take advantage of a multi-core computer.

sys.*

inter.*

bas.*

General system specification (magnet, isotopes, labels,tolerances, algorithm options, output files, etc.)

Interactions, chemical kinetics, relaxation theory options,spin temperature, order matrix, etc.

Simulation formalism, approximation options, permutationsymmetry, conservation law specification, etc.

% Magnet fieldsys.magnet=0.33898;

% Isotope listsys.isotopes={'E','14N','19F','1H','1H','1H','1H'};

% Basis setbas.formalism='sphten-liouv';bas.approximation='ESR-2';bas.sym_group={'S2','S2'};bas.sym_spins={[4 5],[6 7]};

% Zeeman interactionsinter.zeeman.eigs=cell(7,1);inter.zeeman.euler=cell(7,1);inter.zeeman.eigs{1}=[2.0032 2.0012 2.0097];

% Relaxation superoperatorinter.relaxation='redfield';inter.rlx_keep='secular';inter.tau_c=80e-12;

create()

basis()

assume()

Processing of spin system structure and interactions, inputchecking. Creates the spin_system data structure.

Processing of basis set options, approximations, symmetryand conservation laws. Updates spin_system data structure.

Case‐specific simulation assumptions (‘labframe’, ‘nmr’,‘endor’, etc.) that have an effect on the Hamiltonian.

% Spin-spin couplingsinter.coupling.eigs=cell(7,7);inter.coupling.euler=cell(7,7);inter.coupling.eigs{1,2}=(40.40+[24 -12 -12])*1e6;inter.coupling.eigs{1,3}=(22.51+[34.9 -19.8 -15])*1e6;inter.coupling.eigs{1,4}=[9.69 9.69 9.69]*1e6;inter.coupling.eigs{1,5}=[9.69 9.69 9.69]*1e6;inter.coupling.eigs{1,6}=[3.16 3.16 3.16]*1e6;inter.coupling.eigs{1,7}=[3.16 3.16 3.16]*1e6;

% Spinach housekeepingspin_system=create(sys,inter);spin_system=basis(spin_system,bas);spin_system=assume(spin_system,'labframe');

hamiltonian()

relaxation()

equilibrium()

Returns the isotropic Hamiltonian and the irreduciblecomponents of the anisotropic part.

Returns the relaxation superoperator using thetheory specified by the user.

Returns the thermal equilibrium density matrix orstate vector at the specified temperature.

operator()

state()

Returns user‐specified operators or superoperators(including sided product superoperators)

Returns user specified density matrices (Hilbertspace) or state vectors (Liouville space)

average()

evolution()

Performs average Hamiltonian theory treatment(Waugh, Krylov‐Bogolyubov, matrix log)

Runs all types of spin system evolution and detection,uses reduced state spaces under the bonnet.

Et cetera… the amount of functionality is HUGE.

Spinach functionality

N.B.: Latest Matlab (R2013b at the moment) is required, primary reason being parallelization.

Spin system specification in Spinach

Spinach has a very detailed input checker – if something is amiss, it would tell you.

% Spin systemsys.magnet=3.4;sys.isotopes={'1H','1H','E'};

% Zeeman interactionsinter.zeeman.matrix={[5 0 0; 0 5 0; 0 0 5]

[5 0 0; 0 5 0; 0 0 5][2.0023 0 0; 0 2.0025 0; 0 0 2.0027]};

% Coordinatesinter.coordinates={[0.0 0.0 0.0][0.0 2.0 0.0][0.0 0.0 1.5]};

% Treat all dipolar interactionssys.tols.prox_cutoff=Inf;

% Basis setbas.formalism='sphten-liouv';bas.approximation='none';

% Relaxation theoryinter.relaxation='redfield';inter.equilibrium='levitt';inter.rlx_keep='kite';inter.temperature=298;inter.tau_c=10e-12;

Overhauser DNP simulation example

N.B.: most Spinach functions are parallelized – use parpool to enable parallel processing.

% Spinach housekeepingspin_system=create(sys,inter);spin_system=basis(spin_system,bas);spin_system=assume(spin_system,'esr');

% Initial state - thermal equilibriumrho=equilibrium(spin_system);

% Detection state - Lz on all spinscoil=[state(spin_system,{'Lz'},{1})...

state(spin_system,{'Lz'},{2})...state(spin_system,{'Lz'},{3})];

% Hamiltonian and relaxation superoperatorsH=hamiltonian(spin_system);R=relaxation(spin_system);

% Electron control operatorLp=operator(spin_system,'L+','E'); Lx=(Lp+Lp')/2;

% Pi pulse on electronrho=step(spin_system,Lx,rho,pi);

% Evolution (10000 steps, 0.1 microseconds each)answer=evolution(spin_system,H+1i*R,coil,rho,1e-7,10000,'multichannel');

SE and CE DNP simulation examples

N.B.: most Spinach functions are parallelized – use matlabpool to enable parallel processing.

% Experiment parametersparameters.theory='kb_second_order';parameters.time_step=0.01;parameters.n_steps=500;

% Time domain simulationparameters.calc_type='time_dependence';answer=solid_effect(spin_system,parameters);

% Sequence parametersparameters.mw_power=2*pi*100e3;parameters.mw_freqs=2*pi*linspace(-350,350,50000)*1e6;parameters.rho_eq=equilibrium(spin_system);parameters.coil=state(spin_system,'Lz','1H');parameters.mw_oper=(operator(spin_system,'L-','E')+...operator(spin_system,'L+','E'))/2;

parameters.ez_oper=operator(spin_system,'Lz','E');parameters.rlx=relaxation(spin_system);parameters.orientation=[0 0 0];

% Steady state simulationanswer=crystal(spin_system,@dnp_scan,parameters,'dnp_exact');

0 2 4

-0.496

-0.4955

-0.495

0 2 4

0.050.1

0.150.2

0.25

0 2 4

0.01

0.02

0.03

time, seconds0 2 4

1

2

3

4

5

x 10-3

time, seconds

-200 0 200-500

0

500

Microwave frequency offset, MHz

1H D

NP

am

plitu

de, B

oltz

Graphical user interface

N.B.: GUI is somewhat behind the rest of Spinach – not all functionality is exposed via the GUI.

Protein data import

N.B.: User feedback is shaping the enhancements – if you ask for something, it would appear.

% Protein data[sys,inter]=protein('1D3Z.pdb','1D3Z.bmrb');

Spinach reads the first structure in the PDB file and the whole of BMRB file. Then:1. Oxygens, sulphurs and terminal capping groups are ignored.2. Amino acid sequence is checked for a match between BMRB and PDB.3. OH and terminal NH3 protons are ignored (assumed deuterated).4. Chemical shifts for CH2, CH3 are replicated if given once in BMRB.5. Any mismatches or gaps in atom data are reported with an error message.6. Unassigned atoms are removed.

The above policies are a reasonable guess – change the text of protein.m if youwould like to import the data differently, or modify sys.* and inter.* fieldsmanually after the import.

Apart from the full import, three pre-selection options are available: backbone ('H','N', 'C', 'CA', 'HA', 'CB', 'HB', 'HB1', 'HB2', 'HB3'), backbone-minimal ('H', 'N', 'C','CA', 'HA') and backbone-hsqc ('H', 'N', 'C', 'CA', 'HA', 'NE2', 'HE21', 'HE22', 'CD','CG', 'ND2', 'HD21', 'HD22', 'CB').

Manual spin system specification

N.B.: See the Spinach manual -- /docs directory in the distribution.

% Spin systemsys.isotopes={'1H','1H','1H','1H','1H','1H','1H','1H','1H',...

'1H','1H','1H','1H','1H','1H','1H','1H','1H',...'1H','1H','1H','1H'};

% Interactionssys.magnet=5.9;inter.zeeman.scalar={6.72 6.40 4.13 4.56 4.89 6.46 7.79 3.79 2.91...

3.27 5.19 4.89 5.03 1.72 1.72 1.72 3.72 3.72...3.72 3.76 3.76 3.76};

inter.coupling.scalar{3,4}=12.1; inter.coupling.scalar{4,5}=3.1; inter.coupling.scalar{3,5}=1.0; inter.coupling.scalar{3,8}=1.0; inter.coupling.scalar{1,8}=1.0;inter.coupling.scalar{6,7}=8.6; inter.coupling.scalar{5,8}=4.1; inter.coupling.scalar{7,9}=0.7; inter.coupling.scalar{7,10}=0.7; inter.coupling.scalar{9,10}=15.8;inter.coupling.scalar{10,11}=9.8; inter.coupling.scalar{9,11}=8.1; inter.coupling.scalar{13,14}=1.5; inter.coupling.scalar{12,14}=0.9; inter.coupling.scalar{22,22}=0;

% Coordinates inter.coordinates={...[-3.41285300 0.73156000 1.07036600];[-2.18218300 -0.53340100 1.62534100];[-1.83251000 1.55844200 -0.65127900];[-2.51263500 -0.53063900 -0.50722600];[-3.28847400 -0.19858900 -1.08239500];[ 0.45545168 2.23095146 -0.76407436];[-0.46596257 -1.76861142 0.49251865];[ 2.88380973 1.74814805 -0.56768603];[ 1.97436454 -2.26233655 0.71081156];[ 3.65174100 -0.50071826 0.17866774];[-3.41285300 0.73156000 1.07036600]};

Relaxation and chemical kinetics

N.B. Relaxation superoperator is usually the most demanding part of the calculation.

% Relaxation theoryinter.relaxation='redfield';inter.rlx_keep='kite';inter.tau_c=5e-9;

• Bloch-Redfield-Wangsness relaxation theory is supported in full generality(including cross-correlations, scalar relaxation, dynamic frequency shifts, etc.)

• Dipolar couplings are inferred from coordinates, CSAs must be provided.• NOESY spectrum is a reflection of the coordinates supplied – if you have a

conformational ensemble, you would need to run multiple calculations.• Long-lived states are detected automatically (they correspond to small

eigenvalues of the relaxation superoperator).• Situations outside Redfield limit are handled with SLE (small systems only).• A subset of reaction kinetics models (first and pseudo-first order) is supported.

I. Kuprov, "Diagonalization-free implementation of spin relaxation theory for largespin systems", Journal of Magnetic Resonance, 2011, 209(1), 31-38.H.J. Hogben, P.J. Hore, I. Kuprov, "Multiple decoherence-free states in multi-spinsystems", Journal of Magnetic Resonance, 2011, 211(2), 217-220.

% Chemical kineticsinter.chem.parts={[1 2],[3 4]};inter.chem.rates=[-5e2 2e3; 5e2 -2e3];

Basis set selection

N.B. Many further optimizations available – see the basis preparation section of the manual.

% Basis setbas.formalism='sphten-liouv';bas.approximation='IK-1';bas.connectivity='scalar_couplings';bas.level=4; bas.space_level=3;

% Chemical kineticsinter.chem.parts={[1 2],[3 4]};inter.chem.rates=[-5e2 2e3;

5e2 -2e3];

The bigger, the better – same variational principle as quantum chemistry.

Basis set Description

IK-0(n)All spin correlations up to, and including, order n, irrespective ofproximity on J-coupling or dipolar coupling graphs. Generated with acombinatorial procedure.

IK-1(n,k)

All spin correlations up to order n between directly J-coupled spins (withcouplings above a user-specified threshold) and up to order k betweenspatially proximate spins (with distances below the user-specifiedthreshold). Generated by coupling graph analysis.

IK-2(n)For each spin, all of its correlations with directly J-coupled spins, andcorrelations up to order n with spatially proximate spins (below the user-specified distance threshold). Generated by coupling graph analysis.

Pulse sequence programming

Infrastructure functions are available for all common pulse sequence steps.

function fid=noesy(spin_system,parameters,H,R,K)

% Consistency checkgrumble(spin_system,parameters,H,R,K);

% Compose LiouvillianL=H+1i*R+1i*K; clear('H');

% Coherent evolution timesteptimestep=1/parameters.sweep;

% Detection statecoil=state(spin_system,'L+',parameters.spins{1},'cheap');

% Pulse operatorsLp=operator(spin_system,'L+',parameters.spins{1});Lx=(Lp+Lp')/2; Ly=(Lp-Lp')/2i;

% First pulserho=step(spin_system,Lx,parameters.rho0,pi/2);

% F1 evolutionrho_stack=evolution(spin_system,L,[],rho,timestep,parameters.npoints(1)-1,'trajectory');

% Second pulserho_stack_cos=step(spin_system,Lx,rho_stack,pi/2);rho_stack_sin=step(spin_system,Ly,rho_stack,pi/2);

Pulse sequence programming

N.B. Coherence selection in Spinach is analytical – no need to emulate phase cycles.

% Homospoilrho_stack_cos=homospoil(spin_system,rho_stack_cos,'destroy');rho_stack_sin=homospoil(spin_system,rho_stack_sin,'destroy');

% Mixing timerho_stack_cos=evolution(spin_system,1i*R+1i*K,[],rho_stack_cos,parameters.tmix,...

1,'final');rho_stack_sin=evolution(spin_system,1i*R+1i*K,[],rho_stack_sin,parameters.tmix,...

1,'final');

% Homospoilrho_stack_cos=homospoil(spin_system,rho_stack_cos,'destroy');rho_stack_sin=homospoil(spin_system,rho_stack_sin,'destroy');

% Third pulserho_stack_cos=step(spin_system,Ly,rho_stack_cos,pi/2);rho_stack_sin=step(spin_system,Ly,rho_stack_sin,pi/2);

% F2 evolutionfid.cos=evolution(spin_system,L,coil,rho_stack_cos,timestep,...

parameters.npoints(2)-1,'observable');fid.sin=evolution(spin_system,L,coil,rho_stack_sin,timestep,...

parameters.npoints(2)-1,'observable');

end

Protein J-coupling guess function

N.B. You can specify your own couplings or Karplus curves by editing guessj.m function.

Spinach J-coupling guesser for proteins is just a huge collection of literature dataon 1-bond couplings, 2-bond couplings and Karplus curves for three-bondcouplings. The number of unique atom combinations in a protein is quite small.

'CA_CB_HA_HB1', 3, 1, 2, 4, [ 9.5 -1.60 1.80]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HA_HB2', 3, 1, 2, 4, [ 9.5 -1.60 1.80]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HA_HB3', 3, 1, 2, 4, [ 9.5 -1.60 1.80]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HB1_N', 4, 1, 2, 3, [-4.40 1.20 0.10]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HB2_N', 4, 1, 2, 3, [-4.40 1.20 0.10]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HB3_N', 4, 1, 2, 3, [-4.40 1.20 0.10]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_CB_HB_N', 4, 1, 2, 3, [-4.40 1.20 0.10]; % http://dx.doi.org/10.1006/jmbi.1998.1911 [chi1 side-chain] 'CA_H_HA3_N', 2, 4, 1, 3, [6.51 -1.76 1.60]; % http://dx.doi.org/10.1021/ja00070a024 [backbone phi] 'CA_H_HA_N', 2, 4, 1, 3, [6.51 -1.76 1.60]; % http://dx.doi.org/10.1021/ja00070a024 [backbone phi] 'CA_H_HA2_N', 2, 4, 1, 3, [6.51 -1.76 1.60]; % http://dx.doi.org/10.1021/ja00070a024

A complete protein example case

N.B. In most cases you would be parsing some data of your own in the second line.

% Protein data[sys,inter]=protein('1D3Z.pdb','1D3Z.bmrb');

% Magnet fieldsys.magnet=21.1356;

% Tolerancessys.tols.prox_cutoff=4.0;sys.tols.inter_cutoff=2.0;

% Relaxation theoryinter.relaxation='redfield';inter.rlx_keep='kite';inter.tau_c=5e-9;

% Basis setbas.formalism='sphten-liouv';bas.approximation='IK-1';bas.connectivity='scalar_couplings';bas.level=4; bas.space_level=3;

L.J. Edwards, D.V. Savostyanov, Z.T. Welderufael, D. Lee, I. Kuprov, "Quantummechanical NMR simulation algorithm for protein-size spin systems", Journal ofMagnetic Resonance, 2014, 243, 107-113.

% Create the spin system structurespin_system=create(sys,inter);

% Build the basisspin_system=basis(spin_system,bas);

% Sequence parametersparameters.tmix=0.065;parameters.offset=4250;parameters.sweep=10750;parameters.npoints=[512 512];parameters.zerofill=[2048 2048];parameters.spins={'1H'};parameters.axis_units='ppm';

% Simulationfid=liquid(spin_system,@noesy,parameters,'nmr');

spinach - cornell university · spinach is not a black box – it is an open-source matlab library...

Documents