PotentialArray

class abtem.potentials.iam.PotentialArray(array, slice_thickness, extent=None, sampling=None, exit_planes=None, ensemble_axes_metadata=None, metadata=None)

Bases: BasePotential, FieldArray

The potential array represents slices of the electrostatic potential as an array. All other potentials build potential arrays.

Parameters:

• array (3D np.ndarray) – The array representing the potential slices. The first dimension is the slice index and the last two are the spatial dimensions.

• slice_thickness (float) – The thicknesses of potential slices [Å]. If a float, the thickness is the same for all slices. If a sequence, the length must equal the length of the potential array.

• extent (one or two float, optional) – Lateral extent of the potential [Å].

• sampling (one or two float, optional) – Lateral sampling of the potential [1 / Å].

• exit_planes (int or tuple of int, optional) – The exit_planes argument can be used to calculate thickness series. Providing exit_planes as a tuple of int indicates that the tuple contains the slice indices after which an exit plane is desired, and hence during a multislice simulation a measurement is created. If exit_planes is an integer a measurement will be collected every exit_planes number of slices.

• 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.

__init__(array, slice_thickness, extent=None, sampling=None, exit_planes=None, ensemble_axes_metadata=None, metadata=None)

Methods

__init__(array, slice_thickness[, extent, ...])
apply_func(func, **kwargs)	Apply a function to the array object.
apply_transform(transform[, max_batch])	Transform the wave functions by a given transformation.
build([first_slice, last_slice, chunks, lazy])
compute([progress_bar, profiler, ...])	Turn a lazy *ab*TEM object into its in-memory equivalent.
copy()	Make a copy.
copy_to_device(device)	Copy array to specified device.
ensemble_blocks([chunks])	Split the ensemble into an array of smaller ensembles.
ensure_lazy([chunks])	Creates an equivalent lazy version of the array object.
expand_dims([axis, axis_metadata])	Expand the shape of the array object.
from_array_and_metadata(array, ...)	Creates array object from a given array and metadata.
from_zarr(url[, chunks])	Read wave functions from a hdf5 file.
generate_blocks([chunks])	Generate chunks of the ensemble.
generate_slices([first_slice, last_slice])	Generate the slices for the potential.
get_from_metadata(name[, broadcastable])
get_items(items[, keepdims])	Index the array and the corresponding axes metadata.
lazy([chunks])
match_grid(other[, check_match])	Match the grid to another object with a Grid.
max([axis, keepdims, split_every])	Maximum of array object over one or more axes.
mean([axis, keepdims, split_every])	Mean of array object over one or more axes.
min([axis, keepdims, split_every])	Minmimum of array object over one or more axes.
no_base_chunks()	Rechunk to remove chunks across the base dimensions.
project()	Create a 2D array representing a projected image of the potential(s).
rechunk(chunks, **kwargs)	Rechunk dask array.
set_ensemble_axes_metadata(axes_metadata, axis)	Sets the axes metadata of an ensemble axis.
show([project])	Show the potential projection.
squeeze([axis])	Remove axes of length one from array object.
std([axis, keepdims, split_every])	Standard deviation of array object over one or more axes.
sum([axis, keepdims, split_every])	Sum of array object over one or more axes.
tile(repetitions)	Tile the potential.
to_cpu()	Move the array to the host memory from an arbitrary source array.
to_data_array()	Convert ArrayObject to a xarray DataArray.
to_gpu([device])	Move the array from the host memory to a gpu.
to_hyperspy([transpose])	Convert ArrayObject to a Hyperspy signal.
to_images()	Convert slices of the potential to a stack of images.
to_tiff(filename, **kwargs)	Write data to a tiff file.
to_zarr(url[, compute, overwrite])	Write data to a zarr file.
transmission_function(energy)	Calculate the transmission functions for each slice for a specific energy.
transmit(waves[, conjugate])	Transmit a wave function through a potential slice.

Attributes

