The APyT local composition module

The apyt.analysis.chemistry.locomp module provides tools for evaluating local chemical compositions within spherical sub-volumes of a three-dimensional atom probe data set. This is particularly useful for analyzing spatial variations in composition at the nanoscale.

The input data must contain 3D spatial coordinates along with atomic identity information (i.e., element type IDs).

Local composition can be computed using one of two mutually exclusive methods:

1. Fixed neighbor count: Spheres are constructed to contain a constant number of atoms (neighbors).

2. Fixed radius/volume: Spheres are defined with a constant radius.

These methods are controlled via a parameter dictionary with the following keys:

• type: either "neighbor" or "volume"

• param: the number of neighbors (if type is "neighbor"), or the radius of the sphere (if type is "volume")

Spheres can be centered:

• Around every atom in the dataset, or

• On a regular 3D grid with user-defined minimum spacing to avoid overlapping spheres. (See get_query_points() for grid generation details.)

Neighbor searches are performed using the KDTree class from the SciPy library, ensuring efficient spatial queries even for large datasets.

List of functions

This module provides the following functions for computing and analyzing local composition histograms and related statistics:

• calc_stats(): Calculate histogram and statistics.

• check_periodic_box(): Check periodic boundary conditions.

• emulate_efficiency(): Emulate detector efficiency for simulated data.

• get_composition(): Get local compositions for query points.

• get_extended_cell_geometry(): Get simulation cell geometry in extended xyz format.

• get_margin_filter(): Automatically filter margin region.

• get_query_points(): Get query points for neighbor search.

apyt.analysis.chemistry.locomp.calc_stats(data, **kwargs)

Calculate histogram and evaluate histogram statistics.

Parameters:

data (ndarray, shape (n,)) – The data over which to calculate the histogram.

Keyword Arguments:

• bin_method (str) – The method to use to determine the bin width for the histogram. This argument will be passed through to the numpy.histogram() method. Default: None, which evaluates to a bin width of 1.0.

• correlation (int) – The correlation factor of the samples. If the samples are correlated, the statistical error estimates will be underestimated, but can be corrected with this option. Default: 1, i.e. all samples are uncorrelated.

Returns:

• (hist, edges, centers, hist_norm) (tuple) – The tuple containing the respective histogram counts hist, the bin edges edges, the bin centers centers, and the normalized histogram counts hist_norm, each of type ndarray, shape (m,) or shape (m+1,), respectively.

• (μ, Δμ, Var, ΔVar, Var/μ, Δ(Var/μ)) (tuple) – The statistical histogram data including error estimates, each of type float.

apyt.analysis.chemistry.locomp.check_periodic_box(comment)

Check periodic boundary conditions.

This method checks an OVITO comment line for the presence of the periodic boundary flags. If found, this method returns the (periodic) box dimensions, otherwise None is returned.

Parameters:

comment (str) – A valid OVITO comment line from a file in xyz format.

Returns:

box – The box dimensions for periodic boundary conditions.

Return type:

ndarray, shape (3,) or None

apyt.analysis.chemistry.locomp.emulate_efficiency(data, p, seed=None)

Emulate detector efficiency for simulated data.

For data prior to evaporation and reconstruction, the limited detector efficiency can be emulated for a simulated data set by randomly choosing the particles with a certain probability which corresponds to the detection efficiency p.

Parameters:

• data (ndarray, shape (n, 4)) – The n types and three-dimensional coordinates of the atoms.

• p (float) – The detector efficiency to emulate.

• seed (int, optional) – The optional seed to initialize the random number generator. Defaults to None.

Returns:

data_r – The m types and three-dimensional coordinates of the randomly selected atoms.

Return type:

ndarray, shape (m, 4)

apyt.analysis.chemistry.locomp.get_composition(data, query_points, query, **kwargs)

Get local compositions for query points.

Depending on the value of type in the query dictionary argument, either the nearest neighbors ("neighbor") or neighbors within a fixed distance/volume ("volume") will be searched for the provided query points. The composition in terms of number of type 2 particles will be returned for each query point. In addition, either the sphere radii or the total number of atoms in the spheres will be returned.

