abtem.prism.s_matrix

Contents

abtem.prism.s_matrix#

Module describing the scattering matrix used in the PRISM algorithm.

Module Contents#

Classes#

BaseSMatrix

Base class for scattering matrices.

CompressedSMatrixArray

A compressed scattering matrix defined by its truncated singular value decomposition, returned by SMatrix.build() when upsample=True (the C-PRISM algorithm). The coarse phase-removed scattering matrix is interpolated to the plane waves of the aperture at interpolation (1, 1) and factored as \(T \approx U \Sigma V^H\), where the left singular vectors \(U\) are real-space images and the right singular vectors hold the plane-wave coefficients of each mode.

SMatrix

The scattering matrix is used for simulating STEM experiments using the PRISM algorithm.

SMatrixArray

A scattering matrix defined by a given array of dimension 3, where the first indexes the probe plane waves and the latter two are the y and x scan directions.

API#

class abtem.prism.s_matrix.BaseSMatrix[source]#

Bases: abtem.waves.BaseWaves

Base class for scattering matrices.

property base_axes_metadata: list[AxisMetadata]#
property device#

The device where the S-Matrix is created and reduced.

dummy_probes(...) → Probe[source]#

A probe or an ensemble of probes equivalent reducing the SMatrix at a single position.

Parameters:
Returns:

dummy_probes

Return type:

Probes

ensemble_axes_metadata: list[AxisMetadata]#

None

ensemble_shape: tuple[int, ...]#

None

abstract property interpolation#

Interpolation factor in the x and y directions

abstract property semiangle_cutoff: float#

The radial cutoff of the plane-wave expansion [mrad].

abstract property wave_vectors: ndarray#

The wave vectors corresponding to each plane wave.

abstract property window_extent#

The cropping window extent of the waves.

abstract property window_gpts#

The number of grid points describing the cropping window of the wave functions.

class abtem.prism.s_matrix.CompressedSMatrixArray(...)[source]#

Bases: abtem.prism.s_matrix.BaseSMatrix, abtem.core.utils.CopyMixin, abtem.core.utils.EqualityMixin

A compressed scattering matrix defined by its truncated singular value decomposition, returned by SMatrix.build() when upsample=True (the C-PRISM algorithm). The coarse phase-removed scattering matrix is interpolated to the plane waves of the aperture at interpolation (1, 1) and factored as \(T \approx U \Sigma V^H\), where the left singular vectors \(U\) are real-space images and the right singular vectors hold the plane-wave coefficients of each mode.

Parameters:

  • u (ndarray) – Left singular vectors of the phase-removed scattering matrix of shape (K, gpts_x, gpts_y), where K is the number of retained modes.

  • sigma (ndarray) – Retained singular values of shape (K,).

  • vh_dense (ndarray) – Right singular vectors interpolated to the dense plane-wave expansion of shape (K, number of dense plane waves).

  • dense_indices (ndarray) – Integer Fourier-space indices of the dense plane waves of shape (N, 2).

  • semiangle_cutoff (float) – The radial cutoff of the plane-wave expansion [mrad].

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

  • extent (two float) – Lateral extent of the scattering matrix [Å].

  • interpolation (two int) – Interpolation factor used for the coarse plane-wave expansion.

  • window_gpts (two int) – The number of grid points describing the cropping window of the reduced wave functions.

  • position_quantization (int, optional) – If given, the fractional part of the probe positions is quantized to this number of fractions of a pixel. The default is None, ie. the positions are not quantized.

  • device (str) – The device used for the reduction (‘cpu’ or ‘gpu’).

  • metadata (dict) – A dictionary defining wave function metadata.

Initialization

property blend_angle: float | None#

Scattering angle [mrad] above which the reduction follows the plane-wave (PRISM) reduction of the built beams (None: no blending).

property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape: tuple[int, ...]#
property interpolation: tuple[int, int]#
property max_batch_expansion: int | str#

Number of plane waves expanded at a time by the full-window reduction; ‘auto’ materializes the full expansion.

property metadata: dict#
property rank: int#

Number of retained modes.

