The APyT advanced reconstruction module

This module provides methods for the reconstruction of atom probe tomography (APT) data using non-spherical tip geometries. Unlike classic reconstruction models that assume a hemispherical or conical tip shape, the methods here account for local variations in tip curvature, enabling more accurate reconstructions of complex or irregular specimen shapes.

These advanced techniques are particularly useful for high-resolution applications or when the tip shape deviates significantly from idealized models.

List of classes

This module provides the following class for flexible, curvature-based reconstruction:

class apyt.reconstruction.non_spherical.CurvatureReconstructor(xy_data, ids, V_at, R0, r0, L0, ξ, ζ, copy_volumes=True, extrapolation_mode='generic', extrapolation_range=0.75, local_efficiency_correction=None, num_points_tip=101)[source]

Bases: object

Reconstruct tip height profile based on Gaussian curvature.

Parameters:

  • xy_data (ndarray, shape (n, 2)) – The x and y detector positions of all events.

  • ids (ndarray, shape (n,)) – The chemical IDs of all events used for the reconstruction.

  • V_at (ndarray, shape (n,)) – The volumes of all events used for the reconstruction.

  • R0 (float) – The detector radius (in mm)

  • r0 (float) – The tip radius (in nm)

  • L0 (float) – The distance between tip and detector (in mm)

  • ξ (float) – The image compression factor which is defined as \(\xi = \frac{\theta_{\textnormal{crys}}}{\tan\theta_{\textnormal{obs}}}\).

  • ζ (float) – The detection efficiency.

  • copy_volumes (bool) – Whether to create a copy of the provided volumes V_at. The volumes are modified internally to account for the (local) detection efficiency. By default, a copy of the volumes is created, leaving the original volumes unchanged. To apply these changes directly to the provided volumes in-place, set this flag to False.

  • extrapolation_mode (str) –

    The mode used to extrapolate the relative curvature as seen by the detector toward the tip boundary. Supported modes are:

    'generic'

    Use mean value from interior for extrapolation.

    'nearest'

    Use griddata from the SciPy interpolation module with method='nearest' (check link for details).

    Defaults to 'generic'.

  • extrapolation_range (float) – The extrapolation range (between 0 and 1), which controls how far the curvature as seen by the detector should be extrapolated toward the tip boundary. Beyond this fractional range, the Gaussian curvature smoothly transitions to \(K(r = r_0) = \frac{1}{r_0^2}\), which resembles the Gaussian curvature at the tip boundary. Defaults to 0.75.

  • local_efficiency_correction (callable) – A user-provided function to locally correct the detection efficiency (e.g., accounting for possible blind spots, etc.). This function is expected to take two arguments: the x and y coordinates of the detector, each represented as an ndarray of shape (n,). The return values are considered correction factors for the specific positions. Note that the detected atomic volumes are multiplied by the output of this function to artificially mimic a homogeneous density distribution.

  • num_points_tip (int) – The number of points used for the construction of the tip grid. Must be an odd number. Defaults to 101.

The following class methods are provided:

The following general instance properties can be accessed (read-only):

The following tip-related instance properties can be accessed (read-only):

  • X_tip: The x positions of the tip grid.

  • Y_tip: The y positions of the tip grid.

  • mask_tip: The Boolean mask specifying valid circular points.


Below is a list of all class objects with their detailed description.

property X_tip

Getter for the internal _X_tip attribute (read-only).

Returns:

X_tip – The x positions of the tip grid, as returned by the numpy.meshgrid() function.

Return type:

ndarray, shape (n, n)

property Y_tip

Getter for the internal _Y_tip attribute (read-only).

Returns:

Y_tip – The y positions of the tip grid, as returned by the numpy.meshgrid() function.

Return type:

ndarray, shape (n, n)

debug_plot(results)[source]

Show plots for debugging.

Parameters:

results (dict) – The dictionary containing various results for the reconstruction of the height profile. See reconstruct_height_profile() for details.

property mask_reconstruction

Getter for the internal _mask_reconstruction attribute (read-only).

Events outside the detector triangulation are not reconstructed. The reconstruct_positions() method tracks the reconstructed events by setting this attribute with corresponding Boolean values, which can then be used as a mask for filtering other properties.

Returns:

mask_reconstruction – The mask specifying valid reconstructed events.

Return type:

ndarray, shape (N,)

property mask_tip

