abtem.atoms

Module for modifying ASE Atoms objects for use in abTEM.

Module Contents

Functions

B_to_sigma	Convert crystallographic B-factor to displacement standard deviation.
atom_property_dict_to_atom_property_array
atoms_in_cell	Crop atoms outside the cell.
best_orthogonal_cell	Find the closest orthogonal cell for a given cell given a maximum number of repetitions in all directions.
cut_cell	Fit the given atoms into a given cell by cropping atoms that are outside the cell, ignoring periodicity. If the given atoms do not originally fill the cell, they are first repeated until they do.
decompose_affine_transform	Decompose an affine transform into rotation, scale and shear.
euler_sequence	param axes: Specifies the order of rotation axes. It should be a string representing a valid combination of the letters ‘x’, ‘y’, and ‘z’ in any order. For example, ‘xyz’ represents a sequence of rotations about the x-axis, y-axis, and z-axis in that order. type axes: str param convention: Specifies the convention used for the Euler angles. It should be either ‘intrinsic’ or ‘static’ for rotations applied to a fixed frame or ‘extrinsic’ or ‘rotating’ for rotations applied to a rotating frame. type convention: str returns: A tuple of four angles (theta1, theta2, theta3, phi) representing the Euler sequence specified by the given axes and convention. rtype: tuple raises ValueError: If the given convention is not one of the valid options (‘intrinsic’, ‘static’, ‘extrinsic’, ‘rotating’).
euler_to_rotation	Convert sequence of Euler angles to Cartesian rotation matrix.
flip_atoms	Inverts the positions of atoms along a given axis.
is_cell_hexagonal	Check whether the cell of given atoms is hexagonal.
is_cell_orthogonal	Check whether atoms have an orthogonal cell.
is_cell_valid	Check whether the cell of given atoms can be converted to a structure usable by abTEM.
merge_close_atoms	Merge atoms that are closer in distance to each other than the given tolerance.
orthogonalize_cell	Make the cell of the given atoms orthogonal. This is accomplished by repeating the cell until lattice vectors are close to the three principal Cartesian directions. If the structure is not exactly orthogonal after the structure is repeated by a given maximum number, the remaining difference is made up by applying strain.
pad_atoms	Repeat the atoms in the x and y directions, retaining only the repeated atoms within the margin distance from the cell boundary.
plane_to_axes	Convert string representation of Cartesian axes to numerical.
pretty_print_transform	Print a decomposed transformation in an easy-to-read manner.
rotate_atoms	Rotate the positions and cell vectors of atoms using Euler angles.
rotate_atoms_to_plane	Rotate atoms so that their xy plane is rotated into a given plane.
rotation_matrix_from_plane	Give the rotation matrix corresponding to a rotation from a given plane to the xy plane.
rotation_matrix_to_euler	Convert a Cartesian rotation matrix to Euler angles.
shrink_cell	Find and return the smallest non-repeating cell for the given atoms.
sigma_to_B	Convert displacement standard deviation to crystallographic B-factor.
standardize_cell	Standardize the cell of given atoms. The atoms are rotated so that one of the lattice vectors in the xy-plane is aligned with the x-axis, and then all the lattice vectors are made positive.
validate_per_atom_property	Validate and normalise a per-atom scalar or vector property.
validate_sigmas	Validate displacement standard deviations and detect anisotropy.
wrap_with_tolerance	Wrap atoms that are closer to cell boundaries than the given tolerance.

Data

AtomProperties
axis_mapping

API

abtem.atoms.AtomProperties

None

abtem.atoms.B_to_sigma(...) → float | ndarray

Convert crystallographic B-factor to displacement standard deviation.

The r.m.s. displacement sigma is related to the B-factor by σ = sqrt(B / (8π²)).

Parameters:

B (float or ndarray) – B-factor [Ų]. Accepts scalars, (3,) arrays for anisotropic displacements, or any broadcastable shape.

Returns:

Displacement standard deviation [Å].

Return type:

float or ndarray

abtem.atoms.atom_property_dict_to_atom_property_array(...) → ndarray

abtem.atoms.atoms_in_cell(...) → ase.Atoms

Crop atoms outside the cell.

Parameters:

• atoms (ase.Atoms) – Atoms to be cropped.

• margin (float or tuple of three floats) – Atoms that are outside the cell by this margin are not cropped (by default no margin).

Returns:

cropped – Cropped atoms.

Return type:

