soprano.properties.nmr.spinsystem

soprano.properties.nmr.spinsystem#

Implementation of AtomsProperties that relate to NMR SpinSystems.

This is essentially a way to extract the NMR-relevant information from an atoms object and store it as a SpinSystem object.

Functions

get_dipolar_couplings(atoms[, sel_i, sel_j, ...])

Extract a list of DipolarCoupling objects from an Atoms object.

get_j_couplings(atoms[, sel_i, sel_j, tag, ...])

Extract a list of JCoupling objects from an Atoms object.

get_sites(atoms[, isotopes, indices, ...])

Extract a list of Site objects from an Atoms object.

get_spin_system(atoms[, isotopes, ...])

Extract the information needed to output a SpinSystem object from an Atoms object.

Classes

NMRSites([name])

Extract a list of Site objects from an Atoms object.

NMRSpinSystem([name])

Extact the information needed to output a SpinSystem object from an Atoms object.
class soprano.properties.nmr.spinsystem.NMRSites(name=None, **params)[source]#

Bases: AtomsProperty

Extract a list of Site objects from an Atoms object.

Parameters:

  • isotopes – list/dict/None Specify the isotopes to be used. If None, default NMR-active isotopes are chosen. Can be a dict like {‘H’: 2, ‘C’: 13} or a list like [‘2H’, ‘13C’]. If list, you can specify either one isotope per site or a list of the unique isotopes (in which case all sites of that element will have the same isotope).

  • references – list/dict/None Specification of the references to convert magnetic shielding tensors to chemical shifts. Can be a dict like {‘H’: 30, ‘C’: 170} or a list like [30, 170]. If list, you must specify one reference per site in the system. If None, no conversion is done and the outputs will be shieldings.

  • gradients – list/dict/float Specification of the gradients to convert magnetic shielding tensors to chemical shifts. Default is -1.0 corresponding as in the typical formula: delta = (reference + gradient * shielding) / (1 - reference * 1e-6).

  • include_shielding – bool Whether to include magnetic shielding tensors in the output.

  • include_efg – bool Whether to include electric field gradient tensors in the output.

  • use_q_isotopes – bool Whether to use quadrupolar isotopes for elements that have them. This is only relevant if isotopes is None.

Returns:

list

A list of Site objects extracted from the Atoms object.

Return type:

sites

Initialize an AtomsProperty and set its parameters. The AtomsProperty instance can then be called with a structure as its only argument to get the property with the given parameters.

Parameters:

  • name (str) – a name to give to this specific instance of the property (will be used to store it as array if requested)

  • params – named arguments specific to this type of property

__call__(s, store_array=False, selection=None)#

Calling the AtomsProperty returns the value of the property as extracted with the parameters of this specific instance.

Args:
s (ase.Atoms or AtomsCollection): the structure or collection
from which to extract the
property
store_array (bool): if s is a collection, whether to store the
resulting data as an array in the collection
using the given name for this instance
selection (str): a selection string to filter the atoms or AtomSelection

Returns:
property: the value of the property for the given structure or
a list of values if a collection has been passed

static extract(s, isotopes, references, gradients, include_shielding, include_efg, use_q_isotopes, ms_tag, efg_tag)[source]#

Extract the given property with given parameters from an Atoms object.

Parameters:

  • s (ase.Atoms) – the structure from which to extract the property

  • params – named arguments specific to this type of property

Returns:

the value of the property for the given structure and

parameters

Return type:

property

classmethod get(s, store_array=False, selection=None, **kwargs)#

Extract the given property using the default parameters on an Atoms object s

Args:
s (ase.Atoms or AtomsCollection): the structure or collection
from which to extract the
property
store_array (bool): if s is a collection, whether to store the
resulting data as an array in the collection
using the default name for this property
selection (str): a selection string to filter the atoms or AtomSelection

Returns:
property: the value of the property for the given structure or
a list of values if a collection has been passed

mean(s, axis=None, weights=None, **kwargs)#

Compute the mean of the property over a list of structures.

The default behaviours are: - For a list of scalars, compute the mean along the specified axis. - For a list of dictionaries, compute the mean for each key across all dictionaries. - For a list of NMRTensor objects, compute the mean using the NMRTensor.mean method. - For a list of arrays, convert to numpy array and then compute the mean along the specified axis.

Parameters:

  • s (list[ase.Atoms] | AtomsCollection) – The structure or collection from which to extract the property.

  • axis (int | None) – Axis along which the means are computed. If None, compute the mean of scalars.

  • weights (np.ndarray | None) – An array of weights associated with the values. If specified, the weighted average will be computed. Must have the same shape as the property values.

  • **kwargs – Additional arguments passed to the property’s get method.

Returns:

The mean value of the property for the given structures.

Return type:

dict | float | np.ndarray | NMRTensor

Raises:

  • ValueError – If s is not a collection/list, if property values are None, or if there’s an incompatible shape for computing the mean.

  • TypeError – If the property values are of a type that cannot be averaged.

