Introduction to Spin Systems

At the heart of any mrsimulator calculation is the definition of a SpinSystem object describing the sites and couplings within a spin system. We begin by examining the definition of a Site object.

Site

A site object holds single site NMR interaction parameters, which includes the nuclear shielding and quadrupolar interaction parameters. Consider the example below of a JSON serialization of a Site object for a deuterium nucleus.

Listing 1 An example 2H site in JSON representation.
 1{
 2    "isotope": "2H",
 3    "isotropic_chemical_shift": "4.1 ppm",
 4    "shielding_symmetric": {
 5        "zeta": "12.12 ppm",
 6        "eta": 0.82,
 7        "alpha": "5.45 rad",
 8        "beta": "4.82 rad",
 9        "gamma": "0.5 rad"
10    },
11    "quadrupolar": {
12        "Cq": "1.47 MHz",
13        "eta": 0.27,
14        "alpha": "0.212 rad",
15        "beta": "1.231 rad",
16        "gamma": "3.1415 rad"
17    }
18}

The isotope key holds the spin isotope, here given a value of 2H. The isotropic_chemical_shift is the isotropic chemical shift of the site isotope, \(^2\text{H}\), here given as 4.1 ppm. We have additionally defined an optional shielding_symmetric key, whose value holds a dictionary with the components of the second-rank traceless symmetric nuclear shielding tensor. We parameterize this tensor using the Haeberlen convention with parameters zeta and eta, defined as the shielding anisotropy and asymmetry, respectively. The Euler angle orientations, alpha, beta, and gamma are the relative orientation of the nuclear shielding tensor from a common reference frame.

Since deuterium is a quadrupolar nucleus, \(I>1/2\), there also can be a quadrupolar coupling interaction between the nuclear quadrupole moment and the surrounding electric field gradient (EFG) tensor, defined in a dictionary held in the optional key quadrupolar. An EFG tensor is a second-rank traceless symmetric tensor, and we describe its components with Cq and eta, i.e., the quadrupolar coupling constant and asymmetry parameter, respectively. Additionally, we see the Euler angle orientations, alpha, beta, and gamma, which are the relative orientation of the EFG tensor from a common reference frame.

See Table 2 and Table 4 for further information on the Site and SymmetricTensor objects and their attributes, respectively.

Coupling

A coupling object holds two site NMR interaction parameters, which includes the J-coupling and the dipolar coupling interaction parameters. Consider the example below of a JSON serialization of a Coupling object.

Listing 2 A Coupling object in JSON representation.
 1{
 2  "site_index": [0, 1],
 3  "isotropic_j": "15 Hz",
 4  "j_symmetric": {
 5      "zeta": "12.12 Hz",
 6      "eta": 0.82,
 7      "alpha": "2.45 rad",
 8      "beta": "1.75 rad",
 9      "gamma": "0.15 rad"
10  },
11  "dipolar": {
12      "D": "1.7 kHz",
13      "alpha": "0.12 rad",
14      "beta": "0.231 rad",
15      "gamma": "1.1415 rad"
16  }
17}

The site_index key holds a list of two integers corresponding to the index of the two coupled sites within the spin system. The value of the isotropic_j is the isotropic J-coupling, here given as 15 Hz. We have additionally defined an optional j_symmetric key, whose value holds a dictionary with the components of the second-rank traceless symmetric J-coupling tensor. We parameterize this tensor using the Haeberlen convention with parameters zeta and eta, defined as the J-coupling anisotropy and asymmetry parameters, respectively. The Euler angle orientations, alpha, beta, and gamma are the relative orientation of the J-coupling tensor from a common reference frame.

Additionally, the dipolar coupling interaction between the coupled nuclei is defined with an optional dipolar key. A dipolar tensor is a second-rank traceless symmetric tensor, and we describe the dipolar coupling constant with the parameter D. The Euler angle orientations, alpha, beta, and gamma are the relative orientation of the dipolar tensor from a common reference frame.

See Table 3 and Table 4 for further information on the Site and SymmetricTensor objects and their attributes, respectively.

SpinSystem

The SpinSystem object is a collection of sites and couplings within a spin system.

Uncoupled Spin System

Using the previous 2H Site object example, we construct a simple single-site SpinSystem object, as shown below.

Listing 3 An example of uncoupled 2H spin system in JSON representation.
 1{
 2    "name": "2H uncoupled spin system",
 3    "description": "An optional description of the spin system",
 4    "sites": [
 5      {
 6        "isotope": "2H",
 7        "isotropic_chemical_shift": "4.1 ppm",
 8        "shielding_symmetric": {
 9            "zeta": "12.12 ppm",
10            "eta": 0.82,
11            "alpha": "5.45 rad",
12            "beta": "4.82 rad",
13            "gamma": "0.5 rad"
14        },
15        "quadrupolar": {
16            "Cq": "1.47 MHz",
17            "eta": 0.27,
18            "alpha": "0.212 rad",
19            "beta": "1.231 rad",
20            "gamma": "3.1415 rad"
21        }
22      }
23    ],
24    "abundance": "0.148%"
25}

At the root level of the SpinSystem object, we find four keywords, name, description, sites, and abundance. The value of the name key is the optional name of the spin system, here given a value of 2H uncoupled spin system. The value of the description key is an optional string describing the spin system. The value of the sites key is a list of Site objects. Here, this list comprises of single Site object (lines 5-22) from Listing 1. The value of the abundance key is the abundance of the spin system, here given a value of 0.148%.

See Table 1 for further description of the SpinSystem class and its attributes.

Coupled Spin System

Appending to the previous single-site spin system example from Listing 3, we construct a two-spin coupled spin system, as follows.

