Simulator¶

class mrsimulator.Simulator(*, name: str = None, description: str = None, label: str = None, property_units: Dict = {}, spin_systems: List[SpinSystem] = [], spin_system_models: List[Any] = [], methods: List[Method] = [], config: ConfigSimulator = ConfigSimulator(name=None, description=None, label=None, property_units={}, number_of_sidebands=64, number_of_gamma_angles=1, integration_volume='octant', integration_density=70, decompose_spectrum='none', isotropic_interpolation='linear', custom_sampling=None))¶

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) 

optimize() → None¶

Pre-computes transition pathways and associated weights for each of the Method and SpinSystem objects held by the simulator. This increases the efficiency during least-squared minimization since pathways are not re-computed during every iteration.

Example

>>> sim = Simulator()
>>> # Add spin systems and methods
>>> optimization = sim.optimize()
>>> sim.run(opt=optimization)

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, opt: Optional[dict] = None, **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.
opt (dict) – An optional optimization dictionary storing pre-computed transition pathways and transition weights for the given methods and spin systems in the simulator. The default is None, that is, the pathways and weights are calculated in the run 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() 