soprano.properties.linkage.linkage

Implementation of AtomsProperties that relate to linkage of atoms

Classes

BondGraph([name])	Bond graph returns a networkx graph of the molecules in the structure.
Bonds([name])	Produces an array of tuples identifying all bonds existing within the system (calculated using Van der Waals radii).
CoordinationHistogram([name])	Produces an histogram representing, for each pair of species present in the system, how many atoms of species 1 have n bonds with species 2, n being the histogram bins.
DihedralAngleList([name])	Produces a list of dihedral angles found in the system, identified by looking for a bonding pattern.
ElementPairs([name])	Produces an array containing the atomic pair distances in a system, reduced to their shortest periodic version and sorted min to max.
HydrogenBonds([name])	Hydrogen Bonds
HydrogenBondsNumber([name])	Number of hydrogen bonds detected in this system, classified by type.
LinkageList([name])	Produces an array containing the atomic pair distances in a system, reduced to their shortest periodic version and sorted min to max.
MoleculeCOM([name])	List of centers of mass for the molecules present in the system.
MoleculeCOMLinkage([name])	Linkage list - following the same criteria as the atomic one - calculated for the centers of mass of the molecules present in the system.
MoleculeMass([name])	Total mass of each of the molecules detected in this system.
MoleculeNumber([name])	Number of molecules detected in this system.
MoleculeQuaternion([name])	A list of quaternions expressing the rotation of the molecule's intertia tensor principal frame with respect to the cartesian axes.
MoleculeRelativeRotation([name])	A list of relative rotations between molecules.
MoleculeSpectralSort([name])	Reorder molecules to have their indices sorted using a spectral sorting method based on the Fiedler vector of their bonding graph.
Molecules([name])	Produces an array containing multiple AtomSelection objects representing molecules in the system as found by connecting atoms closer than the half sum of their Van der Waals radii.

class soprano.properties.linkage.linkage.BondGraph(name=None, **params)

Bases: AtomsProperty

Bond graph returns a networkx graph of the molecules in the structure. To use this property you must have the networkx library installed.

Parameters:

force_recalc (bool): if True, always recalculate the bond graph

even if already present.

save_info (bool): if True, save the bond graph as part of the Atoms

object info. By default True.

Returns:

graph (nx.Graph): the bond graph for the 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)

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

Bases: AtomsProperty

Produces an array of tuples identifying all bonds existing within the system (calculated using Van der Waals radii). The tuples are structured as:

(atom_1, atom_2, atom_2_cell, bond_length)

with atom_1 and atom_2 being indices and atom_2_cell being an array of integers identifying the unit cell to which atom_2 belongs with respect to atom_1 (which is assumed to be in (0,0,0), the central cell). This is to account for the possibility of course that the bond exists through the periodic boundary. WARNING: the possibility of an atom bonding with another throughout two different periodic boundaries is not accounted for.

Parameters:

vdw_set({ase, jmol, csd}): set of Van der Waals radii to use. Default

is csd [S. Alvarez, 2013].

vdw_scale (float): scaling factor to apply to the base Van der Waals

radii values. Values bigger than one make for more

tolerant bonds.

default_vdw (float): default Van der Waals radius for species for

whom no data is available.

vdw_custom (dict): a dictionary of custom Van der Waals radii to use,

overriding the existing ones, expressed as

{symbol: radius}.

return_matrix (bool): if True, also return an NxN bonding matrix for

all N atoms in the system

save_info (bool): if True, save the found bonds (and in case matrix)

as part of the Atoms object info. By default True.

Returns:

bonds([tuple]): list of bonds in the form of 3-tuples structured as

explained above

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, vdw_set, vdw_scale, default_vdw, vdw_custom, return_matrix, 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.linkage.linkage.CoordinationHistogram(name=None, **params)

Bases: AtomsProperty

Produces an histogram representing, for each pair of species present in the system, how many atoms of species 1 have n bonds with species 2, n being the histogram bins. The histogram is topped at a ‘maximum coordination’ parameter which is 6 by default but can be user defined; the last bin represents all higher values (so by default ‘6 or more’). Two species or lists of species can be given if one wants to restrict the search; otherwise a full histogram for all pairs of species is returned.

Parameters:

vdw_set({ase, jmol, csd}): set of Van der Waals radii to use. Default

is csd [S. Alvarez, 2013].

vdw_scale (float): scaling factor to apply to the base Van der Waals

radii values. Values bigger than one make for more

tolerant bonds.

default_vdw (float): default Van der Waals radius for species for