At least the number of built beams — their row space is retained whole so that the plane-wave branch of the reduction is the PRISM algorithm exactly — unless max_rank was given. The stored modes and the reduction both scale with it.

reduce(...) → BaseMeasurements | Waves | list[BaseMeasurements | Waves][source]#

Scan the probe across the potential and record a measurement for each detector.

Parameters:

  • scan (BaseScan) – Positions of the probe wave functions. If not given, reduces a single probe at the center of the potential.

  • ctf (CTF, optional) – The probe contrast transfer function. Default is None (aperture is set by the plane-wave cutoff).

  • detectors (BaseDetector or list of BaseDetector) – The detectors recording the measurements.

  • max_batch_reduction (int or str, optional) – Number of positions per reduction operation. If ‘auto’ (default), the batch size is automatically chosen based on the abTEM user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • max_batch_expansion (int or str, optional) – The number of plane waves expanded at a time when the reduced wave functions are not cropped. If ‘auto’, the full plane-wave expansion is materialized once (fastest, but with the memory footprint of a PRISM scattering matrix at interpolation 1); an integer streams the expansion instead, bounding the memory at one batch of plane waves plus one batch of reduced wave functions, at the cost of repeating the expansion for every batch of probe positions. If not given (default), the value set on the SMatrix is used. Only used with method='expand'.

  • method ({'auto', 'expand', 'modes'}, optional) – How the full-window reduction is evaluated. 'expand' expands the compressed factorization to the interpolation-(1, 1) scattering matrix and reduces it with one large matrix product per batch of probe positions — high arithmetic intensity, fastest on the CPU, but with a cost proportional to the number of dense plane waves. 'modes' contracts the retained modes directly against a probe-displaced reduction kernel — a cost proportional to the number of modes (usually far fewer than the plane waves), fastest on the GPU where the contraction saturates memory bandwidth. Both produce identical wave functions to floating point precision. 'auto' (default) selects ‘modes’ on the GPU and ‘expand’ on the CPU, unless streaming was requested through max_batch_expansion. Ignored when the reduced wave functions are cropped (window_gpts), which always contracts the modes.

  • blend_angle (float, optional) – Above this scattering angle [mrad] the reduced wave functions follow the plane-wave (PRISM) reduction of the built beams, below it the interpolated (C-PRISM) reduction, with a smooth taper between them. The interpolation is band limited and aliases the contributions of electrons displaced beyond half its period, which harms high-angle detectors; the plane-wave reduction of the same built beams does not, hence blending bounds the high-angle error by that of the PRISM algorithm while keeping the interpolated accuracy at low angles. If not given, the value set on the SMatrix is used (‘auto’ derives it from the aliasing limit of the interpolation); a non-positive value disables blending.

Returns:

measurements

Return type:

BaseMeasurements or Waves or list of BaseMeasurements or Waves

scan(...)[source]#

Reduce the compressed scattering matrix at the positions of a scan.

See CompressedSMatrixArray.reduce().

property semiangle_cutoff: float#
property sigma: ndarray#

Retained singular values.

property singular_values: ndarray#

The full singular-value spectrum of the interpolated operator, including the modes truncated by tolerance and max_rank. Useful for choosing either: where the spectrum falls off is the intrinsic dimensionality of the specimen, and the rank may be cut towards it for proportional savings in memory and reduction time. The retained part is sigma.

property u: ndarray#

Left singular vectors of shape (K, gpts_x, gpts_y).

property vh_dense: ndarray#

Right singular vectors at the dense plane-wave expansion.

property wave_vectors: ndarray#

The wave vectors of the dense plane-wave expansion.

property window_extent: tuple[float, float]#
property window_gpts: tuple[int, int]#
class abtem.prism.s_matrix.SMatrix(...)[source]#

Bases: abtem.prism.s_matrix.BaseSMatrix, abtem.core.ensemble.Ensemble, abtem.core.utils.CopyMixin, abtem.core.utils.EqualityMixin

The scattering matrix is used for simulating STEM experiments using the PRISM algorithm.

