abtem.bloch.dynamical

Module Contents

Classes

BaseStructureFactor
BlochWaves	The BlochWaves class represents a set of Bloch waves. It may be used to calculate the dynamical diffraction patterns.
BlochwaveEnsemble
StructureFactor	The StructureFactors class calculates the structure factors for a given set of atoms and parametrization.
StructureFactorArray	The StructureFactorArray class represents structure factors as an ArrayObject.

Functions

allowed_chars	Check if the string s only contains characters from allowed_chars.
calculate_M_matrix	Calculate the M matrix for a given set of reciprocal space vectors.
calculate_dynamical_scattering	Calculate the dynamical scattering given a structure matrix.
calculate_scattering_factors	Calculate the scattering factors for a given set of atoms and parametrization.
calculate_scattering_matrix	Calculate the scattering matrix for a given set of reciprocal space vectors.
calculate_structure_factors	Calculate the structure factors for a given set of atoms and parametrization.
calculate_structure_matrix	Calculate the structure matrix for a given set of reciprocal space vectors.
calculate_wave_functions
equal_slice_thicknesses
exctinction_distances
expm	Calculate the matrix exponential of a given array.
is_base_distribution_tuple
is_rotations_ensemble
is_valid_rotation_axes
is_valid_rotations
plane_wave_basis	Calculate a plane wave basis for a given set of reciprocal space vectors at a set of real space positions.
plane_wave_coefficients
reduce_plane_wave_expansion
slice_potential
structure_factor_1d_to_3d	Convert 1D structure factors to 3D structure factors.
structure_factor_to_potential	Calculate the potential from the structure factors.
validate_g_max	Check if the provided g_max is valid. If g_max is None, it is set to half the g_max of the structure factor.
validate_rotations

Data

AllowedRotations

API

abtem.bloch.dynamical.AllowedRotations

None

class abtem.bloch.dynamical.BaseStructureFactor(...)

Initialization

abstract property cell: ase.cell.Cell

The unit cell.

property centering: str

The lattice centering.

abstract property device: str

property g_max: float

The maximum scattering vector length.

property g_vec: ndarray

The reciprocal space vectors.

property g_vec_length: ndarray

The lengths of the reciprocal space vectors.

abstract get_potential_3d() → ndarray

Calculate the 3D potential from the structure factors.

abstract get_projected_potential(...) → PotentialArray

Calculate the projected potential from the structure factors.

property gpts: tuple[int, int, int]

Number of reciprocal space grid points.

property hkl: ndarray

The reciprocal space vectors as Miller indices.

class abtem.bloch.dynamical.BlochWaves(...)

The BlochWaves class represents a set of Bloch waves. It may be used to calculate the dynamical diffraction patterns.

Parameters:

• structure_factor (StructureFactor) – The structure factor.

• energy (float or list of float) – Electron energy [eV]. A single float runs a standard single-energy calculation. A list or array of floats runs the calculation at each energy, using a union of the allowed reciprocal-space vectors across all energies; beams that are inactive at a given energy are set to zero. The output gains a leading EnergyAxis dimension.

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

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

• orientation_matrix (ndarray) – An optional orientation matrix given as a (3, 3) array. If provided, the unit cell is rotated. Instead of providing an orientation matrix, the .rotate method can be used.

• centering ({'auto', 'P', 'I', 'A', 'B', 'C', 'F'}) – Lattice centering.

• device ({'cpu', 'gpu'}) – Device to use for calculations. Can be ‘cpu’ or ‘gpu’.

• use_wave_eq (bool) – If True, the Bloch wave equation derived from the wave equation is used. Otherwise standard Bloch wave is used.

Initialization

calculate_diffraction_patterns(...) → IndexedDiffractionPatterns

Calculate the dynamical diffraction patterns for a given set of thicknesses.

Parameters:

• thicknesses (float or sequence of floats) – The thicknesses of the sample [Å].

• return_complex (bool) – If True, the complex diffraction patterns are returned. If False, the intensity is returned. Default is False.

• lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

Returns:

The dynamical diffraction patterns.

Return type:

IndexedDiffractionPatterns

calculate_exit_waves(...) → Waves

Calculate the exit waves for a given set of thicknesses.

Parameters:

• thicknesses (float or sequence of floats) – The thicknesses of the sample [Å].

• gpts (tuple of ints) – The grid points of the exit waves.

• extent (tuple of floats) – The extent of the exit waves [Å].

• normalization ({'values', 'amplitude'}) – The normalization of the exit waves. If ‘values’, the exit waves are

• lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

Returns:

The exit waves.

Return type:

Waves

calculate_scattering_matrix(...) → ndarray

Calculate the scattering matrix for a given thickness.

Parameters:

z (float) – The thickness of the sample [Å].

Returns:

The scattering matrix.

Return type:

ndarray

calculate_structure_matrix(...) → ndarray

Calculate the structure matrix.

Parameters:

lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

property cell: ase.cell.Cell

property device: str

property energy: float

excitation_errors() → ndarray

Excitation errors for the Bloch waves.

property g_max: float

property g_vec: ndarray

property g_vec_length: ndarray

get_kinematical_diffraction_pattern(...) → IndexedDiffractionPatterns

Calculate the kinematical diffraction pattern.

Parameters:

excitation_error_sigma (float) – The standard deviation of the excitation errors used for weigting the structure factor intensities [1/Å].

Returns:

The kinematical diffraction pattern.

Return type:

IndexedDiffractionPatterns

property hkl: ndarray

property hkl_mask: ndarray

property num_bloch_waves: int

The number of Bloch waves used.

rotate(...) → BlochWaves | BlochwaveEnsemble

Rotate the unit cell by a given set of Euler angles.

Parameters:

• args (sequence of (str, float)) – The rotation axes and angles. The axes must be given as a string of ‘x’, ‘y’ or ‘z’, representing a sequence of rotation axes.

• degrees (bool) – If True, the angles are given in degrees. Default is False.

Returns:

• BlochWaves – The rotated Bloch waves.

• BlochWavesEnsemble – The rotated Bloch waves ensemble.

property sg_max: float

property structure_factor: BaseStructureFactor

property structure_matrix_nbytes: int

The number of bytes used by the structure matrix.

property use_wave_eq: bool

property wavelength: float

The wavelength of the electrons [Å].

class abtem.bloch.dynamical.BlochwaveEnsemble(...)

Bases: abtem.core.ensemble.Ensemble, abtem.core.utils.CopyMixin

Initialization

property axes: Sequence[str]

calculate_diffraction_patterns(...) → IndexedDiffractionPatterns

Calculate the dynamical diffraction patterns of the ensemble for a given set of thicknesses.

Parameters:

• thicknesses (float or sequence of floats) – The thicknesses of the sample [Å].

• return_complex (bool) – If True, the complex diffraction patterns are returned. If False, the intensity is returned. Default is False.

• lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

• pbar (bool) – If True, a progress bar is shown. Default is None, which means the value is taken from the configuration.

Returns:

The diffraction patterns.

Return type:

IndexedDiffractionPatterns

calculate_exit_waves(...) → Waves

Calculate the exit waves for the ensemble for a given set of thicknesses.

Parameters:

• thicknesses (float or sequence of floats) – The thicknesses of the sample [Å].

• gpts (tuple of ints, optional) – The grid points of the exit waves.

• extent (tuple of floats, optional) – The extent of the exit waves [Å].

• normalization ({'values', 'amplitude'}) – The normalization of the exit waves.

• g_max (float, optional) – Maximum scattering vector length for the plane wave expansion [1/Å].

• lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

• pbar (bool, optional) – If True, a progress bar is shown. Default is None, which means the value is taken from the configuration.

Returns:

The exit waves.

Return type:

Waves

property centering: str

property device: str

property energy: float

property ensemble_axes_metadata: list[AxisMetadata]

property ensemble_shape: tuple[int, ...]

property g_max: float

get_ensemble_hkl_mask() → ndarray

Get the mask selecting all the reciprocal space vectors included in the ensemble.

Returns:

The mask selecting the reciprocal space vectors.