ase.Atoms

abtem.atoms.axis_mapping

None

abtem.atoms.best_orthogonal_cell(...) → ndarray

Find the closest orthogonal cell for a given cell given a maximum number of repetitions in all directions.

Parameters:

• cell (ndarray) – Cell of dimensions 3x3.

• max_repetitions (int) – Maximum number of allowed repetitions (default is 5).

• eps (float) – Lattice vector components below this value are considered to be zero.

Returns:

cell – Closest orthogonal cell found.

Return type:

ndarray

abtem.atoms.cut_cell(...) → ase.Atoms

Fit the given atoms into a given cell by cropping atoms that are outside the cell, ignoring periodicity. If the given atoms do not originally fill the cell, they are first repeated until they do.

Parameters:

• atoms (ase.Atoms) – Atoms to be fit.

• cell (tuple of floats) – Cell to be fit into.

• plane (str or tuple of tuples) – Plane to be rotated into given as either a string or two tuples (by default xy which results in no rotation for a standardized cell).

• origin (tuple of floats) – Offset of the origin for the given cell with respect to the original cell.

• margin (float or tuple of three floats) – Atoms that are outside the cell by this margin are not cropped (by default no margin).

Returns:

cut – Atoms fit into the cell.

Return type:

ase.Atoms

abtem.atoms.decompose_affine_transform(...) → tuple[ndarray, ndarray, ndarray]

Decompose an affine transform into rotation, scale and shear.

Parameters:

affine_transform (ndarray) – Matrix representation of an affine transformation of dimension 3x3.

Returns:

decomposition – Decomposition of the affine transformation into a tuple of length 3 whose items are arrays of dimension 3 representing rotation, scale and shear.

Return type:

{(3,), (3,), (3,)} tuple

abtem.atoms.euler_sequence(...) → tuple[int, int, int, int]

Parameters:

• axes (str) – Specifies the order of rotation axes. It should be a string representing a valid combination of the letters ‘x’, ‘y’, and ‘z’ in any order. For example, ‘xyz’ represents a sequence of rotations about the x-axis, y-axis, and z-axis in that order.

• convention (str) – Specifies the convention used for the Euler angles. It should be either ‘intrinsic’ or ‘static’ for rotations applied to a fixed frame or ‘extrinsic’ or ‘rotating’ for rotations applied to a rotating frame.

Returns:

A tuple of four angles (theta1, theta2, theta3, phi) representing the Euler sequence specified by the given axes and convention.

Return type:

tuple

Raises:

ValueError – If the given convention is not one of the valid options (‘intrinsic’, ‘static’, ‘extrinsic’, ‘rotating’).

abtem.atoms.euler_to_rotation(...) → ndarray

Convert sequence of Euler angles to Cartesian rotation matrix.

Parameters:

• ai (float) – First Euler angle [rad].

• aj (float) – Second Euler angle [rad].

• ak (float) – Third Euler angle [rad].

• axes (str, optional) – String representation of the axes of rotation. Default is “xyz”.

• convention (str, optional) – Convention for rotation order. Default is “intrinsic”.

Returns:

R – 3x3 rotation matrix

Return type:

ndarray

abtem.atoms.flip_atoms(...) → ase.Atoms

Inverts the positions of atoms along a given axis.

Parameters:

• atoms (ase.Atoms) – Atoms to be inverted.

• axis (int) – Integer representing the Cartesian axis (0 is x, 1 is y, and the default 2 is z).

Returns:

atoms – Inverted atoms.

Return type:

ase.Atoms

abtem.atoms.is_cell_hexagonal(...) → bool

Check whether the cell of given atoms is hexagonal.

Parameters:

atoms (ase.Atoms) – The atoms that should be checked.

Returns:

hexagonal – True if cell is hexagonal.

Return type:

bool

abtem.atoms.is_cell_orthogonal(...)

Check whether atoms have an orthogonal cell.

Parameters:

• cell (ase.Atoms) – The atoms that should be checked.

• tol (float) – Components of the lattice vectors below this value are considered to be zero.

Returns:

orthogonal – True if cell is orthogonal.

Return type:

bool

abtem.atoms.is_cell_valid(...) → bool

Check whether the cell of given atoms can be converted to a structure usable by abTEM.

Parameters:

• atoms (ase.Atoms) – The atoms that should be checked.

• tol (float) – Components of the lattice vectors whose magnitude is below this value are considered to be zero.

