Waves and scattering matrices¶
Module to describe electron waves and their propagation.

class
abtem.waves.
FresnelPropagator
[source]¶ Fresnel propagator object.
This class is used for propagating a wave function object using the nearfield approximation (Fresnel diffraction). The array representing the Fresnel propagator function is cached.

propagate
(waves, dz, in_place=True)[source]¶ Propagate wave functions or scattering matrix.
 Parameters
waves (Waves or SMatrixArray object) – Wave function or scattering matrix to propagate.
dz (float) – Propagation distance [Å].
in_place (bool, optional) – If True the wavefunction array will be modified in place. Default is True.
 Returns
The propagated wave functions.
 Return type
Waves or SMatrixArray object


class
abtem.waves.
PlaneWave
(extent=None, gpts=None, sampling=None, energy=None, tilt=None, device='cpu')[source]¶ Plane wave object
The plane wave object is used for building plane waves.
 Parameters
extent (two float) – Lateral extent of wave function [Å].
gpts (two int) – Number of grid points describing the wave function.
sampling (two float) – Lateral sampling of wave functions [1 / Å].
energy (float) – Electron energy [eV].
tilt (two floats) – Small angle beam tilt [mrad].
device (str) – The plane waves will be build on this device.

property
antialias_aperture
¶ Antialiasing aperture as a fraction of the Nyquist frequency.
 Return type
Tuple
[float
,float
]

property
energy
¶ Acceleration energy [eV].

property
extent
¶ Grid extent in each dimension [Å].

property
gpts
¶ Number of grid points in each dimension.

multislice
(potential, pbar=True, max_batch_potential=1)[source]¶ Build plane wave function and propagate it through the potential. The grid of the two will be matched.
 Parameters
potential (Potential or Atoms object) – The potential through which to propagate the wave function.
pbar (bool, optional) – Display a progress bar. Default is True.
 Returns
Wave function at the exit plane of the potential.
 Return type
Waves object

property
sampling
¶ Grid sampling in each dimension [1 / Å].

property
tilt
¶ Beam tilt [mrad].
 Return type
Tuple
[float
,float
]

property
wavelength
¶ Relativistic wavelength [Å].

class
abtem.waves.
Probe
(extent=None, gpts=None, sampling=None, energy=None, semiangle_cutoff=30.0, ctf=None, tilt=None, device='cpu', **kwargs)[source]¶ Probe wavefunction object
The probe object can represent a stack of electron probe wavefunctions for simulating scanning transmission electron microscopy.
See the docs of abtem.transfer.CTF for a description of the parameters related to the contrast transfer function.
 Parameters
extent (two float, optional) – Lateral extent of wave functions [Å].
gpts (two int, optional) – Number of grid points describing the wave functions.
sampling (two float, optional) – Lateral sampling of wave functions [1 / Å].
energy (float, optional) – Electron energy [eV].
ctf (CTF) – Contrast transfer function object. Note that this can be specified
device (str) – The probe wave functions will be build on this device.
kwargs – Provide the parameters of the contrast transfer function as keyword arguments. See the documentation for the CTF object.

property
antialias_aperture
¶ Antialiasing aperture as a fraction of the Nyquist frequency.
 Return type
Tuple
[float
,float
]

build
(positions=None)[source]¶ Build probe wave functions at the provided positions.
 Parameters
positions (array of xypositions) – Positions of the probe wave functions
 Returns
Probe wave functions as a Waves object.
 Return type
Waves object

property
energy
¶ Acceleration energy [eV].

property
extent
¶ Grid extent in each dimension [Å].

property
gpts
¶ Number of grid points in each dimension.

multislice
(positions, potential, pbar=True)[source]¶ Build probe wave functions at the provided positions and propagate them through the potential.
 Parameters
positions (array of xypositions) – Positions of the probe wave functions.
potential (Potential or Atoms object) – The scattering potential.
pbar (bool, optional) – Display progress bars. Default is True.
 Returns
Probe exit wave functions as a Waves object.
 Return type
Waves object

property
sampling
¶ Grid sampling in each dimension [1 / Å].

