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

A list of SpinSystem or equivalent dict objects representing a collection of isolated NMR spin systems present within the sample. 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

A list of Method or equivalent dict objects representing an NMR methods. The default value is an empty list.

Example

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

A list of Method or equivalent dict objects (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 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 label for the simulation or sample. The default value is None.

Example

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

str (optional)

description

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

classmethod parse_dict_with_units(py_dict: 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
json(include_methods: bool = False, include_version: bool = False)

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 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.0 %',
                   'sites': [{'isotope': '13C',
                              'isotropic_chemical_shift': '20.0 ppm',
                              'shielding_symmetric': {'eta': 0.5,
                                                      'zeta': '10.0 ppm'}}]},
                  {'abundance': '100.0 %',
                   'sites': [{'isotope': '1H',
                              'isotropic_chemical_shift': '-4.0 ppm',
                              'shielding_symmetric': {'eta': 0.1,
                                                      'zeta': '2.1 ppm'}}]},
                  {'abundance': '100.0 %',
                   'sites': [{'isotope': '27Al',
                              'isotropic_chemical_shift': '120.0 ppm',
                              'shielding_symmetric': {'eta': 0.1,
                                                      'zeta': '2.1 ppm'}}]}]}
reduced_dict(exclude=['property_units', 'indexes']) → dict

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

Parameters

exclude (list) – A list of keys to exclude from the dictionary.

Return: A dict.

get_isotopes(spin_I: Optional[float] = None, symbol: bool = False) → list

List of unique isotopes from the sites within the list of the spin systems corresponding to spin quantum number I. If I is None, a list 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.

  • symbol (bool) – If true, return a list of str with isotope symbols.

Returns

A list of Isotope objects.

Example

>>> sim.get_isotopes()
[Isotope(symbol='13C'), Isotope(symbol='1H'), Isotope(symbol='27Al')]
>>> sim.get_isotopes(symbol=True)
['13C', '1H', '27Al']

>>> sim.get_isotopes(spin_I=0.5)
[Isotope(symbol='13C'), Isotope(symbol='1H')]
>>> sim.get_isotopes(spin_I=0.5, symbol=True)
['13C', '1H']

>>> sim.get_isotopes(spin_I=1.5)
[]

>>> sim.get_isotopes(spin_I=2.5)
[Isotope(symbol='27Al')]
>>> sim.get_isotopes(spin_I=2.5, symbol=True)
['27Al']
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)
load_methods(filename: str)

Load a list of methods from the given JSON serialized file.

Parameters

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

Example

>>> sim.load_methods(filename)
export_methods(filename: str)

Export a list of methods to a JSON serialized file.

Parameters

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

Example

>>> sim.export_methods(filename)
run(method_index: Optional[list] = None, n_jobs: int = 1, pack_as_csdm: bool = 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 all 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: bool = 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: bool = 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')

See also

mrsimulator I/O

sites()

Unique sites within the Simulator object as a list of Site objects.

Returns

A Sites object.

Example

>>> sites = sim.sites()