Returns:

valid – True if the atomic structure is usable by abTEM.

Return type:

bool

abtem.atoms.merge_close_atoms(...) → ase.Atoms

Merge atoms that are closer in distance to each other than the given tolerance.

Parameters:

• atoms (ase.Atoms) – Atoms to merge.

• tol (float) – Atoms closer to each other than this value are merged if they have identical atomic numbers.

Returns:

merged_atoms – Merged atoms.

Return type:

ase.Atoms

abtem.atoms.orthogonalize_cell(...)

Make the cell of the given atoms orthogonal. This is accomplished by repeating the cell until lattice vectors are close to the three principal Cartesian directions. If the structure is not exactly orthogonal after the structure is repeated by a given maximum number, the remaining difference is made up by applying strain.

Parameters:

• atoms (ase.Atoms) – The non-orthogonal atoms.

• max_repetitions (int) – The maximum number of repetitions allowed. Increase this to allow more repetitions and hence less strain.

• return_transform (bool) – If true, return the transformations that were applied to make the atoms orthogonal.

• allow_transform (bool) – If false no transformation is applied to make the cell orthogonal, hence a non-orthogonal cell may be returned.

• plane (str or two tuples of three float, optional) – The plane relative to the provided atoms mapped to xy plane of the potential, i.e. provided plane is perpendicular to the propagation direction. If given as a string, it must be a concatenation of two of x, y and z; the default value ‘xy’ indicates that potential slices are cuts along the xy-plane of the atoms. The plane may also be specified with two arbitrary 3D vectors, which are mapped to the x and y directions of the potential, respectively. The length of the vectors has no influence. If the vectors are not perpendicular, the second vector is rotated in the plane to become perpendicular to the first. Providing a value of ((1., 0., 0.), (0., 1., 0.)) is equivalent to providing ‘xy’.

• plane – The plane relative to the provided atoms mapped to xy plane of the potential, i.e. provided plane is perpendicular to the propagation direction. If given as a string, it must be a concatenation of two of x, y and z; the default value ‘xy’ indicates that potential slices are cuts along the xy-plane of the atoms. The plane may also be specified with two arbitrary 3D vectors, which are mapped to the x and y directions of the potential, respectively. The length of the vectors has no influence. If the vectors are not perpendicular, the second vector is rotated in the plane to become perpendicular to the first. Providing a value of ((1., 0., 0.), (0., 1., 0.)) is equivalent to providing ‘xy’.

• origin (three float, optional) – The origin relative to the provided atoms mapped to the origin of the potential. This is equivalent to translating the atoms. The default is (0., 0., 0.).

• box (three float, optional) – The extent of the potential in x, y and z. If not given this is determined from the atoms’ cell. If the box size does not match an integer number of the atoms’ supercell, an affine transformation may be necessary to preserve periodicity, determined by the periodic keyword.

• tolerance (float) – Determines what is defined as a plane. All atoms within a distance equal to tolerance [Å] from a given plane will be considered to belong to that plane.

Returns:

• atoms (ase.Atoms) – The orthogonal atoms.

• transform (tuple of arrays, optional) – The applied transform given as Euler angles (by default not returned).

abtem.atoms.pad_atoms(...) → ase.Atoms

Repeat the atoms in the x and y directions, retaining only the repeated atoms within the margin distance from the cell boundary.

Parameters:

• atoms (ase.Atoms) – The atoms that should be padded.

• margins (one or tuple of three floats) – The padding margin. Can be specified either as a single value for all directions, or three separate values.

• directions (str) – The directions to pad the atoms as a concatenation of one or more of x, y and z for each of the principal directions.

Returns:

padded – Padded atoms.

Return type:

ase.Atoms

abtem.atoms.plane_to_axes(...) → tuple[int, ...]

Convert string representation of Cartesian axes to numerical.

Parameters:

plane (str) – String representation of axes.

Returns:

axes – Numerical representation of axes.

Return type:

tuple

abtem.atoms.pretty_print_transform(...)

Print a decomposed transformation in an easy-to-read manner.

Parameters:

decomposed (tuple of ndarray) – Tuple of length 3 whose items are arrays of dimension 3 representing rotation, scale and shear.

abtem.atoms.rotate_atoms(...) → ase.Atoms

Rotate the positions and cell vectors of atoms using Euler angles.

Parameters:

• atoms (Atoms) – The atoms object to rotate.

