abtem.potentials.iam

Module for describing electrostatic potentials using the independent atom model.

Module Contents

Classes

BaseField
BasePotential	Base class of all potentials. Documented in the subclasses.
CrystalPotential	The crystal potential may be used to represent a potential consisting of a repeating unit. This may allow calculations to be performed with lower computational cost by calculating the potential unit once and repeating it.
FieldArray
Potential	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.
PotentialArray	The potential array represents slices of the electrostatic potential as an array. All other potentials build potential arrays.
TransmissionFunction	Class to describe transmission functions.

Functions

validate_potential

API

class abtem.potentials.iam.BaseField

Bases: abtem.core.ensemble.Ensemble, abtem.core.grid.HasGrid2DMixin, abtem.core.utils.EqualityMixin, abtem.core.utils.CopyMixin

abstract property base_axes_metadata

property base_shape

Shape of the base axes of the potential.

abstract build(...)

depth_profile(...) → Images

Create a depth profile by projecting the potential along a spatial axis.

Parameters:

• projection_axis (str) – Spatial axis to project (sum) along. "y" (default) produces an x–z cross-section; "x" produces a y–z cross-section.

• depth (float, optional) – If given, project only over a finite slab of this thickness [Å], centered on the midpoint of the projected axis. The number of grid points is rounded to the nearest integer. If None, the full extent is projected.

Returns:

depth_profile – 2D image(s) with the remaining spatial axis horizontal and depth (z) vertical. Any ensemble axes (e.g. frozen phonons) are preserved.

Return type:

Images

abstract 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.

generate_chunked_slices(...)

Generate potential slices in memory-budgeted chunks.

Previously, build() always placed the entire slice dimension into a single dask chunk — meaning the full (num_slices, gpts_y, gpts_x) array had to fit in memory (or VRAM) at once. There was no slice-level chunking. This method introduces that missing middle ground: it eagerly builds a group of contiguous slices that fits within a configurable memory budget, yields it as a PotentialArray, and the caller can discard it after propagation before the next chunk is built. This bounds peak memory and enables simulations of systems whose full potential would not fit in memory.

On GPU this is especially important: dask uses a synchronous scheduler, so the full potential chunk would be materialized at once in VRAM. Chunking over slices keeps VRAM usage bounded while still feeding the GPU enough data per chunk for efficient computation.

This default implementation collects slices from generate_slices() and stacks them. Subclasses may override for more efficient implementations (e.g. _FieldBuilderFromAtoms uses build(first_slice, last_slice) to avoid intermediate single-slice allocations).

Parameters:

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

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

• chunk_size (int or str, optional) – Number of slices per chunk. "auto" selects based on the configured memory budget (dask.chunk-size on CPU, dask.chunk-size-gpu on GPU). Can also be set globally via the potential.slice-chunk-size configuration key.

Yields:

PotentialArray – A chunk of contiguous potential slices with correctly assigned exit planes.

abstract generate_slices(...)

abstract property num_configurations

Number of frozen phonons in the ensemble of potentials.

property num_exit_planes: int

Number of exit planes.

property num_slices: int

Number of projected potential slices.

project() → Images

Sum of the potential slices as an image.

Returns:

projected – The projected potential.

Return type:

Images

show(...)

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.

show_depth_profile(...)

Show a depth cross-section of the potential.

Parameters:

• projection_axis (str) – Spatial axis to project (sum) along. "y" (default) produces an x–z cross-section; "x" produces a y–z cross-section.

• depth (float, optional) – If given, project only over a finite slab of this thickness [Å], centered on the midpoint of the projected axis. The number of grid points is rounded to the nearest integer. If None, the full extent is projected.

• z_scale (float) – Scaling factor for the z-axis relative to the spatial axis. Values less than 1 compress the z-axis, making panels of thick specimens more compact. Default is 1.0 (equal scaling).

• slice_lines (bool) – If True (default), draw horizontal lines at slice boundaries.

• ax (matplotlib.axes.Axes, optional) – If given the plot is added to the axis.

• cbar (bool, optional) – Add a colorbar to the plot. Default is False.

• cmap (str, optional) – Matplotlib colormap name.

• vmin (float, optional) – Minimum of the color scale.

• vmax (float, optional) – Maximum of the color scale.

• power (float) – Show image on a power scale.

• common_color_scale (bool, optional) – If True, all images in a grid share the same color scale.

• explode (bool or sequence of int, optional) – If True, create a grid of images for ensemble items.

• figsize (two int, optional) – Figure size as (width, height) in inches.

• title (bool or str, optional) – Column title for the images.

• **kwargs – Additional keyword arguments passed to the show method.

Returns:

visualization

Return type:

Visualization

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

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

abstract property slice_thickness: tuple[float, ...]

Slice thicknesses for each slice.

property thickness: float

Thickness of the potential [Å].

to_images()

Converts the potential to an ensemble of images.

Returns:

image_ensemble – The potential slices as images.

Return type:

Images

class abtem.potentials.iam.BasePotential

Bases: abtem.potentials.iam.BaseField