Return type:

ndarray

get_orientation_matrices() → ndarray

Get the orientation matrices for the ensemble.

Returns:

The orientation matrices. The shape is the ensemble shape + (3, 3).

Return type:

ndarray

property rotations: tuple[BaseDistribution | Number, ...]

property sg_max: float

property structure_factor: BaseStructureFactor

property use_degrees: bool

property use_wave_eq: bool

class abtem.bloch.dynamical.StructureFactor(...)

Bases: abtem.bloch.dynamical.BaseStructureFactor, abtem.core.utils.CopyMixin

The StructureFactors class calculates the structure factors for a given set of atoms and parametrization.

Parameters:

• atoms (Atoms) – Atoms object.

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

• parametrization (str) – Parametrization for the scattering factors.

• thermal_sigma (float or dict) – Standard deviation of the atomic displacements for the Debye-Waller factor [Å].

• occupancy (float) – The occupancy of the atoms.

• cutoff ({'taper', 'hard'}) – Cutoff function for the scattering factors. ‘taper’ is a smooth cutoff, ‘hard’ is a hard cutoff.

• device ({'cpu', 'gpu'}) – Device to use for calculations. Can be ‘cpu’ or ‘gpu’.

• centering ({'auto', 'P', 'I', 'A', 'B', 'C', 'F'}) – Lattice centering.

Initialization

property atoms: ase.Atoms

build(...) → StructureFactorArray

Calculate the structure factors to obtain a StructureFactorArray object.

Parameters:

lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

Returns:

The structure factors.

Return type:

StructureFactorArray

calculate_scattering_factors() → ndarray

Calculate the scattering factors for each atomic species in the structure.

property cell: ase.cell.Cell

property device: str

property g_max: float

get_potential_3d(...) → ndarray

Calculate the 3D potential from the structure factors.

Parameters:

lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

Returns:

The 3D potential.

Return type:

ndarray

get_projected_potential(...) → PotentialArray

Calculate the projected potential from the structure factors.

Parameters:

• slice_thickness (float or sequence of floats) – The thickness of the slices.

• sampling (float or tuple of floats) – The sampling of the projected potential [Å].

• gpts (int or tuple of ints) – The grid points of the projected potential.

• lazy (bool) – If True, the calculation is done lazily using dask. If False, the calculation is done eagerly.

Returns:

The projected potential.

Return type:

PotentialArray

property occupancy: ndarray | dict[str, ndarray]

property parametrization: Parametrization

property thermal_sigma: ndarray | dict[str, ndarray]

class abtem.bloch.dynamical.StructureFactorArray(...)

Bases: abtem.array.ArrayObject, abtem.bloch.dynamical.BaseStructureFactor

The StructureFactorArray class represents structure factors as an ArrayObject.

Parameters:

• array (ndarray) – The structure factors as a 1D array.

• hkl (ndarray) – The reciprocal space vectors as Miller indices as a (N, 3) array. N must be the same as the length of the structure factor.

• cell (Cell) – The unit cell.

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

• ensemble_axes_metadata (list of AxisMetadata) – Metadata for the ensemble axes.

• metadata (dict) – Metadata for the ArrayObject.

Initialization

property cell: ase.cell.Cell

abstract classmethod from_array_and_metadata(...) → StructureFactorArray

get_potential_3d() → ndarray

Calculate the 3D potential from the structure factors.

Returns:

The 3D potential.

Return type:

ndarray

get_projected_potential(...) → PotentialArray

Calculate the projected potential from the structure factors.

Parameters:

• slice_thickness (float or sequence of floats) – The thickness of the slices.

• sampling (float or tuple of floats) – The sampling of the projected potential [Å].

• gpts (int or tuple of ints) – The grid points of the projected potential.

• lazy (bool) –

  If True, the calculation is done lazily using dask. If False, the

  calculation is done eagerly.

Returns:

The projected potential.

Return type:

PotentialArray

property gpts: tuple[int, int, int]

Number of reciprocal space grid points for 3D structure factors.

to_3d_array() → ndarray

Convert the 1D structure factors to 3D structure factors.

