abtem.core.grid

Module for the Grid class and related functions.

Module Contents

Classes

Grid	The Grid object represent the simulation grid on which the wave functions and potential are discretized.
HasGrid2DMixin

Functions

adjusted_gpts	Adjust the number of grid points to match a target sampling.
coordinate_grid
disk_meshgrid	Return all indices inside a disk with a given radius.
disk_meshgrid_iter	Yield chunks of disk indices without building the full (2r+1)² array.
polar_spatial_frequencies	Return the polar spatial frequencies of a grid.
real_space_grid
round_auto_derived_gpts	Whether grids abTEM derives on its own are rounded to fast FFT lengths.
spatial_frequencies	Return the spatial frequencies of a grid.
validate_gpts	Ensure that the prodived grid points are valid.

Data

T
U

API

class abtem.core.grid.Grid(...)

Bases: abtem.core.utils.CopyMixin, abtem.core.utils.EqualityMixin

The Grid object represent the simulation grid on which the wave functions and potential are discretized.

Parameters:

• extent (two float) – Grid extent in each dimension [Å].

• gpts (two int) – Number of grid points in each dimension.

• sampling (two float) – Grid sampling in each dimension [Å].

• dimensions (int) – Number of dimensions represented by the grid.

• endpoint (bool) – If true include the grid endpoint. Default is False. For periodic grids the endpoint should not be included.

• lock_extent (bool) – If true the extent cannot be modified. Default is False.

• lock_gpts (bool) – If true the gpts cannot be modified. Default is False.

• lock_sampling (bool) – If true the sampling cannot be modified. Default is False.

Initialization

check_is_defined(...)

Raise error if the grid is not defined.

check_match(...)

Raise error if the grid of another object is different from this object.

Parameters:

other (Grid object) – The grid that should be checked.

property dimensions: int

Number of dimensions represented by the grid.

property endpoint: tuple[bool] | tuple[bool, bool] | tuple[bool, ...]

Include the grid endpoint.

property extent: tuple[float, ...] | None

Grid extent in each dimension [Å].

property gpts: tuple[int, ...] | None

Number of grid points in each dimension.

match(...)

Set the parameters of this grid to match another grid.

Parameters:

• other (Grid object) – The grid that should be matched.

• check_match (bool) – If true check whether grids can match without overriding already defined grid parameters.

property reciprocal_space_sampling: tuple[float, ...]

Reciprocal-space sampling [1/Å].

round_to_fast_fft() → tuple[int, ...]

Round the grid gpts up to the nearest fast FFT lengths.

Fast lengths factorize completely into the primes 2, 3, 5 and 7, for which FFT libraries (FFTW, pocketfft, MKL and cuFFT) ship optimized kernels; any other length falls back to a slower generic algorithm – on cuFFT the Bluestein algorithm, which additionally allocates a workspace of several times the transform size. Rounding is always upward, so the realized sampling is never coarser than before.

Every gpts is rounded, including on an endpoint grid – unlike the automatic rounding, which leaves endpoint grids alone because they are not periodic FFT grids.

Automatic rounding is governed by the configuration option grid.round-to-fast-fft: 'auto' (the default) rounds the grids abTEM derives on its own, such as Potential(sampling='auto'); True additionally rounds gpts derived from a numeric sampling; False disables it everywhere.

Grids that are never Fourier transformed (fft_grid=False, e.g. the probe positions of a GridScan) are returned unchanged: a fast length buys them nothing, and changing them would change what is simulated rather than how fast it runs.

Returns:

The rounded gpts.

Return type:

tuple of int

round_to_power(...) → tuple[int, ...]

Round the grid gpts up to a whole power of one of the given bases.

Each gpts becomes base ** k for whichever base gives the smallest such value at or above it – a pure power, not a product of several bases, so 2623 rounds to 4096 rather than to 2625. That is a much larger grid than fast FFTs actually require: see round_to_fast_fft(), which rounds to the nearest length whose prime factors all lie in {2, 3, 5, 7} and is what “faster for arrays whose size factorizes into small primes” normally means.

(For a handful of inputs that are already exact powers of 5 or 7 – 125, 15625, 16807 – floating-point log rounds the exponent up and the result overshoots to the next power.)

Parameters:

