pyiron.atomistics.structure.neighbors module

class pyiron.atomistics.structure.neighbors.Neighbors(ref_structure, tolerance=2)

Bases: pyiron.atomistics.structure.neighbors.Tree

Class for storage of the neighbor information for a given atom based on the KDtree algorithm

Main attributes (do not modify them):

• distances (numpy.ndarray/list): Distances to the neighbors of all atoms

• indices (numpy.ndarray/list): Indices of the neighbors of all atoms

• vecs (numpy.ndarray/list): Vectors to the neighbors of all atoms

Auxiliary attributes:

• allow_ragged (bool): Whether to allow a ragged list of numpy arrays or not. This is relevant

  only if the cutoff length was specified, in which case the number of neighbor atoms for each atom could differ. allow_ragged = False is computationally more efficient in most of the methods. When allow_ragged = False, the variables 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

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

Furthermore, you can re-employ the original tree structure to get neighborhood information via get_indices, get_vectors, get_distances and get_neighborhood. The information delivered by get_neighborhood is the same as what can be obtained through the other three getters (except for the fact that get_neighborhood returns a Tree instance, while the others return numpy arrays), but since get_vectors anyway has to call get_distances and get_indices internally, the computational cost of get_neighborhood and get_vectors is the same.

cluster_analysis(id_list, return_cluster_sizes=False)

Parameters

• id_list –

• return_cluster_sizes –

Returns:

cluster_by_distances(distance_threshold=None, n_clusters=None, linkage='complete', affinity='euclidean', use_vecs=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)

• affinity (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=None, n_clusters=None, linkage='complete', affinity='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)

• affinity (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.

find_neighbors_by_vector(vector, return_deviation=False)

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=inf, max_shells=None, prec=0.1)

Parameters

• radius –

• max_shells –

• prec – minimum distance between any two clusters (if smaller considered to be single cluster)

Returns:

get_global_shells(tolerance=None, cluster_by_distances=False, cluster_by_vecs=False)

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

• tolerance (int) – decimals in np.round for rounding up distances (default: 2)

• 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. For more, see the DocString of cluster_by_distances. (default: False)

• 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. (default: False)

Returns

shell indices (cf. shells)

Return type

shells (numpy.ndarray)

get_local_shells(tolerance=None, cluster_by_distances=False, cluster_by_vecs=False)

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

• 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. For more, see the DocString of cluster_by_distances. (default: False)

• 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. (default: False)

Returns

shell indices

Return type

shells (numpy.ndarray)

get_shell_matrix(chemical_pair=None, cluster_by_distances=False, cluster_by_vecs=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 pyiron import Project structure = Project(‘.’).create_structure(‘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)))

reset_clusters(vecs=True, distances=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

Returns the cell numbers of each atom according to the distances

class pyiron.atomistics.structure.neighbors.Tree(ref_structure)

Bases: object

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:

• allow_ragged (bool): Whether to allow a ragged list of numpy arrays or not. This is relevant

  only if the cutoff length was specified, in which case the number of atoms for each position could differ. allow_ragged = False is computationally more efficient in most of the methods. When allow_ragged = False, the variables 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

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

Furthermore, you can re-employ the original tree structure to get neighborhood information via get_indices, get_vectors, get_distances and get_neighborhood. The information delivered by get_neighborhood is the same as what can be obtained through the other three getters (except for the fact that get_neighborhood returns a Tree instance, while the others return numpy arrays), but since get_vectors anyway has to call get_distances and get_indices internally, the computational cost of get_neighborhood and get_vectors is the same.

property allow_ragged

Whether to allow ragged list of distancs/vectors/indices or fill empty slots with numpy.inf to get rectangular arrays

copy()

get_distances(positions=None, allow_ragged=None, num_neighbors=None, cutoff_radius=inf, width_buffer=1.2)

Get current positions or neighbor positions for given positions using the same Tree structure used for the instantiation of the Neighbor class. This function should not be used if the structure changed in the meantime. If positions is None and allow_ragged is None, this function returns the same content as positions.

Parameters

• positions (list/numpy.ndarray/None) – Positions around which neighborhood vectors are to be computed (None to get current vectors)

• allow_ragged (bool) – Whether to allow ragged list of arrays or rectangular numpy.ndarray filled with np.inf for values outside cutoff_radius

• num_neighbors (int/None) – Number of neighboring atoms to calculate vectors for. Ignored if positions is None.

• cutoff_radius (float) – cutoff radius. Ignored if positions is None.

• width_buffer (float) – Buffer length for the estimation of num_neighbors. Ignored if positions is None.

Returns

(list/numpy.ndarray) list (if allow_ragged=True) or numpy.ndarray (otherwise) of

neighbor distances

get_indices(positions=None, allow_ragged=None, num_neighbors=None, cutoff_radius=inf, width_buffer=1.2)

Get current indices or neighbor indices for given positions using the same Tree structure used for the instantiation of the Neighbor class. This function should not be used if the structure changed in the meantime. If positions is None and allow_ragged is None, this function returns the same content as indices.

Parameters

• positions (list/numpy.ndarray/None) – Positions around which neighborhood vectors are to be computed (None to get current vectors)

• allow_ragged (bool) – Whether to allow ragged list of arrays or rectangular numpy.ndarray filled with np.inf for values outside cutoff_radius

• num_neighbors (int/None) – Number of neighboring atoms to calculate vectors for. Ignored if positions is None.

• cutoff_radius (float) – cutoff radius. Ignored if positions is None.

• width_buffer (float) – Buffer length for the estimation of num_neighbors. Ignored if positions is None.

Returns

(list/numpy.ndarray) list (if allow_ragged=True) or numpy.ndarray (otherwise) of

neighbor indices

get_neighborhood(positions, num_neighbors=None, t_vec=True, cutoff_radius=inf, width_buffer=1.2)

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

• position – Position in a box whose neighborhood information is analysed

• num_neighbors (int) – Number of nearest neighbors

• t_vec (bool) – True: compute distance vectors (pbc are taken into account)

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

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

Returns

Neighbors instances with the neighbor indices,

distances and vectors

Return type

pyiron.atomistics.structure.atoms.Tree

get_vectors(positions=None, allow_ragged=False, num_neighbors=None, cutoff_radius=inf, width_buffer=1.2)

Get current vectors or neighbor vectors for given positions using the same Tree structure used for the instantiation of the Neighbor class. This function should not be used if the structure changed in the meantime. If positions is None and allow_ragged is None, this function returns the same content as vecs.

Parameters

• positions (list/numpy.ndarray/None) – Positions around which neighborhood vectors are to be computed (None to get current vectors)

• allow_ragged (bool) – Whether to allow ragged list of arrays or rectangular numpy.ndarray filled with np.inf for values outside cutoff_radius

• num_neighbors (int/None) – Number of neighboring atoms to calculate vectors for. Ignored if positions is None.

• cutoff_radius (float) – cutoff radius. Ignored if positions is None.

• width_buffer (float) – Buffer length for the estimation of num_neighbors. Ignored if positions is None.

Returns

(list/numpy.ndarray) list (if allow_ragged=True) or numpy.ndarray (otherwise) of

neighbor vectors

property norm_order

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.