soprano.properties.nmr.dipolar

Implementation of AtomsProperties that relate to NMR dipole-dipole couplings

Classes

DipolarCoupling([name])	Produces a dictionary of dipole-dipole coupling constants for atom pairs in the system.
DipolarDiagonal([name])	Produces a dictionary of dipole-dipole tensors as eigenvalues and eigenvectors for atom pairs in the system.
DipolarEuler([name])	Produces a dictionary of dipole-dipole coupling tensor Euler angles for atom pairs in the system.
DipolarRSS([name])	Compute the Dipolar constant Root Sum Square for each atom in a system, including periodicity, within a cutoff.
DipolarTensor([name])	Produces a dictionary of dipole-dipole coupling tensors for atom pairs in the system.

class soprano.properties.nmr.dipolar.DipolarCoupling(name=None, **params)

Bases: AtomsProperty

Produces a dictionary of dipole-dipole coupling constants for atom pairs in the system. For each pair, the closest periodic copy will be considered. The constant for a pair of nuclei i and j is defined as:

\[d_{ij} = -\frac{\mu_0\hbar\gamma_i\gamma_j}{8\pi^2r_{ij}^3}\]

where the gammas represent the gyromagnetic ratios of the nuclei and the r is their distance. The full tensor of the interaction is then defined as

\[\begin{split}D_{ij} = \begin{bmatrix} -d_{ij} & 0 & 0 \\ 0 & -d_{ij} & 0 \\ 0 & 0 & 2d_{ij} \\ \end{bmatrix}\end{split}\]

where the z-axis is aligned with \(r_{ij}\) and the other two can be any directions in the orthogonal plane.

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.

• isotope_list (list) – list of isotopes, atom-by-atom. To be used if different atoms of the same element are supposed to be of different isotopes. Where a ‘None’ is present will fall back on the previous definitions. Where an isotope is present it overrides everything else.

• 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.

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

Returns:

Dictionary of couplings in Hz and r_{ij} versors,

pointing from i to j, by atomic index pair.

Return type:

dip_dict (dict)

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.

Args:

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, sel_i, sel_j, isotopes, isotope_list, self_coupling, block_size, isonuclear)

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

Args:

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

params: named arguments specific to this type of property

Returns:

property: the value of the property for the given structure and

parameters

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.dipolar.DipolarDiagonal(name=None, **params)

Bases: AtomsProperty

Produces a dictionary of dipole-dipole tensors as eigenvalues and eigenvectors for atom pairs in the system. For each pair, the closest periodic copy will be considered.

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 i 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.

• isotope_list (list) – list of isotopes, atom-by-atom. To be used if different atoms of the same element are supposed to be of different isotopes. Where a ‘None’ is present will fall back on the previous definitions. Where an isotope is present it overrides everything else.

• 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.

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

Returns:

Dictionary of dipolar eigenvalues (in Hz) and

eigenvectors, by atomic index pair.

Return type:

dip_tens_dict (dict)

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.

Args:

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, sel_i, sel_j, isotopes, isotope_list, self_coupling, block_size, isonuclear)

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

Args:

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

params: named arguments specific to this type of property

Returns:

property: the value of the property for the given structure and

parameters

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.dipolar.DipolarEuler(name=None, **params)

Bases: AtomsProperty

Produces a dictionary of dipole-dipole coupling tensor Euler angles for atom pairs in the system. See the DipolarTensor property for details on the tensor.

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.

• isotope_list (list) – list of isotopes, atom-by-atom. To be used if different atoms of the same element are supposed to be of different isotopes. Where a ‘None’ is present will fall back on the previous definitions. Where an isotope is present it overrides everything else.

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

• isonuclear (bool) – if True, only compute couplings between nuclei of the same element. 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.

• convention (str) – ‘zyz’ or ‘zxz’ accepted - the ordering of the Euler angle rotation axes. Default is zyz

• passive (bool) – active or passive rotations. Default is active (passive=False)

• degrees (bool) – return the angles in degrees. Default is False

Returns:

Dictionary of tensors in Hz by atomic index pair.

Return type:

dip_dict (dict)

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.

Args:

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, sel_i, sel_j, isotopes, isotope_list, self_coupling, isonuclear, block_size, rotation_axis, convention, passive, degrees)

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

Args:

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

params: named arguments specific to this type of property

Returns:

property: the value of the property for the given structure and

parameters

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.dipolar.DipolarRSS(name=None, **params)

Bases: AtomsProperty

Compute the Dipolar constant Root Sum Square for each atom in a system, including periodicity, within a cutoff.

Parameters:

• cutoff (float) – cutoff radius in Angstroms at which the sum stops. By default 5 Ang.

• isonuclear (bool) – if True, only nuclei of the same species will be considered. By default is False.

• isotopes (dict) – dictionary of specific isotopes to use, by element symbol. If the isotope doesn’t exist an error will be raised.

• isotope_list (list) – list of isotopes, atom-by-atom. To be used if different atoms of the same element are supposed to be of different isotopes. Where a ‘None’ is present will fall back on the previous definitions. Where an isotope is present it overrides everything else.

Returns:

dipolar constant RSS for each atom in the system

Return type:

dip_rss (np.ndarray)

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.

Args:

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, cutoff, isonuclear, isotopes, isotope_list)

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

Args:

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

params: named arguments specific to this type of property

Returns:

property: the value of the property for the given structure and

parameters

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.dipolar.DipolarTensor(name=None, **params)

Bases: AtomsProperty

Produces a dictionary of dipole-dipole coupling tensors for atom pairs in the system. For each pair, the closest periodic copy will be considered. The coupling constant for a pair of nuclei i and j is defined as:

\[d_{ij} = -\frac{\mu_0\hbar\gamma_i\gamma_j}{8\pi^2r_{ij}^3}\]

where the gammas represent the gyromagnetic ratios of the nuclei and the r is their distance. The full tensor of the interaction is then defined as

\[D_{ij} = d_{ij}(3\hat{r}_{ij}\otimes \hat{r}_{ij}-\mathbb{I})\]

where \(\hat{r}_{ij} = r_{ij}/|r_{ij}|\) and the Kronecker product is used.

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.

• isotope_list (list) – list of isotopes, atom-by-atom. To be used if different atoms of the same element are supposed to be of different isotopes. Where a ‘None’ is present will fall back on the previous definitions. Where an isotope is present it overrides everything else.

• 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.

Returns:

Dictionary of NMRTensor objects in Hz by atomic index pair.

Return type:

dip_dict (dict)

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.

Args:

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, sel_i, sel_j, isotopes, isotope_list, self_coupling, block_size, rotation_axis, isonuclear)

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

Args:

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

params: named arguments specific to this type of property

Returns:

property: the value of the property for the given structure and

parameters

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.