Parameters:

  • semiangle_cutoff (float) – The radial cutoff of the plane-wave expansion [mrad].

  • energy (float or list of float) – Electron energy [eV]. A single float runs a standard single-energy calculation. A list or array of floats builds the scattering matrix at each energy independently; the plane-wave sets are zero-padded to the union of all energies’ wave vectors (higher energies include more plane waves within the semiangle cutoff), and the result gains a leading EnergyAxis dimension.

  • potential (Atoms or AbstractPotential, optional) – Atoms or a potential that the scattering matrix represents. If given as atoms, a default potential will be created. If nothing is provided the scattering matrix will represent a vacuum potential, in which case the sampling and extent must be provided.

  • gpts (one or two int, optional) – Number of grid points describing the scattering matrix. Provide only if potential is not given.

  • sampling (one or two float, optional) – Lateral sampling of scattering matrix [Å]. Provide only if potential is not given. Will be ignored if ‘gpts’ is also provided.

  • extent (one or two float, optional) – Lateral extent of scattering matrix [Å]. Provide only if potential is not given.

  • interpolation (one or two int, optional) – Interpolation factor in the x and y directions (default is 1, ie. no interpolation). If a single value is provided, assumed to be the same for both directions.

  • upsample (bool, optional) – If True, interpolate the plane-wave expansion built at the given interpolation factor back to the full plane-wave expansion of the aperture and compress it by an exact adaptive truncated singular value decomposition (the C-PRISM algorithm); SMatrix.build() then returns a CompressedSMatrixArray. Every probe is reduced from the full expansion, avoiding the real-space cropping and coarsened aperture sampling errors of PRISM at the same interpolation factor: the interpolation factor only affects the number of multislice runs required to build the scattering matrix. At an interpolation factor of 1 the expansion is already complete and this option has no effect. Default is False.

  • tolerance (float, optional) –

    Relative singular value threshold applied when upsample=True to the part of the interpolated scattering matrix that the built beams do not already span (default is 1e-3). Decrease for higher accuracy at increased cost of the reduction. Ignored when upsample=False.

    Note that this does not set the rank on its own. The row space of the built beams is retained whole, which is what makes the plane-wave branch of the reduction the PRISM algorithm exactly, so the rank is at least the number of built beams however large the tolerance. Use max_rank to go below that.

  • max_rank (int, optional) –

    Maximum number of modes retained by the compression when upsample=True, keeping those carrying the largest amplitude. If None (default) every mode described above is retained.

    This is the parameter that trades accuracy for the memory and the reduction time, both of which are proportional to the rank: the modes are the bulk of the stored scattering matrix, and the reduction contracts them. It is worth setting when the beams outnumber the intrinsic dimensionality of the specimen, which is the case at small interpolation factors — halving the rank of a factor-2 expansion costs a few percent of the error on the cells measured, while at factor 4 there is little to no slack and truncating is expensive. Inspect CompressedSMatrixArray.singular_values to see where the spectrum of a given specimen falls off.

  • blend_angle (float or str, optional) – Scattering angle [mrad] above which the reduction of the compressed scattering matrix follows the plane-wave (PRISM) reduction of the built beams, below which the interpolated (C-PRISM) reduction. Acts through the detector routing of the reduction: the angle is snapped down to a detector collection boundary and each detector reads the branch its band lies in, guaranteeing the dark-field bands match the PRISM algorithm. ‘auto’ (default with upsample=True) derives the angle from the aliasing limit of the interpolation, extent / (2 * interpolation * thickness); a number fixes it; 0 disables blending. Only used when upsample=True.

  • window_gpts (one or two int or 'full', optional) – The number of grid points describing the cropping window of the wave functions reduced from the compressed scattering matrix. Only used when upsample=True. If None (default), the window is inferred from the specimen and the probe (the probe tails plus the beam spreading over the thickness), falling back to the full grid when there is no potential; ‘full’ disables cropping. Unlike the PRISM cropping window, this window is decoupled from the interpolation factor.

  • position_quantization (int, optional) – If given, the fractional part of the probe positions is quantized to this number of fractions of a pixel, limiting the number of reduction kernels calculated by the windowed compressed reduction for scans that are incommensurate with the grid of the scattering matrix. The maximum position error is half a quantization step. Only used when upsample=True. The default is None, ie. the positions are not quantized.

  • max_batch_expansion (int, optional) – The number of plane waves expanded at a time by the reduction of the compressed scattering matrix. By default the full plane-wave expansion is materialized once (fastest, but with the memory footprint of a PRISM scattering matrix at interpolation 1); providing a batch size streams the expansion instead, bounding the memory at one batch of plane waves plus one batch of reduced wave functions, at the cost of repeating the expansion for every batch of probe positions. Only used when upsample=True and the reduced wave functions are not cropped.

  • downsample ({'cutoff', 'valid'} or float or bool) –

    Controls whether to downsample the scattering matrix after running the multislice algorithm.

    cutoff :

    Downsample to the antialias cutoff scattering angle (default).

    valid :

    Downsample to the largest rectangle that fits inside the circle with a radius defined by the antialias cutoff scattering angle.

    float :

    Downsample to a specified maximum scattering angle [mrad].

  • device (str, optional) – The calculations will be carried out on this device (‘cpu’ or ‘gpu’). Default is ‘cpu’. The default is determined by the user configuration.

  • store_on_host (bool, optional) – If True, store the scattering matrix in host (cpu) memory so that the necessary memory is transferred as chunks to the device to run calculations (default is False).

