abtem.transfer

Module to describe the contrast transfer function (CTF) and the related apertures.

Module Contents

Classes

Aberrations	Phase aberrations.
AnnularAperture	Annular aperture.
Aperture	A circular aperture cutting off the wave function at a specified angle, employed in both STEM and HRTEM. The abrupt cutoff may be softened by tapering it.
BaseAperture	Base class for apertures. Documented in the subclasses.
BaseTransferFunction	Base class for transfer functions.
Bullseye	Bullseye aperture.
CTF	The contrast transfer function (CTF) describes the aberrations of the objective lens in HRTEM and specifies how the condenser system shapes the probe in STEM.
RadialPhasePlate
SpatialEnvelope	Envelope function for simulating partial spatial coherence in the quasi-coherent approximation.
TemporalEnvelope	Envelope function for simulating partial temporal coherence in the quasi-coherent approximation.
Vortex	Vortex-beam aperture.
Zernike	Zernike aperture.

Functions

cartesian2polar	Convert between Cartesian and polar aberration coefficients.
hard_aperture	Calculates an array with a disk of ones and a soft edge.
nyquist_sampling	Calculate the Nyquist sampling.
point_resolution	Calculate the Scherzer point resolution.
polar2cartesian	Convert between polar and Cartesian aberration coefficients.
scherzer_defocus	Calculate the Scherzer defocus.
soft_aperture	Calculates an array with a disk of ones and a soft edge.
symbol_to_tex_symbol

Data

polar_aliases
polar_symbols

API

class abtem.transfer.Aberrations(...)

Bases: abtem.transfer.BaseTransferFunction, abtem.transfer._HasAberrations

Phase aberrations.

Parameters:

• aberration_coefficients (dict, optional) – Mapping from aberration symbols to their corresponding values. All aberration magnitudes should be given in [Å] and angles should be given in [radian].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [Å]. If ‘gpts’ is also given, will be ignored.

• kwargs (dict, optional) – Optionally provide the aberration coefficients as keyword arguments.

Initialization

property defocus: float | BaseDistribution

The defocus [Å].

property ensemble_axes_metadata: list[AxisMetadata]

class abtem.transfer.AnnularAperture(...)

Bases: abtem.transfer.BaseAperture

Annular aperture.

Parameters:

• inner_cutoff (float) – The cutoff semiangle of inner radius of the aperture [mrad].

• semiangle_cutoff (float) – The cutoff semiangle of the aperture [mrad].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

Initialization

property inner_cutoff: float

The cutoff semiangle of inner radius of the aperture.

property soft: bool

True if the aperture has a soft edge.

class abtem.transfer.Aperture(...)

Bases: abtem.transfer.BaseAperture

A circular aperture cutting off the wave function at a specified angle, employed in both STEM and HRTEM. The abrupt cutoff may be softened by tapering it.

Parameters:

• semiangle_cutoff (float or BaseDistribution) – The cutoff semiangle of the aperture [mrad]. Alternatively, a distribution of angles may be provided.

• soft (bool, optional) – If True, the edge of the aperture is softened (default is True).

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

Initialization

property ensemble_axes_metadata: list[AxisMetadata]

property soft: bool

True if the aperture has a soft edge.

class abtem.transfer.BaseAperture(...)

Bases: abtem.transfer.BaseTransferFunction

Base class for apertures. Documented in the subclasses.

Initialization

property ensemble_axes_metadata: list[AxisMetadata]

property metadata: dict

property nyquist_sampling: float

Nyquist sampling corresponding to the semiangle cutoff of the aperture [Å].

property semiangle_cutoff: float | BaseDistribution

Semiangle cutoff of the aperture [mrad].

class abtem.transfer.BaseTransferFunction(...)

Bases: abtem.transform.ReciprocalSpaceMultiplication, abtem.core.energy.HasAcceleratorMixin, abtem.core.grid.HasGrid2DMixin

Base class for transfer functions.

Initialization

property angular_sampling: tuple[float, float]

The sampling in scattering angles of the transfer function [mrad].

