Basis set specification

From Spinach Documentation Wiki
Jump to: navigation, search

Any Spinach input must contain a specification of the formalism to be used (Hilbert or Liouville space), a specification of the type of basis operators to be used (Pauli matrices or irreducible spherical tensors), and a choice of which quantum states should be taken into consideration during the simulation process. The selection of formalism, approximation and basis set is accomplished by a call to basis.m function:


which updates the spin_system data structure with formalism and basis set information. All relevant parameters are supplied as subfields of the bas structure, which is described in detail in this chapter.

What does basis set mean in spin dynamics?

Every quantum state of the spin system may be described by a density matrix, and the density matrix may be written as a linear combination of some basis matrices. In the simple case of one spin:

[math]\hat{\rho }=a{{\hat{\sigma }}_{\text{X}}}+b{{\hat{\sigma }}_{\text{Y}}}+c{{\hat{\sigma }}_{\text{Z}}}[/math]

where [math]\left\{ {{{\hat{\sigma }}}_{\text{X}}},{{{\hat{\sigma }}}_{\text{Y}}},{{{\hat{\sigma }}}_{\text{Z}}} \right\}[/math] are Pauli matrices and [math]\left\{ a,b,c \right\}[/math] are complex numbers. In this case, the Pauli matrices are the basis set and the complex numbers are the expansion coefficients. Systems with multiple spins have many more operators in the basis set: not only single-spin operators, but also multi-spin operators (for example [math]\hat{\sigma }_{\text{Z}}^{\left( 1 \right)}\otimes \hat{\sigma }_{\text{Z}}^{\left( 2 \right)}[/math]) which describe correlated simultaneous dynamics of multiple spins.

It is these multi-spin correlated states that are often unnecessary. Consider a very large coupled spin system of the kind shown in Figure 1. Even though, technically speaking, the two methyl groups on the opposite sides of the molecule are connected through the network of J-couplings, the practical likelihood of the corresponding correlation actually appearing in a regular liquid state NMR experiment is negligible - the groups are simply too far.

Figure 1. Stereo plot of the anti-difluoroheptane spin system with significant J-couplings shown by dashed lines. In regular liquid state NMR simulations it may safely be assumed that the spins belonging to different methyl groups on the opposite sides of the molecule never become correlated.

The corresponding operators may be dropped from the basis set. This reduces the number of coefficients in the density matrix expansion, and therefore the matrix dimension required for simulation. It is easy to demonstrate that, in very large molecules, the number of different correlated states that never get populated is very large. Dropping these states from the basis set accelerates simulations by many orders of magnitude. Some specific states may also be inaccessible due to the presence of symmetries, conservation laws, spin relaxation, and many other factors. Spinach can take all of these factors into account (and run simulations at a massively reduced computational cost), but it needs you to provide the information that would enable it to make the decisions about which states should and should not be considered relevant.

Figure 2. Numerical simulation of the density matrix norm dynamics during the evolution and detection period of a pulse-acquire NMR experiment on the 22-spin system of strychnine. All distances and magnetic parameters imported from a GIAO DFT B3LYP/EPR-II calculation. Bloch-Redfield-Wangsness relaxation superoperator (including DD, CSA and cross-correlation terms) was used with isotropic rotational diffusion correlation time of 200 ps.

Figure 2 gives the general idea about the correlation orders expected in typical liquid state NMR simulations - it is clear that correlations involving large numbers of spins are not populated and may therefore be dropped from the basis set. The theory of incomplete basis set simulations in magnetic resonance is currently under active development. The following equation provides an estimate of the minimal basis set requirements:

[math]k \gt 2\sqrt {\frac{h}{r}} {\rm{erf}}{{\rm{c}}^{ - 1}}\left( {\xi {\rm{erfc}}\left( {\frac{1}{2}\sqrt {\frac{r}{h}} } \right)} \right)[/math]

