SpinSystem¶

class mrsimulator.SpinSystem(*, property_units: Dict = {'abundance': 'pct'}, name: str = None, label: str = None, description: str = None, sites: List[mrsimulator.spin_system.site.Site] = [], abundance: mrsimulator.spin_system.ConstrainedFloatValue = 100, transition_pathways: List = None)¶

Bases: mrsimulator.utils.parseable.Parseable

Base class representing an isolated spin system containing multiple sites and couplings amongst them.

Attribute Documentation

sites¶

The value is a list of sites within the spin system, where each site represents a single-site nuclear spin interaction tensor parameters. The default value is an empty list.

Example

>>> sys1 = SpinSystem()
>>> sys1.sites = [Site(isotope='17O'), Site(isotope='1H')]
>>> # or equivalently
>>> sys1.sites = [{'isotope': '17O'}, {'isotope': '1H'}]

Type: A list of Site objects or equivalent dict objects (optional).

abundance¶

The abundance of the spin system in units of %. The default value is 100. The value of this attribute is useful when multiple spin systems are present.

Example

>>> sys1.abundance = 10

Type: float (optional)

name¶

The value is the name or id of the spin system. The default value is None.

Example

>>> sys1.name = '1H-17O-0'
>>> sys1.name
'1H-17O-0'

Type: str (optional)

label¶

The value is a label for the spin system. The default value is None.

Example

>>> sys1.label = 'Heteronuclear spin system'
>>> sys1.label
'Heteronuclear spin system'

Type: str (optional)

description¶

The value is a description of the spin system. The default value is None.

Example

>>> sys1.description = 'A test for the spin system'
>>> sys1.description
'A test for the spin system'

Type: str (optional)

transition_pathways¶

The value is a list of lists, where the inner list represents a transition pathway, and the outer list is the number of transition pathways. Each transition pathways is a list of Transition objects. The resulting spectrum is a sum of the resonances arising from individual transition pathways. The default value is None.

Example

>>> sys1.transition_pathways = [
...     [
...         {'initial': [-2.5, 0.5], 'final': [2.5, 0.5]},
...         {'initial': [0.5, 0.5], 'final': [-0.5, 0.5]}
...     ]
... ]

Note

From any given spin system, the list of relevant transition pathways is determined by the applied NMR method. For example, consider a single site I=3/2 spin system. For this system, a Bloch decay spectrum method will select three transition pathways, one corresponding to the central and two to the satellite transitions. On the other hand, a Bloch decay central transition selective method will only select one transition pathway, corresponding to the central transition.

Since the spin system is independent of the NMR method, the value of this attribute is, therefore, transient. You may use this attribute to override the default transition pathway query selection criterion of the NMR method objects.

Only use this attribute if you know what you are doing.

At times, this attribute may provide a significant improvement in the performance, especially in iterative algorithms, such as the least-squares algorithm, where a one-time transition pathway query is sufficient. Repeated queries for the transition pathways will add significant overhead to the computation.

See also

Fitting example

Type: list (optional)

Method Documentation

get_isotopes(spin_I=None) → list¶

An ordered list of isotopes from sites within the spin system corresponding to the given value of spin quantum number I. If I is None, a list of all isotopes is returned instead.

Parameters: spin_I (float) – An optional spin quantum number. The valid inputs are the multiples of 0.5.
Returns: A list of isotopes.

Example

>>> spin_systems.get_isotopes() # three spin systems
['13C', '1H', '27Al']
>>> spin_systems.get_isotopes(spin_I=0.5) # isotopes with I=0.5
['13C', '1H']
>>> spin_systems.get_isotopes(spin_I=1.5) # isotopes with I=1.5
[]
>>> spin_systems.get_isotopes(spin_I=2.5) # isotopes with I=2.5
['27Al']

zeeman_energy_states() → list¶

Return a list of all Zeeman energy states of the spin system, where the energy states are represented by a list of quantum numbers,

(25)¶\[|\Psi⟩ = [m_1, m_2,.. m_n],\]

where \(m_i\) is the quantum number associated with the \(i^\text{th}\) site within the spin system, and \(\Psi\) is the energy state.

Example

>>> spin_system_1H_13C.get_isotopes() # two site (spin-1/2) spin systems
['13C', '1H']
>>> spin_system_1H_13C.zeeman_energy_states()  # four energy level system.
[|-0.5, -0.5⟩, |-0.5, 0.5⟩, |0.5, -0.5⟩, |0.5, 0.5⟩]

Returns: A list of ZeemanState objects.

all_transitions() → mrsimulator.transition.transition_list.TransitionList¶

Returns a list of all possible spin transitions in the given spin system.

Example

>>> spin_system_1H_13C.get_isotopes()  # two site (spin-1/2) spin system
['13C', '1H']
>>> spin_system_1H_13C.all_transitions()  # 16 two energy level transitions
[|-0.5, -0.5⟩⟨-0.5, -0.5|,
|-0.5, 0.5⟩⟨-0.5, -0.5|,
|0.5, -0.5⟩⟨-0.5, -0.5|,
|0.5, 0.5⟩⟨-0.5, -0.5|,
|-0.5, -0.5⟩⟨-0.5, 0.5|,
|-0.5, 0.5⟩⟨-0.5, 0.5|,
|0.5, -0.5⟩⟨-0.5, 0.5|,
|0.5, 0.5⟩⟨-0.5, 0.5|,
|-0.5, -0.5⟩⟨0.5, -0.5|,
|-0.5, 0.5⟩⟨0.5, -0.5|,
|0.5, -0.5⟩⟨0.5, -0.5|,
|0.5, 0.5⟩⟨0.5, -0.5|,
|-0.5, -0.5⟩⟨0.5, 0.5|,
|-0.5, 0.5⟩⟨0.5, 0.5|,
|0.5, -0.5⟩⟨0.5, 0.5|,
|0.5, 0.5⟩⟨0.5, 0.5|]

classmethod parse_dict_with_units(py_dict: dict) → dict¶

Parse the physical quantity from a dictionary representation of the SpinSystem 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: SpinSystem object.

Example

>>> spin_system_dict = {
...     "sites": [{
...         "isotope":"13C",
...         "isotropic_chemical_shift": "20 ppm",
...         "shielding_symmetric": {
...             "zeta": "10 ppm",
...             "eta": 0.5
...         }
...     }]
... }
>>> spin_system_1 = SpinSystem.parse_dict_with_units(spin_system_dict)

to_freq_dict(B0: float) → dict¶

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

frequency: Hz
angle: rad

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

Example

>>> pprint(spin_system_1.to_freq_dict(B0=9.4))
{'abundance': 100,
 'description': None,
 'label': None,
 'name': None,
 'sites': [{'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}}],
 'transition_pathways': None}

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(spin_system_1.json())
{'abundance': '100 %',
 'sites': [{'isotope': '13C',
            'isotropic_chemical_shift': '20.0 ppm',
            'shielding_symmetric': {'eta': 0.5, 'zeta': '10.0 ppm'}}]}