Potential#
- class abtem.potentials.iam.Potential(atoms=None, gpts=None, sampling=None, slice_thickness=1, parametrization='lobato', projection='infinite', exit_planes=None, plane='xy', origin=(0.0, 0.0, 0.0), box=None, periodic=True, integrator=None, device=None)[source]#
Bases:
_FieldBuilderFromAtoms
,BasePotential
Calculate the electrostatic potential of a set of atoms or frozen phonon configurations. The potential is calculated with the Independent Atom Model (IAM) using a user-defined parametrization of the atomic potentials.
- Parameters:
atoms (ase.Atoms or abtem.FrozenPhonons) – Atoms or FrozenPhonons defining the atomic configuration(s) used in the independent atom model for calculating the electrostatic potential(s).
gpts (one or two int, optional) – Number of grid points in x and y describing each slice of the potential. Provide either “sampling” (spacing between consecutive grid points) or “gpts” (total number of grid points).
sampling (one or two float, optional) – Sampling of the potential in x and y [1 / Å]. Provide either “sampling” or “gpts”.
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.
parametrization ('lobato' or 'kirkland', optional) – The potential parametrization describes the radial dependence of the potential for each element. Two of the most accurate parametrizations are available (by Lobato et al. and Kirkland; default is ‘lobato’). See the citation guide for references.
projection ('finite' or 'infinite', optional) – If ‘finite’ the 3D potential is numerically integrated between the slice boundaries. If ‘infinite’ (default), the infinite potential projection of each atom will be assigned to a single slice.
exit_planes (int or tuple of int, optional) – The exit_planes argument can be used to calculate thickness series. Providing exit_planes as a tuple of int indicates that the tuple contains the slice indices after which an exit plane is desired, and hence during a multislice simulation a measurement is created. If exit_planes is an integer a measurement will be collected every exit_planes number of slices.
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 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.
periodic (bool, True) – If a transformation of the atomic structure is required, periodic determines how the atomic structure is transformed. If True, the periodicity of the Atoms is preserved, which may require applying a small affine transformation to the atoms. If False, the transformed potential is effectively cut out of a larger repeated potential, which may not preserve periodicity.
integrator (ProjectionIntegrator, optional) – Provide a custom integrator for the projection integrals of the potential slicing.
device (str, optional) – The device used for calculating the potential, ‘cpu’ or ‘gpu’. The default is determined by the user configuration file.
- __init__(atoms=None, gpts=None, sampling=None, slice_thickness=1, parametrization='lobato', projection='infinite', exit_planes=None, plane='xy', origin=(0.0, 0.0, 0.0), box=None, periodic=True, integrator=None, device=None)[source]#
Methods
__init__
([atoms, gpts, sampling, ...])build
([first_slice, last_slice, max_batch, lazy])Build the potential.
copy
()Make a copy.
ensemble_blocks
([chunks])Split the ensemble into an array of smaller ensembles.
generate_blocks
([chunks])Generate chunks of the ensemble.
generate_slices
([first_slice, last_slice, ...])Generate the slices for the potential.
The atoms grouped into the slices given by the slice thicknesses.
The atoms used in the multislice algorithm, transformed to the given plane, origin and box.
match_grid
(other[, check_match])Match the grid to another object with a Grid.
project
()Sum of the potential slices as an image.
select_block
(index, chunks)Select a block from the ensemble.
show
([project])Show the potential projection.
Converts the potential to an ensemble of images.
Attributes
List of AxisMetadata.
List of AxisMetadata for the base axes.
Shape of the base axes of the potential.
The extent of the potential in x, y and z.
The device where the potential is created.
List of AxisMetadata of the ensemble axes.
Shape of the ensemble axes.
The "exit planes" of the potential.
The "exit thicknesses" of the potential.
Extent of grid for each dimension in Ångstrom.
Ensemble of atomic configurations representing frozen phonons.
Number of grid points for each dimension.
Simulation grid.
The integrator determining how the projection integrals for each slice is calculated.
Size of the ensemble of atomic configurations representing frozen phonons.
Number of exit planes.
Number of projected potential slices.
The origin relative to the provided atoms mapped to the origin of the potential.
Specifies whether the potential is periodic.
The plane relative to the atoms mapped to xy plane of the potential, i.e. the plane is perpendicular to the propagation direction.
Reciprocal-space sampling in reciprocal Ångstrom.
Grid sampling for each dimension in Ångstrom per grid point.
Shape of the ensemble.
The entrance and exit thicknesses of each slice [Å].
Slice thicknesses for each slice.
Thickness of the potential [Å].
- property axes_metadata: AxesMetadataList#
List of AxisMetadata.
- property base_axes_metadata#
List of AxisMetadata for the base axes.
- property base_shape#
Shape of the base axes of the potential.
- property box: tuple[float, float, float]#
The extent of the potential in x, y and z.
- build(first_slice=0, last_slice=None, max_batch=1, lazy=None)#
Build the potential.
- Parameters:
first_slice (int, optional) – Index of the first slice of the generated potential.
last_slice (int, optional) – Index of the last slice of the generated potential
max_batch (int or str, optional) – Maximum number of slices to calculate in task. Default is 1.
lazy (bool, optional) – If True, create the wave functions lazily, otherwise, calculate instantly. If None, this defaults to the value set in the configuration file.
- Returns:
potential_array – The built potential as an array.
- Return type:
- copy()#
Make a copy.
- property device: str#
The device where the potential is created.
- property ensemble_axes_metadata#
List of AxisMetadata of the ensemble axes.
- ensemble_blocks(chunks=None)#
Split the ensemble into an array of smaller ensembles.
- Parameters:
chunks (iterable of tuples) – Block sizes along each dimension.
- Return type:
Array
- property ensemble_shape: tuple[int, ...]#
Shape of the ensemble axes.
- property exit_planes: tuple[int]#
The “exit planes” of the potential. The indices of slices where a measurement is returned.
- property exit_thicknesses: tuple[float]#
The “exit thicknesses” of the potential. The thicknesses in the potential where a measurement is returned.
- property extent: tuple[float] | tuple[float, float] | tuple[float, ...]#
Extent of grid for each dimension in Ångstrom.
- property frozen_phonons: BaseFrozenPhonons#
Ensemble of atomic configurations representing frozen phonons.
- generate_blocks(chunks=1)#
Generate chunks of the ensemble.
- Parameters:
chunks (iterable of tuples) – Block sizes along each dimension.
- generate_slices(first_slice=0, last_slice=None, return_depth=False)#
Generate the slices for the potential.
- Parameters:
first_slice (int, optional) – Index of the first slice of the generated potential.
last_slice (int, optional) – Index of the last slice of the generated potential.
return_depth (bool) – If True, return the depth of each generated slice.
- Yields:
slices (generator of np.ndarray) – Generator for the array of slices.
- get_sliced_atoms()#
The atoms grouped into the slices given by the slice thicknesses.
- Returns:
sliced_atoms
- Return type:
BaseSlicedAtoms
- get_transformed_atoms()#
The atoms used in the multislice algorithm, transformed to the given plane, origin and box.
- Returns:
transformed_atoms – Transformed atoms.
- Return type:
Atoms
- property gpts: tuple[int] | tuple[int, int] | tuple[int, ...]#
Number of grid points for each dimension.
- property grid: Grid#
Simulation grid.
- property integrator#
The integrator determining how the projection integrals for each slice is calculated.
- match_grid(other, check_match=False)#
Match the grid to another object with a Grid.
- property num_configurations: int#
Size of the ensemble of atomic configurations representing frozen phonons.
- property num_exit_planes: int#
Number of exit planes.
- property num_slices: int#
Number of projected potential slices.
- property origin: tuple[float, float, float]#
The origin relative to the provided atoms mapped to the origin of the potential.
- property periodic: bool#
Specifies whether the potential is periodic.
- property plane: str#
The plane relative to the atoms mapped to xy plane of the potential, i.e. the plane is perpendicular to the propagation direction.
- project()#
Sum of the potential slices as an image.
- Returns:
projected – The projected potential.
- Return type:
- property reciprocal_space_sampling: tuple[float] | tuple[float, float] | tuple[float, ...]#
Reciprocal-space sampling in reciprocal Ångstrom.
- property sampling: tuple[float] | tuple[float, float] | tuple[float, ...]#
Grid sampling for each dimension in Ångstrom per grid point.
- select_block(index, chunks)#
Select a block from the ensemble.
- Parameters:
index (tuple of ints) – Index of selected block.
chunks (iterable of tuples) – Block sizes along each dimension.
- property shape#
Shape of the ensemble.
- show(project=True, **kwargs)#
Show the potential projection. This requires building all potential slices.
- Parameters:
project (bool, optional) – Show the projected potential (True, default) or show all potential slices. It is recommended to index a subset of the potential slices when this keyword set to False.
kwargs – Additional keyword arguments for the show method of
Images
.
- 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.
- property thickness: float#
Thickness of the potential [Å].