Base class of all potentials. Documented in the subclasses.

property base_axes_metadata

List of AxisMetadata for the base axes.

class abtem.potentials.iam.CrystalPotential(...)

Bases: abtem.potentials.iam._PotentialBuilder

The crystal potential may be used to represent a potential consisting of a repeating unit. This may allow calculations to be performed with lower computational cost by calculating the potential unit once and repeating it.

If the repeating unit is a potential with frozen phonons, it is treated as a pool of displaced configurations: every repetition of the unit (each lateral tile of every z-repetition) draws a configuration from the pool. Draws are balanced over the whole crystal, so reuse of a configuration is the minimum the pool size allows – no two tiles within a layer are identical whenever the pool permits, and a pool of at least repetitions[0] * repetitions[1] * repetitions[2] configurations gives every repeated unit a distinct configuration (statistically equivalent to tiling the displaced atoms directly). If num_frozen_phonons is set, an ensemble of crystal potentials is created; each member independently rebuilds its own pool of atomic displacement snapshots (reseeded from that member’s own seed) rather than sharing one fixed pool across the ensemble, so members are genuinely independent thermal realisations – there is no need to size the pool for the ensemble, only for a single crystal (see above).

Parameters:

• potential_unit (BasePotential) – The potential unit to assemble the crystal potential from.

• repetitions (three int) – The repetitions of the potential in x, y and z.

• num_frozen_phonons (int, optional) – Number of crystal realisations in the frozen-phonon ensemble; each realisation independently rebuilds its own pool of atomic displacement snapshots.

• 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.

• seeds (int or sequence of int) – Seed for the random number generator (RNG), or one seed for each RNG in the frozen phonon ensemble.

• ensemble_mean (bool, optional) – If True (default), the mean over the frozen-phonon ensemble is calculated. If False, the individual configurations are returned.

Initialization

property ensemble_axes_metadata: list[AxisMetadata]

property ensemble_mean: bool

property ensemble_shape: tuple[int, ...]

generate_chunked_slices(...)

Generate potential slices in memory-budgeted chunks.

Unlike the base-class implementation, this override builds the unit potential once (not once per chunk) and fills each output chunk array in-place, slice by slice, using xp.tile. This avoids the ~2× peak-memory spike that the base class incurs from accumulating per-slice tiled arrays into a list before concatenating them.

The dtype of the output follows the unit potential’s array dtype, which is set by the abtem precision config key (float32 / float64).

generate_slices(...)

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 numpy.ndarray) – Generator for the array of slices.

get_sliced_atoms() → BaseSlicedAtoms

The atoms of the full crystal grouped into the slices given by the slice thicknesses.

The atoms are reconstructed by tiling the unit potential’s transformed (orthogonalised) atoms by the crystal repetitions. This makes CrystalPotential work with any code path that derives atomic sites from a potential via get_sliced_atoms – e.g. the core-loss EELS driver’s automatic site extraction – without special-casing the repeating-unit structure.

Notes

• Frozen phonons are not displaced. get_transformed_atoms returns the equilibrium (mean) positions, so the returned sites are the un-displaced atomic columns. This is deliberate: a CrystalPotential ensemble draws an independent random unit configuration per z-repetition, so there is no single displaced realisation to return, and atomic-column site identification (the main consumer) wants the equilibrium column positions anyway. This differs from Potential.get_sliced_atoms, which applies the frozen-phonon displacement of its single configuration.

• The result is cached; the tile is non-trivial for large supercells.

Returns:

sliced_atoms

Return type:

BaseSlicedAtoms

property gpts: tuple[int, int] | None

property num_configurations

property num_slices: int

property potential_unit: BasePotential

property repetitions: tuple[int, int, int]

property sampling: tuple[float, float] | None

property seeds

class abtem.potentials.iam.FieldArray(...)

Bases: abtem.potentials.iam.BaseField, abtem.array.ArrayObject

build(...)

depth_profile(...) → Images

Create a depth profile by projecting the potential along a spatial axis.

Parameters:

• projection_axis (str) – Spatial axis to project (sum) along. "y" (default) produces an x–z cross-section; "x" produces a y–z cross-section.

• depth (float, optional) – If given, project only over a finite slab of this thickness [Å], centered on the midpoint of the projected axis. The number of grid points is rounded to the nearest integer. If None, the full extent is projected.

Returns:

depth_profile – 2D image(s) with the remaining spatial axis horizontal and depth (z) vertical.

Return type:

Images

property exit_planes: tuple[int, ...]

generate_chunked_slices(...)

Generate potential slices in memory-budgeted chunks.

For a pre-built PotentialArray the data is already in memory (or backed by a dask array whose single chunk spans all slices). This method yields views into the existing array without any new allocation or copy, so chunking only controls iteration grouping.

Note: if the array is dask-backed, the full potential is still materialized as a single chunk when computed (dask never chunks along the slice axis). To benefit from true memory-bounded slice chunking, pass an unbuilt Potential to the multislice algorithm instead.

Parameters:

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

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