array	Underlying array describing the array object.
axes_metadata	List of AxisMetadata.
base_axes_metadata	List of AxisMetadata for the base axes.
base_dims	Number of base dimensions.
base_shape	Shape of the base axes of the potential.
device	The device where the array is stored.
dtype	Datatype of array.
ensemble_axes_metadata	List of AxisMetadata of the ensemble axes.
ensemble_dims	Number of ensemble dimensions.
ensemble_shape	Shape of the ensemble axes of the underlying array.
exit_planes	The "exit planes" of the potential.
exit_thicknesses	The "exit thicknesses" of the potential.
extent	Extent of grid for each dimension in Ångstrom.
gpts	Number of grid points for each dimension.
grid	Simulation grid.
is_complex	True if array is complex.
is_lazy	True if array is lazy.
metadata	Metadata stored as a dictionary.
num_configurations	Number of frozen phonons in the ensemble of potentials.
num_exit_planes	Number of exit planes.
num_slices	Number of projected potential slices.
reciprocal_space_sampling	Reciprocal-space sampling in reciprocal Ångstrom.
sampling	Grid sampling for each dimension in Ångstrom per grid point.
shape	Shape of the underlying array.
slice_limits	The entrance and exit thicknesses of each slice [Å].
slice_thickness	Slice thicknesses for each slice.
thickness	Thickness of the potential [Å].

apply_func(func, **kwargs)

Apply a function to the array object. The function must take an array as its first argument, only the array is modified, the metadata is not changed. The function is applied lazily if the array object is lazy.

Parameters:

• func (callable) – Function to apply to the array object.

• kwargs – Additional keyword arguments passed to the function.

Returns:

array_object – The array object with the function applied.

Return type:

ArrayObject or subclass of ArrayObject

apply_transform(transform, max_batch='auto')

Transform the wave functions by a given transformation.

Parameters:

• transform (ArrayObjectTransform) – The array object transformation to apply.

