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, is_complex=True))

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 method. 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 is 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 a 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 pairs corresponding to keys listed in the exclude argument, and keys with a value of 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 methods 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()