whom no data is available.

vdw_custom (dict): a dictionary of custom Van der Waals radii to use,

overriding the existing ones, expressed as

{symbol: radius}.

species_1 (str or [str]): list of species to compute the histogram

for. By default all of them.

species_2 (str or [str]): list of species whose coordination with

species_1 should be checked. By default all

of them.

max_coord (int): what should be the largest coordination number

considered for an atom (default 6).

Returns:

coord_hist (dict): dictionary of dictionaries indexed by species_1

followed by species_2. The elements are arrays of

integers constituting the histogram.

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, vdw_set, vdw_scale, default_vdw, vdw_custom, species_1, species_2, max_coord)

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

Bases: AtomsProperty

Produces a list of dihedral angles found in the system, identified by looking for a bonding pattern. The amount of said angles can vary from zero (if the pattern is not present) to an arbitrary number. They will be returned sorted from lowest to highest. Periodic boundary conditions are taken into account. If no pattern is provided, HCCH groups are searched by default.

Parameters:

dihedral_pattern ([str]*4): a list of four chemical symbols

identifying the dihedral pattern to look

for

bonds_params (dict): parameters to pass to the Bonds property used to

compute bonds. See the Bonds docstring for

details. If not provided, defaults are used

Returns:

dihedral_angles (np.ndarray): sorted list of dihedral angles found

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, dihedral_pattern, bonds_params)

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

Bases: AtomsProperty

Produces an array containing the atomic pair distances in a system, reduced to their shortest periodic version and sorted min to max.

This is a modified version of LinkageList that operates only on the subset of atoms that are of the specified elements. The pair_list will therefore always have element 1 in the first index and element 2 in the second index of each tuple.

Parameters:

• element1 (str) – first element to consider

• element2 (str) – second element to consider

• maxsize (int) –

  maximum number of distances to include. If not present, all of them will be included. If present, arrays will be cut reach this size. If the number of pairs is less than

  maxsize, only those pairs will be returned. This is different to the behaviour of LinkageList.

• rcut (float) – maximum distance to consider (in Angstroms). If rcut is <= 0, no cutoff is applied.

• return_pairs (bool) – if True, return the pairs of atoms to which the distances correspond, as a list of tuples of indices.

Returns:

sorted list of interatomic linkage distances pair_list ([(int, int)]): only if return_pairs is True, list of pairs

corresponding to the distances

Return type:

link_list ([float])

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, element1, element2, rcut, maxsize, return_pairs)

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

Bases: AtomsProperty

Hydrogen Bonds

Produces a dictionary containing the atom indices defining hydrogen bonds detected in the system - if required, classified by type. By default only O and N atoms are considered for hydrogen bonds (OH..O, OH..N and so on). The type is defined as AH..B where A is the symbol of the atom directly bonded to the proton and B the one of the hydrogen bonded one.

Parameters:

vdw_set({ase, jmol, csd}): set of Van der Waals radii to use. Default

is csd [S. Alvarez, 2013].

vdw_scale (float): scaling factor to apply to the base Van der Waals

radii values. Values bigger than one make for more

tolerant molecules.

default_vdw (float): default Van der Waals radius for species for

whom no data is available.

hbond_elems ([str]): chemical symbols of elements considered capable

of forming hydrogen bonds (by default O and N)

max_length (float): maximum A-B length of the hydrogen bond in

Angstrom - default is 3.5 Ang

max_angle (float): maximum A-H/A-B angle in the hydrogen bond in

degrees - default is 45 deg

save_info (bool): if True, save the found hydrogen bonds as part of

the Atoms object info. By default True.

Returns:

hbondss ([dict]): list of hydrogen bonds detected

in the system by type (can contain empty arrays).

For each hydrogen bond we give index of the H

atom, index and unit cell of the A atom (the one

directly bonded), index and unit cell of the B atom

(the one that’s hydrogen bonded), length and angle

in degrees.

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, vdw_set, vdw_scale, default_vdw, vdw_custom, hbond_elems, max_length, max_angle, 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.linkage.linkage.HydrogenBondsNumber(name=None, **params)

Bases: AtomsProperty

Number of hydrogen bonds detected in this system, classified by type. By default will use already existing hydrogen bonds if they’re present as a saved array in the system.

Parameters:

force_recalc (bool): if True, always recalculate the hydrogen bonds

even if already present.

Returns:

hbonds_n (int): number of hydrogen bonds found

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)

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

Bases: AtomsProperty

Produces an array containing the atomic pair distances in a system, reduced to their shortest periodic version and sorted min to max.