Getter for the internal _mask_tip attribute (read-only).

Returns:

mask_tip – The Boolean mask specifying valid circular points on the square tip grid.

Return type:

ndarray, shape (n, n)

reconstruct_height_profile(i1, i2, ΔH_0=None, N_simp=500, maxiter=100, tol=0.01, tri=None, verbose=False, debug_plot=False)[source]

Reconstruct tip height profile for given data interval.

The core routine uses the Krylov root finding algorithm from the SciPy Optimization and root finding package for the reconstruction of the height profile.

Parameters:

  • i1 (int) – The index of the first event to use (inclusive).

  • i2 (int) – The index of the last event to use (exclusive).

  • ΔH_0 (ndarray, shape (n, n)) – The height profile of the tip surface, expressed as the deviation \(\Delta H\) from a perfect sphere. If not provided, a perfect hemisphere is assumed for the height profile.

  • N_simp (int) – The (approximate) target number of simplices for the detector triangulation. Defaults to 500.

  • maxiter (int) – The maximum number of iterations for the root solver. See also maxiter. Defaults to 100.

  • tol (float) – The maximum absolute relative curvature residual allowed for the reconstruction of the height profile. See also tol. Defaults to 0.01.

  • tri (class) – The custom detector triangulation, as obtained by scipy.spatial.Delaunay(). Defaults to None, i.e. use internal adaptive triangulation. This option may be useful if the internal triangulation fails.

  • verbose (bool) – Whether to print additional information. Defaults to False.

  • debug_plot (bool) – Whether to show debug plots with various information. Defaults to False. Setting this parameter to True is equivalent to calling debug_plot() with the returned results.

Returns:

results – The dictionary containing various results for the reconstruction of the height profile, e.g. the reconstructed height profile and information on the detector triangulation. Use results.keys() to get a complete list of the dictionary content. This dictionary can be passed directly to debug_plot().

Return type:

dict

reconstruct_positions(p_list, N_simp=500, extrapolate=False, tri_list=None, verbose=False)[source]

Reconstruct three-dimensional atomic positions between height profiles.

This method takes a list of reconstructed height profiles, obtained from reconstruct_height_profile(), and iteratively reconstructs the three-dimensional atomic positions between each consecutive pair of height profiles.

The height increment \(\Delta z\) between consecutive height profile pairs is determined such that the total reconstructed volume matches exactly the volume spanned by the triangulated upper and lower height profiles. Each triangulated simplex, corresponding to both height profiles, forms a distorted prism.

The volumes of these distorted prisms are calculated as follows: Consider two simplices, \((A_1, B_1, C_1)\) from the upper profile and \((A_2, B_2, C_2)\) from the lower profile. The lateral surface of this distorted prism is triangulated through the edges \((A_1, B_2)\), \((B_2, C_1)\), and \((C_1, A_2)\).

The volume of the prism can be divided into three tetrahedra:

\[\begin{split}T_1 &= (A_1, B_1, C_1, B_2) \\ T_2 &= (A_2, B_2, C_2, C_1) \\ T_3 &= (A_1, C_1, A_2, B_2).\end{split}\]

The total volume is then calculated as the sum of the volumes of these three tetrahedra.

Note that events outside the detector triangulation are not reconstructed. This method tracks the reconstructed events by setting the mask_reconstruction attribute with corresponding Boolean values, which can then be used as a mask for filtering other properties.

Parameters:

  • p_list (list) – The list of the reconstructed height profiles, as obtained by reconstruct_height_profile().

  • N_simp (int) – The (approximate) target number of simplices for the detector triangulation. Defaults to 500.

  • extrapolate (bool) – Whether to reconstruct the positions extrapolated beyond the first and last height profile.

  • tri_list (list) – The list of custom detector triangulations, as obtained by scipy.spatial.Delaunay(). One triangulation is needed for every reconstruction interval. Defaults to None, i.e. use internal adaptive triangulation. The list may contain None for individual reconstruction intervals to switch between user-provided and internal triangulation. This option may be useful if the internal triangulation fails.

  • verbose (bool) – Whether to print additional information. Defaults to False.

Returns:

xyz – The three-dimensional \(xyz\) tip positions of the \(N\) reconstructed events.

Return type:

ndarray, shape (N, 3)

property ω

Getter for the internal _ω attribute (read-only).

Returns:

ω – The (half) aperture angle (in radians).

Return type:

float