structuretoolkit.analyse.neighbors.Neighbors

class structuretoolkit.analyse.neighbors.Neighbors(ref_structure: Atoms, tolerance: int = 2)

Bases: Tree

Class to get tree structure for the neighborhood information.

Main attributes (do not modify them):

• distances (numpy.ndarray/list): Distances to the neighbors of given positions

• indices (numpy.ndarray/list): Indices of the neighbors of given positions

• vecs (numpy.ndarray/list): Vectors to the neighbors of given positions

Auxiliary attributes:

• wrap_positions (bool): Whether to wrap back the positions entered by user in get_neighborhood

  etc. Since the information outside the original box is limited to a few layer, wrap_positions=False might miss some points without issuing an error.

Change representation mode via :attribute:`.Neighbors.mode` (cf. its DocString)

Furthermore, you can re-employ the original tree structure to get neighborhood information via get_neighborhood.

__init__(ref_structure: Atoms, tolerance: int = 2)

Neighbors class for analyzing neighboring atoms in a structure.

Parameters:

• ref_structure (ase.Atoms) – Reference structure.

• tolerance (int) – Tolerance for rounding distances (default: 2).

Methods

__init__(ref_structure[, tolerance])	Neighbors class for analyzing neighboring atoms in a structure.
cluster_analysis(id_list[, return_cluster_sizes])	Perform cluster analysis on a list of atom IDs.
cluster_by_distances([distance_threshold, ...])	Method to group vectors which have similar lengths.
cluster_by_vecs([distance_threshold, ...])	Method to group vectors which have similar values.
copy()	Create a copy of the Tree object.
find_neighbors_by_vector(vector[, ...])	param vector: vector by which positions are translated (and neighbors are searched)
get_bonds([radius, max_shells, prec])	Get the bonds in the structure.
get_global_shells([mode, tolerance, ...])	Set shell indices based on all distances available in the system instead of setting them according to the local distances (in contrast to shells defined as an attribute in this class).
get_local_shells([mode, tolerance, ...])	Set shell indices based on distances available to each atom.
get_neighborhood(positions[, num_neighbors, ...])	Get neighborhood information of positions.
get_shell_matrix([chemical_pair, ...])	Shell matrices for pairwise interaction.
get_spherical_harmonics(l, m[, ...])	param l: Degree of the harmonic (int); must have l >= 0.
get_steinhardt_parameter(l[, cutoff_radius])	param l: Order of Steinhardt parameter
reset_clusters([vecs, distances])	Method to reset clusters.

Attributes

atom_numbers	Get the indices of atoms.
centrosymmetry	Calculate centrosymmetry parameter for the given environment.
chemical_symbols	Returns chemical symbols of the neighboring atoms.
distances	Get the distances to neighboring atoms.
indices	Get the indices of neighboring atoms.
mode	Change the mode of representing attributes (vecs, distances, indices, shells).
norm_order	Norm to use for the neighborhood search and shell recognition.
numbers_of_neighbors	Get the number of neighbors for each atom.
shells	Returns the cell numbers of each atom according to the distances.
vecs	Get the vectors to neighboring atoms.

property atom_numbers: ndarray

Get the indices of atoms.

Returns:

The indices of atoms.

Return type:

np.ndarray

property centrosymmetry: ndarray

Calculate centrosymmetry parameter for the given environment.

cf. https://doi.org/10.1103/PhysRevB.58.11085

NB: Currently very memory intensive for a large number of neighbors (works maybe up to 10)

property chemical_symbols: ndarray

Returns chemical symbols of the neighboring atoms.

Undefined neighbors (i.e. if the neighbor distance is beyond the cutoff radius) are considered as vacancies and are marked by ‘v’.

Returns:

Chemical symbols of neighboring atoms.

Return type:

np.ndarray

cluster_analysis(id_list: list, return_cluster_sizes: bool = False) → dict[int, list[int]] | tuple[dict[int, list[int]], list[int]]

