Coupling¶

class mrsimulator.Coupling(*, name: str = None, description: str = None, label: str = None, property_units: Dict = {'isotropic_j': 'Hz'}, site_index: List[int], isotropic_j: float = 0.0, j_symmetric: SymmetricTensor = None, j_antisymmetric: AntisymmetricTensor = None, dipolar: SymmetricTensor = None)¶

Bases: Parseable

Base class representing a two-site coupled nuclear spin interaction tensor parameters, which include the J-coupling and dipolar tensor.

Attribute Documentation

site_index¶

A list of two integers, each corresponding to the index of the coupled sites.

Example

>>> coupling = Coupling(site_index=[0, 1])

Type:: list of int (required).

isotropic_j¶

The isotropic j-coupling, in Hz, between the coupled sites. The default is 0.

Example

>>> coupling.isotropic_j = 43.3

Type:: float (optional).

j_symmetric¶

The attribute represents the parameters of the irreducible second-rank traceless symmetric part of the J-coupling tensor. The default value is None.

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

Example

>>> coupling.j_symmetric = {'zeta': 10, 'eta': 0.5}

>>> # or equivalently
>>> coupling.j_symmetric = SymmetricTensor(zeta=10, eta=0.5)

Type:: SymmetricTensor or equivalent dict object (optional).

j_antisymmetric¶

The attribute represents the parameters of the irreducible first-rank antisymmetric part of the J tensor. The default value is None.

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

Example

>>> coupling.j_antisymmetric = {'zeta': 20}

>>> # or equivalently
>>> coupling.j_antisymmetric = AntisymmetricTensor(zeta=20)

Type:: AntisymmetricTensor or equivalent dict object (optional).

dipolar¶

The attribute represents the parameters of the irreducible second-rank traceless symmetric part of the direct-dipolar coupling tensor. The default value is None.

The allowed attributes of the SymmetricTensor class for dipolar are D, alpha, beta, and gamma, where D is the dipolar coupling constant, in Hz. The Euler angles alpha, beta, and gamma are in radians.

Example

>>> coupling.dipolar = {'D': 320}

>>> # or equivalently
>>> coupling.dipolar = SymmetricTensor(D=320)

Type:: SymmetricTensor or equivalent dict object (optional).

name¶

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

Example

>>> coupling.name = '1H-1H'
>>> coupling.name
'1H-1H'

Type:: str (optional).

label¶

The label for the coupling. The default value is None.

Example

>>> coupling.label = 'Weak coupling'
>>> coupling.label
'Weak coupling'

Type:: str (optional).

description¶

A description of the coupling. The default value is None.

Example

>>> coupling.description = 'An example coupled sites.'
>>> coupling.description
'An example coupled sites.'

Type:: str (optional).

Example

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

>>> coupling1 = Coupling(
...     site_index=[0, 1],
...     isotropic_j=20, # in Hz
...     j_symmetric={
...         "zeta": 10, # in Hz
...         "eta": 0.5
...     },
...     dipolar={"D": 5.1e3}, # in Hz
... )

Using SymmetricTensor objects.

>>> coupling1 = Coupling(
...     site_index=[0, 1],
...     isotropic_j=20, # in Hz
...     j_symmetric=SymmetricTensor(zeta=10, eta=0.5),
...     dipolar=SymmetricTensor(D=5.1e3), # in Hz
... )

json(exclude={}, units=True) → dict¶

Parse the class object to a JSON compliant Python dictionary object.

Parameters:

exclude – Set of keys that will be excluded from the result.
units – If true, the attribute value is a physical quantity expressed as a string with a number and a unit, else a float.

Returns: dict

classmethod parse_dict_with_units(py_dict: dict)¶

Parse the physical quantity from a dictionary representation of the Coupling 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

>>> coupling_dict = {
...    "site_index": [1, 2],
...    "isotropic_j": "20 Hz",
...    "j_symmetric": {"zeta": "10 Hz", "eta":0.5}
... }
>>> coupling1 = Coupling.parse_dict_with_units(coupling_dict)

reduced_dict(exclude={}) → dict¶

Returns a reduced dictionary representation of the class object by removing all key-value pairs corresponding to keys listed in the exclude argument, and keys with a value of None.

Parameters:: exclude – A list of keys to exclude from the dictionary.

Return: A dict.

rotate(euler_angles: list) → None¶

Rotate the site tensors (shielding, quadrupolar) by the given list of Euler angle rotations. Euler angles are given as a list of (alpha, beta, gamma) tuples, and rotations happen in the Haeberlen (ZYZ) convention.

Parameters:: euler_angles ((list)) – An ordered list of angle tuples (alpha, beta, gamma) to rotate through each tensor.