soprano.properties.labeling.labeling

Implementation of AtomsProperties that relate to labeling of systems

Classes

CarbonHybridationState([name])	Returns an integer indicating the hybridation state of any given carbon atom in a system, 1, 2, or 3 for sp1, sp2 or sp3, obtained by counting its bonds.
HydrogenBondTypes([name])	Assign MoleculeSites labels to atoms, then characterise existing hydrogen bonds based on them, and return a list of such bonds detected in a system.
MagresViewLabels([name])	Compute labels for a structure following the MagresView convention.
MoleculeSites([name])	Assigns unique labels to atoms belonging to molecules by exploiting network topology.
SiteLabels([name])	Compute a unique label for an atom belonging to a molecule by exploiting network topology.
UniqueSites([name])	Assigns unique labels to atoms based on their position in the system and the allowed symmetry operations.

class soprano.properties.labeling.labeling.CarbonHybridationState(name=None, **params)

Bases: AtomsProperty

Returns an integer indicating the hybridation state of any given carbon atom in a system, 1, 2, or 3 for sp1, sp2 or sp3, obtained by counting its bonds. For non-carbon atoms or carbon atoms that can’t be identified returns 0.

Parameters:

bonds ([tuple]): if present, use this list of bonds instead of

recalculating them (must be formatted like the output

of the linkage.Bonds property).

save_info (bool): if True, save the found hybridation states as an

array in the Atoms object. By default True.

Returns:

hybrid ([int]): list of integers encoding the hybridation states

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, bonds, save_info)

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

Bases: AtomsProperty

Assign MoleculeSites labels to atoms, then characterise existing hydrogen bonds based on them, and return a list of such bonds detected in a system. The bonds come in the form ‘{0}<{1},{2}>..{3}<{4}>’, where {0} is the name of the molecule containing the hydrogen, {2} is the hydrogen, {1} the atom to which the hydrogen is bonded, {3} the name of the other molecule and {4} the atom to which the hydrogen is hydrogen bonded.

Parameters:

force_recalc (bool): if True, always recalculate the molecules even if

already present.

save_info (bool): if True, save the found hydrogen bond types as part

of the Atoms object info. By default True.

Returns:

hydrogen_bond_types (list): A list containing info characterising the

hydrogen bonds present in the system in a

detailed way.

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, force_recalc, save_info)

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

Bases: AtomsProperty

Compute labels for a structure following the MagresView convention.

Parameters:

save_asarray (bool): if True the magresview site labels are also saved

as an array. By default False.

Returns:

magresview_labels (list[str]): A list of the computed site labels

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, save_asarray)

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

Bases: AtomsProperty

Assigns unique labels to atoms belonging to molecules by exploiting network topology. Atoms can have the same label, but only if they’re fundamentally indistinguishable in the molecule’s chemical context (for example, three hydrogen atoms on a CH3 group). The molecule will be described by a characteristic string and by a series of labels in the format [element]_[number]. These sites will be saved by default and can be used for better insight when carrying out other analysis.

Parameters:

force_recalc (bool): if True, always recalculate the molecules even if

already present.

save_info (bool): if True, save the found molecular sites as part of

the Atoms object info. By default True.

save_asarray (bool): if True the molecular site names are also saved

as an array of the molecule selection.

Returns:

molecular_sites (dict): A dictionary containing info characterising

the molecule’s chemical sites unequivocally.

These are a string representation of the

molecule itself and a dictionary linking

atomic indices (as found in the molecule in

AtomSelection form) to site labels.

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, force_recalc, save_info, save_asarray)

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

Bases: AtomsProperty

Compute a unique label for an atom belonging to a molecule by exploiting network topology. Atoms can have the same label, but only if they’re fundamentally indistinguishable in the molecule’s chemical context (for example, three hydrogen atoms on a CH3 group). The label describes the molecular network as traversed starting from the given site, with each pair of square brackets indicating the traversal of a further bond, and all paths kept to the shortest possible.

Parameters:

force_recalc (bool): if True, always recalculate the molecules even if

already present.

sites (list[int]): the sites for which the label have to be calculated.

If not given, all of them are calculated.

custom_symbol (str): if present, replace the usual chemical symbol

with a custom name for the site on which the

label is being calculated, to make it

distinguishable from equivalent elements.

Returns:

site_labels (list[str]): A list of the computed site labels

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, force_recalc, sites, custom_symbol)

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

Bases: AtomsProperty

Assigns unique labels to atoms based on their position in the system and the allowed symmetry operations.

Basically a wrapper around the ASE functionality.

Atoms can have the same label, but only if they’re fundamentally indistinguishable. These sites will be saved by default and can be used for better insight when carrying out other analysis.

Parameters:

save_info (bool): if True, save the found unique sites as part of

the Atoms object info. By default True.

symprec (float): the tolerance for symmetry operations. Default: 1e-4

Returns:

unique ([int]): list of integers

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, force_recalc, save_info, symprec, override_cif=False)

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