Perform cluster analysis on a list of atom IDs.

Parameters:

• id_list (list) – List of atom IDs to perform cluster analysis on.

• return_cluster_sizes (bool) – Whether to return the sizes of each cluster.

Returns:

Dictionary mapping cluster IDs to a list of atom IDs in each cluster.

If return_cluster_sizes is True, also returns a list of cluster sizes.

Return type:

Union[Dict[int, List[int]], Tuple[Dict[int, List[int]], List[int]]]

cluster_by_distances(distance_threshold: float | None = None, n_clusters: int | None = None, linkage: str = 'complete', metric: str = 'euclidean', use_vecs: bool = False)

Method to group vectors which have similar lengths. This method should be used as a part of neigh.get_global_shells(cluster_by_vecs=True) or neigh.get_local_shells(cluster_by_distances=True). However, in order to specify certain arguments (such as n_jobs or max_iter), it might help to have run this function before calling parent functions, as the data obtained with this function will be stored in the variable _cluster_distances

Parameters:

• distance_threshold (float/None) – The linkage distance threshold above which, clusters will not be merged. (cf. sklearn.cluster.AgglomerativeClustering)

• n_clusters (int/None) – The number of clusters to find. (cf. sklearn.cluster.AgglomerativeClustering)

• linkage (str) – Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. (cf. sklearn.cluster.AgglomerativeClustering)

• metric (str/callable) – Metric used to compute the linkage. Can be euclidean, l1, l2, manhattan, cosine, or precomputed. If linkage is ward, only euclidean is accepted.

• use_vecs (bool) – Whether to form clusters for vecs beforehand. If true, the distances obtained from the clustered vectors is used for the distance clustering. Otherwise neigh.distances is used.

cluster_by_vecs(distance_threshold: float | None = None, n_clusters: int | None = None, linkage: str = 'complete', metric: str = 'euclidean')

Method to group vectors which have similar values. This method should be used as a part of neigh.get_global_shells(cluster_by_vecs=True) or neigh.get_local_shells(cluster_by_vecs=True). However, in order to specify certain arguments (such as n_jobs or max_iter), it might help to have run this function before calling parent functions, as the data obtained with this function will be stored in the variable _cluster_vecs

Parameters:

• distance_threshold (float/None) – The linkage distance threshold above which, clusters will not be merged. (cf. sklearn.cluster.AgglomerativeClustering)

• n_clusters (int/None) – The number of clusters to find. (cf. sklearn.cluster.AgglomerativeClustering)

• linkage (str) – Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. (cf. sklearn.cluster.AgglomerativeClustering)

• metric (str/callable) – Metric used to compute the linkage. Can be euclidean, l1, l2, manhattan, cosine, or precomputed. If linkage is ward, only euclidean is accepted.

copy() → Tree

Create a copy of the Tree object.

Returns:

A copy of the Tree object.

Return type:

Tree

property distances: ndarray

Get the distances to neighboring atoms.

Returns:

The distances to neighboring atoms.

Return type:

np.ndarray

find_neighbors_by_vector(vector: ndarray, return_deviation: bool = False) → ndarray | tuple[ndarray, ndarray]

Parameters:

• vector (list/np.ndarray) – vector by which positions are translated (and neighbors are searched)

• return_deviation (bool) – whether to return distance between the expect positions and real positions

Returns:

list of id’s for the specified translation

Return type:

np.ndarray

Example

a_0 = 2.832 structure = pr.create_structure(‘Fe’, ‘bcc’, a_0) id_list = structure.find_neighbors_by_vector([0, 0, a_0]) # In this example, you get a list of neighbor atom id’s at z+=a_0 for each atom. # This is particularly powerful for SSA when the magnetic structure has to be translated # in each direction.

get_bonds(radius: float = inf, max_shells: int | None = None, prec: float = 0.1) → list[dict[str, list[list[int]]]]

Get the bonds in the structure.

Parameters:

