soprano.properties.nmr.ms

Implementation of AtomsProperties that relate to NMR shieldings/shifts

Classes

MSAnisotropy([name])	Produces an array containing the magnetic shielding anisotropies in a system (ppm).
MSAsymmetry([name])	Produces an array containing the magnetic shielding asymmetries in a system (adimensional).
MSDiagonal([name])	Produces an array containing eigenvalues and eigenvectors for the symmetric part of each magnetic shielding tensor in the system.
MSEuler([name])	Produces an array of Euler angles in radians expressing the orientation of the MS tensors with respect to the cartesian axes for each site in the Atoms object.
MSIsotropy([name])	Produces an array containing the magnetic shielding isotropies in a system (ppm).
MSQuaternion([name])	Produces a list of ase.Quaternion objects expressing the orientation of the MS tensors with respect to the cartesian axes.
MSReducedAnisotropy([name])	Produces an array containing the magnetic shielding reduced anisotropies in a system (ppm).
MSShielding([name])	Produces an array containing the magnetic shielding isotropies in a system (ppm).
MSShift([name])	Produces an array containing the chemical shifts (ppm).
MSSkew([name])	Produces an array containing the magnetic shielding tensor skew in a system.
MSSpan([name])	Produces an array containing the magnetic shielding tensor span in a system (ppm).
MSTensor([name])	Produces a list of MagneticShielding objects containing the magnetic shielding tensors for each atom in the system.

class soprano.properties.nmr.ms.MSAnisotropy(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding anisotropies in a system (ppm). Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

force_recalc (bool): if True, always diagonalise the tensors even if

already present.

Returns:

ms_list (np.ndarray): list of anisotropies

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSAsymmetry(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding asymmetries in a system (adimensional). Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

force_recalc (bool): if True, always diagonalise the tensors even if

already present.

Returns:

ms_list (np.ndarray): list of asymmetries

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSDiagonal(name=None, **params)

Bases: AtomsProperty

Produces an array containing eigenvalues and eigenvectors for the symmetric part of each magnetic shielding tensor in the system. By default saves them as part of the Atoms’ arrays as well. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

save_array (bool): if True, save the diagonalised tensors in the

Atoms object as an array. By default True.

Returns:

ms_diag (np.ndarray): list of eigenvalues and eigenvectors

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSEuler(name=None, **params)

Bases: AtomsProperty

Produces an array of Euler angles in radians expressing the orientation of the MS tensors with respect to the cartesian axes for each site in the Atoms object. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

• order (str) – Order to use for eigenvalues/eigenvectors. Can be ‘i’ (ORDER_INCREASING), ‘d’ (ORDER_DECREASING), ‘h’ (ORDER_HAEBERLEN) or ‘n’ (ORDER_NQR). Default is ‘h’ for MS tensors.

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

Returns:

array of Euler angles in radians

Return type:

ms_eulers (np.array)

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSIsotropy(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding isotropies in a system (ppm). If references are provided, the returned values represent the chemical shift.

Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Refactored into MSShielding and MSShift. This remains here for backwards compatibility.

Parameters:

ref (float/dict): reference frequency per element. If provided, the chemical shift

will be returned instead of the magnetic shielding.

gradients float/list/dict: usually around -1.

save_array (bool): if True, save the diagonalised tensors in the

Atoms object as an array. By default True.

Returns:

ms_iso (np.ndarray): list of shieldings/shifts

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSQuaternion(name=None, **params)

Bases: AtomsProperty

Produces a list of ase.Quaternion objects expressing the orientation of the MS tensors with respect to the cartesian axes. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

This is now deprecated in favour of an explicit Euler angle calculation that better handles NMR tensors.

Parameters:

order (str): Order to use for eigenvalues/eigenvectors. Can be ‘i’ (ORDER_INCREASING), ‘d’ (ORDER_DECREASING), ‘h’ (ORDER_HAEBERLEN) or ‘n’ (ORDER_NQR). Default is ‘i’.

Returns:

ms_quat (list): list of quaternions

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSReducedAnisotropy(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding reduced anisotropies in a system (ppm). Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

force_recalc (bool): if True, always diagonalise the tensors even if

already present.

Returns:

ms_list (np.ndarray): list of reduced anisotropies

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSShielding(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding isotropies in a system (ppm).

Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

save_array (bool): if True, save the ms_shielding array in the

Atoms object as an array. By default True.

Returns:

ms_shielding (np.ndarray): list of shieldings

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSShift(name=None, **params)

Bases: AtomsProperty

Produces an array containing the chemical shifts (ppm). References must be provided for the chemical shifts to be calculated. Optionally, the you can also specify the gradient, m

\[\delta = \sigma_{ref} - m\sigma\]

Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

ref (list/float/dict): reference frequency per element. Must

be provided.

gradients float/list/dict: usually around -1. Optional.

Default: -1 for all elements.

save_array (bool): if True, save the ms_shift array in the

Atoms object as an array. By default True.

Returns:

ms_shift (np.ndarray): list of shifts

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSSkew(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding tensor skew in a system. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

force_recalc (bool): if True, always diagonalise the tensors even if

already present.

Returns:

ms_list (np.ndarray): list of skews

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSSpan(name=None, **params)

Bases: AtomsProperty

Produces an array containing the magnetic shielding tensor span in a system (ppm). Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

force_recalc (bool): if True, always diagonalise the tensors even if

already present.

Returns:

ms_list (np.ndarray): list of spans

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed

class soprano.properties.nmr.ms.MSTensor(name=None, **params)

Bases: AtomsProperty

Produces a list of MagneticShielding objects containing the magnetic shielding tensors for each atom in the system. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

Parameters:

order (str) – Order to use for eigenvalues/eigenvectors. Can be ‘i’ (ORDER_INCREASING), ‘d’ (ORDER_DECREASING), ‘h’ (ORDER_HAEBERLEN) or ‘n’ (ORDER_NQR). Default is ‘i’.

Returns:

list of MagneticShielding objects

Return type:

ms_tensors (list)

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)

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

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, *args, **kwargs)

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, **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

Returns:

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

a list of values if a collection has been passed