property energy: float | BaseDistribution | None

Electron energy [eV], or a distribution of energies for ensembles.

show(...) → abtem.visualize.Visualization

to_diffraction_patterns(...) → DiffractionPatterns

Converts the transfer function instance to DiffractionPatterns.

Parameters:

• max_angle (float, optional) – The maximum diffraction angle in radians. If not provided, the maximum angle will be determined based on the self._max_semiangle_cutoff attribute of the instance. If neither max_angle nor self._max_semiangle_cutoff is available, a RuntimeError will be raised.

• gpts (int | tuple[int, int], optional) – The number of grid points in reciprocal space for performing Fourier Transform. If not provided, a default value of 128 will be used.

Returns:

The diffraction patterns obtained from the conversion.

Return type:

DiffractionPatterns

class abtem.transfer.Bullseye(...)

Bases: abtem.transfer.BaseAperture

Bullseye aperture.

The aperture is divided radially into num_rings periods, each consisting of an open annulus followed by an opaque gap; ring_width is the open fraction of each period. The open annulus width is ds = semiangle_cutoff * ring_width / (ring_width + num_rings - 1), and a ring_width of 1 gives a fully open disk. Opaque spokes cross all rings except the central disk; each spoke is a straight bar of constant linear width spoke_width * ds (in the same reciprocal-angle units as ds), not a wedge of constant angular width. Consequently spoke_width has no meaningful upper bound of 1 the way ring_width does: a fixed spoke_width blocks a larger angular fraction of rings closer to the center than rings farther out, so increasing it reduces transmission monotonically but not linearly, with rings saturating to fully blocked from the center outward. The central disk is never affected by spokes, so transmission approaches (but never reaches) “central disk only” as spoke_width grows.

Parameters:

• num_spokes (int) – Number of spokes.

• spoke_width (float) – Width of the opaque spokes, as a multiple of the open annulus width ds (see above) rather than an angular fraction. Must be non-negative; unlike ring_width, values greater than 1 are valid and simply widen the spokes further.

• num_rings (int) – Number of rings.

• ring_width (float) – Open fraction of each radial ring period. Must be in the interval (0, 1], where 1 gives a fully open disk.

• semiangle_cutoff (float) – The cutoff semiangle of the aperture [mrad].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

• edge_softness (float, optional) – Edge softness in mrads. Default value is 0.0.

• corner_radius (float, optional) – Corner radius in mrads. Default value is 0.0

Initialization

property corner_radius: float

Corner radius [mrads]

property edge_softness: float

Edge softness [mrads]

property num_rings: int

Number of rings.

property num_spokes: int

Number of spokes.

property ring_width: float

Open fraction of each radial ring period.

property soft: bool

True if the aperture has a soft edge

property soft_edges: bool

True if using soft edges

property spoke_width: float

Width of the opaque spokes as a multiple of the open annulus width.

class abtem.transfer.CTF(...)

Bases: abtem.transfer._HasAberrations, abtem.transfer.BaseAperture

The contrast transfer function (CTF) describes the aberrations of the objective lens in HRTEM and specifies how the condenser system shapes the probe in STEM.

abTEM implements phase aberrations up to 5th order using polar coefficients. See Eq. 2.22 in Kirkland (2010).

Cartesian coefficients can be converted to polar using the utility function abtem.transfer.cartesian2polar.

Partial coherence is included as envelopes in the quasi-coherent approximation. See Chapter 3.2 in Kirkland (2010).

Parameters:

• semiangle_cutoff (float, optional) – The semiangle cutoff describes the sharp reciprocal-space cutoff due to the objective aperture [mrad] (default is no cutoff).

• soft (bool, optional) – If True, the edge of the aperture is softened (default is True).

• focal_spread (float, optional) – The 1/e width of the focal spread distribution due to chromatic aberration and lens current instability [Å] (default is 0). Note: this uses the 1/e width convention (as in Kirkland), not the standard deviation; to convert, use focal_spread = sqrt(2)*sigma.