Initialization

property base_shape: tuple[int, int, int]#

Shape of the base axes of the SMatrix.

property blend_angle: float | str | None#

Scattering angle [mrad] above which the reduction follows the plane-wave (PRISM) reduction of the built beams; ‘auto’ derives it from the aliasing limit of the interpolation, None disables blending.

build(...) → SMatrixArray | CompressedSMatrixArray[source]#

Build the plane waves of the scattering matrix and propagate them through the potential using the multislice algorithm.

When upsample=True, the scattering matrix is subsequently compressed by phase removal, interpolation to the full plane-wave expansion and an adaptive truncated singular value decomposition, and a CompressedSMatrixArray is returned. The multislice stage may be computed lazily, however, the compression requires the scattering matrix in memory, hence the returned CompressedSMatrixArray is always computed. At an interpolation factor of (1, 1) the plane-wave expansion is complete, hence the compression provides no benefit and the uncompressed SMatrixArray is returned; the reduction is then identical to the PRISM algorithm.

Parameters:

  • lazy (bool, optional) – If True, create the wave functions lazily, otherwise, calculate instantly. If not given, defaults to the setting in the user configuration file.

  • max_batch (int or str, optional) – The number of expansion plane waves in each run of the multislice algorithm.

Returns:

s_matrix_array – The built scattering matrix.

Return type:

SMatrixArray or CompressedSMatrixArray

property downsample: str | bool#

How to downsample the scattering matrix after running the multislice algorithm.

property downsampled_gpts: tuple[int, int]#

The gpts of the SMatrix after downsampling. When upsampling, the downsampled gpts are independent of the interpolation factor, hence probe positions commensurate with the grid remain commensurate at any interpolation.

property ensemble_axes_metadata#

Axis metadata for each ensemble axis.

property ensemble_shape: tuple[int, ...]#

Shape of the SMatrix ensemble axes.

property interpolation: tuple[int, int]#
property max_batch_expansion: int | str#

Number of plane waves expanded at a time by the reduction of the compressed scattering matrix; ‘auto’ materializes the full expansion.

property max_rank: int | None#

Maximum number of retained modes, or None to keep every one.

The rank sets both the memory of the compressed scattering matrix and the cost of its reduction, and is the parameter to lower on a small device.

property metadata#
multislice(...)[source]#
Parameters:

  • potential

  • lazy (bool, optional) – If True, create the wave functions lazily, otherwise, calculate instantly. If not given, defaults to the setting in the user configuration file.

  • max_batch (int or str, optional) – The number of expansion plane waves in each run of the multislice algorithm.

property position_quantization: int | None#

Quantization of the fractional probe positions in fractions of a pixel.