Parameters:

• data (ndarray, shape (n, 4)) – The n types and three-dimensional coordinates of the atoms.

• query_points (ndarray, shape (m, 3)) – The m three-dimensional query points for the search.

• query (dict) – The dictionary containing the query type ("neighbor" or "volume") and the query parameter param (number of neighbors or neighbor search cutoff).

Keyword Arguments:

• box (ndarray, shape (3,) or None) – The periodic box dimensions (if present).

• memory (float) – The maximum amount of memory (GB) to use. If not provided, an internally specified fraction of the available system memory will be used at maximum.

• verbose (bool) – Whether to be verbose. Default: False.

• workers (int) – The optional number of worker threads to use. If not provided, all system cores will be used.

Returns:

• r (ndarray, shape (m,)) – The m sphere radii, i.e. the distance to the furthest neighbor for the "neighbor" query type.

• n_2 (ndarray, shape (m,)) – The m numbers of type 2 atoms in the spheres.

or

Returns:

• n (ndarray, shape (m,)) – The m numbers of total atoms in the spheres for the "volume" query type.

• n_2 (ndarray, shape (m,)) – The m numbers of type 2 atoms in the spheres.

apyt.analysis.chemistry.locomp.get_extended_cell_geometry(comment)

Get simulation cell geometry in extended xyz format.

This method checks an OVITO comment line in standard xyz format for the simulation cell geometry and, if present, returns the cell geometry in extended xyz format.

Parameters:

comment (str) – A valid OVITO comment line from a file in xyz format.

Returns:

cell – The simulation cell geometry in extended xyz format (empty if no cell geometry found).

Return type:

str

apyt.analysis.chemistry.locomp.get_margin_filter(query_points, r, box_l, box_u, threshold=1.1)

Automatically filter margin region.

Query points close to the surface in the margin region should not be included in the evaluation since the nearest neighbors will typically not be confined in a spherical volume, but rather in a truncated sphere. Only if the distance of the query point to the surface is sufficiently large, the maximum nearest neighbor distance becomes equal to the sphere radius. The critical condition is reached if the distance of the query point is identical to the maximum nearest neighbor distance. By default, an additional buffer of 10% is included, which can be controlled by the optional threshold argument.

Parameters:

• query_points (ndarray, shape (n, 3)) – The n three-dimensional query points.

• r (ndarray, shape (n,)) – The n sphere radii (maximum nearest neighbor distances).

• box_l (ndarray, shape (3,)) – The lower box boundary.

• box_u (ndarray, shape (3,)) – The upper box boundary.

• threshold (float) – The optional threshold used for filtering. Defaults to 1.1.

Returns:

mask – The boolean mask indicating which query points do not belong to the margin region.

Return type:

ndarray, shape (n,)

apyt.analysis.chemistry.locomp.get_query_points(coords, **kwargs)

Get query points for neighbor search.

This method can be used to specify the query points for the neighbor search. If no additional argument is provided, all atomic positions will be used as query points. The margin keyword argument can be used to exclude surface artifacts. With the distance keyword argument, a minimum separation between the query points is ensured, which is achieved by the construction of a regular three-dimensional grid. For periodic boxes, the box dimensions should be passed using the box keyword argument. By default, internal consistency checks for appropriate use of the margin keyword argument are performed, but these checks can be disabled with the no_margin_checks keyword argument.

Parameters:

coords (ndarray, shape (n, 3)) – The n three-dimensional coordinates.

Keyword Arguments:

• box (ndarray, shape (3,) or None) – The periodic box dimensions (if present).

• distance (float) – The (minimum) separation between the query points.

• margin (float) – The width of the margin region to exclude for the query points.

• no_margin_checks (bool) – Whether to disable internal margin checks.

Returns:

query_points – The m three-dimensional query points for the neighbor search.

Return type:

ndarray, shape (m, 3)