class soprano.properties.nmr.spinsystem.NMRSpinSystem(name=None, **params)[source]#

Bases: AtomsProperty

Extact the information needed to output a SpinSystem object from an Atoms object.

Parameters:

  • isotopes – list/dict/None Specify the isotopes to be used. If None, default NMR-active isotopes are chosen. Can be a dict like {‘H’: 2, ‘C’: 13} or a list like [‘2H’, ‘13C’]. If list, you can specify either one isotope per site or a list of the unique isotopes (in which case all sites of that element will have the same isotope).

  • references – list/dict/None Specification of the references to convert magnetic shielding tensors to chemical shifts. Can be a dict like {‘H’: 30, ‘C’: 170} or a list like [30, 170]. If list, you must specify one reference per site in the system. If None, no conversion is done and the outputs will be shieldings.

  • gradients – list/dict/float Specification of the gradients to convert magnetic shielding tensors to chemical shifts. Default is -1.0 corresponding as in the typical formula: delta = (reference + gradient * shielding) / (1 - reference * 1e-6).

  • include_shielding – bool Whether to include magnetic shielding tensors in the output.

  • include_efg – bool Whether to include electric field gradient tensors in the output.

  • include_dipolar – bool Whether to include dipolar couplings in the output.

  • include_j – bool Whether to include spin-spin (J) couplings in the output.

  • coupling_kwargs – dict A dictionary of keyword arguments to pass to the Coupling constructor. (see the documentation of the Coupling class for more details)

Returns:

SpinSystem

The SpinSystem object containing the extracted information.

Return type:

spin_system

Initialize an AtomsProperty and set its parameters. The AtomsProperty instance can then be called with a structure as its only argument to get the property with the given parameters.

Parameters:

  • name (str) – a name to give to this specific instance of the property (will be used to store it as array if requested)

  • params – named arguments specific to this type of property

__call__(s, store_array=False, selection=None)#

Calling the AtomsProperty returns the value of the property as extracted with the parameters of this specific instance.

Args:
s (ase.Atoms or AtomsCollection): the structure or collection
from which to extract the
property
store_array (bool): if s is a collection, whether to store the
resulting data as an array in the collection
using the given name for this instance
selection (str): a selection string to filter the atoms or AtomSelection

Returns:
property: the value of the property for the given structure or
a list of values if a collection has been passed

static extract(s, isotopes, references, gradients, include_shielding, include_efg, include_dipolar, include_j, use_q_isotopes, coupling_kwargs, ms_tag, efg_tag)[source]#

Extract the given property with given parameters from an Atoms object.

Parameters:

  • s (ase.Atoms) – the structure from which to extract the property

  • params – named arguments specific to this type of property

Returns:

the value of the property for the given structure and

parameters

Return type:

property

classmethod get(s, store_array=False, selection=None, **kwargs)#

Extract the given property using the default parameters on an Atoms object s

Args:
s (ase.Atoms or AtomsCollection): the structure or collection
from which to extract the
property
store_array (bool): if s is a collection, whether to store the
resulting data as an array in the collection
using the default name for this property
selection (str): a selection string to filter the atoms or AtomSelection

Returns:
property: the value of the property for the given structure or
a list of values if a collection has been passed

mean(s, axis=None, weights=None, **kwargs)#

Compute the mean of the property over a list of structures.

The default behaviours are: - For a list of scalars, compute the mean along the specified axis. - For a list of dictionaries, compute the mean for each key across all dictionaries. - For a list of NMRTensor objects, compute the mean using the NMRTensor.mean method. - For a list of arrays, convert to numpy array and then compute the mean along the specified axis.

Parameters:

  • s (list[ase.Atoms] | AtomsCollection) – The structure or collection from which to extract the property.

  • axis (int | None) – Axis along which the means are computed. If None, compute the mean of scalars.

  • weights (np.ndarray | None) – An array of weights associated with the values. If specified, the weighted average will be computed. Must have the same shape as the property values.

  • **kwargs – Additional arguments passed to the property’s get method.

Returns:

The mean value of the property for the given structures.

Return type:

dict | float | np.ndarray | NMRTensor

Raises:

  • ValueError – If s is not a collection/list, if property values are None, or if there’s an incompatible shape for computing the mean.

  • TypeError – If the property values are of a type that cannot be averaged.

soprano.properties.nmr.spinsystem.get_dipolar_couplings(atoms, sel_i=None, sel_j=None, isotopes=None, isotope_list=None, self_coupling=False, rotation_axis=None, isonuclear=False)[source]#

Extract a list of DipolarCoupling objects from an Atoms object.

