abtem.detectors

Module for describing the detection of transmitted waves and different detector types.

Module Contents

Classes

AnnularDetector	The annular detector integrates the intensity of the detected wave functions between an inner and outer radial integration limits, i.e. over an annulus.
BaseDetector	Base detector class.
FlexibleAnnularDetector	The flexible annular detector allows choosing the integration limits after running the simulation by binning the intensity in annular integration regions.
PixelatedDetector	The pixelated detector records the intensity of the Fourier-transformed exit wave function, i.e. the diffraction patterns. This may be used for example for simulating 4D-STEM.
SegmentedDetector	The segmented detector covers an annular angular range, and is partitioned into several integration regions divided to radial and angular segments. This can be used for simulating differential phase contrast (DPC) imaging.
SpectralAnnularDetector	Sweeps an offset circular acceptance region over q to build S(q, E).
SpectralSlitDetector	A rectangular slit detector in reciprocal (diffraction) space.
WavesDetector	Detect the complex wave functions.

Functions

validate_detectors

Validate that a variable is a list of detectors.

API

class abtem.detectors.AnnularDetector(...)

Bases: abtem.detectors._AbstractRadialDetector

The annular detector integrates the intensity of the detected wave functions between an inner and outer radial integration limits, i.e. over an annulus.

Parameters:

• inner (float) – Inner integration limit [mrad].

• outer (float) – Outer integration limit [mrad].

• offset (two float, optional) – Center offset of the annular integration region [mrad].

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

angular_limits(...) → tuple[float, float]

property azimuthal_sampling: float

detect(...) → Images | RealSpaceLineProfiles | MeasurementsEnsemble

Detect the given waves producing images.

Parameters:

waves (Waves) – The waves to detect.

Returns:

measurement

Return type:

Images or RealSpaceLineProfiles

get_detector_region(...)

Get the annular detector region as a diffraction pattern.

Parameters:

• waves (BaseWaves or DiffractionPatterns) – The waves or diffraction patterns used to derive grid calibration.

• fftshift (bool, optional) – If True, the zero-frequency of the detector region is shifted to the centre of the array, otherwise the centre is at (0, 0).

Returns:

detector_region

Return type:

DiffractionPatterns

property inner: float

Inner integration limit in mrad.

property nbins_azimuthal

property nbins_radial

property offset: tuple[float, float]

Center offset of the annular integration region [mrad].

property outer: float | None

Outer integration limit in mrad.

property radial_sampling: float

class abtem.detectors.BaseDetector(...)

Bases: abtem.transform.ArrayObjectTransform[abtem.waves.Waves, abtem.measurements.BaseMeasurements | abtem.waves.Waves]

Base detector class.

Parameters:

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

apply(...) → BaseMeasurements | Waves

detect(...) → BaseMeasurements | Waves

Detect the given waves producing a measurement.

Parameters:

waves (Waves) – The waves to detect.

Returns:

measurement

Return type:

BaseMeasurements

property to_cpu: bool

The measurements are copied to host memory.

property url: Optional[str]

The storage location of the measurement data.

class abtem.detectors.FlexibleAnnularDetector(...)

Bases: abtem.detectors._AbstractRadialDetector

The flexible annular detector allows choosing the integration limits after running the simulation by binning the intensity in annular integration regions.

Parameters:

• step_size (float, optional) – Radial extent of the bins [mrad] (default is 1).

• inner (float, optional) – Inner integration limit of the bins [mrad].

• outer (float, optional) – Outer integration limit of the bins [mrad].

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

property azimuthal_sampling: float

detect(...) → PolarMeasurements

property nbins_azimuthal

property nbins_radial

property radial_sampling: float

property step_size: float

Step size [mrad].

class abtem.detectors.PixelatedDetector(...)

Bases: abtem.detectors.BaseDetector

The pixelated detector records the intensity of the Fourier-transformed exit wave function, i.e. the diffraction patterns. This may be used for example for simulating 4D-STEM.

Parameters:

• max_angle (float or {'cutoff', 'valid', 'full'}) –

  The diffraction patterns will be detected up to this angle [mrad]. If str, it must be one of:

  cutoff

  The maximum scattering angle will be the cutoff of the antialiasing aperture.

  valid

  The maximum scattering angle will be the largest rectangle that fits inside the circular antialiasing aperture (default).

  full

  Diffraction patterns will not be cropped and will include angles outside the antialiasing aperture.

• resample (str or False) – If ‘uniform’, the diffraction patterns from rectangular cells will be downsampled to a uniform angular sampling.

• reciprocal_space (bool, optional) – If True (default), the diffraction pattern intensities are detected, otherwise the probe intensities are detected as images.

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

angular_limits(...) → tuple[float, float]

detect(...) → DiffractionPatterns | Images

Detect the given waves producing diffraction patterns.

Parameters:

waves (Waves) – The waves to detect.

Returns:

measurement

Return type:

DiffractionPatterns

property max_angle: str | float

Maximum detected scattering angle.

property reciprocal_space: bool

