Site¶

class mrsimulator.Site(*, property_units: Dict = {'isotropic_chemical_shift': 'ppm'}, name: str = None, label: str = None, description: str = None, isotope: str = '1H', isotropic_chemical_shift: float = 0, shielding_symmetric: mrsimulator.spin_system.tensors.SymmetricTensor = None, shielding_antisymmetric: mrsimulator.spin_system.tensors.AntisymmetricTensor = None, quadrupolar: mrsimulator.spin_system.tensors.SymmetricTensor = None)¶

Bases: mrsimulator.utils.parseable.Parseable

Base class representing a single-site nuclear spin interaction tensor parameters. The single-site nuclear spin interaction tensors include the nuclear shielding and the electric quadrupolar tensor.

Attribute Documentation

isotope¶

A string expressed as an atomic number followed by an isotope symbol, eg., ‘13C’, ‘17O’. The default value is ‘1H’.

Example

>>> site = Site(isotope='2H')

Type: str (optional)

isotropic_chemical_shift¶

The value is the isotropic chemical shift of the site in the unit of ppm. The default value is 0.

Example

>>> site.isotropic_chemical_shift = 43.3

Type: float (optional)

shielding_symmetric¶

The value of this attribute represents the irreducible second-rank traceless symmetric part of the nuclear shielding tensor. The default value is None.

The allowed attributes of the SymmetricTensor class for shielding_symmetric are zeta, eta, alpha, beta, and gamma, where zeta is the shielding anisotropy, in ppm, and eta is the shielding asymmetry parameter defined using the Haeberlen convention. The Euler angles alpha, beta, and gamma are in radians.

Example

>>> site.shielding_symmetric = {'zeta': 10, 'eta': 0.5}
>>> # or equivalently
>>> site.shielding_symmetric = SymmetricTensor(zeta=10, eta=0.5)

Type: SymmetricTensor or equivalent dict object (optional).

shielding_antisymmetric¶

The value of this attribute represents the irreducible first-rank antisymmetric part of the nuclear shielding tensor. The default value is None.

The allowed attributes of the AntisymmetricTensor class for shielding_antisymmetric are zeta, alpha, and beta, where zeta is the anisotropy parameter of the anti-symmetric first-rank tensor given in ppm. The angles alpha and beta are in radians.

Example

>>> site.shielding_antisymmetric = {'zeta': 20}
>>> # or equivalently
>>> site.shielding_antisymmetric = AntisymmetricTensor(zeta=20)

Type: AntisymmetricTensor or equivalent dict object (optional).

quadrupolar¶

The value of this attribute represents the irreducible second-rank traceless symmetric part of the electric-field gradient tensor. The default value is None.

The allowed attributes of the SymmetricTensor class for quadrupolar are Cq, eta, alpha, beta, and gamma, where Cq is the quadrupolar coupling constant, in Hz, and eta is the quadrupolar asymmetry parameter. The Euler angles alpha, beta, and gamma are in radians.

Example

>>> site.quadrupolar = {'Cq': 3.2e6, 'eta': 0.52}
>>> # or equivalently
>>> site.quadrupolar = SymmetricTensor(Cq=3.2e6, eta=0.52)

Type: SymmetricTensor or equivalent dict object (optional).

name¶

The value is the name or id of the site. The default value is None.

Example

>>> site.name = '2H-0'
>>> site.name
'2H-0'

Type: str (optional)

label¶

The value is a label for the site. The default value is None.

Example

>>> site.label = 'Quad site'
>>> site.label
'Quad site'

Type: str (optional)

description¶

The value is a description of the site. The default value is None.

Example

>>> site.description = 'An example Quadrupolar site.'
>>> site.description
'An example Quadrupolar site.'

Type: str (optional)

Example

The following are a few examples of setting the site object.

>>> site1 = Site(
...     isotope='33S',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric={
...         "zeta": 10, # in ppm
...         "eta": 0.5
...     },
...     quadrupolar={
...         "Cq": 5.1e6, # in Hz
...         "eta": 0.5
...     }
... )

Using SymmetricTensor objects.

>>> site1 = Site(
...     isotope='13C',
...     isotropic_chemical_shift=20, # in ppm
...     shielding_symmetric=SymmetricTensor(zeta=10, eta=0.5),
... )

Method Documentation

classmethod parse_dict_with_units(py_dict)¶

Parse the physical quantity from a dictionary representation of the Site object, where the physical quantity is expressed as a string with a number and a unit.

Parameters: py_dict (dict) – A required python dict object.
Returns: Site object.

Example

>>> site_dict = {
...    "isotope": "13C",
...    "isotropic_chemical_shift": "20 ppm",
...    "shielding_symmetric": {"zeta": "10 ppm", "eta":0.5}
... }
>>> site1 = Site.parse_dict_with_units(site_dict)

to_freq_dict(B0)¶

Serialize the Site object to a JSON compliant python dictionary object, where the attribute value is a number expressed in the attribute’s default unit. The default unit for the attributes with respective dimensionalities is:

frequency: Hz
angle: rad

Parameters: B0 (float) – A required macroscopic magnetic flux density in units of T.
Returns: Python dict object.

Example

>>> pprint(site1.to_freq_dict(B0=9.4))
{'description': None,
 'isotope': '13C',
 'isotropic_chemical_shift': -2013.1791999999998,
 'label': None,
 'name': None,
 'quadrupolar': None,
 'shielding_antisymmetric': None,
 'shielding_symmetric': {'alpha': None,
                         'beta': None,
                         'eta': 0.5,
                         'gamma': None,
                         'zeta': -1006.5895999999999}}

json() → dict¶: Parse the class object to a JSON compliant python dictionary object where the attribute value with physical quantity is expressed as a string with a number and a unit.

>>> pprint(site1.json())
{'isotope': '13C',
 'isotropic_chemical_shift': '20.0 ppm',
 'shielding_symmetric': {'eta': 0.5, 'zeta': '10.0 ppm'}}