soprano.calculate.nmr.nmr

soprano.calculate.nmr.nmr#

Classes and functions for simulating approximated NMR spectroscopic results from structures.

Classes

NMRCalculator(sample[, larmor_frequency, ...])

An object providing an interface to produce basic simulated NMR spectra from .magres files.

NMRData2D([atoms, xelement, yelement, ...])

Class to hold and extract 2D NMR data.

NMRPlot2D(nmr_data[, plot_settings])

Class to plot 2D NMR data.

PlotSettings([xlim, ylim, x_axis_label, ...])

class soprano.calculate.nmr.nmr.NMRCalculator(sample, larmor_frequency=400, larmor_units='MHz')[source]#

Bases: object

An object providing an interface to produce basic simulated NMR spectra from .magres files. It should be kept in mind that this is not a proper spin simulation tool, but merely provides a ‘guide for the eye’ kind of spectrum to compare to experimental results. What it can simulate:

  • chemical shift of NMR peaks

  • quadrupolar shifts of NMR peaks up to second order corrections

  • effects of crystal orientation (single crystal)

  • powder average (policrystalline/powder)

  • ultrafast MAS limit spectra

What it can NOT simulate:

  • finite speed MAS spectra

  • J couplings

  • dipolar interactions

  • complex NMR experiments

A list of the currently available NMRFlags to be used in conjunction with methods that require a list of effects of interest:

NMRFlags.CS_ISO     => chemical shielding, isotropic effect
        .CS_ORIENT  => chemical shielding, orientation dependent
                       effects
        .CS         => chemical shielding, everything
        .Q_1_ORIENT => quadrupolar, 1st order, orientation dependent
                       effects
        .Q_2_SHIFT  => quadrupolar, 2nd order, isotropic shift
        .Q_2_ORIENT_STATIC => quadrupolar, 2nd order, orientation
                              dependent effects; static limit
        .Q_2_ORIENT_MAS => quadrupolar, 2nd order, orientation
                              dependent effects; ultrafast MAS limit
        .Q_2_STATIC => quadrupolar, 2nd order, all static effects
        .Q_2_MAS    => quadrupolar, 2nd order, all ultrafast MAS
                       effects
        .Q_STATIC   => quadrupolar, all static effects
        .Q_MAS      => quadrupolar, all ultrafast MAS effects
        .STATIC     => all static effects
        .MAS        => all ultrafast MAS effects
Args:
sample (ase.Atoms): an Atoms object describing the system to simulate
on. Should be loaded with ASE from a .magres file
if data on shieldings and EFGs is necessary. It
can also have an optional ‘isotopes’ array. If it
does, it will be used in the set_isotopes method
and interpreted as described in its documentation.
larmor_frequency (float): larmor frequency of the virtual spectrometer
(referenced to Hydrogen). Default is 400.
larmor_units (str): units in which the larmor frequency is expressed.
Default are MHz.
property B#

Static magnetic field, in Tesla

dq_buildup(sel_i, sel_j=None, t_max=0.001, t_steps=1000, R_cut=3, kdq=0.155, A=1, tau=inf)[source]#

Return a dictionary of double quantum buildup curves for given pairs of atoms, built according to the theory given in:

G. Pileio et al., “Analytical theory of gamma-encoded double-quantum recoupling sequences in solid-state nuclear magnetic resonance” Journal of Magnetic Resonance 186 (2007) 65-74

Args:
sel_i (AtomSelection or [int]): Selection or list of indices of
atoms for which to compute the
curves. By default is None
(= all of them).
sel_i (AtomSelection or [int]): Selection or list of indices of
atoms for which to compute the
curves with sel_i. By default is
None (= same as sel_i).
t_max (float): maximum DQ buildup time, in seconds. Default
is 1e-3.
t_steps (int): number of DQ buildup time steps. Default is 1000.
R_cut (float): cutoff radius for which periodic copies to consider
in each pair, in Angstrom. Default is 3.
kdq (float): same as the k constant in eq. 35 of the reference. A
parameter depending on the specific sequence used.
Default is 0.155.
A (float): overall scaling factor for the curve. Default is 1.
tau (float): exponential decay factor for the curve. Default
is np.inf.
Returns:
curves (dict): a dictionary of all buildup curves indexed by pair,
plus the time axis in seconds as member ‘t’.
get_larmor_frequency(element)[source]#

