soprano.properties.basic.basic

Implementation of some basic AtomsProperty classes

Classes

CalcEnergy([name])	Property representing the energy calculated by an ASE calulator
LatticeABC([name])	Property representing the axis-angles form of a structure's lattice
LatticeCart([name])	Property representing the Cartesian form of a structure's lattice
NumAtoms([name])	Property representing the number of atoms in a structure

class soprano.properties.basic.basic.CalcEnergy(name=None, **params)

Bases: AtomsProperty

Property representing the energy calculated by an ASE calulator

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)

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

Bases: AtomsProperty

Property representing the axis-angles form of a structure’s lattice

Parameters:

shape (tuple): the shape to give to the array

deg (bool): whether to give the angles in degrees instead of radians

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, shape, deg)

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

Bases: AtomsProperty

Property representing the Cartesian form of a structure’s lattice

Parameters:

shape (tuple): the shape to give to the 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, shape)

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

Bases: AtomsProperty

Property representing the number of atoms in a structure

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)

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.