structuretoolkit.analyse.neighbors.Tree

class structuretoolkit.analyse.neighbors.Tree(ref_structure: Atoms)

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:

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

Parameters:

ref_structure (ase.atoms.Atoms) – Reference structure.

Methods

__init__(ref_structure)	param ref_structure: Reference structure.
copy()	Create a copy of the Tree object.
get_neighborhood(positions[, num_neighbors, ...])	Get neighborhood information of positions.
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

Attributes

atom_numbers	Get the indices of atoms.
centrosymmetry	Calculate centrosymmetry parameter for the given environment.
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.
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)

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

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_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

property vecs: ndarray

Get the vectors to neighboring atoms.

Returns:

The vectors to neighboring atoms.

Return type:

np.ndarray