abtem.slicing

Module for slicing atoms for the multislice algorithm.

Module Contents

Classes

BaseSlicedAtoms	Base class for sliced atoms used for grouping each atom in an ASE atoms object into a collection of slices along the z-direction.
SliceIndexedAtoms	Sliced atoms assigning each atom to a specific slice index.
SlicedAtoms	Sliced atoms assigning each atom to multiple slices.

Functions

commensurate_gpts	Find grid points such that the sampling grid is commensurate with the atom positions in x and y, closest to a target sampling.
commensurate_slice_thickness	Find slice thicknesses commensurate with the crystal planes, closest to a target thickness.
crystal_slice_thicknesses	Calculates slice thicknesses to match the spacing between the crystal planes of a given collection of atoms.
is_number	Check if the value is a number, including a NumPy array with a single element, an integer, or a float.
slice_limits	The entrance and exit thicknesses of each slice [Å].

API

class abtem.slicing.BaseSlicedAtoms(...)

Bases: abtem.core.utils.EqualityMixin

Base class for sliced atoms used for grouping each atom in an ASE atoms object into a collection of slices along the z-direction.

Parameters:

• atoms (Atoms) – The atoms to be sliced. Must have an orthgonal cell.

• slice_thickness (float or sequence of float, optional) – Thickness of the potential slices in the propagation direction in [Å] (default is 0.5 Å). If given as a float, the number of slices is calculated by dividing the slice thickness into the z-height of supercell. The slice thickness may be given as a sequence of values for each slice, in which case an error will be thrown if the sum of slice thicknesses is not equal to the height of the atoms.

Initialization

property atoms: ase.Atoms

The Atoms before slicing.

property box: tuple[float, float, float]

The simulation box [Å].

check_slice_idx(...)

Raises an error if index is greater than the number of slices.

generate_atoms_in_slices(...)

Generate atoms in slices.

Parameters:

• first_slice (int, optional) – Index of the first slice of the atoms to return.

• last_slice (int, optional) – Index of the last slice of the atoms to return.

• atomic_number (int, optional) – If given, only atoms with the given atomic number is returned.

Yields:

atoms (Atoms) – The atoms in each slice.

abstract get_atoms_in_slices(...) → ase.Atoms

Get the atoms between two slice indices.

Parameters:

• first_slice (int, optional) – Index of the first slice of the atoms to return.

• last_slice (int, optional) – Index of the last slice of the atoms to return.

• atomic_number (int, optional) – If given, only atoms with the given atomic number is returned.

Returns:

atoms

Return type:

Atoms

property num_slices: int

Number of projected potential slices.

property slice_limits: list[tuple[float, float]]

The entrance and exit thicknesses of each slice [Å].

property slice_thickness: tuple[float, ...]

Slice thicknesses for each slice.

class abtem.slicing.SliceIndexedAtoms(...)

Bases: abtem.slicing.BaseSlicedAtoms

Sliced atoms assigning each atom to a specific slice index.

Parameters:

• atoms (Atoms) – The atoms to be sliced. Must have an orthgonal cell.

• slice_thickness (float or sequence of float, optional) – Thickness of the potential slices in the propagation direction in [Å] (default is 0.5 Å). If given as a float, the number of slices is calculated by dividing the slice thickness into the z-height of supercell. The slice thickness may be given as a sequence of values for each slice, in which case an error will be thrown if the sum of slice thicknesses is not equal to the height of the atoms.

Initialization

get_atoms_in_slices(...) → ase.Atoms

class abtem.slicing.SlicedAtoms(...)

Bases: abtem.slicing.BaseSlicedAtoms

Sliced atoms assigning each atom to multiple slices.

Parameters:

• atoms (Atoms) – The atoms to be sliced. Must have an orthgonal cell.