• radius (float) – The maximum distance for a bond to be considered.

• max_shells (int, optional) – The maximum number of shells to consider for each atom.

• prec (float) – The minimum distance between any two clusters. If smaller, they are considered as a single cluster.

Returns:

A list of dictionaries, where each dictionary represents the shells around an atom.

The keys of the dictionary are the element symbols, and the values are lists of atom indices for each shell.

Return type:

List[Dict[str, List[List[int]]]]

get_global_shells(mode: str | None = None, tolerance: int | None = None, cluster_by_distances: bool = False, cluster_by_vecs: bool = False) → ndarray

Set shell indices based on all distances available in the system instead of setting them according to the local distances (in contrast to shells defined as an attribute in this class). Clustering methods can be used at the same time, which will be useful at finite temperature results, but depending on how dispersed the atoms are, the algorithm could take some time. If the clustering method(-s) have already been launched before this function, it will use the results already available and does not execute the clustering method(-s) again.

Parameters:

• mode (str) – Representation of the variable. Choose from ‘filled’, ‘ragged’ and ‘flattened’.

• tolerance (int) – Decimals in np.round for rounding up distances.

• cluster_by_distances (bool) – If True, cluster_by_distances is called first and the distances obtained from the clustered distances are used to calculate the shells. If cluster_by_vecs is True at the same time, cluster_by_distances will use the clustered vectors for its clustering algorithm.

• cluster_by_vecs (bool) – If True, cluster_by_vectors is called first and the distances obtained from the clustered vectors are used to calculate the shells.

Returns:self.cluster_by_distances(use_vecs=cluster_by_vecs)

np.ndarray: Shell indices.

get_local_shells(mode: str | None = None, tolerance: int | None = None, cluster_by_distances: bool = False, cluster_by_vecs: bool = False) → ndarray

Set shell indices based on distances available to each atom. Clustering methods can be used at the same time, which will be useful at finite temperature results, but depending on how dispersed the atoms are, the algorithm could take some time. If the clustering method(-s) have already been launched before this function, it will use the results already available and does not execute the clustering method(-s) again.

Parameters:

• mode (str) – Representation of the variable. Choose from ‘filled’, ‘ragged’ and ‘flattened’.

• tolerance (int) – Decimals in np.round for rounding up distances.

• cluster_by_distances (bool) – If True, cluster_by_distances is called first and the distances obtained from the clustered distances are used to calculate the shells. If cluster_by_vecs is True at the same time, cluster_by_distances will use the clustered vectors for its clustering algorithm.

• cluster_by_vecs (bool) – If True, cluster_by_vectors is called first and the distances obtained from the clustered vectors are used to calculate the shells.

Returns:

Shell indices.

Return type:

np.ndarray

get_neighborhood(positions: ndarray, num_neighbors: int | None = None, cutoff_radius: float = inf, width_buffer: float = 1.2) → Tree

Get neighborhood information of positions. What it returns is in principle the same as get_neighborhood in Atoms. The only one difference is the reuse of the same Tree structure, which makes the algorithm more efficient, but will fail if the reference structure changed in the meantime.

Parameters:

• positions (np.ndarray) – Positions in a box whose neighborhood information is analyzed.

• num_neighbors (Optional[int]) – Number of nearest neighbors. Defaults to None.

• cutoff_radius (float) – Upper bound of the distance to which the search is to be done. Defaults to np.inf.

• width_buffer (float) – Width of the layer to be added to account for pbc. Defaults to 1.2.

Returns:

Neighbors instance with the neighbor indices, distances, and vectors.

Return type:

Tree

get_shell_matrix(chemical_pair: list[str] | None = None, cluster_by_distances: bool = False, cluster_by_vecs: bool = False)

Shell matrices for pairwise interaction. Note: The matrices are always symmetric, meaning if you use them as bilinear operators, you have to divide the results by 2.

Parameters:

chemical_pair (list) – pair of chemical symbols (e.g. [‘Fe’, ‘Ni’])