property potential: BasePotential#

The potential described by the SMatrix.

reduce(...) → BaseMeasurements | Waves | list[BaseMeasurements | Waves][source]#

Run the multislice algorithm, then reduce the SMatrix using coefficients calculated by a BaseScan and a CTF, to obtain the exit wave functions at given initial probe positions and aberrations.

Parameters:

  • scan (BaseScan) – Positions of the probe wave functions. If not given, scans across the entire potential at Nyquist sampling.

  • detectors (BaseDetector, list of BaseDetector, optional) – A detector or a list of detectors defining how the wave functions should be converted to measurements after running the multislice algorithm. See abtem.measurements.detect for a list of implemented detectors.

  • ctf (CTF) – Contrast transfer function from used for calculating the expansion coefficients in the reduction of the SMatrix.

  • max_batch_multislice (int, optional) – The number of wave functions in each chunk of the Dask array. If ‘auto’ (default), the batch size is automatically chosen based on the abTEM user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • max_batch_reduction (int or str, optional) – Number of positions per reduction operation. A large number of positions better utilize thread parallelization, but requires more memory and floating point operations. If ‘auto’ (default), the batch size is automatically chosen based on the abtem user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • reduction_scheme (str, optional) – Parallel reduction of the SMatrix requires rechunking the Dask array from chunking along the expansion axis to chunking over the spatial axes. If given as a tuple of int of length the SMatrix is rechunked to have those chunks. If ‘auto’ (default) the chunks are taken to be identical to the interpolation factor.

  • disable_s_matrix_chunks (bool, optional) – If True, each S-Matrix is kept as a single chunk, thus lowering the communication overhead, but providing fewer opportunities for parallelization.

  • lazy (bool, optional) – If True, create the measurements lazily, otherwise, calculate instantly. If None, this defaults to the value set in the configuration file.

Returns:

  • measurements (BaseMeasurements or Waves or list of BaseMeasurements or list of)

  • Waves – The detected measurement (if detector(s) given).

round_gpts_to_interpolation() → SMatrix[source]#

Round the gpts of the SMatrix to the closest multiple of the interpolation factor.

Returns:

s_matrix_with_rounded_gpts

Return type:

SMatrix

scan(...) → BaseMeasurements | Waves | list[BaseMeasurements | Waves][source]#

Run the multislice algorithm, then reduce the SMatrix using coefficients calculated by a BaseScan and a CTF, to obtain the exit wave functions at given initial probe positions and aberrations.

Parameters:

  • scan (BaseScan) – Positions of the probe wave functions. If not given, scans across the entire potential at Nyquist sampling.

  • detectors (BaseDetector, list of BaseDetector, optional) – A detector or a list of detectors defining how the wave functions should be converted to measurements after running the multislice algorithm. See abtem.measurements.detect for a list of implemented detectors.

  • ctf (CTF) – Contrast transfer function from used for calculating the expansion coefficients in the reduction of the SMatrix.

  • max_batch_multislice (int, optional) – The number of wave functions in each chunk of the Dask array. If ‘auto’ (default), the batch size is automatically chosen based on the abTEM user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • max_batch_reduction (int or str, optional) – Number of positions per reduction operation. A large number of positions better utilize thread parallelization, but requires more memory and floating point operations. If ‘auto’ (default), the batch size is automatically chosen based on the abtem user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • reduction_scheme (str or tuple of int, optional) – Parallel reduction of the SMatrix requires rechunking the Dask array from chunking along the expansion axis to chunking over the spatial axes. If given as a tuple of int of length the SMatrix is rechunked to have those chunks. If ‘auto’ (default) the chunks are taken to be identical to the interpolation factor.

  • disable_s_matrix_chunks (bool, optional) – If True, each S-Matrix is kept as a single chunk, thus lowering the communication overhead, but providing fewer opportunities for parallelization.

  • lazy (bool, optional) – If True, create the measurements lazily, otherwise, calculate instantly. If None, this defaults to the value set in the configuration file.