Parameters:

size (int): maximum number of distances to include. If not present,

all of them will be included. If present, arrays will be

cut or padded to reach this size.

return_pairs (bool): if True, return the pairs of atoms to which the

distances correspond, as a list of tuples of

indices.

Returns:

link_list ([float]): sorted list of interatomic linkage distances

pair_list ([(int, int)]): only if return_pairs is True, list of pairs

corresponding to the distances

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, size, return_pairs)

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

Bases: AtomsProperty

List of centers of mass for the molecules present in the system. By default will use already existing molecules if they’re present as a saved array in the system.

Parameters:

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

already present.

Return:

mol_com (np.ndarray): list of centers of mass for the system’s

molecules

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)

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

Bases: AtomsProperty

Linkage list - following the same criteria as the atomic one - calculated for the centers of mass of the molecules present in the system. By default will use already existing molecules if they’re present as a saved array in the system.

Parameters:

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

already present.

size (int): maximum number of distances to include. If not present,

all of them will be included. If present, arrays will be

cut or padded to reach this sizeber.

Returns:

molecule_linkage ([float]): distances between all centers of mass of

molecules in the system, sorted.

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

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

Bases: AtomsProperty

Total mass of each of the molecules detected in this system. By default will use already existing molecules if they’re present as a saved array in the system.

Parameters:

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

already present.

size (int): maximum number of distances to include. If not present,

all of them will be included. If present, arrays will be

cut or padded to reach this sizeber.

Returns:

molecule_m ([float]): mass of each of the molecules present, sorted.

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

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

Bases: AtomsProperty

Number of molecules detected in this system. By default will use already existing molecules if they’re present as a saved array in the system.

Parameters:

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

already present.

Returns:

molecule_n (int): number of molecules found

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)

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

Bases: AtomsProperty

A list of quaternions expressing the rotation of the molecule’s intertia tensor principal frame with respect to the cartesian axes.

Parameters:

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

already present.

Returns:

mol_quat ([ase.Quaternion]): 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, force_recalc)

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

Bases: AtomsProperty

A list of relative rotations between molecules. Uses the inertia tensor eigenvectors to establish a local frame for each molecule, then uses quaternions to define a rotational distance between molecules. It then produces a list of geodesic distances between these quaternions.

Parameters:

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

already present.

size (int): maximum number of distances to include. If not present,

all of them will be included. If present, arrays will be

cut or padded to reach this size.

twist_axis ([float]): if present, only compare the Twist component of

quaternion along the given axis. The Twist/Swing

decomposition splits a quaternion in a rotation

around an axis and one around an orthogonal

direction. Only one between this and swing_plane

can be present.

swing_plane ([float]): if present, only compare the Swing component of

quaternion along the given axis. The Twist/Swing

decomposition splits a quaternion in a rotation

around an axis and one around an orthogonal

direction. Only one between this and twist_axis

can be present.

Returns:

molecule_relrot ([float]): list of relative rotations, as quaternion

distances, with the required ordering.

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, size, swing_plane, twist_axis)

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

Bases: AtomsProperty

Reorder molecules to have their indices sorted using a spectral sorting method based on the Fiedler vector of their bonding graph. This sorting should be equivalent for equivalent molecules - except for the arbitrary ordering of equivalent atoms.

Parameters:

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

already present.

Returns:

mol_specsort ([np.ndarray]): list of Molecules with indices sorted by spectral method.

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)

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

Bases: AtomsProperty

Produces an array containing multiple AtomSelection objects representing molecules in the system as found by connecting atoms closer than the half sum of their Van der Waals radii. It will return the entire unit cell if the system can not be split in molecules at all.

Parameters:

vdw_set({ase, jmol, csd}): set of Van der Waals radii to use. Default

is csd [S. Alvarez, 2013].

vdw_scale (float): scaling factor to apply to the base Van der Waals

radii values. Values bigger than one make for more

tolerant molecules.

default_vdw (float): default Van der Waals radius for species for

whom no data is available.

vdw_custom (dict): a dictionary of custom Van der Waals radii to use,

overriding the existing ones, expressed as

{symbol: radius}.

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

Atoms object info. By default True.

Returns:

molecules ([AtomSelection]): list of molecules in the form of

AtomSelection objects.

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, vdw_set, vdw_scale, default_vdw, vdw_custom, 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

soprano.properties.linkage.linkage._compute_bonds(s, vdw_set, vdw_scale=1.0, default_vdw=2.0, vdw_custom={})

Convenience function that covers the core of bond computation