Detect the exit wave functions in real or reciprocal space.

property resample: str | bool | tuple[float, float]

How to resample the detected diffraction patterns.

class abtem.detectors.SegmentedDetector(...)

Bases: abtem.detectors._AbstractRadialDetector

The segmented detector covers an annular angular range, and is partitioned into several integration regions divided to radial and angular segments. This can be used for simulating differential phase contrast (DPC) imaging.

Parameters:

• nbins_radial (int) – Number of radial bins.

• nbins_azimuthal (int) – Number of angular bins.

• inner (float) – Inner integration limit of the bins [mrad].

• outer (float) – Outer integration limit of the bins [mrad].

• rotation (float) – Rotation of the bins around the origin [mrad].

• offset (two float) – Offset of the bins from the origin in x and y [mrad].

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location,typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

property azimuthal_sampling

property nbins_azimuthal: int

Number of angular bins.

property nbins_radial: int

Number of radial bins.

property radial_sampling

property rotation

class abtem.detectors.SpectralAnnularDetector(...)

Bases: abtem.detectors.AnnularDetector

Sweeps an offset circular acceptance region over q to build S(q, E).

The acceptance disk (radius outer, inner always 0) is centred at (q·cos(angle), q·sin(angle)) for each q in [q_min, q_max). Pass to abtem.momentum_resolved_spectrum() together with energy-resolved diffraction patterns to obtain a MomentumResolvedSpectrum.

Parameters:

• outer (float) – Acceptance radius [mrad] of the integration disk at each q-point. The full disk diameter is 2 * outer. The q-axis in the resulting MomentumResolvedSpectrum runs from q_min to q_max in approximately outer-sized steps. For equivalent perpendicular acceptance as a SpectralSlitDetector with width=w, use outer = w / 2.

• q_min (float, optional) – Start of the q sweep [mrad]. Default is 0.

• q_max (float, optional) – End of the q sweep [mrad]. If None (default), the diffraction-pattern cutoff angle is used at call time. To cover the same q-range as a SpectralSlitDetector with q_max=Q, use the same q_max=Q.

• angle (float, optional) – Direction of the q sweep [degrees, CCW from kx]. Default is 0.

• q_sampling (float, optional) – Step between q-points [mrad]. If None (default) the step equals outer (one disk-radius per step). Setting a larger value produces fewer q-points and a faster spectrum.

• to_cpu (bool, optional)

• url (str, optional)

Notes

Comparing annular and slit detectors

SpectralAnnularDetector	SpectralSlitDetector
outer — disk radius	width/2 — half-width
q_max — max q	q_max — max q

For equivalent perpendicular acceptance and the same q-range:

SpectralAnnularDetector(outer=r, q_max=Q)
SpectralSlitDetector(q_max=Q, width=2*r)

Initialization

property q_max: Optional[float]

End of the q sweep [mrad], or None to use the DP cutoff angle.

property q_min: float

Start of the q sweep [mrad].

property q_sampling: Optional[float]

Step between q-points [mrad], or None to use outer.

show(...)

Show all acceptance-disk positions along the q-sweep.

Each disk (radius outer) is drawn at the q-position it would be centred on when computing a spectrum, so the full sweep from q_min to q_max is visible at once.

Parameters:

• waves (BaseWaves or DiffractionPatterns) – Provides grid calibration and, when show_pattern is True, the diffraction data. Must be a DiffractionPatterns when show_pattern is True.

• show_pattern (bool, optional) – Overlay the disks on the summed diffraction pattern shown as a grayscale background.

• power (float, optional) – Exponent applied to the pattern before display (default 0.5 → square-root stretch). Ignored when show_pattern is False.

• ax (matplotlib Axes, optional)

• figsize (tuple, optional)

property sweep_angle: float

Direction of the q sweep [degrees, CCW from kx].

class abtem.detectors.SpectralSlitDetector(...)

Bases: abtem.detectors.BaseDetector

A rectangular slit detector in reciprocal (diffraction) space.

The slit can be defined in two ways:

Geometry mode — specify size, q-range and orientation:

Parameters:

• width (float) – Full width of the slit perpendicular to its long axis [mrad]. This is the full integration aperture, not the half-width. For equivalent integration coverage perpendicular to the q-scan direction as a SpectralAnnularDetector with acceptance radius outer=r, use width = 2 * r (the disk diameter, not the radius).

• q_min (float, optional) – Start of the q-axis [mrad]. Default is 0, which includes q=0 (the direct beam direction) as the first point of the spectrum. Set to a positive value to exclude the low-q / direct-beam region, e.g. q_min=10 to start at 10 mrad. Directly comparable to the q_min parameter of SpectralAnnularDetector.

• q_max (float) – Maximum scattering vector along the slit’s long axis [mrad]. Directly comparable to the q_max parameter of SpectralAnnularDetector.

• angle (float, optional) – Rotation of the long axis of the slit [degrees, CCW from kx axis]. Default is 0.