Returns:

  • detected_waves (BaseMeasurements or list of BaseMeasurements) – The detected measurement (if detector(s) given).

  • exit_waves (Waves) – Wave functions at the exit plane(s) of the potential (if no detector(s) given).

property semiangle_cutoff: float#

Plane-wave expansion cutoff.

property shape: tuple[int, ...]#

Shape of the SMatrix.

property store_on_host: bool#

Store the SMatrix in host memory. The reduction may still be calculated on the device.

property tilt#

The small-angle tilt of applied to the Fresnel propagator [mrad].

property tolerance: float#

Relative singular value threshold applied to the part of the interpolated scattering matrix that the built beams do not already span. The row space of the built beams is retained whole regardless, so this does not lower the rank below their number — see max_rank.

transition_potential_scan(...)[source]#

Experimental PRISM-based core-loss scan.

Mirrors Probe.transition_potential_scan() but uses the S-matrix plane-wave decomposition instead of running a full multislice per scan position. Supports any interpolation factor and both single- and double-channel modes. At interpolation=(1, 1) the result is bit-equivalent to Probe.transition_potential_scan (float32 noise) against the matching double_channel setting. At interpolation > 1 the reduced wave functions are returned at window_gpts size, matching the elastic scan() convention.

See abtem.inelastic.core_loss.prism_transition_potential_scan() for the algorithm details.

Parameters:

  • transition_potentials (BaseTransitionPotential) – Atomic transition potential (single instance).

  • scan (BaseScan or tuple, optional) – Scan positions. Defaults to a GridScan over the full extent at Nyquist sampling, mirroring scan().

  • detectors (BaseDetector or list, optional) – Detectors. Defaults to a FlexibleAnnularDetector.

  • sites (Atoms or SliceIndexedAtoms, optional) – Scattering sites. Auto-extracted from the potential if not given.

  • double_channel (bool, optional) – If True, propagate the scattered wave through the remaining potential slices to the exit before detection (matching the multislice EELS double_channel=True branch). If False (default), detect immediately at the scatter slice — Brown’s single-channel approximation.

  • inelastic_crop (float or tuple of float, optional) – Real-space side length [Å] of the window on which the transition potential and scattered wave are evaluated (Brown et al. Sec. IV B). Smaller windows speed up the scatter and double-channel propagation at the cost of truncating the transition-potential tails. Defaults to None (the full PRISM cell, extent / interpolation). Values larger than the PRISM cell are clamped with a warning.

  • lazy (bool, optional) – If True, create the measurements lazily using Dask; otherwise, compute eagerly. Defaults to the user configuration value.

Returns:

One measurement per detector.

Return type:

BaseMeasurements or list of BaseMeasurements

property upsample: bool#

Interpolate the coarse plane-wave expansion back to the full expansion of the aperture and compress it (the C-PRISM algorithm).

property wave_vectors: ndarray#

The wave vectors of the plane-wave expansion. When upsampling, the coarse expansion spans a disk around the aperture (see _coarse_mask()), padding it by a support margin so that the interpolation of the compressed modes is supported on all sides.

property window_extent#
property window_gpts#

The number of grid points describing the cropping window of the reduced wave functions.

class abtem.prism.s_matrix.SMatrixArray(...)[source]#

Bases: abtem.prism.s_matrix.BaseSMatrix, abtem.array.ArrayObject

A scattering matrix defined by a given array of dimension 3, where the first indexes the probe plane waves and the latter two are the y and x scan directions.

