structuretoolkit.analyse.spatial.Interstitials

class structuretoolkit.analyse.spatial.Interstitials(structure: Atoms, num_neighbors: int, n_gridpoints_per_angstrom: int = 5, min_distance: float = 1, use_voronoi: bool = False, x_eps: float = 0.1, l_values: ndarray = array([2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]), q_eps: float = 0.3, var_ratio: float = 5.0, min_samples: int | None = None, neigh_args: dict | None = None, **kwargs)

Bases: object

Class to search for interstitial sites

This class internally does the following steps:

0. Initialize grid points (or Voronoi vertices) which are considered as

   interstitial site candidates.

1. Eliminate points within a distance from the nearest neighboring atoms as

   given by min_distance

2. Shift interstitial candidates to the nearest symmetric points with respect to the

   neighboring atom sites/vertices.

3. Cluster interstitial candidate positions to avoid point overlapping.

4. Cluster interstitial candidates by their Steinhardt parameters (cf. l_values for

   the values of the spherical harmonics) and the variance of the distances and take the group with the smallest average distance variance

The interstitial sites can be obtained via positions

In complex structures (i.e. grain boundary, dislocation etc.), the default parameters should be chosen properly. In order to see other quantities, which potentially characterize interstitial sites, see the following class methods:

• get_variances()

• get_distances()

• get_steinhardt_parameters()

• get_volumes()

• get_areas()

Troubleshooting:

Identifying interstitial sites is not a very easy task. The algorithm employed here will probably do a good job, but if it fails, it might be good to look at the following points

• The intermediate results can be accessed via run_workflow by specifying the step number.

• The most vulnerable point is the last step, clustering by Steinhardt parameters. Take a

  look at the step before and after. If the interstitial sites are present in the step before the clustering by Steinhardt parameters, you might want to change the values of q_eps and var_ratio. It might make a difference to use l_values as well.

• It might fail to find sites if the box is very small. In that case it might make sense to

  set min_samples very low (you can take 1)

__init__(structure: Atoms, num_neighbors: int, n_gridpoints_per_angstrom: int = 5, min_distance: float = 1, use_voronoi: bool = False, x_eps: float = 0.1, l_values: ndarray = array([2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]), q_eps: float = 0.3, var_ratio: float = 5.0, min_samples: int | None = None, neigh_args: dict | None = None, **kwargs)

Parameters:

• num_neighbors (int) – Number of neighbors/vertices to consider for the interstitial sites. By definition, tetrahedral sites should have 4 vertices and octahedral sites 6.

• n_gridpoints_per_angstrom (int) – Number of grid points per angstrom for the initialization of the interstitial candidates. The finer the mesh (i.e. the larger the value), the likelier it is to find the correct sites but then also it becomes computationally more expensive. Ignored if use_voronoi is set to True

• min_distance (float) – Minimum distance from the nearest neighboring atoms to the positions for them to be considered as interstitial site candidates. Set min_distance to 0 if no point should be removed.

• use_voronoi (bool) – Use Voronoi vertices for the initial interstitial candidate positions instead of grid points.

• x_eps (bool) – eps value for the clustering of interstitial candidate positions

• l_values (list) – list of values for the Steinhardt parameter values for the classification of the interstitial candidate points

• q_eps (float) – eps value for the clustering of interstitial candidate points based on Steinhardt parameters and distance variances. This might play a crucial role in identifying the correct interstitial sites

• var_ratio (float) – factor to be multiplied to the variance values in order to give a larger weight to the variances.

• min_samples (int/None) – min_sample in the point clustering.

• neigh_args (dict) – arguments to be added to get_neighbors

Methods

__init__(structure, num_neighbors[, ...])	param num_neighbors: Number of neighbors/vertices to consider for the interstitial
get_areas()	returns: Convex hull area of each site.
get_distances([function_to_apply])	Get per-position return values of a given function for the neighbors.
get_steinhardt_parameters(l)	param l: Order of Steinhardt parameter
get_variances()	Get variance of neighboring distances.
get_volumes()	returns: Convex hull volume of each site.
run_workflow([positions, steps])	Run the workflow to obtain the interstitial positions.

Attributes

hull	Convex hull of each atom.
neigh	Neighborhood information of each interstitial candidate and their surrounding atoms.
positions	Get the positions of the interstitial sites.

get_areas() → ndarray

Returns:

Convex hull area of each site.

Return type:

(numpy.array (n,))

get_distances(function_to_apply=<function min>) → ndarray

Get per-position return values of a given function for the neighbors.

Parameters:

function_to_apply (function) – Function to apply to the distance array. Default is numpy.minimum

Returns:

(numpy.array (n,)) Function values on the distance array

get_steinhardt_parameters(l: int) → ndarray

Parameters:

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

Returns:

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

get_variances() → ndarray

Get variance of neighboring distances. Since interstitial sites are mostly in symmetric sites, the variance values tend to be small. In the case of fcc, both tetrahedral and octahedral sites as well as tetrahedral sites in bcc should have the value of 0.

Returns:

(numpy.array (n,)) Variance values

get_volumes() → ndarray

Returns:

Convex hull volume of each site.

Return type:

(numpy.array (n,))

property hull: list

Convex hull of each atom. It is mainly used for the volume and area calculation of each interstitial candidate. For more info, see get_volumes and get_areas.

property neigh

Neighborhood information of each interstitial candidate and their surrounding atoms. E.g. class.neigh.distances[0][0] gives the distance from the first interstitial candidate to its nearest neighboring atoms. The functionalities of neigh follow those of structuretoolkit.analyse.neighbors.

property positions: ndarray

Get the positions of the interstitial sites.

Returns:

Positions of the interstitial sites.

Return type:

np.ndarray

run_workflow(positions: ndarray | None = None, steps: int = -1) → ndarray

Run the workflow to obtain the interstitial positions.

Parameters:

• positions (numpy.ndarray, optional) – Initial positions of the interstitial candidates. If not provided, the initial positions stored in self.initial_positions will be used.

• steps (int, optional) – Number of steps to run in the workflow. If set to -1 (default), all steps will be run.

Returns:

Final positions of the interstitial sites.

Return type:

numpy.ndarray