• axes (str, optional) – The sequence of axes for rotation. Default is “zxz”.

• angles (tuple[float, float, float], optional) – The Euler angles in radians. Default is (0.0, 0.0, 0.0).

• convention (str, optional) – The convention for Euler angles. Default is “intrinsic”.

Returns:

The rotated atoms object.

Return type:

Atoms

abtem.atoms.rotate_atoms_to_plane(...) → ase.Atoms

Rotate atoms so that their xy plane is rotated into a given plane.

Parameters:

• atoms (ASE Atoms objet) – Atoms to be rotated.

• plane (str or tuple of tuple) – Plane to be rotated into given as either a string or two tuples.

Returns:

rotated – Rotated atoms.

Return type:

ase.Atoms

abtem.atoms.rotation_matrix_from_plane(...) → ndarray

Give the rotation matrix corresponding to a rotation from a given plane to the xy plane.

Parameters:

plane (str or tuple of tuple) – Plane from which to rotate given either as a string or two tuples.

Returns:

rotation – Rotation matrix of dimension 3x3.

Return type:

ndarray

abtem.atoms.rotation_matrix_to_euler(...) → tuple[float, float, float]

Convert a Cartesian rotation matrix to Euler angles.

Parameters:

• R (ndarray) – Rotation array of dimension 3x3.

• axes (str) – String representation of Cartesian axes.

• convention (str, optional) – Convention for rotation order. Default is “intrinsic”.

• eps (float) – Components of the rotation matrix whose magnitude is below this value are ignored.

Returns:

angles – Euler angles corresponding to the given rotation matrix.

Return type:

tuple

abtem.atoms.shrink_cell(...) → ase.Atoms

Find and return the smallest non-repeating cell for the given atoms.

Parameters:

• atoms (ase.Atoms) – Atoms whose repetition is to be removed.

• repetitions (tuple) – Integer number of repetitions in x and y directions to be checked.

• tol (float) – Repetitions with a mismatch smaller than this value are considered to be repeated.

Returns:

atoms – Smallest non-repeating cell for the given atoms.

Return type:

ase.Atoms

abtem.atoms.sigma_to_B(...) → float | ndarray

Convert displacement standard deviation to crystallographic B-factor.

The B-factor (also called the Debye-Waller factor or temperature factor) is related to the r.m.s. displacement sigma by B = 8π²σ².

Parameters:

sigma (float or ndarray) – Displacement standard deviation [Å]. Accepts scalars, (3,) arrays for anisotropic displacements (Bx, By, Bz), or any broadcastable shape.

Returns:

B-factor [Ų].

Return type:

float or ndarray

abtem.atoms.standardize_cell(...) → ase.Atoms

Standardize the cell of given atoms. The atoms are rotated so that one of the lattice vectors in the xy-plane is aligned with the x-axis, and then all the lattice vectors are made positive.

Parameters:

• atoms (ase.Atoms) – The atoms that should be standardized.

• tol (float) – Components of the lattice vectors whose magnitude is below this value are considered to be zero.

Returns:

atoms – The standardized atoms.

Return type:

ase.Atoms

abtem.atoms.validate_per_atom_property(...) → ndarray | dict[str, ndarray]

Validate and normalise a per-atom scalar or vector property.

Parameters:

• atoms (Atoms)

• props (float, dict, or array-like) – A single value for all atoms, a dict keyed by symbol or atomic number, or a sequence with one entry per atom.

• return_array (bool) – If True, always return a flat ndarray rather than a dict.

abtem.atoms.validate_sigmas(...) → tuple[ndarray | dict[str, ndarray], bool]

Validate displacement standard deviations and detect anisotropy.

Parameters:

• atoms (Atoms)

• sigmas (AtomProperties) – Isotropic: a single float, per-element dict of floats, or length-N array. Anisotropic: a 3-tuple of floats (identical for all atoms), a per-element dict of 3-tuples/arrays, or an (N, 3) array.

• return_array (bool) – If True, always return a flat ndarray rather than a dict.

Returns:

• validated_sigmas (ndarray or dict)

• anisotropic (bool)

abtem.atoms.wrap_with_tolerance(...) → ase.Atoms

Wrap atoms that are closer to cell boundaries than the given tolerance.

Parameters:

• atoms (ase.Atoms) – Atoms to be wrapped.

• tol (float) – Minimum distance to any cell boundary.

Returns:

atoms – Wrapped atoms.

Return type:

ase.Atoms