abtem.scan

abtem.scan#

Module for describing different types of scans.

Module Contents#

Classes#

BaseScan

Abstract class to describe scans.

CustomScan

Custom scan based on explicit 2D probe positions.

GridScan

A scan over a regular grid for calculating scanning transmission electron microscopy.

LineScan

A scan along a straight line.

Functions#

validate_coordinate

validate_scan

Validate that the input is a valid scan or a sequence of valid scan positions.

Data#

ScanWithSampling

API#

class abtem.scan.BaseScan(...)[source]#

Bases: abtem.transform.ReciprocalSpaceMultiplication

Abstract class to describe scans.

Initialization

property ensemble_shape: tuple[int, ...]#
abstract get_positions(...) → ndarray[source]#

Get the scan positions as numpy array.

abstract property limits#

Lower left and upper right corner of the bounding box containing all positions in the scan.

abstract match_probe(...)[source]#

Match the scan to a probe or s-matrix.

property num_positions: int#

Number of probe positions in the scan.

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

The shape the scan.

class abtem.scan.CustomScan(...)[source]#

Bases: abtem.scan.BaseScan

Custom scan based on explicit 2D probe positions.

Parameters:

positions (ndarray, optional) – Scan positions [Å]. Anything that can be converted to a ndarray of shape (n, 2) is accepted. Default is (0., 0.).

Initialization

add_to_plot(...)[source]#

Add a visualization of the scan positions to a matplotlib plot.

Parameters:

  • ax (matplotlib Axes or Visualization) – The axes of the matplotlib plot the visualization should be added to.

  • kwargs – Additional options for matplotlib.pyplot.scatter as keyword arguments.

property ensemble_axes_metadata#
get_positions() → ndarray[source]#
property limits#
match_probe(...)[source]#

Sets the positions to a single position in the center of the probe extent.

Parameters:

probe (Probe or BaseSMatrix) – The matched probe or s-matrix.

property positions#

Scan positions [Å].

property shape#
class abtem.scan.GridScan(...)[source]#

Bases: abtem.core.grid.HasGrid2DMixin, abtem.scan.BaseScan

A scan over a regular grid for calculating scanning transmission electron microscopy.

Parameters:

  • start (two float or Atom, optional) – Start corner of the scan [Å]. May be given as fractional coordinate if fractional=True. Default is (0., 0.).

  • end (two float or Atom, optional) – End corner of the scan [Å]. May be given as fractional coordinate if fractional=True. Default is None, the scan end point will match the extent of the potential.

  • gpts (two int, optional) – Number of scan positions in the x- and y-direction of the scan. Provide one of gpts or sampling.

  • sampling (two float, optional) – Sampling rate of scan positions [1 / Å]. Provide one of gpts or sampling. If not provided the sampling will match the Nyquist sampling of the Probe in a multislice simulation.

  • endpoint (bool, optional) – If True, end is the last position. Otherwise, it is not included. Default is False.

  • fractional (bool, optional) – If True, use fractional coordinates with respect to the given potential for start and end.

  • potential (BasePotential or Atoms, optional) – Potential defining the grid with respect to which the fractional coordinates should be given.

Initialization

add_to_plot(...)[source]#

Add a visualization of the scan area to a matplotlib plot.

Parameters:

  • ax (matplotlib Axes) – The axes of the matplotlib plot the visualization should be added to.

  • alpha (float, optional) – Transparency of the scan area visualization. Default is 0.33.

  • facecolor (str, optional) – Color of the scan area visualization.

  • edgecolor (str, optional) – Color of the edge of the scan area visualization.

  • kwargs – Additional options for matplotlib.patches.Rectangle used for scan area visualization as keyword arguments.

classmethod commensurate(...) → GridScan[source]#

Create a grid scan whose step is a whole number of pixels of the grid the given scattering matrix is reduced on.

Scattering-matrix reductions with upsample=True are much faster for such scans, since every probe position falls on the pixel grid of the reduced wave functions. The requested number of positions or sampling is snapped to the nearest whole-pixel step; when the scanned span is itself a whole number of pixels, the step is snapped to a divisor of the span so the scan tiles it exactly, otherwise the end point is moved to the nearest lattice point.

Parameters:

  • matrix (BaseSMatrix or BasePotential or Atoms) – The scattering matrix (built or not) whose reduction grid the scan steps along. Given a potential, the grid of a scattering matrix with default downsampling is assumed.

  • gpts (one or two int, optional) – Requested number of scan positions in the x- and y-direction. Provide either gpts or sampling.

  • sampling (one or two float, optional) – Requested sampling rate of the scan positions [Å]. Provide either gpts or sampling.

  • start (one or two float or Atom, optional) – Start corner of the scan [Å]. Default is (0., 0.).

  • end (one or two float or Atom, optional) – End corner of the scan [Å] (not included, as for endpoint=False). Default is the scanned extent.

