Utility functions

mrsimulator.utils.collection.single_site_system_generator(isotope: Union[str, List[str]], isotropic_chemical_shift: Union[float, List[float], ndarray] = 0, shielding_symmetric: Optional[Dict] = None, shielding_antisymmetric: Optional[Dict] = None, quadrupolar: Optional[Dict] = None, abundance: Optional[Union[float, List[float], ndarray]] = None, site_name: Optional[Union[str, List[str]]] = None, site_label: Optional[Union[str, List[str]]] = None, site_description: Optional[Union[str, List[str]]] = None, rtol: float = 0.001) → List[SpinSystem]

Generate and return a list of single-site spin systems from the input parameters

Parameters:

  • isotope – A required string or a list of site isotopes.

  • isotropic_chemical_shift – A float or a list/ndarray of isotropic chemical shifts per site per spin system. The default is 0.

  • shielding_symmetric – A shielding symmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are zeta, eta, alpha, beta, and gamma.

  • shielding_antisymmetric – A shielding antisymmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are zeta, alpha, and beta.

  • quadrupolar – A quadrupolar dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are Cq, eta, alpha, beta, and gamma.

  • abundance – A float or a list/ndarray of floats describing the abundance of each spin system.

  • site_name – A string or a list of strings with site names per site per spin system. The default is None.

  • site_label – A string or a list of strings with site labels per site per spin system. The default is None.

  • site_description – A string or a list of strings with site descriptions per site per spin system. The default is None.

  • rtol – The relative tolerance used in determining the cutoff abundance, given as, \(\tt{abundance}_{\tt{cutoff}} = \tt{rtol} * \tt{max(abundance)}.\) The spin systems with abundance below this threshold are ignored.

Returns:

List of SpinSystem objects with a single Site

Example

Single spin system:

>>> sys1 = single_site_system_generator(
...     isotope=["1H"],
...     isotropic_chemical_shift=10,
...     site_name="Single Proton",
... )
>>> print(len(sys1))
1

Multiple spin system:

>>> sys2 = single_site_system_generator(
...     isotope="1H",
...     isotropic_chemical_shift=[10] * 5,
...     site_name="5 Protons",
... )
>>> print(len(sys2))
5

Multiple spin system with dictionary arguments:

>>> Cq = [4.2e6] * 12
>>> sys3 = single_site_system_generator(
...     isotope="17O",
...     isotropic_chemical_shift=60.0,  # in ppm,
...     quadrupolar={"Cq": Cq, "eta": 0.5},  # Cq in Hz
... )
>>> print(len(sys3))
12

Note

The parameter value can either be a float or a list/ndarray. If the parameter value is a float, the given value is assigned to the respective parameter in all the spin systems. If the parameter value is a list or ndarray, its ith value is assigned to the respective parameter of the ith spin system. When multiple parameter values are given as lists/ndarrays, the length of all the lists must be the same.

mrsimulator.utils.collection.site_generator(isotope: Union[str, List[str]], isotropic_chemical_shift: Union[float, List[float], ndarray] = 0, shielding_symmetric: Optional[Dict] = None, shielding_antisymmetric: Optional[Dict] = None, quadrupolar: Optional[Dict] = None, name: Optional[Union[str, List[str]]] = None, label: Optional[Union[str, List[str]]] = None, description: Optional[Union[str, List[str]]] = None) → List[Site]

Generate a list of Site objects from lists of site attributes.

Parameters:

  • isotope – A required string or a list of site isotopes.

  • isotropic_chemical_shift – A float or a list/ndarray of isotropic chemical shifts per site. The default is 0.

  • shielding_symmetric – A shielding symmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are zeta, eta, alpha, beta, and gamma.

  • shielding_antisymmetric – A shielding antisymmetric dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are zeta, alpha, and beta.

  • quadrupolar – A quadrupolar dict object, where the keyword value can either be a float or a list/ndarray of floats. The default value is None. The allowed keywords are Cq, eta, alpha, beta, and gamma.

  • name – A string or a list of strings with site names per site. The default is None.

  • label – A string or a list of strings with site labels per site. The default is None.

  • description – A string or a list of strings with site descriptions per site. The default is None.

Returns:

List of Site objects

Return type:

sites

Example

Generating 10 hydrogen sites:

>>> sites1 = site_generator(
...     isotope=["1H"] * 10,
...     isotropic_chemical_shift=-15,
...     name="10 Protons",
... )
>>> print(len(sites1))
10

Generating 10 hydrogen sites with different shifts:

>>> shifts = np.arange(-10, 10, 2)
>>> sites2 = site_generator(
...     isotope=["1H"] * 10,
...     isotropic_chemical_shift=shifts,
...     name="10 Proton",
... )
>>> print(len(sites2))
10

Generating multiple sites with dictionary arguments:

>>> Cq = [4.2e6] * 12
>>> sys3 = site_generator(
...     isotope="17O",
...     isotropic_chemical_shift=60.0,  # in ppm,
...     quadrupolar={"Cq": Cq, "eta": 0.5},  # Cq in Hz
... )
>>> print(len(sys3))
12
mrsimulator.utils.get_spectral_dimensions(csdm_object, units=False)

Extract the count, spectral_width, and reference_offset parameters, associated with the spectral dimensions of the method, from the CSDM dimension objects.

Parameters:

csdm_object – A CSDM object holding the measurement dataset.

Returns:

A list of dict objects, where each dict contains the count, spectral_width, and reference_offset.