Listing 4 An example of coupled 2H-13C spin system in JSON representation.
 1{
 2    "name": "2H-13C coupled spin system",
 3    "description": "An optional description of the spin system",
 4    "sites": [
 5      {
 6        "isotope": "2H",
 7        "isotropic_chemical_shift": "4.1 ppm",
 8        "shielding_symmetric": {
 9            "zeta": "12.12 ppm",
10            "eta": 0.82,
11            "alpha": "5.45 rad",
12            "beta": "4.82 rad",
13            "gamma": "0.5 rad"
14        },
15        "quadrupolar": {
16            "Cq": "1.47 MHz",
17            "eta": 0.27,
18            "alpha": "0.212 rad",
19            "beta": "1.231 rad",
20            "gamma": "3.1415 rad"
21        }
22      },
23      {
24        "isotope": "13C",
25        "isotropic_chemical_shift": "-53.2 ppm",
26        "shielding_symmetric": {
27            "zeta": "90.5 ppm",
28            "eta": 0.64
29        }
30      }
31    ],
32    "couplings": [
33      {
34        "site_index": [0, 1],
35        "isotropic_j": "15 Hz",
36        "j_symmetric": {
37            "zeta": "12.12 Hz",
38            "eta": 0.82,
39            "alpha": "2.45 rad",
40            "beta": "1.75 rad",
41            "gamma": "0.15 rad"
42        },
43        "dipolar": {
44            "D": "1.7 kHz",
45            "alpha": "0.12 rad",
46            "beta": "0.231 rad",
47            "gamma": "1.1415 rad"
48        }
49      }
50    ],
51    "abundance": "0.48%"
52}

In comparison to the previous example, there are five keywords at the root level of the SpinSystem object, name, description, sites, couplings, and abundance. In this example, the value of the sites key holds a list of two Site objects. At index 0 (lines 5-22) is the 2H site from Listing 1, and at index 1 (lines 23-30) is a 13C site. The value of the couplings key is a list of Coupling objects. In this example, we define a single coupling object (lines 33-49) from Listing 2. The value of the site_index key within the coupling object, line 34, corresponds to the site index from the sites list.

Table of Class Attributes

Table 1 The attributes of a SpinSystem object.

Attributes

Type

Description

name

String

An optional attribute with a name for the spin system. Naming is a good practice as it improves the readability, especially when multiple spin systems are present. The default value is an empty string.

description

String

An optional attribute describing the spin system. The default value is an empty string.

sites

List

An optional list of Site objects. The default value is an empty list.

couplings

List

An optional list of coupling objects. The default value is an empty list.

abundance

String

An optional quantity representing the abundance of the spin system. The abundance is given as percentage, for example, 25.4 %. This value is useful when multiple spin systems are present. The default value is 100 %.
Table 2 The attributes of a Site object.

Attribute name

Type

Description

isotope

String

A required isotope string given as the atomic number followed by the isotope symbol, for example, 13C, 29Si, 27Al, and so on.

isotropic_chemical_shift

ScalarQuantity

An optional physical quantity describing the isotropic chemical shift of the site. The value is given in dimensionless frequency ratio, for example, 10 ppm or 10 µHz/Hz. The default value is 0 ppm.

shielding_symmetric

SymmetricTensor

An optional object describing the second-rank traceless symmetric nuclear shielding tensor following the Haeberlen convention. The default is a NULL object. See the description for the SymmetricTensor object.

quadrupolar

SymmetricTensor

An optional object describing the second-rank traceless electric quadrupole tensor. The default is a NULL object. See the description for the SymmetricTensor object.
Table 3 The attributes of a Coupling object.

Attribute name

Type

Description

site_index

List of two integers

A required list with integers corresponding to the site index of the coupled sites, for example, [0, 1], [2, 1]. The order of the integers is irrelevant.

isotropic_j

ScalarQuantity

An optional physical quantity describing the isotropic J-coupling in Hz. The default value is 0 Hz.

j_symmetric

SymmetricTensor

An optional object describing the second-rank traceless symmetric J-coupling tensor following the Haeberlen convention. The default is a NULL object. See the description for the SymmetricTensor object.

dipolar

SymmetricTensor

An optional object describing the second-rank traceless dipolar tensor. The default is a NULL object. See the description for the SymmetricTensor object.
Table 4 The attributes of a SymmetricTensor object.

Attribute name

Type

Description

zeta

or

Cq

or

D

ScalarQuantity

A required quantity.

Nuclear shielding: The shielding anisotropy, zeta, calculated using the Haeberlen convention. The value is a physical quantity given in dimensionless frequency ratio, for example, 10 ppm or 10 µHz/Hz.

Electric quadrupole: The quadrupole coupling constant, Cq. The value is a physical quantity given in units of frequency, for example, 3.1 MHz.

J-coupling: The J-coupling anisotropy, zeta, calculated using the Haeberlen convention. The value is a physical quantity given in frequency unit, for example, 10 Hz or 0.3 kHz.

Dipolar-coupling: The dipolar-coupling constant, D. The value is a physical quantity given in frequency unit, for example, 1 kHz or 9 kHz.

eta

Float

A required asymmetry parameter calculated using the Haeberlen convention, for example, 0.75. The parameter is set to zero for the dipolar tensor.

alpha

ScalarQuantity

An optional Euler angle, \(\alpha\). For example, 2.1 rad. The default value is 0 rad.

beta

ScalarQuantity

An optional Euler angle, \(\beta\). For example, 90°. The default value is 0 rad.

gamma

ScalarQuantity

An optional Euler angle, \(\gamma\). For example, 0.5 rad. The default value is 0 rad.