Parameters:

  • sel_i (AtomSelection or [int]) – Selection or list of indices of atoms for which to compute the dipolar coupling. By default is None (= all of them).

  • sel_j (AtomSelection or [int]) – Selection or list of indices of atoms for which to compute the dipolar coupling with the ones in sel_i. By default is None (= same as sel_i).

  • isotopes (dict) – dictionary of specific isotopes to use, by element symbol. If the isotope doesn’t exist an error will be raised. e.g. {‘H’: 2, ‘C’: 13}

  • self_coupling (bool) – if True, include coupling of a nucleus with its own closest periodic copy. Otherwise excluded. Default is False.

  • block_size (int) – maximum size of blocks used when processing large chunks of pairs. Necessary to avoid memory problems for very large systems. Default is 1000.

  • rotation_axis (np.ndarray) – if present, return the residual dipolar tensors after fast averaging around the given axis. Default is None.

  • isonuclear (bool) – if True, only compute couplings between nuclei of the same element. Default is False.

  • atoms (Atoms)

  • isotope_list (list[int | None] | None)

Returns:

List of DipolarCoupling objects.

Return type:

dip_list (list)

soprano.properties.nmr.spinsystem.get_j_couplings(atoms, sel_i=None, sel_j=None, tag='isc', isotopes=None, isotope_list=None, self_coupling=False)[source]#

Extract a list of JCoupling objects from an Atoms object.

Parameters:

  • sel_i (AtomSelection or [int]) – Selection or list of indices of atoms for which to compute the J coupling. By default is None (= all of them).

  • sel_j (AtomSelection or [int]) –

    Selection or list of indices of atoms

    for which to compute the J coupling with the ones in sel_i. By default is None (= same as sel_i).

    tag (str): tag to use for the J coupling. Magres files

    usually contain isc, isc_spin, isc_fc, isc_orbital_p and isc_orbital_d. Default is isc.

  • isotopes (dict) –

    dictionary of specific isotopes to use, by element

    symbol. If the isotope doesn’t exist an error will be raised. e.g. {‘H’: 2, ‘C’: 13}

    isotope_list (list): list of isotopes to use for the J coupling.

    If None, the default isotopes for the elements in the system are used. If provided, it should match the number of sites in the system.

  • self_coupling (bool) – if True, include coupling of a nucleus with its own closest periodic copy. Otherwise excluded. Default is False.

  • atoms (Atoms)

  • tag (str)

  • isotope_list (list[int | None] | None)

Returns:

List of JCoupling objects.

Return type:

j_list (list)

soprano.properties.nmr.spinsystem.get_sites(atoms, isotopes=None, indices=None, selection=None, include_shielding=True, include_efg=True, use_q_isotopes=False)[source]#

Extract a list of Site objects from an Atoms object. You can specify the indices of the atoms to extract as sites or use an AtomSelection object to extract the sites. Don’t use both indices and selection at the same time.

This is a wrapper around the NMRSites.get method - you can use that for more advanced options. For even more advanced use cases, you can build Site objects manually.

Parameters:

  • atoms (ase.Atoms) – The Atoms object from which to extract the sites.

  • isotopes (dict[str, int]) – A dictionary of isotopes to use for the sites. e.g. {‘H’: 2, ‘C’: 13}

  • indices (list[int]) – The indices of the atoms to extract as sites.

  • selection (AtomSelection) – An AtomSelection object to use to extract the sites

Returns:

A list of Site objects extracted from the Atoms object.

Return type:

list

soprano.properties.nmr.spinsystem.get_spin_system(atoms, isotopes=None, references=None, gradients=-1.0, include_shielding=True, include_efg=True, include_dipolar=False, include_j=False, use_q_isotopes=False, coupling_kwargs=None, ms_tag='ms', efg_tag='efg')[source]#

Extract the information needed to output a SpinSystem object from an Atoms object.

Parameters:

  • atoms (ase.Atoms) – The Atoms object from which to extract the sites.

  • isotopes (dict[str, int]) – A dictionary of isotopes to use for the sites. e.g. {‘H’: 2, ‘C’: 13}

  • references (dict[str, float]) – Specification of the references to convert magnetic shielding tensors to chemical shifts. e.g. {‘H’: 30, ‘C’: 170}

  • gradients (dict[str, float]/float) – Specification of the gradients to convert magnetic shielding tensors to chemical shifts. Default is -1.0 corresponding as in the typical formula: delta = (reference + gradient * shielding) / (1 - reference * 1e-6).

  • include_shielding (bool) – Whether to include magnetic shielding tensors in the output.

  • include_efg (bool) – Whether to include electric field gradient tensors in the output.

  • include_dipolar (bool) – Whether to include dipolar couplings in the output.

  • include_j (bool) – Whether to include spin-spin (J) couplings in the output.

  • use_q_isotopes (bool) – Whether to use quadrupolar isotopes for elements that have them. This is only relevant if isotopes is None.

  • coupling_kwargs (dict) – A dictionary of keyword arguments to pass to the Coupling constructor.

  • ms_tag (str) – Name of the array containing magnetic shielding tensors. Default: ‘ms’.

  • efg_tag (str) – Name of the array containing electric field gradient tensors. Default: ‘efg’.

Returns:

The SpinSystem object containing the extracted information.

Return type:

spin_system (SpinSystem)