Returns:

The 3D structure factors.

Return type:

ndarray

to_dict() → dict

Convert the structure factors to a dictionary. The keys are the Miller indices and the values are the structure factors.

abtem.bloch.dynamical.allowed_chars(...) → bool

Check if the string s only contains characters from allowed_chars.

Parameters:

• s (str) – The string to check.

• allowed_chars (str) – A string containing all allowed characters.

Returns:

True if s only contains characters from allowed_chars, False otherwise.

Return type:

bool

abtem.bloch.dynamical.calculate_M_matrix(...) → ndarray

Calculate the M matrix for a given set of reciprocal space vectors.

Parameters:

• hkl (ndarray) – The reciprocal space vectors as Miller indices. Given as a (N, 3) array.

• cell (Cell) – The unit cell.

• energy (float) – The energy of the electrons [eV].

Returns:

The M matrix.

Return type:

ndarray

abtem.bloch.dynamical.calculate_dynamical_scattering(...) → ndarray

Calculate the dynamical scattering given a structure matrix.

Parameters:

• structure_matrix (ndarray) – The structure matrix as a (N, N) array.

• hkl (ndarray) – The reciprocal space vectors as Miller indices. Given as a (N, 3) array.

• cell (Cell) – The unit cell.

• energy (float) – The energy of the electrons [eV].

• thicknesses (sequence of floats) – The thicknesses of the sample [Å].

Returns:

The dynamical scattering as a complex array with shape (len(thicknesses), len(hkl)).

Return type:

ndarray

abtem.bloch.dynamical.calculate_scattering_factors(...) → ndarray

Calculate the scattering factors for a given set of atoms and parametrization.

Parameters:

• g_vec (ndarray) – Scattering vectors [1/Å]. Either Cartesian vectors with shape (N_g, 3), or plain magnitudes with shape (N_g,). Anisotropic Debye-Waller factors require shape (N_g, 3); passing magnitudes with anisotropic sigmas raises an error.

• atoms (Atoms) – Atoms object.

• g_max (float) – Maximum scattering vector length [1/Å]. The scattering factors are set to zero for g > g_max.

• parametrization ({'lobato', 'kirkland', 'peng'}) – Parametrization for the scattering factors.

• thermal_sigma (dict) – Standard deviation of the atomic displacements for the Debye-Waller factor [Å]. For anisotropic displacements, provide three values per atom or element (σx, σy, σz).

• cutoff ({'taper', 'hard'}) – Cutoff function for the scattering factors. ‘taper’ is a smooth cutoff, ‘hard’ is a hard cutoff.

abtem.bloch.dynamical.calculate_scattering_matrix(...) → ndarray

Calculate the scattering matrix for a given set of reciprocal space vectors.

Parameters:

• A (ndarray) – The structure matrix. The last two dimensions must be square.

• hkl (ndarray) – The reciprocal space vectors as Miller indices. Given as a (N, 3) array.

• cell (Cell) – The unit cell.

• z (float) – The thickness of the sample [Å].

• energy (float) – The energy of the electrons [eV].

• method ({'expm', 'decomposition'}) –

  The method to use for calculating the scattering matrix.

  expm :

  Use a matrix exponential.

  decomposition :

  Use a Hermitian matrix eigendecomposition.

Returns:

The scattering matrix.

Return type:

ndarray

abtem.bloch.dynamical.calculate_structure_factors(...) → ndarray

Calculate the structure factors for a given set of atoms and parametrization.

Parameters:

• hkl (ndarray) – The reciprocal space vectors as Miller indices. Given as a (N, 3) array.

• atoms (Atoms) – The Atoms object.

• parametrization ({'lobato', 'kirkland', 'peng'}) – Parametrization for the scattering factors.

• g_max (float) – Maximum scattering vector length [1/Å]. The scattering factors are set to zero for g > g_max.

• thermal_sigma (float) – Standard deviation of the atomic displacements for the Debye-Waller factor [Å].

• cutoff ({'taper', 'hard'}) – Cutoff function for the scattering factors. ‘taper’ is a smooth cutoff, ‘hard’ is a hard cutoff.