• slice_thickness (float or sequence of float, optional) – Thickness of the potential slices in the propagation direction in [Å] (default is 0.5 Å). If given as a float, the number of slices is calculated by dividing the slice thickness into the z-height of supercell. The slice thickness may be given as a sequence of values for each slice, in which case an error will be thrown if the sum of slice thicknesses is not equal to the height of the atoms.

• xy_padding (float, optional) – Padding of the atoms in x and y included in each of the slices [Å].

• z_padding (float, optional) – Padding of the atoms along z in each slice included in the slices [Å].

Initialization

get_atoms_in_slices(...) → ase.Atoms

abtem.slicing.commensurate_gpts(...) → tuple[int, int]

Find grid points such that the sampling grid is commensurate with the atom positions in x and y, closest to a target sampling.

For each axis the function identifies the unique atom planes and computes the GCD of the spacings between them. This gives the primitive lattice spacing and therefore the required grid period p (= number of grid points per unit cell of the primitive lattice). The result is invariant under rigid translations of the structure: a crystal that has been centered or otherwise shifted within the cell always yields the same p as the unshifted version.

When round_to_fast_fft is enabled the number of grid points additionally factorizes completely into the primes 2, 3, 5 and 7 whenever that is compatible with commensurability, so FFTs run on fast radix kernels instead of the slow, memory-hungry Bluestein fallback. The multiple of p nearest the target sampling is kept when it is already such a length, and otherwise the next one up – so enabling this never coarsens the grid. If p itself contains a prime factor larger than 7 no multiple of it can be fast, and commensurability takes precedence.

Structures whose internal parameters are irrational (rutile, brookite) have no commensurate grid at all. For those, round_to_fast_fft additionally selects among fast sizes within a few percent of the target the one whose grid the atom planes come closest to sitting on, subject to keeping the grid a multiple of the plane set’s translational period – without which symmetry-equivalent atoms in different unit cells would discretise differently. This is the only case in which the returned grid is not the one closest to target_sampling.

Parameters:

• extent (tuple of float) – Grid extent in x and y [Å].

• positions (ndarray) – Atom positions with shape (N, 3) or (N, 2).

• target_sampling (float) – Target grid sampling [Å].

• tolerance (float) – Tolerance for identifying distinct atom planes [Å].

• round_to_fast_fft (bool) – If True (default), prefer grids that are also fast FFT sizes (all prime factors in {2, 3, 5, 7}). The realized sampling is then never coarser than commensurability alone would give, and at most a few percent finer. Setting this to False reproduces the plain commensurate grid exactly, including for the incommensurate structures above, which then simply take the target size.

Returns:

Number of grid points in x and y.

Return type:

tuple of int

abtem.slicing.commensurate_slice_thickness(...) → tuple[float, ...]

Find slice thicknesses commensurate with the crystal planes, closest to a target thickness.

Unique z-positions (within tolerance) define candidate slice boundaries between 0 and the cell height. Adjacent plane-level slices are merged so that each resulting slice thickness is as close as possible to target_thickness while keeping boundaries aligned with atomic planes.

Parameters:

• atoms (Atoms) – The atoms to be sliced. Must have an orthogonal cell.

• target_thickness (float) – Target slice thickness [Å].

• tolerance (float) – Tolerance for identifying distinct crystal planes [Å].

Returns:

Commensurate slice thicknesses.

Return type:

tuple of float

abtem.slicing.crystal_slice_thicknesses(...) → ndarray

Calculates slice thicknesses to match the spacing between the crystal planes of a given collection of atoms.

Parameters:

• atoms (Atoms) – The atoms to be sliced. Must have an orthogonal cell.

• tolerance (float, optional) – The tolerance between atomic positions in the z-direction

abtem.slicing.is_number(...) → TypeGuard[int | float | ndarray]

Check if the value is a number, including a NumPy array with a single element, an integer, or a float.

Parameters:

value (Any) – The value to check.

Returns:

True if the value is a number, False otherwise.

Return type:

bool

abtem.slicing.slice_limits(...) → list[tuple[float, float]]

The entrance and exit thicknesses of each slice [Å].