soprano.properties.nmr.efg

Implementation of AtomsProperties that relate to NMR electric field gradients

Functions

tensor_mean_property(property_name)

Decorator for creating mean methods that extract a specific property from ElectricFieldGradient objects.

Classes

EFGAnisotropy([name])	Produces an array containing the electric field gradient anisotropies in a system (au).
EFGAsymmetry([name])	Produces an array containing the electric field gradient asymmetries in a system (adimensional).
EFGDiagonal([name])	Produces an array containing eigenvalues and eigenvectors for the symmetric part of each EFG tensor in the system.
EFGEuler([name])	Produces an array of Euler angles in radians expressing the orientation of the EFG tensors with respect to the cartesian axes for each site in the Atoms object.
EFGNQR([name])	Produces an array containing NQR transition frequencies (in Hz) for every atom in a system.
EFGQuadrupolarConstant([name])	Produces an array containing the quadrupolar constant in Hz for every atom in a system.
EFGQuadrupolarProduct([name])	Produces an array containing the quadrupolar product values in a system.
EFGQuaternion([name])	Produces a list of ase.Quaternion objects expressing the orientation of the EFG tensors with respect to the cartesian axes.
EFGReducedAnisotropy([name])	Produces an array containing the electric field gradient reduced anisotropies in a system (au).
EFGSkew([name])	Produces an array containing the electric field gradient tensor skew in a system.
EFGSpan([name])	Produces an array containing the electric field gradient tensor span in a system (au).
EFGTensor([name])	Produces a list of ElectricFieldGradient objects containing the electric field gradient tensors for each atom in the system.
EFGVzz([name])	Produces an array containing the major component of the electric field gradient in a system (au).

class soprano.properties.nmr.efg.EFGAnisotropy(name=None, **params)

Bases: AtomsProperty

Produces an array containing the electric field gradient anisotropies in a system (au). 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:

list of anisotropies

Return type:

efg_list (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, *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, 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.efg.EFGAsymmetry(name=None, **params)

Bases: AtomsProperty

Produces an array containing the electric field gradient 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:

list of asymmetries

Return type:

efg_list (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, *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, 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.efg.EFGDiagonal(name=None, **params)

Bases: AtomsProperty

Produces an array containing eigenvalues and eigenvectors for the symmetric part of each EFG 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:

list of eigenvalues and eigenvectors

Return type:

efg_diag (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, *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, 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)

Calculate the mean of the EFGDiagonal property.

Parameters:

• s (AtomsCollection) – The collection of structures to calculate the mean for.

• axis (int or None) – Axis along which to calculate the mean. Default is None.

• weights (array-like or None) – Weights for each structure. Default is None.

Returns:

The mean of the EFGDiagonal property.

Return type:

efg_diag_mean (np.ndarray)

class soprano.properties.nmr.efg.EFGEuler(name=None, **params)

Bases: AtomsProperty

Produces an array of Euler angles in radians expressing the orientation of the EFG 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 ‘n’ for EFG 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:

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

Calculate the mean of the EFGEuler property.

Parameters:

• s (AtomsCollection) – The collection of structures to calculate the mean for.

• axis (int or None) – Axis along which to calculate the mean. Default is None.

• weights (array-like or None) – Weights for each structure. Default is None.

• **kwargs – Additional parameters for euler angles calculation.

Returns:

The mean of the EFGEuler property.

Return type:

efg_euler_mean (np.ndarray)

class soprano.properties.nmr.efg.EFGNQR(name=None, **params)

Bases: AtomsProperty

Produces an array containing NQR transition frequencies (in Hz) for every atom in a system. For non-quadrupole active nuclei, the we return an empty dictionary. Unless specified otherwise, the spin and quadrupole moment of the most common NMR-active isotope is used.

For reference: the value returned by this property is defined as

\[A = \frac{V_{zz} Q}{4I(2I - 1)} fq = 3A(2m+1)\sqrt{1 + \eta^2/3}\]

in Hz. It is important to keep in mind that therefore this represents a frequency; the corresponding ‘omega’ (pulsation) would be the same value multiplied by 2*pi. TODO: double-check convention TODO: better data structure for the output?

Parameters:

• force_recalc (bool) – if True, always diagonalise the tensors even if already present.

• use_q_isotopes (bool) – if True, always use the most common quadrupole active isotope for each element, if there is one.

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

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

list of dictionaries of the possible NQR frequencies in Hz

The keys of the dictionary are the possible m->m+1 values For example: “m=1->2” for non-quadrupole active nuclei the corresponding element will be an empty dictionary.

Return type:

q_list (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, 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, *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, 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.efg.EFGQuadrupolarConstant(name=None, **params)

Bases: AtomsProperty

Produces an array containing the quadrupolar constant in Hz for every atom in a system. The constant will be zero for non-quadrupole active nuclei. Unless specified otherwise, the quadrupole moment of the most common NMR-active isotope is used. For reference: the value returned by this property is defined as

\[\frac{e^2qQ}{h}\]

in Hz. It is important to keep in mind that therefore this represents a frequency; the corresponding ‘omega’ (pulsation) would be the same value multiplied by 2*pi. This is, for example, exactly the value required as input in Simpson’s SPINSYS section.

Parameters:

• force_recalc (bool) – if True, always diagonalise the tensors even if already present.

• use_q_isotopes (bool) – if True, always use the most common quadrupole active isotope for each element, if there is one.

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

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

list of quadrupole constants in Hz

Return type:

q_list (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, *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, 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.efg.EFGQuadrupolarProduct(name=None, **params)

Bases: AtomsProperty

Produces an array containing the quadrupolar product values in a system. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

\[\P_Q = C_Q (1+frac{\eta_Q^2}{3})^{1/2}\]

Parameters:

• force_recalc (bool) – if True, always diagonalise the tensors even if already present.

• use_q_isotopes (bool) – if True, always use the most common quadrupole active isotope for each element, if there is one.

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

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

list of quadrupole products in Hz (units of Cq)

Return type:

Pq_list (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, *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, 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.efg.EFGQuaternion(name=None, **params)

Bases: AtomsProperty

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

The default convention for EFG tensors is the NQR one (|Vxx| ≤ |Vyy| ≤ |Vzz|). This is different from the default convention for MS tensors (Haeberlen). You can change this by specifying the ‘order’ parameter.

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 ‘n’.

Returns:

list of quaternions

Return type:

efg_quat (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, 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, *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, 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.efg.EFGReducedAnisotropy(name=None, **params)

Bases: AtomsProperty

Produces an array containing the electric field gradient reduced anisotropies in a system (au). 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:

list of reduced anisotropies

Return type:

efg_list (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, *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, 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.efg.EFGSkew(name=None, **params)

Bases: AtomsProperty

Produces an array containing the electric field gradient 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:

list of skews

Return type:

efg_list (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, *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, 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.efg.EFGSpan(name=None, **params)

Bases: AtomsProperty

Produces an array containing the electric field gradient tensor span in a system (au). 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:

list of spans

Return type:

efg_list (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, *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, 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.efg.EFGTensor(name=None, **params)

Bases: AtomsProperty

Produces a list of ElectricFieldGradient objects containing the electric field gradient tensors for each atom in the system. Requires the Atoms object to have been loaded from a .magres file containing the relevant information.

The default convention for EFG tensors is the NQR one (|Vxx| ≤ |Vyy| ≤ |Vzz|). This is different from the default convention for MS tensors (Haeberlen). You can change this by specifying the ‘order’ parameter.

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 ‘n’.

• use_q_isotopes (bool) – if True, always use the most common quadrupole active isotope for each element, if there is one.

• isotopes (dict) –

  dictionary of specific isotopes to use, by element symbol. If the isotope doesn’t exist an error will

  be raised. Overrides use_q_isotopes.

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

list of ElectricFieldGradient objects

Return type:

efg_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, 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, *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, 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.efg.EFGVzz(name=None, **params)

Bases: AtomsProperty

Produces an array containing the major component of the electric field gradient in a system (au). 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:

list of Vzz values

Return type:

efg_list (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, *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, 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.efg.tensor_mean_property(property_name)

Decorator for creating mean methods that extract a specific property from ElectricFieldGradient objects.

Parameters:

property_name (str) – The name of the property to extract from each ElectricFieldGradient object. Must be a valid attribute or property of ElectricFieldGradient.

Returns:

A decorator for mean methods

Return type:

decorator