property end: tuple[float, float] | None#

End corner of the scan [Å].

property endpoint: tuple[bool, bool]#

True if the scan endpoint is the last position. Otherwise, the endpoint is not included.

property ensemble_axes_metadata#
property ensemble_shape#
get_positions() → ndarray[source]#
property limits#
match_probe(...)[source]#

Sets sampling to the Nyquist frequency. If the start and end point of the scan is not given, set them to the lower left and upper right corners of the probe extent.

Parameters:

probe (Probe or BaseSMatrix) – The matched probe or s-matrix.

property shape: tuple[int, int]#
property start: tuple[float, float] | None#

Start corner of the scan [Å].

class abtem.scan.LineScan(...)[source]#

Bases: abtem.scan.BaseScan

A scan along a straight line.

Parameters:

  • start (two float or Atom, optional) – Start point of the scan [Å]. May be given as fractional coordinate if fractional=True. Default is (0., 0.).

  • end (two float or Atom, optional) – End point of the scan [Å]. May be given as fractional coordinate if fractional=True. Default is None, the scan end point will match the extent of the potential.

  • gpts (int, optional) – Number of scan positions. Default is None. Provide one of gpts or sampling.

  • sampling (float, optional) – Sampling rate of scan positions [1 / Å]. Provide one of gpts or sampling. If not provided the sampling will match the Nyquist sampling of the Probe in a multislice simulation.

  • endpoint (bool, optional) – If True, end is the last position. Otherwise, it is not included. Default is True.

  • fractional (bool, optional) – If True, use fractional coordinates with respect to the given potential for start and end.

  • potential (BasePotential or Atoms, optional) – Potential defining the grid with respect to which the fractional coordinates should be given.

Initialization

add_margin(...)[source]#

Extend the line scan by adding a margin to the start and end of the line scan.

Parameters:

margin (float or tuple of float) – The margin added to the start and end of the linescan [Å]. If float the same margin is added.

add_to_axes(...)[source]#

Deprecated: use add_to_plot() instead.

add_to_plot(...)[source]#

Add a visualization of a scan line to a matplotlib plot.

Parameters:

  • ax (matplotlib Axes or Visualization) – The axes of the matplotlib plot the visualization should be added to.

  • width (float, optional) – Width of line [Å].

  • kwargs – Additional options for matplotlib.pyplot.plot as keyword arguments.

property angle#

Angle of the line from start to end and the x-axis [deg.].

classmethod at_position(...)[source]#

Make a line scan centered at a given position.

Parameters:

  • center (two float) – Center position of the line [Å]. May be given as an Atom.

  • angle (float) – Angle of the line [deg.].

  • extent (float) – Extent of the line [Å].

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

  • sampling (float) – Sampling of grid points along the line [Å].

  • endpoint (bool) – Sets whether the ending position is included or not.

Returns:

line_scan

Return type:

LineScan

property direction#

Normal vector pointing from start to end.

property end: tuple[float, float] | None#

End point of the scan [Å].

property endpoint: bool#

True if the scan endpoint is the last position. Otherwise, the endpoint is not included.

property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape#
property extent: float | None#

Grid extent [Å].

get_positions(...) → ndarray[source]#
property gpts: int | None#

Number of grid points.

property limits: Tuple[Optional[Tuple[float, float]], Optional[Tuple[float, float]]]#
match_probe(...)[source]#

Sets sampling to the Nyquist frequency. If the start and end point of the scan is not given, set them to the lower and upper left corners of the probe extent.

Parameters:

probe (Probe or BaseSMatrix) – The matched probe or s-matrix.

property metadata#
property sampling: float | None#

Grid sampling [Å].

property shape: tuple[int]#
property start: tuple[float, float] | None#

Start point of the scan [Å].

abtem.scan.ScanWithSampling#

None

abtem.scan.validate_coordinate(...) → tuple[float, float] | None[source]#
abtem.scan.validate_scan(...) → BaseScan[source]#

Validate that the input is a valid scan or a sequence of valid scan positions.

Parameters:

  • scan (Sequence or ndarray or BaseScan) – The scan or scan positions to validate. If None, a scan with a single position at (0, 0) is returned.

  • probe (Probe or None) – If given the scan is matched to the extent of the probe.

Returns:

validated_scan – The validated scan object.

Return type:

BaseScan