• angular_spread (float, optional) – The standard deviation of the angular deviations due to source size [Å] (default is 0).

• aberration_coefficients (dict, optional) – Mapping from aberration symbols to their corresponding values. All aberration magnitudes should be given in [Å] and angles should be given in [radian].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

• flip_phase (bool, optional) – Changes the sign of all negative parts of the CTF to positive (following doi:10.1016/j.ultramic.2008.03.004) (default is False).

• wiener_snr (float, optional) – Applies a Wiener filter to the CTF(following doi:10.1016/j.ultramic.2008.03.004) with a given SNR value. If no value is given, the default value of 0.0 means that no filter is applied.

• kwargs (dict, optional) – Optionally provide the aberration coefficients as keyword arguments.

References

Kirkland, E. J. (2010). Advanced Computing in Electron Microscopy (2nd ed.).

Springer.

Initialization

property angular_spread: float | BaseDistribution

The standard deviation of the angular deviations due to source size [mrad].

property crossover_angle: float

The first zero-crossing of the phase at Scherzer defocus [mrad].

property ensemble_axes_metadata: list[AxisMetadata]

property flip_phase: bool

If true the signs of all negative parts of the CTF are changed to positive.

property focal_spread: float | BaseDistribution

The 1/e width of the focal spread distribution [Å].

property point_resolution: float

The Scherzer point resolution [Å].

profiles(...) → ReciprocalSpaceLineProfiles

Calculate radial line profiles for each included component (phase aberrations, aperture, temporal and spatial envelopes) of the contrast transfer function.

Parameters:

• gpts (int) – Number of grid points along the line profiles.

• max_angle (float) – The maximum scattering angle included in the radial line profiles [mrad]. The default is 1.5 times the semiangle cutoff or 50 mrad if no semiangle cutoff is set.

• phi (float) – The azimuthal angle of the radial line profiles [rad]. Default is 0.

Returns:

ctf_profiles – Ensemble of reciprocal space line profiles. The first ensemble dimension represents the different

Return type:

ReciprocalSpaceLineProfiles

property scherzer_defocus: float

The Scherzer defocus [Å].

property semiangle_cutoff: float | BaseDistribution

The semiangle cutoff [mrad].

property soft: float

True if the aperture has a soft edge.

to_point_spread_functions(...) → Images

property wiener_snr: float

If true a Wiener filter is applied to the CTF.

class abtem.transfer.RadialPhasePlate(...)

Bases: abtem.transfer.BaseAperture

property num_flips: int

Number of phase flips.

property phase_shift: float

Phase shift of the phase plate.

property power_law: float

Power law of the phase plate.

property shift_central_semiangle: float

Shift central semiangle of the phase plate.

property soft: bool

True if the aperture has a soft edge.

class abtem.transfer.SpatialEnvelope(...)

Bases: abtem.transfer.BaseTransferFunction, abtem.transfer._HasAberrations

Envelope function for simulating partial spatial coherence in the quasi-coherent approximation.

Parameters:

• angular_spread (float or 1D array or BaseDistribution) – The standard deviation of the angular deviations due to source size [mrad]. Alternatively, a distribution of standard deviations may be provided.

• aberration_coefficients (dict, optional) – Mapping from aberration symbols to their corresponding values. All aberration magnitudes should be given in [Å] and angles should be given in [radian].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

• kwargs (dict, optional) – Optionally provide the aberration coefficients as keyword arguments.

Initialization

property angular_spread: float | BaseDistribution

The standard deviation of the angular deviations due to source size [mrad].

property ensemble_axes_metadata: list[AxisMetadata]

class abtem.transfer.TemporalEnvelope(...)

Bases: abtem.transfer.BaseTransferFunction

Envelope function for simulating partial temporal coherence in the quasi-coherent approximation.

Parameters:

• focal_spread (float or 1D array or BaseDistribution) – The 1/e width of the focal spread distribution due to chromatic aberration and lens current instability [Å]. Note: this uses the 1/e width convention (as in Kirkland), not the standard deviation; to convert, use focal_spread = sqrt(2)*sigma. Alternatively, a distribution of values may be provided.

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