Parameters:

  • array (ndarray) – Array defining the scattering matrix. Must be 3D or higher, dimensions before the last three dimensions should represent ensemble dimensions, the next dimension indexes the plane waves and the last two dimensions represent the spatial extent of the plane waves.

  • wave_vectors (ndarray) – Array defining the wave vectors corresponding to each plane wave. Must have shape Nx2, where N is equal to the number of plane waves.

  • semiangle_cutoff (float) – The radial cutoff of the plane-wave expansion [mrad].

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

  • sampling (one or two float, optional) – Lateral sampling of wave functions [Å]. Provide only if potential is not given. Will be ignored if ‘gpts’ is also provided.

  • extent (one or two float, optional) – Lateral extent of wave functions [Å]. Provide only if potential is not given.

  • interpolation (one or two int, optional) – Interpolation factor in the x and y directions (default is 1, ie. no interpolation). If a single value is provided, assumed to be the same for both directions.

  • window_gpts (tuple of int) – The number of grid points describing the cropping window of the wave functions.

  • window_offset (tuple of int) – The number of grid points from the origin the cropping windows of the wave functions is displaced.

  • periodic (tuple of bool) – Specifies whether the SMatrix should be assumed to be periodic along the x and y-axis.

  • device (str, optional) – The calculations will be carried out on this device (‘cpu’ or ‘gpu’). Default is ‘cpu’. The default is determined by the user configuration.

  • 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

copy_to_device(...) → SMatrixArray[source]#

Copy SMatrixArray to specified device.

property device#

The device on which the SMatrixArray is reduced.

property ensemble_axes_metadata: list[AxisMetadata]#

Axis metadata for each ensemble axis.

property ensemble_shape: tuple[int, int]#
abstract from_array_and_metadata(...)[source]#
property interpolation: tuple[int, int]#
property metadata: dict#
multislice(...) → SMatrixArray[source]#
Parameters:

potential

property periodic: tuple[bool, bool]#

If True the SMatrix is assumed to be periodic along corresponding axis.

rechunk(...)[source]#
reduce(...) → BaseMeasurements | Waves | list[BaseMeasurements | Waves][source]#

Scan the probe across the potential and record a measurement for each detector.

Parameters:

  • detectors (list of Detector objects) – The detectors recording the measurements.

  • scan (Scan object) – Scan defining the positions of the probe wave functions.

  • ctf (CTF object, optional) – The probe contrast transfer function. Default is None (aperture is set by the planewave cutoff).

  • max_batch_reduction (int or str, optional) – Number of positions per reduction operation. A large number of positions better utilize thread parallelization, but requires more memory and floating point operations. If ‘auto’ (default), the batch size is automatically chosen based on the abtem user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • rechunk (two int or str, optional) – Partitioning of the scan. The scattering matrix will be reduced in similarly partitioned chunks. Should be equal to or greater than the interpolation.

scan(...)[source]#

Reduce the SMatrix using coefficients calculated by a BaseScan and a CTF, to obtain the exit wave functions at given initial probe positions and aberrations.

Parameters:

  • scan (BaseScan) – Positions of the probe wave functions. If not given, scans across the entire potential at Nyquist sampling.

  • detectors (BaseDetector, list of BaseDetector, optional) – A detector or a list of detectors defining how the wave functions should be converted to measurements after running the multislice algorithm. See abtem.measurements.detect for a list of implemented detectors.

  • ctf (CTF) – Contrast transfer function from used for calculating the expansion coefficients in the reduction of the SMatrix.

  • max_batch_reduction (int or str, optional) – Number of positions per reduction operation. A large number of positions better utilize thread parallelization, but requires more memory and floating point operations. If ‘auto’ (default), the batch size is automatically chosen based on the abtem user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

  • rechunk (str or tuple of int, optional) – Parallel reduction of the SMatrix requires rechunking the Dask array from chunking along the expansion axis to chunking over the spatial axes. If given as a tuple of int of length the SMatrix is rechunked to have those chunks. If ‘auto’ (default) the chunks are taken to be identical to the interpolation factor.

Returns:

  • detected_waves (BaseMeasurements or list of BaseMeasurements) – The detected measurement (if detector(s) given).

  • exit_waves (Waves) – Wave functions at the exit plane(s) of the potential (if no detector(s) given).

property semiangle_cutoff: float#

The cutoff semiangle of the plane wave expansion.

property storage_device#

The device on which the SMatrixArray is stored.

property wave_vectors: ndarray#
property waves: Waves#

The wave vectors describing each plane wave.

property window_extent: tuple[float, float]#
property window_gpts: tuple[int, int]#
property window_offset: tuple[float, float]#

The number of grid points from the origin the cropping windows of the wave functions is displaced.

Contents