powers (int or list of int, optional) – The bases to consider. Default [2, 3, 5, 7].

property sampling: tuple[float, ...] | None

Grid sampling in each dimension [Å].

spatial_frequencies()

exception abtem.core.grid.GridUndefinedError

Bases: Exception

Exception raised when the grid is not defined.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class abtem.core.grid.HasGrid2DMixin

property extent: tuple[float, float] | None

Extent of grid for each dimension in Ångstrom.

property gpts: tuple[int, int] | None

Number of grid points for each dimension.

property grid: Grid

Simulation grid.

match_grid(...)

Match the grid to another object with a Grid.

property reciprocal_space_sampling: tuple[float, float]

Reciprocal-space sampling in reciprocal Ångstrom.

property sampling: tuple[float, float] | None

Grid sampling for each dimension in Ångstrom per grid point.

abtem.core.grid.T

‘TypeVar(…)’

abtem.core.grid.U

‘TypeVar(…)’

abtem.core.grid.adjusted_gpts(...) → tuple[tuple[float, ...], tuple[int, ...]]

Adjust the number of grid points to match a target sampling.

Parameters:

• target_sampling (tuple of float) – The target sampling [Å].

• old_sampling (tuple of float) – The old sampling [Å].

• old_gpts (tuple of int) – The old number of grid points.

Returns:

The new sampling [Å].

Return type:

tuple of float

abtem.core.grid.coordinate_grid(...) → tuple[ndarray, ...]

abtem.core.grid.disk_meshgrid(...) → ndarray

Return all indices inside a disk with a given radius.

Parameters:

r (int) – Radius of disc in pixels.

Returns:

disc_indices

Return type:

ndarray

abtem.core.grid.disk_meshgrid_iter(...)

Yield chunks of disk indices without building the full (2r+1)² array.

For large radii the standard disk_meshgrid() allocates two (2r+1, 2r+1) intermediate arrays on the CPU and a single output that can each be many gigabytes. This generator builds the result row-by-row and yields it in manageable chunks of at most chunk_size (row, col) pairs.

Parameters:

• r (int) – Disk radius in pixels.

• chunk_size (int, optional) – Maximum number of (row, col) pairs per yielded chunk.

Yields:

numpy.ndarray – (N, 2) int32 array of (row_offset, col_offset) pairs where row_offset² + col_offset² <= r².

abtem.core.grid.polar_spatial_frequencies(...) → tuple[ndarray, ndarray]

Return the polar spatial frequencies of a grid.

Parameters:

• gpts (tuple of int) – Number of grid points.

• sampling (tuple of float) – Sampling of the potential [1 / Å].

• xp (module) – Array module to use, options are numpy or cupy. Default is numpy.

Returns:

k_and_phi – Tuple of spatial frequencies in polar coordinates. First element is the radial frequency and the second element is the azimuthal angle.

Return type:

tuple of ndarray

abtem.core.grid.real_space_grid(...)

abtem.core.grid.round_auto_derived_gpts() → bool

Whether grids abTEM derives on its own are rounded to fast FFT lengths.

This covers grids abTEM chooses without a user-supplied sampling, such as Potential(..., sampling='auto'). Grids derived from a numeric sampling are governed separately (they are only rounded in the 'always' mode), because rounding those changes the result of an existing script.

abtem.core.grid.spatial_frequencies(...)

Return the spatial frequencies of a grid.

Parameters:

• gpts (tuple of int) – Number of grid points.

• sampling (tuple of float) – Sampling of the grid [Å].

• return_grid (bool) – If True, return the grid as a single meshgrid array.

• xp (module) – Array module to use, options are numpy or cupy. Default is numpy.

Returns:

• spatial_frequencies (tuple of numpy.ndarray) – Tuple of spatial frequencies in each dimension.

• spatial_frequencies_grid (numpy.ndarray) – If return_grid is True, the spatial frequencies as a single meshgrid array.

abtem.core.grid.validate_gpts(...) → tuple[int, ...]

Ensure that the prodived grid points are valid.

Parameters:

gpts (tuple of int) – The tuple of integers representing the GPTs (General Purpose Tokens).

Returns:

The validated tuple of integers representing the GPTs.

Return type:

tuple of int

Raises:

ValueError – If any value in the gpts tuple is not greater than 0.