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 near-field 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

Anti-aliasing aperture as a fraction of the Nyquist frequency.

Return type

Tuple[float, float]

build()[source]

Build the plane wave function as a Waves object.

Return type

Waves

copy()[source]

Make a copy.

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, 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

Anti-aliasing 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 xy-positions) – Positions of the probe wave functions

Returns

Probe wave functions as a Waves object.

Return type

Waves object

property ctf

Probe contrast transfer function.

Return type

CTF

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 xy-positions) – 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', 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’.

  • 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

Anti-aliasing aperture as a fraction of the Nyquist frequency.

Return type

Tuple[float, float]

build()[source]

Build the scattering matrix.

Return type

Union[SMatrixArray, PartitionedSMatrix]

copy()[source]

Make a copy.

Return type

SMatrix

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

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

Anti-aliasing 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 xy-positions) – 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

copy()[source]

Make a copy.

property ctf

Probe contrast transfer function.

Return type

CTF

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)[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

Measurement

property antialias_aperture

Anti-aliasing 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

copy()[source]

Make a copy.

Return type

Waves

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

Measurement

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

Waves

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.

property tilt

Beam tilt [mrad].

Return type

Tuple[float, float]

property wavelength

Relativistic wavelength [Å].

write(path)[source]

Write wave functions to a hdf5 file.

pathstr

The path to write the file.