Simulator¶

class mrsimulator.Simulator(*, name: str = None, label: str = None, description: str = None, spin_systems: List[mrsimulator.spin_system.SpinSystem] = [], methods: List[mrsimulator.method.Method] = [], config: mrsimulator.simulator.config.ConfigSimulator = ConfigSimulator(number_of_sidebands=64, integration_volume='octant', integration_density=70, decompose_spectrum='none'), indexes: list = [])¶

Bases: pydantic.main.BaseModel

The simulator class.

spin_systems¶

The value is a list of NMR spin systems present within the sample, where each spin system is an isolated system. The default value is an empty list.

Example

>>> sim = Simulator()
>>> sim.spin_systems = [
...     SpinSystem(sites=[Site(isotope='17O')], abundance=0.015),
...     SpinSystem(sites=[Site(isotope='1H')], abundance=1),
... ]
>>> # or equivalently
>>> sim.spin_systems = [
...     {'sites': [{'isotope': '17O'}], 'abundance': 0.015},
...     {'sites': [{'isotope': '1H'}], 'abundance': 1},
... ]

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

methods¶

The value is a list of NMR methods. The default value is an empty list.

Example

>>> from mrsimulator.methods import BlochDecaySpectrum
>>> from mrsimulator.methods import BlochDecayCentralTransitionSpectrum
>>> sim.methods = [
...     BlochDecaySpectrum(channels=['17O'], spectral_width=50000),
...     BlochDecayCentralTransitionSpectrum(channels=['17O'])
... ]

Type: A list of Method (optional).

config¶

The ConfigSimulator object is used to configure the simulation. The valid attributes of the ConfigSimulator object are

number_of_sidebands,
integration_density,
integration_volume, and
decompose_spectrum

Example

>>> from mrsimulator.simulator.config import ConfigSimulator
>>> sim.config = ConfigSimulator(
...     number_of_sidebands=32,
...     integration_density=64,
...     integration_volume='hemisphere',
...     decompose_spectrum='spin_system',
... )
>>> # or equivalently
>>> sim.config = {
...     'number_of_sidebands': 32,
...     'integration_density': 64,
...     'integration_volume': 'hemisphere',
...     'decompose_spectrum': 'spin_system',
... }

See Configuring Simulator object for details.

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

name¶

The value is the name or id of the simulation or sample. The default value is None.

Example

>>> sim.name = '1H-17O'
>>> sim.name
'1H-17O'

Type: str (optional)

label¶

The value is a label for the simulation or sample. The default value is None.

Example

>>> sim.label = 'Test simulator'
>>> sim.label
'Test simulator'

Type: str (optional)

description¶

The value is a description of the simulation or sample. The default value is None.

Example

>>> sim.description = 'Simulation for sample 1'
>>> sim.description
'Simulation for sample 1'

Type: str (optional)

Method Documentation

get_isotopes(spin_I=None) → set¶

Set of unique isotopes from the sites within the list of the spin systems corresponding to spin quantum number I. If I is None, a set of all unique isotopes is returned instead.

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

Example

>>> sim.get_isotopes() 
{'1H', '27Al', '13C'}
>>> sim.get_isotopes(spin_I=0.5) 
{'1H', '13C'}
>>> sim.get_isotopes(spin_I=1.5)
set()
>>> sim.get_isotopes(spin_I=2.5)
{'27Al'}

json(include_methods: bool = False, include_version: bool = False)¶

Serialize the Simulator object to a JSON compliant python dictionary object where physical quantities are represented as string with a value and a unit.

Parameters

include_methods (bool) – If True, the output dictionary will include the serialized method objects. The default value is False.
include_version (bool) – If True, add a version key-value pair to the serialized output dictionary. The default is False.

Returns

A Dict object.

Example

