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
, andgamma
, wherezeta
is the J anisotropy, in Hz, andeta
is the J asymmetry parameter defined using the Haeberlen convention. The Euler anglesalpha
,beta
, andgamma
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
, andbeta
, wherezeta
is the anisotropy parameter of the anti-symmetric first-rank tensor given in Hz. The anglesalpha
andbeta
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
, andgamma
, whereD
is the dipolar coupling constant, in Hz. The Euler anglesalpha
,beta
, andgamma
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.