Returns:

list of sparse matrices for different shells

Example

from ase.build import bulk structure = bulk(‘Fe’, ‘bcc’, 2.83).repeat(2) J = -0.1 # Ising parameter magmoms = 2*np.random.random((len(structure)), 3)-1 # Random magnetic moments between -1 and 1 neigh = structure.get_neighbors(num_neighbors=8) # Iron first shell shell_matrices = neigh.get_shell_matrix() print(‘Energy =’, 0.5*J*magmoms.dot(shell_matrices[0].dot(matmoms)))

get_spherical_harmonics(l: ndarray, m: ndarray, cutoff_radius: float = inf, rotation: ndarray | None = None) → ndarray

Parameters:

• l (int/numpy.array) – Degree of the harmonic (int); must have l >= 0.

• m (int/numpy.array) – Order of the harmonic (int); must have |m| <= l.

• cutoff_radius (float) – maximum neighbor distance to include (default: inf, i.e. all

• search). (atoms included in the neighbor)

• rotation ((3,3) numpy.array/list) – Rotation to make sure phi does not become nan

Returns:

( (natoms,) numpy.array) spherical harmonic values

Spherical harmonics defined as follows

Y^m_l( heta,phi) = sqrt{ rac{2l+1}{4pi} rac{(l-m)!}{(l+m)!}} e^{i m heta} P^m_l(cos(phi))

The angles are calculated based on self.vecs, where the azimuthal angle is defined on the xy-plane and the polar angle is along the z-axis.

See more on: scipy.special.sph_harm_y

get_steinhardt_parameter(l: ndarray, cutoff_radius: float = inf) → ndarray

Parameters:

• l (int/numpy.array) – Order of Steinhardt parameter

• cutoff_radius (float) – maximum neighbor distance to include (default: inf, i.e. all

• search). (atoms included in the neighbor)

Returns:

( (natoms,) numpy.array) Steinhardt parameter values

See more on https://pyscal.org/part3/steinhardt.html

Note: This function does not have an internal algorithm to calculate a suitable cutoff radius. For automated uses, see Atoms.analyse.pyscal_steinhardt_parameter()

property indices: ndarray

Get the indices of neighboring atoms.

Returns:

The indices of neighboring atoms.

Return type:

np.ndarray

property mode: str

Change the mode of representing attributes (vecs, distances, indices, shells). The shapes of filled and ragged differ only if cutoff_radius is specified.

• ‘filled’: Fill variables for the missing entries are filled as follows: np.inf in

  distances, numpy.array([np.inf, np.inf, np.inf]) in vecs, n_atoms+1 (or a larger value) in indices and -1 in shells.

• ‘ragged’: Create lists of different lengths.

• ‘flattened’: Return flattened arrays for distances, vecs and shells. The indices

  corresponding to the row numbers in ‘filled’ and ‘ragged’ are in atom_numbers

The variables are stored in the filled mode.

property norm_order: int

Norm to use for the neighborhood search and shell recognition. The definition follows the conventional Lp norm (cf. https://en.wikipedia.org/wiki/Lp_space). This is still an experimental feature and for anything other than norm_order=2, there is no guarantee that this works flawlessly.

property numbers_of_neighbors: int

Get the number of neighbors for each atom.

Returns:

The number of neighbors for each atom. Same number is returned if cutoff_radius was not given in the initialization.

Return type:

int

reset_clusters(vecs: bool = True, distances: bool = True)

Method to reset clusters.

Parameters:

• vecs (bool) – Reset _cluster_vecs (cf. cluster_by_vecs)

• distances (bool) – Reset _cluster_distances (cf. cluster_by_distances)

property shells: ndarray

Returns the cell numbers of each atom according to the distances.

Returns:

Shell indices.

Return type:

np.ndarray

property vecs: ndarray

Get the vectors to neighboring atoms.

Returns:

The vectors to neighboring atoms.

Return type:

np.ndarray