>>> pprint(sim.json())
{'config': {'decompose_spectrum': 'none',
            'integration_density': 70,
            'integration_volume': 'octant',
            'number_of_sidebands': 64},
 'spin_systems': [{'abundance': '100 %',
                   'sites': [{'isotope': '13C',
                              'isotropic_chemical_shift': '20.0 ppm',
                              'shielding_symmetric': {'eta': 0.5,
                                                      'zeta': '10.0 ppm'}}]},
                  {'abundance': '100 %',
                   'sites': [{'isotope': '1H',
                              'isotropic_chemical_shift': '-4.0 ppm',
                              'shielding_symmetric': {'eta': 0.1,
                                                      'zeta': '2.1 ppm'}}]},
                  {'abundance': '100 %',
                   'sites': [{'isotope': '27Al',
                              'isotropic_chemical_shift': '120.0 ppm',
                              'shielding_symmetric': {'eta': 0.1,
                                                      'zeta': '2.1 ppm'}}]}]}

classmethod parse_dict_with_units(py_dict)¶

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

Example

>>> sim_py_dict = {
...     'config': {
...         'decompose_spectrum': 'none',
...         'integration_density': 70,
...         'integration_volume': 'octant',
...         'number_of_sidebands': 64
...     },
...     'spin_systems': [
...         {
...             'abundance': '100 %',
...             'sites': [{
...                 'isotope': '13C',
...                 'isotropic_chemical_shift': '20.0 ppm',
...                 'shielding_symmetric': {'eta': 0.5, 'zeta': '10.0 ppm'}
...             }]
...         },
...         {
...             'abundance': '100 %',
...             'sites': [{
...                 'isotope': '1H',
...                     'isotropic_chemical_shift': '-4.0 ppm',
...                     'shielding_symmetric': {'eta': 0.1, 'zeta': '2.1 ppm'}
...             }]
...         },
...         {
...             'abundance': '100 %',
...             'sites': [{
...                 'isotope': '27Al',
...                 'isotropic_chemical_shift': '120.0 ppm',
...                 'shielding_symmetric': {'eta': 0.1, 'zeta': '2.1 ppm'}
...             }]
...         }
...     ]
... }
>>> sim = Simulator.parse_dict_with_units(sim_py_dict)
>>> len(sim.spin_systems)
3

load_spin_systems(filename: str)¶

Load a list of spin systems from the given JSON serialized file.

See an example of a JSON serialized file. For details, refer to the mrsimulator I/O section of this documentation.

Parameters: filename (str) – A local or remote address to a JSON serialized file.

Example

>>> sim.load_spin_systems(filename) 

export_spin_systems(filename: str)¶

Export a list of spin systems to a JSON serialized file.

See an example of a JSON serialized file. For details, refer to the mrsimulator I/O section.

Parameters: filename (str) – A filename of the serialized file.

Example

>>> sim.export_spin_systems(filename) 

run(method_index=None, pack_as_csdm=True, **kwargs)¶

Run the simulation and compute spectrum.

Parameters

method_index – An integer or a list of integers. If provided, only the simulations corresponding to the methods at the given index/indexes will be computed. The default is None, i.e., the simulation for every method will be computed.
pack_as_csdm (bool) – If true, the simulation results are stored as a CSDM object, otherwise, as a ndarray object. The simulations are stored as the value of the simulation attribute of the corresponding method.

Example

>>> sim.run() 

save(filename: str, with_units=True)¶

Serialize the simulator object to a JSON file.

Parameters

with_units (bool) – If true, the attribute values are serialized as physical quantities expressed as a string with a value and a unit. If false, the attribute values are serialized as floats.
filename (str) – The filename of the serialized file.

Example

>>> sim.save('filename') 

classmethod load(filename: str, parse_units=True)¶

Load the Simulator object from a JSON file by parsing.

Parameters

parse_units (bool) – If true, parse the attribute values from the serialized file for physical quantities, expressed as a string with a value and a unit.
filename (str) – The filename of a JSON serialized mrsimulator file.

Returns

A Simulator object.

Example

>>> sim_1 = sim.load('filename') 