Simulator¶

class mrsimulator.Simulator(*, name: str = None, description: str = None, label: str = None, property_units: Dict = {}, spin_systems: List[SpinSystem] = [], methods: List[Method] = [], 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'))¶

Bases: 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 ConfigSimulator 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() 