scan
(scan, detectors, potential, measurements=None, max_batch=None, pbar=True)[source]¶ Raster scan the probe across the potential and record a measurement for each detector.
 Parameters
scan (Scan object) – Scan object defining the positions of the probe wave functions.
detectors (Detector or list of detectors) – The detectors recording the measurements.
potential (Potential) – The potential to scan the probe over.
measurements (Measurement or list of measurements) – Diction
max_batch (int, optional) – The probe batch size. Larger batches are faster, but require more memory. Default is None.
pbar (bool, optional) – Display progress bars. Default is True.
 Returns
Dictionary of measurements with keys given by the detector.
 Return type
dict

show
(**kwargs)[source]¶ Show the probe wave function.
 Parameters
angle (float, optional) – Angle along which the profile is shown [deg]. Default is 0 degrees.
kwargs (Additional keyword arguments for the abtem.plot.show_image function.) –

property
tilt
¶ Beam tilt [mrad].
 Return type
Tuple
[float
,float
]

property
wavelength
¶ Relativistic wavelength [Å].

class
abtem.waves.
SMatrix
(energy, expansion_cutoff=None, interpolation=1, ctf=None, num_partitions=None, extent=None, gpts=None, sampling=None, tilt=None, device='cpu', downsample=True, storage=None, **kwargs)[source]¶ Scattering matrix builder class
The scattering matrix builder object is used for creating scattering matrices and simulating STEM experiments using the PRISM algorithm.
 Parameters