where [math]k[/math] gives the maximum spin correlation order to be included in the basis, [math]\xi[/math] is the target accuracy, [math]r[/math] is the average relaxation rate in the system and [math]h[/math] is the average spin-spin coupling (single-spin interactions, such as Zeeman, NQI and ZFS, do not count).

Formalism selection

The first decision you are required to make concerns the simulation formalism, using bas.formalism parameter, for example:


Unless you have good reasons not to, choose 'sphten-liouv' here. The following formalisms are supported by the kernel:

Formalism keyword Formalism description

Liouville space formalism; the fundamental operators from which the basis set is built are single-spin irreducible spherical tensors. These operators are ordered with respect to many common transformations and conservation laws encountered in magnetic resonance. Many useful operations may therefore be performed semi-analytically. A lot of Spinach functionality either requires this formalism or operates most efficiently within it. This should be the default choice unless you have good reasons to pick something else.

'zeeman-liouv' Liouville space formalism; the fundamental operators from which the basis set is built are single transition operators between the projection states on the Z axis. The state vector coefficients in this formalism are easy to interpret because they correspond to populations of standard textbook spin states. This formalism is essentially a vectorisation of 'zeeman-hilb'; it permits only limited state space reduction; most calculations would have exponential complexity scaling if this option is chosen.
'zeeman-hilb' Hilbert space formalism; the fundamental states from which the basis set is built are the projection states on the Z axis. This is the standard density operator formalism described in most magnetic resonance textbooks. Only the core functionality (operators, states, propagators, evolution) is available. This option is mostly useful for backwards compatibility checks; it cannot support complicated relaxation theories or chemical kinetics. All calculations within this formalism would have exponential complexity scaling.

System-level state space reduction, and therefore polynomial complexity scaling, is only available within 'sphten-liouv' formalism. If your system has more than 20 spins, 'sphten-liouv' is your only realistic choice. For small but strongly coupled spin systems without significant relaxation effects, choose 'zeeman-hilb'.

Approximation selection

To run an exact calculation in any formalism, set:


This option requests a complete basis set, which is only practical up to about twelve spins in Hilbert space and six spins in Liouville space. Approximate calculations are those that use an incomplete basis set. The user is expected to provide the information that Spinach would use to build the basis set. The following frequently encountered choices are provided with the kernel:

Approximation Approximation description Parameters
bas.approximation='IK-0' Includes all product states between up to (and including) bas.level spins located anywhere within the system. The asymptotic scaling of this basis set is polynomial. bas.level
bas.approximation='IK-1' Includes all product states between up to (and including) bas.level directly coupled spins, and up to order bas.space_level between spins that are closer than tols.prox_cutoff (default is 100 Angstrom). The asymptotic scaling of this basis set is polynomial. bas.level, bas.space_level, tols.prox_cutoff
bas.approximation='IK-2' Includes, for every spin, all correlations with all directly coupled spins, and correlations with up to (and including) bas.space_level with spins that are closer than tols.prox_cutoff (default is 100 Angstrom). The asymptotic scaling of this basis set is polynomial. bas.space_level, tols.prox_cutoff

Note that, in most liquid state NMR calculations, the proximity cut-off of 100 Angstroms is an overkill, and a 5 Angstrom cut-off is usually adequate. The default is so large to accommodate more exotic situations, such as those in DNP and MAS NMR simulations.

An important parameter that controls the basis state selection process defines what is considered to be an interaction. In liquid state NMR, the most appropriate interaction network is defined by J-couplings because dipolar couplings and other anisotropic interactions are averaged out. In that case, setting


instructs Spinach to use the isotropic parts of the coupling tensors to build the spin interaction graph. However, in solid state NMR, DNP and many ESR systems a coupling is essentially anisotropic and the interaction network must also count traceless interactions because they manifest directly. In that case, setting


instructs Spinach to use full interaction tensors to build the spin interaction graph.

Advanced state space tailoring

