Simulator

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

Bases: mrsimulator.utils.parseable.Parseable

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.method.lib import BlochDecaySpectrum
>>> from mrsimulator.method.lib import BlochDecayCTSpectrum
>>> sim.methods = [
...     BlochDecaySpectrum(channels=['17O'], rotor_frequency=15000),
...     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 the 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)

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) 
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 Saving and Loading Spin Systems from a File section.

Parameters

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

Example

>>> sim.export_spin_systems(filename) 
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']
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 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 Simulator object file.

Returns

A Simulator object.

Example

>>> sim_1 = sim.load('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) 
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 Saving and Loading Spin Systems from a File section of this documentation.

Parameters

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

Example

>>> sim.load_spin_systems(filename) 
classmethod parse(py_dict: dict, parse_units: bool = True)

Parse a dictionary for Simulator object.

Parameters
  • py_dict (dict) – Dictionary object.

  • parse_units (bool) – If true, parse quantity from string.

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
reduced_dict(exclude={})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 – A list of keys to exclude from the dictionary.

Return: A dict.

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') 
sites()

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

Returns

A Sites object.

Example

>>> sites = sim.sites()