Initialization

property ensemble_axes_metadata: list[AxisMetadata]

property focal_spread: float | BaseDistribution

The 1/e width of the focal spread distribution [Å].

class abtem.transfer.Vortex(...)

Bases: abtem.transfer.BaseAperture

Vortex-beam aperture.

Parameters:

• quantum_number (int) – Quantum number of vortex beam.

• semiangle_cutoff (float) – The cutoff semiangle of the aperture [mrad].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

Initialization

property quantum_number: int

Quantum number of vortex beam.

property soft: bool

True if the aperture has a soft edge.

class abtem.transfer.Zernike(...)

Bases: abtem.transfer.BaseAperture

Zernike aperture.

Parameters:

• center_hole_cutoff (float) – Cutoff semiangle of aperture hole [mrad].

• phase_shift (float) – Phase shift of Zernike film [rad]

• semiangle_cutoff (float) – The cutoff semiangle of the aperture [mrad].

• energy (float, optional) – Electron energy [eV]. If not provided, inferred from the wave functions.

• extent (float or two float, optional) – Lateral extent of wave functions [Å] in x and y directions. If a single float is given, both are set equal.

• gpts (two ints, optional) – Number of grid points describing the wave functions.

• sampling (two float, optional) – Lateral sampling of wave functions [1 / Å]. If ‘gpts’ is also given, will be ignored.

Initialization

property center_hole_cutoff: float

Cutoff semiangle of aperture hole.

property phase_shift: float

Phase shift of Zernike film.

property soft: bool

True if the aperture has a soft edge.

abtem.transfer.cartesian2polar(...) → dict

Convert between Cartesian and polar aberration coefficients.

Parameters:

cartesian (dict) – Mapping from Cartesian aberration symbols to their corresponding values.

Returns:

polar – Mapping from polar aberration symbols to their corresponding values.

Return type:

dict

abtem.transfer.hard_aperture(...) → ndarray

Calculates an array with a disk of ones and a soft edge.

Parameters:

• alpha (2D array) – Array of radial angles [mrad].

• semiangle_cutoff (float or 1D array) – Semiangle cutoff(s) of the aperture(s). If given as an array, a 3D array is returned where the first dimension represents a different aperture for each item in the array of semiangle cutoffs.

Returns:

hard_aperture_array

Return type:

2D or 3D numpy.ndarray

abtem.transfer.nyquist_sampling(...) → float

Calculate the Nyquist sampling.

Parameters:

• semiangle_cutoff (float) – Semiangle cutoff [mrad].

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

abtem.transfer.point_resolution(...) → float

Calculate the Scherzer point resolution.

Parameters:

• Cs (float) – Spherical aberration [Å].

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

abtem.transfer.polar2cartesian(...) → dict

Convert between polar and Cartesian aberration coefficients.

Parameters:

polar (dict) – Mapping from polar aberration symbols to their corresponding values.

Returns:

cartesian – Mapping from Cartesian aberration symbols to their corresponding values.

Return type:

dict

abtem.transfer.polar_aliases

None

abtem.transfer.polar_symbols

None

abtem.transfer.scherzer_defocus(...) → float

Calculate the Scherzer defocus.

Parameters:

• Cs (float) – Spherical aberration [Å].

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

abtem.transfer.soft_aperture(...) → ndarray

Calculates an array with a disk of ones and a soft edge.

Parameters:

• alpha (2D array) – Array of radial angles [mrad].

• phi (2D array) – Array of azimuthal angles [rad].

• semiangle_cutoff (float or 1D array) – Semiangle cutoff(s) of the aperture(s). If given as an array, a 3D array is returned where the first dimension represents a different aperture for each item in the array of semiangle cutoffs.

• angular_sampling (tuple of float) – Reciprocal-space sampling in units of scattering angles [mrad].

Returns:

soft_aperture_array

Return type:

2D or 3D numpy.ndarray

abtem.transfer.symbol_to_tex_symbol(...) → str