• offset (two floats, optional) – Origin of the q-axis sweep (kx, ky) [mrad]. The q-axis starts here (at q_min) and extends in the direction given by angle. Default is (0, 0), i.e. the sweep starts from the diffraction pattern centre.

• q_sampling (float, optional) – Desired q-axis bin size [mrad]. If None (default) the native pixel sampling of the diffraction pattern is used. Setting a larger value bins adjacent line samples together, producing fewer q-points and a faster spectrum.

• directly (**Corner mode** — specify the four sides)

• corners ((kx_min, kx_max, ky_min, ky_max)) – Axis-aligned bounds of the rectangle [mrad], with signs measured from the diffraction-pattern origin. Incompatible with offset, angle, q_min, q_max and width. The q-axis origin is taken as (kx_min, (ky_min+ky_max)/2), so q=0 maps to the left edge of the rectangle.

• parameters (Common)

• -----------------

• to_cpu (bool, optional) – Copy result to CPU after detection. Default is True.

• url (str, optional) – Save path for the measurement.

Notes

Comparing slit and annular detectors

Both detector types share the same q_min/q_max convention — the same numerical value gives the same scattering-vector range in the output spectrum. The perpendicular acceptance differs: the slit integrates a rectangle of full width width, while the annular detector integrates a disk of radius outer.

SpectralSlitDetector	SpectralAnnularDetector
width — full slit width	outer — acceptance radius
q_min — start q (≥ 0)	q_min — start q (≥ 0)
q_max — max q	q_max — max q
angle — sweep direction	angle — sweep direction

For equivalent perpendicular acceptance and the same q-range:

SpectralSlitDetector(width=2*r, q_min=Q0, q_max=Q)
SpectralAnnularDetector(outer=r, q_min=Q0, q_max=Q)

Note that width = 2 * outer: the slit width is the full aperture diameter, whereas outer is the acceptance radius.

Initialization

property angle: float

Long-axis rotation angle [degrees].

angular_limits(...) → tuple[float, float]

Radial bounds [mrad] of the acceptance region, for grid-sufficiency checks. The slit has no rotationally-symmetric inner exclusion, so the inner bound is 0; the outer bound is the farthest distance from the origin reached by the bounding rectangle’s corners.

property corners: tuple[float, float, float, float]

Axis-aligned bounding rectangle (kx_min, kx_max, ky_min, ky_max) [mrad].

detect(...) → Images | RealSpaceLineProfiles | MeasurementsEnsemble

Detect the given waves producing images.

Parameters:

waves (Waves)

Returns:

measurement

Return type:

Images or RealSpaceLineProfiles

property extent: float

Physical length of the slit along its long axis [mrad] (= q_max - q_min).

get_detector_region(...)

Get the slit detector region as a DiffractionPatterns object.

Parameters:

• waves (BaseWaves or DiffractionPatterns) – The waves or diffraction patterns used to derive grid calibration.

• fftshift (bool, optional) – If True, the zero-frequency component is shifted to the centre.

property offset: tuple[float, float]

Origin of the q-axis sweep (kx, ky) [mrad]. The q-axis starts here.

property q_max: float

Maximum scattering vector along the slit’s long axis [mrad] (= q_min + extent).

property q_min: float

Start of the q-axis [mrad].

property q_sampling: Optional[float]

q-axis bin size [mrad], or None for native DP sampling.

show(...)

Show the slit detector region as a polygon patch.

Parameters:

• waves (BaseWaves or DiffractionPatterns) – Provides grid calibration. When show_pattern is True, the diffraction pattern (summed over all ensemble axes) is shown as a grayscale background and waves must be a DiffractionPatterns.

• show_pattern (bool, optional) – Overlay the patch on the summed diffraction pattern. Requires a DiffractionPatterns as waves.

• power (float, optional) – Exponent applied to the pattern before display (default 0.5 → square-root stretch). Ignored when show_pattern is False.

• ax (matplotlib Axes, optional)

• figsize (tuple, optional)

property width: float

Full width perpendicular to the long axis [mrad].

class abtem.detectors.WavesDetector(...)

Bases: abtem.detectors.BaseDetector

Detect the complex wave functions.

Parameters:

• to_cpu (bool, optional) – If True, copy the measurement data from the calculation device to CPU memory after applying the detector, otherwise the data stays on the respective devices. Default is True.

• url (str, optional) – If this parameter is set the measurement data is saved at the specified location, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data. If not set (default) the data stays in memory.

Initialization

angular_limits(...) → tuple[float, float]

detect(...) → Waves

Detect the given waves directly as complex waves.

Parameters:

waves (Waves) – The waves to detect.

Returns:

measurement

Return type:

Waves

abtem.detectors.validate_detectors(...) → list[BaseDetector]

Validate that a variable is a list of detectors.

Parameters:

• detectors (BaseDetector or list of BaseDetector) – The detectors to validate.

• waves (Waves, optional) – The waves to match the detectors to.

Returns:

A list of validated detectors.

Return type:

list of BaseDetector

Raises:

TypeError – If detectors is not a BaseDetector or a list of BaseDetector.