Get the Larmor frequency of the virtual spectrometer for the desired element in MHz.

Args:
element (str): element and isotope whose frequency we require.
Should be in the form <isotope><element>. Isotope
is optional, if absent the most abundant NMR active
one will be used. Default is 1H.
Returns:
larmor (float): Larmor frequency in MHz
set_element_isotope(element, isotope)[source]#

Set the isotope for all occurrences of a given element.

Args:
element (str): chemical symbol of the element for which to set the
isotope.
isotope (int or str): isotope to set for the given element. The
same conventions as described for the array
passed to set_isotopes apply.
set_isotopes(isotopes)[source]#

Set the isotopes for each atom in sample.

Args:
isotopes (list): list of isotopes for each atom in sample.
Isotopes can be given as an array of integers or
of symbols in the form <isotope><element>.
Their order must match the one of the atoms in
the original sample ase.Atoms object.
If an element of the list is None, the most
common NMR-active isotope is used. If an element
is the string ‘Q’, the most common quadrupolar
active isotope for that nucleus (if known) will
be used.
set_larmor_frequency(larmor_frequency=400, larmor_units='MHz', element='1H')[source]#

Set the Larmor frequency of the virtual spectrometer with the desired units and reference element.

Args:
larmor_frequency (float): larmor frequency of the virtual
spectrometer. Default is 400.
larmor_units (str): units in which the larmor frequency is
expressed. Can be MHz or T. Default are MHz.
element (str): element and isotope to reference the frequency to.
Should be in the form <isotope><element>. Isotope
is optional, if absent the most abundant NMR active
one will be used. Default is 1H.
set_powder(N=8, mode='hemisphere')[source]#

Set the orientation of the sample as a powder average.

Args:
N (int): the number of subdivisions used to generate orientations
within the POWDER algorithm. Higher values make for
better but more expensive averages.
mode (str): which part of the solid angle to cover with the
orientations. Can be ‘octant’, ‘hemisphere’ or
‘sphere’. The latter should not be necessary for any
NMR interaction. Default is ‘hemisphere’.
set_reference(ref, element)[source]#

Set the chemical shift reference (in ppm) for a given element. If not provided it will be assumed to be zero.

Args:
ref (float): reference shielding value in ppm. Chemical shift will
be calculated as this minus the atom’s ms.
element (str): element and isotope whose reference is set.
Should be in the form <isotope><element>. Isotope
is optional, if absent the most abundant NMR active
one will be used.
set_single_crystal(theta, phi)[source]#

Set the orientation of the sample as a single crystallite.

Args:
theta (float): zenithal angle for the crystallite
phi (float): azimuthal angle for the crystallite
spectrum_1d(element, min_freq=-50, max_freq=50, bins=100, freq_broad=None, freq_units='ppm', effects=1, use_central=False, use_reference=None)[source]#

Return a simulated spectrum for the given sample and element.

Args:
element (str): element and isotope to get the spectrum of.
Should be in the form <isotope><element>. Isotope
is optional, if absent the most abundant NMR active
one will be used.
min_freq (float): lower bound of the frequency range
(default is -50)
min_freq (float): upper bound of the frequency range
(default is 50)
bins (int): number of bins in which to separate the frequency range
(default is 500)
freq_broad (float): Gaussian broadening width to apply to the
final spectrum (default is None)
freq_units (str): units used for frequency, can be ppm or MHz
(default is ppm).
effects (NMRFlags): a flag, or bitwise-joined set of flags, from
this module’s NMRFlags tuple, describing which
effects should be included and accounted for
in the calculation. For a list of available
flags check the docstring for NMRCalculator
(default is NMRFlags.CS_ISO).
use_central (bool): if True, for half-integer spin nuclei, only
show the central transition. Ignored for
integer spin nuclei (default is False).
use_reference (bool): if True, return frequencies as referenced to
the appropriate nucleus, in chemical shift
form. If no reference has been provided for
this nucleus, a value of 0 ppm is used and
the frequencies are simply flipped in sign
(default is None, in which case use_reference is True if
references have been set).
Returns:
spec (np.ndarray): array of length ‘bins’ containing the spectral
intensities
freq (np.ndarray): array of length ‘bins’ containing the frequency
axis
Parameters:

use_reference (bool | None)

class soprano.calculate.nmr.nmr.NMRData2D(atoms=None, xelement=None, yelement=None, references=None, gradients=None, peaks=None, pairs=None, correlation_strengths=None, correlation_strength_metric=None, rcut=None, isotopes=None, is_shift=None, include_quadrupolar=False, yaxis_order='1Q', x_axis_label=None, y_axis_label=None)[source]#

Bases: object

Class to hold and extract 2D NMR data.

Parameters:

  • atoms (Atoms | None)

  • xelement (str | None)

  • yelement (str | None)

  • references (dict[str, float] | None)

  • gradients (dict[str, float] | None)

  • peaks (List[Peak2D] | None)

  • pairs (List[Tuple[int, int]] | None)

  • correlation_strengths (List[float] | None)

  • correlation_strength_metric (str | None)

  • rcut (float | None)

  • isotopes (dict[str, int] | None)

  • is_shift (bool | None)

  • include_quadrupolar (bool)

  • yaxis_order (str)

  • x_axis_label (str | None)

  • y_axis_label (str | None)

get_pairs()[source]#

Get the pairs of x and y indices to plot

self.idx_x and self.idx_y are the indices of the x and y elements in the atoms object

This method will set the following attributes: self.pairs_el_idx: a list of tuples of the form (xindex, yindex) self.pairs: a list of tuples of the form (xindex, yindex)

get_peaks(merge_identical=True, should_sort_peaks=False)[source]#

Get the correlation peaks.

If self.peaks already exists, then we return them as is. If they don’t exist, we make sure the required data is available and then generate the peaks and merge if desired.

class soprano.calculate.nmr.nmr.NMRPlot2D(nmr_data, plot_settings=None)[source]#

Bases: object

Class to plot 2D NMR data.

Parameters:
_plot_annotations(unique=True, optimise=True, labels_offset=0.1)[source]#

Get the annotations for the plot

plot(ax=None)[source]#

Plot the 2D NMR data.

Parameters:

ax (Optional[Axes], optional) – The axes to plot the data on. If not provided, a new figure and axis will be created.

Returns:

  • fig (Figure) – The figure object

  • ax (Axes) – The axis object

class soprano.calculate.nmr.nmr.PlotSettings(xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, x_axis_label: str | None = None, y_axis_label: str | None = None, plot_filename: str | None = None, show_markers: bool = True, marker: str = '+', marker_linewidth: float = 0.5, max_marker_size: int = 10, show_labels: bool = True, auto_adjust_labels: bool = True, label_fontsize: int | None = None, show_lines: bool = True, show_diagonal: bool = True, show_connectors: bool = True, marker_color: str | None = None, show_legend: bool = False, num_legend_elements: int | None = None, show_heatmap: bool = False, heatmap_levels: int | collections.abc.Iterable[float] = 20, show_contour: bool = False, x_broadening: float | None = None, y_broadening: float | None = None, broadening_type: str = 'gaussian', heatmap_grid_size: int = 150, colormap: str = 'bone_r', contour_color: str = 'C1', contour_linewidth: float = 0.2, contour_levels: collections.abc.Iterable[float] | int = 10)[source]#

Bases: object

Parameters:

  • xlim (Tuple[float, float] | None)

  • ylim (Tuple[float, float] | None)

  • x_axis_label (str | None)

  • y_axis_label (str | None)

  • plot_filename (str | None)

  • show_markers (bool)

  • marker (str)

  • marker_linewidth (float)

  • max_marker_size (int)

  • show_labels (bool)

  • auto_adjust_labels (bool)

  • label_fontsize (int | None)

  • show_lines (bool)

  • show_diagonal (bool)

  • show_connectors (bool)

  • marker_color (str | None)

  • show_legend (bool)

  • num_legend_elements (int | None)

  • show_heatmap (bool)

  • heatmap_levels (int | Iterable[float])

  • show_contour (bool)

  • x_broadening (float | None)

  • y_broadening (float | None)

  • broadening_type (str)

  • heatmap_grid_size (int)

  • colormap (str)

  • contour_color (str)

  • contour_linewidth (float)

  • contour_levels (Iterable[float] | int)