The built-in approximations described in the table above are usually sufficient in practice. However, particularly tough cases may require you to exercise finer control over which states are included and which are not. To that end, Spinach provides an option to force the inclusion of user-specified correlations. A typical specification for a 16-spin system (protons and fluorine, numbered sequentially along the chain) of difluoroheptane shown in Figure 1 would look like the following:

    bas.manual=[1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0; ...
                0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0; ...
                0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1];

This specification requests the simplest possible basis set (IK-0, level 1) that simply contains the states of individual spins, but no correlations. However, the bas.manual specification then instructs Spinach to add the complete basis set of the subsystem with spins 1 to 10, the complete basis set of the subsystem with spins 4 to 13, and the complete basis set of the subsystem with spins 7 to 16, and to eliminate repetitions within the resulting list of operators (note that the subsystems overlap). The complete Liouville space basis set for a 16-spin system would be 4,294,967,296-dimensional, which is far too big. However, the basis set described above is only 1,564,672-dimensional, which is manageable, but still contains all the spin orders that are realistically populated during the system dynamics - a plot similar to Figure 2 reveals that only correlations between up to eight spins are populated significantly in this system in liquid state.

The recipe for the manual state space tailoring therefore is to identify overlapping clusters of strongly correlated spins, so that every relevant state occurs in at least one of those clusters, and to give the information about the clusters to Spinach, which will take care of the basis set construction. Running trajan.m function to produce the plot of the kind shown in Figure 2 and confirm that the basis set is sufficiently large is always a good idea – research literature comparing the performance of different basis sets in different settings has yet to emerge.

Symmetry factorisation

A simulation that starts in a state of particular symmetry and evolves under the Hamiltonian that conserves that symmetry would never populate states of different symmetries. This is recognized by the Spinach kernel, which supports spin permutation symmetries (not geometric point groups!). The following permutation groups are supported ('A' index indicates the largest Abelian subgroup):

    S2, S3, S4, S4A, S5, S6

along with their direct products (which are generated internally in an automatic way). All spin quantum numbers are supported. The following example declares three groups of equivalent spins, each related by S3 permutation group, the first one incorporating spins 14, 15, 16, the second one spins 17, 18, 19 and the third one spins 20, 21, 22.

    bas.sym_spins={[14 15 16],[17 18 19],[20 21 22]};

Although all irreducible representations are commonly populated in Hilbert space simulations, in Liouville space only the fully symmetric irreducible representation is normally active. Accordingly, Spinach defaults to projecting the system into the fully symmetric irrep. Processing of other irreps may be forced by setting


It is important to stress that the symmetry factorization described above is using permutation groups – all interaction tensors of symmetry-related spins must be identical in orientation, in magnitude, and in the identity of external coupled partner spins.

Correlation and coherence order screening

It is often the case that the coherence order is conserved (exactly or approximately) during the system evolution process. Spinach offers three options to screen the basis sets according to coherence order and only keep the user-specified coherences. The following statement:

    bas.projections=[-1 0 1];

causes coherences of order –1, 0 and 1 to be kept in the basis. Coherence order is defined as the sum of the projection quantum numbers of all single-spin irreducible spherical tensor operators entering the direct product state. Everything else would be dropped.

The coherence order filter above refers to the whole system. In common high-field NMR experiments it is also the case that only longitudinal states are populated on specific spins (such as 15N in a 1H pulse-acquire NMR experiment). The following statement:


screens the basis so as to keep only the longitudinal spin states on the specified spins (in this case 15N and 13C).

In some exotic cases (e.g. very strongly coupled heteronuclei) it is necessary to include not only the longitudinal but also zero-quantum states of those nuclei. The following statement:


instructs Spinach to keep the zero-quantum subspaces with respect to the specified (in this case 15N and 13C).

When any two, or all three, of these options are specified simultaneously, the resulting basis set would only contain states that comply with all of the criteria at the same time.

Version 2.1, authors: Ilya Kuprov