abtem.bloch.utils

Module Contents

Functions

all_positions_have_relative_periodic_pair	Check if all positions have a relative periodic pair.
are_vectors_orthogonal	Check if two vectors are orthogonal within a given tolerance.
auto_detect_centering	Automatically detect the lattice centering of a crystal structure.
calculate_g_vec
calculate_g_vec_length
cell_bounds
check_orthogonality	Check if three vectors are pairwise orthogonal within a given tolerance.
excitation_errors	Calculate excitation errors for a set of reciprocal space vectors.
fast_filter_excitation_errors
filter_reciprocal_space_vectors	Filter reciprocal space vectors based on excitation errors and reflection conditions.
generate_linear_combinations	Generate all possible linear combinations of the given vectors with the given coefficients.
get_reflection_condition	Returns a boolean mask indicating which reflections satisfy the reflection condition based on the given lattice centering.
get_shortest_g_vec_length	Get the length of the shortest reciprocal space vector in the given unit cell.
hkl_strings_to_array
make_hkl_grid
ravel_hkl
reciprocal_cell	Calculate the reciprocal cell of a unit cell.
reciprocal_space_gpts
relative_positions_for_centering	Returns the relative positions for each lattice centering type.
retrieve_structure_factor_values	Convert a raveled array to a 3D array with the shape of the structure factor.
wrapped_is_close

API

abtem.bloch.utils.all_positions_have_relative_periodic_pair(...) → bool

Check if all positions have a relative periodic pair.

Parameters:

• positions (ndarray) – The positions to check.

• relative_positions (ndarray) – The possible relative shifts of each position.

Returns:

True if all positions have a relative periodic pair, False otherwise.

Return type:

bool

abtem.bloch.utils.are_vectors_orthogonal(...) → bool

Check if two vectors are orthogonal within a given tolerance.

Parameters:

• v1 (ndarray) – The first vector.

• v2 (ndarray) – The second vector.

• tol (float) – The tolerance for floating-point comparison.

Returns:

True if the vectors are orthogonal within the given tolerance, False otherwise.

Return type:

bool

abtem.bloch.utils.auto_detect_centering(...) → str

Automatically detect the lattice centering of a crystal structure.

Parameters:

• atoms (Atoms) – The crystal structure.

• centerings_to_check (set, optional) – The centering types to check. If None, all centering types are checked.

Returns:

The detected lattice centering type.

Return type:

str

abtem.bloch.utils.calculate_g_vec(...) → ndarray

abtem.bloch.utils.calculate_g_vec_length(...) → ndarray

abtem.bloch.utils.cell_bounds(...) → ndarray

abtem.bloch.utils.check_orthogonality(...) → bool

Check if three vectors are pairwise orthogonal within a given tolerance.

Parameters:

• vectors (ndarray) – A 2D array where each row is a vector.

• tol (float) – The tolerance for floating-point comparison.

Returns:

True if all pairs of vectors are orthogonal within the given tolerance, False otherwise.

Return type:

bool

abtem.bloch.utils.excitation_errors(...) → ndarray

Calculate excitation errors for a set of reciprocal space vectors.

Parameters:

• g (ndarray) – Reciprocal space vectors [1/Å], as an array of shape (N, 3).

• energy (float) – Electron energy [eV].

• use_wave_eq (bool, optional) – Whether to use the excitation errors derived from the wave equation. Default is False.

Returns:

Excitation errors [1/Å].

Return type:

ndarray

abtem.bloch.utils.fast_filter_excitation_errors(...) → None

abtem.bloch.utils.filter_reciprocal_space_vectors(...) → ndarray

Filter reciprocal space vectors based on excitation errors and reflection conditions.

Parameters:

• hkl (ndarray) – Reciprocal space vectors.

• cell (Cell) – Unit cell.

• energy (float) – Electron energy [eV].

• sg_max (float) – Maximum excitation error [1/Å].

• g_max (float) – Maximum scattering vector length [1/Å].

• centering (str, optional) – Crystal centering must be one of ‘P’, ‘I’, ‘A’, ‘B’, ‘C’ or ‘F’. Default is ‘P’.

• orientation_matrices (ndarray, optional) – Orientation matrices for each crystallographic direction.

Returns:

Mask for the reciprocal space vectors.

Return type:

ndarray

abtem.bloch.utils.generate_linear_combinations(...) → ndarray

Generate all possible linear combinations of the given vectors with the given coefficients.

Parameters:

• vectors (numpy.array) – Array of vectors.

• coefficients (sequence of int) – Coefficients to use in the linear combinations.

• exclude_zero (bool, optional) – Whether to exclude the zero vector from the output.

Returns:

Array of linear combinations.

Return type:

numpy.array

abtem.bloch.utils.get_reflection_condition(...) → ndarray

Returns a boolean mask indicating which reflections satisfy the reflection condition based on the given lattice centering.

Parameters:

• hkl (ndarray) – Array of shape (N, 3) representing the Miller indices of reflections.

• centering (str) – The lattice centering type. Must be one of “P”, “I”, “F”, “A”, “B”, or “C”.

Returns:

Boolean mask indicating which reflections satisfy the reflection condition.

Return type:

ndarray

abtem.bloch.utils.get_shortest_g_vec_length(...) → float

Get the length of the shortest reciprocal space vector in the given unit cell.

Parameters:

cell (Cell) – Unit cell.

Returns:

Length of the shortest reciprocal space vector [1/Å].

Return type:

float

abtem.bloch.utils.hkl_strings_to_array(...) → ndarray

abtem.bloch.utils.make_hkl_grid(...) → ndarray

abtem.bloch.utils.ravel_hkl(...) → ndarray

abtem.bloch.utils.reciprocal_cell(...) → ndarray

Calculate the reciprocal cell of a unit cell.

Parameters:

cell (3x3 numpy.ndarray) – The unit cell.

Returns:

The reciprocal cell.

Return type:

3x3 numpy.ndarray

abtem.bloch.utils.reciprocal_space_gpts(...) → tuple[int, int, int]

abtem.bloch.utils.relative_positions_for_centering() → dict[str, ndarray]

Returns the relative positions for each lattice centering type.

Returns:

A dictionary where the keys are the centering types and the values are the relative positions.

Return type:

dict

abtem.bloch.utils.retrieve_structure_factor_values(...) → ndarray

Convert a raveled array to a 3D array with the shape of the structure factor.

Parameters:

• array (ndarray) – The raveled array.

• hkl_source (ndarray) – The reciprocal space vectors as Miller indices for the source array.

• hkl_destination (ndarray) – The reciprocal space vectors as Miller indices for the destination array.

• gpts (tuple of ints) – The number of grid points in the 3D structure factor.

Returns:

The 3D array.

Return type:

ndarray

abtem.bloch.utils.wrapped_is_close(...)