• device ({'cpu', 'gpu'}) – Device to use for calculations. Can be ‘cpu’ or ‘gpu’.

Returns:

The structure factors.

Return type:

ndarray

abtem.bloch.dynamical.calculate_structure_matrix(...) → ndarray

Calculate the structure matrix for a given set of reciprocal space vectors.

Parameters:

• structure_factor (ndarray) – The structure factors as a 1D array.

• hkl (ndarray) – The reciprocal space vectors as Miller indices corresponding to the structure factors. Given as a (N, 3) array.

• hkl_selected (ndarray) – The reciprocal space vectors as Miller indices for which the structure matrix is calculated. Given as a (N, 3) array.

• cell (Cell) – The unit cell.

• energy (float) – The energy of the electrons [eV].

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

• use_wave_eq (bool) – If True, the Bloch wave equation derived from the wave equation is used. Otherwise standard Bloch wave is used.

Returns:

The structure matrix.

Return type:

ndarray

abtem.bloch.dynamical.calculate_wave_functions(...)

abtem.bloch.dynamical.equal_slice_thicknesses(...) → tuple[tuple[float, ...], tuple[int, ...]]

abtem.bloch.dynamical.exctinction_distances(...) → ndarray

abtem.bloch.dynamical.expm(...) → ndarray

Calculate the matrix exponential of a given array.

This is a device agnostic version of the scipy.linalg.expm function.

Parameters:

A (ndarray) – Input with last two dimensions are square.

Returns:

The resulting matrix exponential with the same shape of A.

Return type:

ndarray

abtem.bloch.dynamical.is_base_distribution_tuple(...) → TypeGuard[tuple[BaseDistribution, ...]]

abtem.bloch.dynamical.is_rotations_ensemble(...) → bool

abtem.bloch.dynamical.is_valid_rotation_axes(...) → TypeGuard[tuple[str, ...]]

abtem.bloch.dynamical.is_valid_rotations(...) → TypeGuard[tuple[abtem.bloch.dynamical.AllowedRotations, ...]]

abtem.bloch.dynamical.plane_wave_basis(...) → ndarray

Calculate a plane wave basis for a given set of reciprocal space vectors at a set of real space positions.

Parameters:

• g (ndarray) – The reciprocal space vectors as an Nx3 array [1 / Å].

• x (ndarray) – The x positions as a 1D array [Å].

• y (ndarray) – The y positions as a 1D array [Å].

• z (ndarray) – The z positions as a 1D array [Å].

Returns:

The plane wave basis at the given positions.

Return type:

ndarray

abtem.bloch.dynamical.plane_wave_coefficients(...) → ndarray

abtem.bloch.dynamical.reduce_plane_wave_expansion(...)

abtem.bloch.dynamical.slice_potential(...) → tuple[ndarray, ndarray]

abtem.bloch.dynamical.structure_factor_1d_to_3d(...) → ndarray

Convert 1D structure factors to 3D structure factors.

Parameters:

• structure_factor (ndarray) – The structure factors as a 1D array.

• hkl (ndarray) – The reciprocal space vectors as Miller indices as a (N, 3) array. N must be the same as the length of the structure factor.

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

Returns:

The 3D structure factors.

Return type:

ndarray

abtem.bloch.dynamical.structure_factor_to_potential(...) → ndarray

Calculate the potential from the structure factors.

Parameters:

• structure_factor (ndarray) – The structure factors as a 1D array.

• hkl (ndarray) – The reciprocal space vectors as Miller indices as a (N, 3) array. N must be the same as the length of the structure factor.

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

Returns:

The potential.

Return type:

ndarray

abtem.bloch.dynamical.validate_g_max(...) → float

Check if the provided g_max is valid. If g_max is None, it is set to half the g_max of the structure factor.

Parameters:

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

• structure_factor (BaseStructureFactor) – The structure factor.

Returns:

The validated g_max.

Return type:

float

abtem.bloch.dynamical.validate_rotations(...) → tuple[tuple[str, ...], tuple[abtem.bloch.dynamical.AllowedRotations, ...]]