expansion_cutoff (float) – The angular cutoff of the plane wave expansion [mrad].
energy (float) – Electron energy [eV].
interpolation (one or two int, optional) – Interpolation factor. Default is 1 (no interpolation).
ctf (CTF object, optional) – The probe contrast transfer function. Default is None (aperture is set by the cutoff of the expansion).
num_partitions (int) – The number of partitions used for in the parent scattering matrix.
extent (one or two float, optional) – Lateral extent of wave functions [Å]. Default is None (inherits the extent from the potential).
gpts (one or two int, optional) – Number of grid points describing the wave functions. Default is None (inherits the gpts from the potential).
sampling (one or two float, None) – Lateral sampling of wave functions [1 / Å]. Default is None (inherits the sampling from the potential.
tilt (two float) – Small angle beam tilt [mrad].
device (str, optional) – The calculations will be carried out on this device. Default is ‘cpu’.
downsample ({'cutoff', 'valid'} or float or bool) –
If not False, the scattering matrix is downsampled to a maximum given scattering angle after running the multislice algorithm.
cutoff
or True :Downsample to the antialias cutoff scattering angle.
valid
:Downsample to the largest rectangle inside the circle with a radius defined by the antialias cutoff scattering angle.
 float :
Downsample to a maximum scattering angle specified by a float.
storage (str, optional) – The scattering matrix will be stored on this device. Default is None (uses the option chosen for device).
kwargs – The parameters of a new CTF object as keyword arguments.

property
antialias_aperture
¶ Antialiasing aperture as a fraction of the Nyquist frequency.
 Return type
Tuple
[float
,float
]

build
(normalize=True)[source]¶ Build the scattering matrix.
 Return type
Union
[SMatrixArray
,PartitionedSMatrix
]

property
ctf
¶ The contrast transfer function of the probes.

property
energy
¶ Acceleration energy [eV].

property
expansion_cutoff
¶ Plane wave expansion cutoff.
 Return type
float

property
extent
¶ Grid extent in each dimension [Å].

property
gpts
¶ Number of grid points in each dimension.

property
interpolation
¶ Interpolation factor.
 Return type
Tuple
[int
,int
]

multislice
(potential, max_batch=None, pbar=True)[source]¶ Build scattering matrix and propagate the scattering matrix through the provided potential.
 Parameters
potential (AbstractPotential) – Scattering potential.
max_batch (int, optional) – The probe batch size. Larger batches are faster, but require more memory. Default is None.
pbar (bool, optional) – Display progress bars. Default is True.
 Returns
Probe exit wave functions as a Waves object.
 Return type
Waves object

property
sampling
¶ Grid sampling in each dimension [1 / Å].

scan
(scan, detectors, potential, measurements=None, max_batch_probes=None, max_batch_expansion=None, pbar=True)[source]¶ Build the scattering matrix. Raster scan the probe across the potential, record a measurement for each detector.
 Parameters
scan (Scan object) – Scan defining the positions of the probe wave functions.
detectors (List of Detector objects) – The detectors recording the measurements.
potential (Potential object) – The potential to scan the probe over.
max_batch_probes (int, optional) – The probe batch size. Larger batches are faster, but require more memory. Default is None.
max_batch_expansion (int, optional) – The expansion plane wave batch size. Default is None.
pbar (bool, optional) – Display progress bars. Default is True.
 Returns
Dictionary of measurements with keys given by the detector.
 Return type
dict

show
(**kwargs)[source]¶ Show the probe wave function.
 Parameters
angle (float, optional) – Angle along which the profile is shown [deg]. Default is 0 degrees.
kwargs (Additional keyword arguments for the abtem.plot.show_image function.) –

property
tilt
¶ Beam tilt [mrad].
 Return type
Tuple
[float
,float
]

property
wavelength
¶ Relativistic wavelength [Å].

class
abtem.waves.
SMatrixArray
(array, energy, k, ctf=None, extent=None, sampling=None, tilt=None, periodic=True, offset=0, 0, interpolated_gpts=None, antialias_aperture=None, device='cpu')[source]¶ Scattering matrix array object.
The scattering matrix array object represents a plane wave expansion of a probe, it is used for STEM simulations with the PRISM algorithm.
 Parameters
array (3d array) – The array representation of the scattering matrix.
expansion_cutoff (float) – The angular cutoff of the plane wave expansion [mrad].
energy (float) – Electron energy [eV].
k (2d array) – The spatial frequencies of each plane in the plane wave expansion.
ctf (CTF object, optional) – The probe contrast transfer function. Default is None.
extent (one or two float, optional) – Lateral extent of wave functions [Å]. Default is None (inherits extent from the potential).
sampling (one or two float, optional) – Lateral sampling of wave functions [1 / Å]. Default is None (inherits sampling from the potential).
tilt (two float, optional) – Small angle beam tilt [mrad].
periodic (bool, optional) – Should the scattering matrix array be considered periodic. This may be false if the scattering matrix is a cropping of a larger scattering matrix.
interpolated_gpts (two int, optional) – The gpts of the probe window after Fourier interpolation. This may differ from the shape determined by dividing each side by the interpolation is the scattering matrix array is cropped from a larger scattering matrix.
antialiasing_aperture (two float, optional) – Assumed antialiasing aperture as a fraction of the real space Nyquist frequency. Default is 2/3.
device (str, optional) – The calculations will be carried out on this device. Default is ‘cpu’.

property
antialias_aperture
¶ Antialiasing aperture as a fraction of the Nyquist frequency.
 Return type
Tuple
[float
,float
]

property
array
¶ Array representing the scattering matrix.
 Return type
ndarray

collapse
(positions=None, max_batch_expansion=None)[source]¶ Collapse the scattering matrix to probe wave functions centered on the provided positions.
 Parameters
positions (array of xypositions) – The positions of the probe wave functions.
max_batch_expansion (int, optional) – The maximum number of plane waves the reduction is applied to simultanously. If set to None, the number is chosen automatically based on available memory. Default is None.
 Returns
Probe wave functions for the provided positions.
 Return type
Waves object

property
energy
¶ Acceleration energy [eV].

property
extent
¶ Grid extent in each dimension [Å].

property
gpts
¶ Number of grid points in each dimension.

property
interpolated_gpts
¶ The grid of the interpolated scattering matrix.
 Return type
Tuple
[int
,int
]

property
k
¶ The spatial frequencies of each wave in the plane wave expansion.
 Return type
ndarray

multislice
(potential, max_batch=None, multislice_pbar=True, plane_waves_pbar=True, transposed=False)[source]¶ Propagate the scattering matrix through the provided potential.
 Parameters
potential (AbstractPotential object) – Scattering potential.
max_batch (int, optional) – The probe batch size. Larger batches are faster, but require more memory. Default is None.
multislice_pbar (bool, optional) – Display multislice progress bar. Default is True.
plane_waves_pbar (bool, optional) – Display plane waves progress bar. Default is True.
 Returns
Probe exit wave functions for the provided positions.
 Return type
Waves object.

property
sampling
¶ Grid sampling in each dimension [1 / Å].

scan
(scan, detectors, measurements=None, max_batch_probes=None, max_batch_expansion=None, pbar=True)[source]¶ Raster scan the probe across the potential and record a measurement for each detector.
 Parameters
scan (Scan object) – Scan defining the positions of the probe wave functions.
detectors (List of Detector objects) – The detectors recording the measurements.
max_batch_probes (int, optional) – The probe batch size. Larger batches are faster, but require more memory. Default is None.
max_batch_expansion (int, optional) – The expansion plane wave batch size. Default is None.
pbar (bool, optional) – Display progress bars. Default is True.
 Returns
Dictionary of measurements with keys given by the detector.
 Return type
dict

property
tilt
¶ Beam tilt [mrad].
 Return type
Tuple
[float
,float
]

property
wavelength
¶ Relativistic wavelength [Å].

class
abtem.waves.
Waves
(array, extent=None, sampling=None, energy=None, tilt=None, antialias_aperture=0.6666666666666666, 0.6666666666666666)[source]¶ Waves object
The waves object can define a batch of arbitrary 2D wave functions defined by a complex numpy array.
 Parameters
extent (one or two float) – Lateral extent of wave function [Å].
sampling (one or two float) – Lateral sampling of wave functions [1 / Å].
energy (float) – Electron energy [eV].
tilt (two float) – Small angle beam tilt [mrad].
antialiasing_aperture (float) – Assumed antialiasing aperture as a fraction of the real space Nyquist frequency. Default is 2/3.

allocate_measurement
(fourier_space=False)[source]¶ Allocate a measurement object
 Parameters
fourier_space –
 Return type

property
antialias_aperture
¶ Antialiasing aperture as a fraction of the Nyquist frequency.
 Return type
Tuple
[float
,float
]

apply_ctf
(ctf=None, in_place=False, **kwargs)[source]¶ Apply the aberrations defined by a CTF object to wave function.
 Parameters
ctf (CTF) – Contrast Transfer Function object to be applied.
kwargs – Provide the parameters of the contrast transfer function as keyword arguments. See the documentation for the CTF object.
 Returns
The wave functions with aberrations applied.
 Return type
Waves object

property
array
¶ Array representing the wave functions.
 Return type
ndarray

diffraction_pattern
(max_angle='valid', block_zeroth_order=False)[source]¶ Calculate the intensity of the wave functions at the diffraction plane.
 Returns
The intensity of the diffraction pattern(s).
 Return type
Measurement object

property
energy
¶ Acceleration energy [eV].

property
extent
¶ Grid extent in each dimension [Å].

property
gpts
¶ Number of grid points in each dimension.

intensity
()[source]¶ Calculate the intensity of the wave functions at the image plane.
 Returns
The wave function intensity.
 Return type

multislice
(potential, pbar=True, detector=None, max_batch_potential=1)[source]¶ Propagate and transmit wave function through the provided potential.
 Parameters
potential (Potential) – The potential through which to propagate the wave function.
pbar (bool) – If true, display a progress bar.
 Returns
Wave function at the exit plane of the potential.
 Return type
Waves object

classmethod
read
(path)[source]¶ Read wave functions from a hdf5 file.
 pathstr
The path to read the file.
 Return type

property
sampling
¶ Grid sampling in each dimension [1 / Å].

show
(ax=None, **kwargs)[source]¶ Show the wave function.
 kwargs :
Additional keyword arguments for the abtem.plot.show_image function.

tile
(reps)[source]¶ Tile wave function.
 Parameters
reps (to int) – Number of repetitions in x and y
 Returns
The tiled wave function.
 Return type

property
tilt
¶ Beam tilt [mrad].
 Return type
Tuple
[float
,float
]

property
wavelength
¶ Relativistic wavelength [Å].