• chunk_size (int or str, optional) – Number of slices per chunk. "auto" selects based on the configured memory budget.

Yields:

PotentialArray – A view into the existing array covering a chunk of slices.

generate_slices(...)

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.

Yields:

slices (generator of numpy.ndarray) – Generator for the array of slices.

property num_configurations

project() → Images

Create a 2D array representing a projected image of the potential(s).

Returns:

images – One or more images of the projected potential(s).

Return type:

Images

property slice_thickness: tuple[float, ...]

tile(...)

Tile the potential.

Parameters:

repetitions (two or three int) – The number of repetitions of the potential along each axis. NOTE: if three integers are given, the last represents the number of repetitions along the z-axis.

Returns:

The tiled potential.

Return type:

PotentialArray object

to_hyperspy(...)

to_images()

Convert slices of the potential to a stack of images.

class abtem.potentials.iam.Potential(...)

Bases: abtem.potentials.iam._FieldBuilderFromAtoms, abtem.potentials.iam.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 or 'auto', optional) – Sampling of the potential in x and y [Å]. Provide either “sampling” or “gpts”. If ‘auto’, the grid points are chosen to be commensurate with the atom positions (closest to a default of 0.05 Å) and, whenever compatible with commensurability, a fast FFT size (all prime factors in {2, 3, 5, 7}); the commensurate grid nearest the target is kept when it is already such a size. Set the configuration option ‘grid.round-to-fast-fft’ to False for the plain commensurate grid. For an AtomsEnsemble with more than one configuration (e.g. an MD trajectory), each configuration is an independent, generally non-commensurate snapshot, so commensurability is not attempted and the target sampling is used directly (rounded up to a fast FFT size).

• slice_thickness (float or sequence of float or 'auto', optional) – Thickness of the potential slices in the propagation direction in [Å] (default is 1 Å). 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. If ‘auto’, slice boundaries are aligned with the crystal planes, with slices merged to stay close to a default of 1.0 Å. As with sampling, this commensurability search is skipped for an AtomsEnsemble with more than one configuration, which uses a uniform 1.0 Å target thickness instead.

• 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.

Initialization

class abtem.potentials.iam.PotentialArray(...)

Bases: abtem.potentials.iam.BasePotential, abtem.potentials.iam.FieldArray

The potential array represents slices of the electrostatic potential as an array. All other potentials build potential arrays.

Parameters:

• array (3D numpy.ndarray) – The array representing the potential slices. The first dimension is the slice index and the last two are the spatial dimensions.

• slice_thickness (float) – The thicknesses of potential slices [Å]. If a float, the thickness is the same for all slices. If a sequence, the length must equal the length of the potential array.

• extent (one or two float, optional) – Lateral extent of the potential [Å].

• sampling (one or two float, optional) – Lateral sampling of the potential [1 / Å].

• 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.

• ensemble_axes_metadata (list of AxesMetadata) – Axis metadata for each ensemble axis. The axis metadata must be compatible with the shape of the array.

• metadata (dict) – A dictionary defining wave function metadata. All items will be added to the metadata of measurements derived from the waves.

Initialization

abstract classmethod from_array_and_metadata(...) → PotentialArray

transmission_function(...) → TransmissionFunction

Calculate the transmission functions for each slice for a specific energy.

Parameters:

energy (float) – Electron energy [eV].

Returns:

transmissionfunction – Transmission functions for each slice.

Return type:

TransmissionFunction

transmit(...) → Waves

Transmit a wave function through a potential slice.

Parameters:

• waves (Waves) – Waves object to transmit.

• conjugate (bool, optional) – If True, use the conjugate of the transmission function. Default is False.

Returns:

transmission_function – Transmission function for the wave function through the potential slice.

Return type:

TransmissionFunction

class abtem.potentials.iam.TransmissionFunction(...)

Bases: abtem.potentials.iam.PotentialArray, abtem.core.energy.HasAcceleratorMixin

Class to describe transmission functions.

Parameters:

• array (3D numpy.ndarray) – The array representing the potential slices. The first dimension is the slice index and the last two are the spatial dimensions.

• slice_thickness (float) – The thicknesses of potential slices [Å]. If a float, the thickness is the same for all slices. If a sequence, the length must equal the length of the potential array.

• extent (one or two float, optional) – Lateral extent of the potential [Å].

• sampling (one or two float, optional) – Lateral sampling of the potential [1 / Å].

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

Initialization

get_chunk(...) → TransmissionFunction

transmission_function(...) → TransmissionFunction

Calculate the transmission functions for each slice for a specific energy.

Parameters:

energy (float) – Electron energy [eV].

Returns:

transmissionfunction – Transmission functions for each slice.

Return type:

TransmissionFunction

transmit(...) → Waves

Transmit a wave function through a potential slice.

Parameters:

• waves (Waves) – Waves object to transmit.

• conjugate (bool, optional) – If True, use the conjugate of the transmission function. Default is False.

Returns:

transmission_function – Transmission function for the wave function through the potential slice.

Return type:

Waves

abtem.potentials.iam.validate_potential(...) → BasePotential