• max_batch (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”.

Returns:

transformed_array_object – The transformed array object.

Return type:

ArrayObject

property array: ndarray | Array

Underlying array describing the array object.

property axes_metadata: AxesMetadataList

List of AxisMetadata.

property base_axes_metadata

List of AxisMetadata for the base axes.

property base_dims: int

Number of base dimensions.

property base_shape

Shape of the base axes of the potential.

compute(progress_bar=None, profiler=False, resource_profiler=False, **kwargs)

Turn a lazy *ab*TEM object into its in-memory equivalent.

Parameters:

• progress_bar (bool) – Display a progress bar in the terminal or notebook during computation. The progress bar is only displayed with a local scheduler.

• profiler (bool) – Return Profiler class used to profile Dask’s execution at the task level. Only execution with a local scheduler is profiled.

• resource_profiler (bool) – Return ResourceProfiler class used to profile Dask’s execution at the resource level.

• kwargs – Additional keyword arguments passed to dask.compute.

Return type:

Union[Self, tuple[Self, tuple]]

copy()

Make a copy.

Return type:

Self

copy_to_device(device)

Copy array to specified device.

Parameters:

device (str)

Returns:

object_on_device

Return type:

ArrayObject

property device: str

The device where the array is stored.

property dtype: dtype

Datatype of array.

property ensemble_axes_metadata: list[AxisMetadata]

List of AxisMetadata of the ensemble axes.

ensemble_blocks(chunks=None)

Split the ensemble into an array of smaller ensembles.

Parameters:

chunks (iterable of tuples) – Block sizes along each dimension.

Return type:

Array

property ensemble_dims: int

Number of ensemble dimensions.

property ensemble_shape: tuple[int, ...]

Shape of the ensemble axes of the underlying array.

ensure_lazy(chunks='auto')

Creates an equivalent lazy version of the array object.

Parameters:

chunks (int or tuple or str) – How to chunk the array. See dask.array.from_array.

Returns:

lazy_array_object – Lazy version of the array object.

Return type:

ArrayObject or subclass of ArrayObject

property exit_planes: tuple[int, ...]

The “exit planes” of the potential. The indices of slices where a measurement is returned.

property exit_thicknesses: tuple[float, ...]

The “exit thicknesses” of the potential. The thicknesses in the potential where a measurement is returned.

expand_dims(axis=None, axis_metadata=None)

Expand the shape of the array object.

Parameters:

• axis (int or tuple of ints) – Position in the expanded axes where the new axis (or axes) is placed.

• axis_metadata (AxisMetadata or List of AxisMetadata, optional) – The axis metadata describing the expanded axes. Default is UnknownAxis.

Returns:

expanded – View of array object with the number of dimensions increased.

Return type:

ArrayObject or subclass of ArrayObject

property extent: tuple[float, float] | None

Extent of grid for each dimension in Ångstrom.

classmethod from_array_and_metadata(array, axes_metadata, metadata)

Creates array object from a given array and metadata.

Parameters:

• array (ndarray) – Array defining the array object.

• axes_metadata (list of AxesMetadata) – Axis metadata for each axis. The axis metadata must be compatible with the shape of the array.

• metadata (dict) – A dictionary defining the metadata of the array object.

Returns:

array_object – The array object.

Return type:

ArrayObject or subclass of ArrayObject

classmethod from_zarr(url, chunks='auto')

Read wave functions from a hdf5 file.

Return type:

Self

urlstr

Location of the data, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data.

chunkstuple of ints or tuples of ints

Passed to dask.array.from_array(), allows setting the chunks on initialisation, if the chunking scheme in the on-disc dataset is not optimal for the calculations to follow.

generate_blocks(chunks=1)

Generate chunks of the ensemble.

Parameters:

chunks (iterable of tuples) – Block sizes along each dimension.

Return type:

Generator[tuple[tuple[int, ...], tuple[slice, ...], ndarray], None, None]

generate_slices(first_slice=0, last_slice=None)

Generate the slices for the potential.

Parameters:

• first_slice (int, optional) – Index of the first slice of the generated potential.

• last_slice (int, optional) – Index of the last slice of the generated potential.

Yields:

slices (generator of np.ndarray) – Generator for the array of slices.

get_items(items, keepdims=False)

Index the array and the corresponding axes metadata. Only ensemble axes can be indexed.

Parameters:

• items (int or tuple of int or slice) – The array is indexed according to this.

• keepdims (bool, optional) – If True, all ensemble axes are left in the result as dimensions with size one. Default is False.

Returns:

indexed_array – The indexed array object.

Return type:

ArrayObject or subclass of ArrayObject

property gpts: tuple[int, int] | None

Number of grid points for each dimension.

property grid: Grid

Simulation grid.

property is_complex: bool

True if array is complex.

property is_lazy: bool

True if array is lazy.

match_grid(other, check_match=False)

Match the grid to another object with a Grid.

max(axis=None, keepdims=False, split_every=2)

Maximum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters:

• axis (int or tuple of ints, optional) – Axis or axes along which a maxima are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the maxima are calculated over multiple axes. The indicated axes must be ensemble axes.

• keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.

• split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns:

reduced_array – The reduced array object.

Return type:

ArrayObject or subclass of ArrayObject

mean(axis=None, keepdims=False, split_every=2)

Mean of array object over one or more axes. Only ensemble axes can be reduced.

Parameters:

• axis (int or tuple of ints, optional) – Axis or axes along which a means are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the mean is calculated over multiple axes. The indicated axes must be ensemble axes.

• keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.

• split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns:

reduced_array – The reduced array object.

Return type:

ArrayObject or subclass of ArrayObject

property metadata: dict

Metadata stored as a dictionary.

min(axis=None, keepdims=False, split_every=2)

Minmimum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters:

• axis (int or tuple of ints, optional) – Axis or axes along which a minima are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the minima are calculated over multiple axes. The indicated axes must be ensemble axes.

• keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.

• split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns:

reduced_array – The reduced array object.

Return type:

ArrayObject or subclass of ArrayObject

no_base_chunks()

Rechunk to remove chunks across the base dimensions.

property num_configurations

Number of frozen phonons in the ensemble of potentials.

property num_exit_planes: int

Number of exit planes.

property num_slices: int

Number of projected potential slices.

project()

Create a 2D array representing a projected image of the potential(s).

Returns:

images – One or more images of the projected potential(s).

Return type:

Images

rechunk(chunks, **kwargs)

Rechunk dask array.

Return type:

ArrayObject

chunksint or tuple or str

How to rechunk the array. See dask.array.rechunk.

kwargs :

Additional keyword arguments passes to dask.array.rechunk.

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.

set_ensemble_axes_metadata(axes_metadata, axis)

Sets the axes metadata of an ensemble axis.

Parameters:

• axes_metadata (AxisMetadata) – The new axis metadata.

• axis (int) – The axis to set.

Return type:

Self

property shape: tuple[int, ...]

Shape of the underlying array.

show(project=True, **kwargs)

Show the potential projection. This requires building all potential slices.

Parameters:

• project (bool, optional) – Show the projected potential (True, default) or show all potential slices. It is recommended to index a subset of the potential slices when this keyword set to False.

• kwargs – Additional keyword arguments for the show method of Images.

property slice_limits: list[tuple[float, float]]

The entrance and exit thicknesses of each slice [Å].

property slice_thickness: tuple[float, ...]

Slice thicknesses for each slice.

squeeze(axis=None)

Remove axes of length one from array object.

Parameters:

axis (int or tuple of ints, optional) – Selects a subset of the entries of length one in the shape.

Returns:

squeezed – The input array object, but with all or a subset of the dimensions of length 1 removed.

Return type:

ArrayObject or subclass of ArrayObject

std(axis=None, keepdims=False, split_every=2)

Standard deviation of array object over one or more axes. Only ensemble axes can be reduced.

Parameters:

• axis (int or tuple of ints, optional) – Axis or axes along which a standard deviations are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the standard deviations are calculated over multiple axes. The indicated axes must be ensemble axes.

• keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.

• split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns:

reduced_array – The reduced array object.

Return type:

ArrayObject or subclass of ArrayObject

sum(axis=None, keepdims=False, split_every=2)

Sum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters:

• axis (int or tuple of ints, optional) – Axis or axes along which a sums are performed. The default is to compute the mean of the flattened array. If this is a tuple of ints, the sum is performed over multiple axes. The indicated axes must be ensemble axes.

• keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.

• split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns:

reduced_array – The reduced array object.

Return type:

ArrayObject or subclass of ArrayObject

property thickness: float

Thickness of the potential [Å].

tile(repetitions)

Tile the potential.

Parameters:

repetitions (two or three int) – The number of repetitions of the potential along each axis. NOTE: if three integers are given, the last represents the number of repetitions along the z-axis.

Returns:

The tiled potential.

Return type:

PotentialArray object

to_cpu()

Move the array to the host memory from an arbitrary source array.

Return type:

Self

to_data_array()

Convert ArrayObject to a xarray DataArray. Requires xarray to be installed.

Returns:

The converted xarray DataArray.

Return type:

xarray.DataArray

Raises:

ImportError – If xarray is not installed.

to_gpu(device='gpu')

Move the array from the host memory to a gpu.

Return type:

Self

to_hyperspy(transpose=True)

Convert ArrayObject to a Hyperspy signal.

Parameters:

transpose (bool, optional) – If True, transpose the base axes of the array before converting to a Hyperspy signal. Default is True.

Returns:

signal – The converted Hyperspy signal.

Return type:

Hyperspy signal

Raises:

• ImportError – If Hyperspy is not installed.

• RuntimeError – If the number of base dimensions is not 1 or 2.

Notes

This method requires Hyperspy to be installed. You can find more information about Hyperspy at https://hyperspy.org.

to_images()

Convert slices of the potential to a stack of images.

to_tiff(filename, **kwargs)

Write data to a tiff file.

Parameters:

• filename (str) – The filename of the file to write.

• kwargs – Keyword arguments passed to tifffile.imwrite.

to_zarr(url, compute=True, overwrite=False, **kwargs)

Write data to a zarr file.

Parameters:

• url (str) – Location of the data, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data.

• compute (bool) – If true compute immediately; return dask.delayed.Delayed otherwise.

• overwrite (bool) – If given array already exists, overwrite=False will cause an error, where overwrite=True will replace the existing data.

• kwargs – Keyword arguments passed to dask.array.to_zarr.

transmission_function(energy)

Calculate the transmission functions for each slice for a specific energy.

Parameters:

energy (float) – Electron energy [eV].

Returns:

transmissionfunction – Transmission functions for each slice.

Return type:

TransmissionFunction

transmit(waves, conjugate=False)

Transmit a wave function through a potential slice.

Parameters:

• waves (Waves) – Waves object to transmit.

• conjugate (bool, optional) – If True, use the conjugate of the transmission function. Default is False.

Returns:

transmission_function – Transmission function for the wave function through the potential slice.

Return type:

TransmissionFunction