GPAWPotential

class abtem.potentials.gpaw.GPAWPotential(calculators, gpts=None, sampling=None, slice_thickness=1.0, exit_planes=None, plane='xy', origin=(0.0, 0.0, 0.0), box=None, periodic=True, frozen_phonons=None, repetitions=(1, 1, 1), gridrefinement=4, device=None)

Bases: abtem.potentials.iam._PotentialBuilder

Calculate the electrostatic potential from a (set of) converged GPAW DFT calculation(s). Frozen phonons can be included either by specifying multiple GPAW calculators corresponding to the different phonon configurations, or approximately for a single calculator by using the frozen_phonons keyword.

Parameters

• calculators ((list of) gpaw.calculator.GPAW or (list of) str) – GPAW calculator or path to GPAW calculator or list of calculators or paths. Atoms are read from the calculator.

• gpts (one or two int, optional) – Number of grid points in x and y describing each slice of the potential. Provide either “sampling” (spacing between consecutive grid points) or “gpts” (total number of grid points).

• sampling (one or two float, optional) – Sampling of the potential in x and y [1 / Å]. Provide either “sampling” or “gpts”.

• slice_thickness (float or sequence of float, optional) – Thickness of the potential slices in the propagation direction in [Å] (default is 0.5 Å). If given as a float the number of slices is calculated by dividing the slice thickness into the z-height of supercell. The slice thickness may be given as a sequence of values for each slice, in which case an error will be thrown if the sum of slice thicknesses is not equal to the height of the atoms.

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

• plane (str or two tuples of three float, optional) – The plane relative to the provided atoms mapped to xy plane of the potential, i.e. provided plane is perpendicular to the propagation direction. If string, it must be a concatenation of two of ‘x’, ‘y’ and ‘z’; the default value ‘xy’ indicates that potential slices are cuts along the xy-plane of the atoms. The plane may also be specified with two arbitrary 3D vectors, which are mapped to the x and y directions of the potential, respectively. The length of the vectors has no influence. If the vectors are not perpendicular, the second vector is rotated in the plane to become perpendicular to the first. Providing a value of ((1., 0., 0.), (0., 1., 0.)) is equivalent to providing ‘xy’.

• origin (three float, optional) – The origin relative to the provided Atoms mapped to the origin of the Potential. This is equivalent to translating the atoms. The default is (0., 0., 0.)

• box (three float, optional) – The extent of the potential in x, y and z. If not given this is determined from the atoms’ cell. If the box size does not match an integer number of the atoms’ supercell, an affine transformation may be necessary to preserve periodicity, determined by the periodic keyword

• periodic (bool) – If a transformation of the atomic structure is required, periodic determines how the atomic structure is transformed. If True (default), the periodicity of the Atoms is preserved, which may require applying a small affine transformation to the atoms. If False, the transformed potential is effectively cut out of a larger repeated potential, which may not preserve periodicity.

• frozen_phonons (abtem.AbstractFrozenPhonons, optional) – Approximates frozen phonons for a single GPAW calculator by displacing only the nuclear core potentials. Supercedes the atoms from the calculator.

• repetitions (tuple of int) – Repeats the atoms by integer amounts in the x, y and z directions before applying frozen phonon displacements to calculate the potential contribution of the nuclear cores. Necessary when using frozen phonons.

• gridrefinement (int) – Necessary interpolation of the charge density into a finer grid for improved numerical precision. Allowed values are ‘2’ and ‘4’.

• device (str, optional) – The device used for calculating the potential, ‘cpu’ or ‘gpu’. The default is determined by the user configuration file.

__init__(calculators, gpts=None, sampling=None, slice_thickness=1.0, exit_planes=None, plane='xy', origin=(0.0, 0.0, 0.0), box=None, periodic=True, frozen_phonons=None, repetitions=(1, 1, 1), gridrefinement=4, device=None)

Methods

__init__(calculators[, gpts, sampling, ...])
build([first_slice, last_slice, max_batch, lazy])	Build the potential.
copy()	Make a copy.
ensemble_blocks([chunks])	Split the ensemble into an array of smaller ensembles.
generate_blocks([chunks])	Generate chunks of the ensemble.
generate_slices([first_slice, last_slice])	Generate the slices for the potential.
match_grid(other[, check_match])	Match the grid to another object with a Grid.
project()	Sum of the potential slices as an image.
select_block(index, chunks)	Select a block from the ensemble.
show([project])	Show the potential projection.
to_images()	Converts the potential to an ensemble of images.

Attributes

axes_metadata	List of AxisMetadata.
base_axes_metadata	List of AxisMetadata for the base axes.
base_shape	Shape of the base axes of the potential.
box	The extent of the potential in x, y and z.
calculators
device	The device where the potential is created.
ensemble_axes_metadata	List of AxisMetadata of the ensemble axes.
ensemble_shape	Shape of the ensemble axes.
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.
frozen_phonons
gpts	Number of grid points for each dimension.
grid	Simulation grid.
gridrefinement
num_exit_planes	Number of exit planes.
num_frozen_phonons	Number of frozen phonons in the ensemble of potentials.
num_slices	Number of projected potential slices.
origin	The origin relative to the provided atoms mapped to the origin of the potential.
periodic	Specifies whether the potential is periodic.
plane	The plane relative to the atoms mapped to xy plane of the potential, i.e. the plane is perpendicular to the propagation direction.
reciprocal_space_sampling	Reciprocal-space sampling in reciprocal Ångstrom.
repetitions
sampling	Grid sampling for each dimension in Ångstrom per grid point.
shape	Shape of the ensemble.
slice_limits	The entrance and exit thicknesses of each slice [Å].
slice_thickness	Slice thicknesses for each slice.
thickness	Thickness of the potential [Å].

property axes_metadata: abtem.core.axes.AxesMetadataList

List of AxisMetadata.

Return type

AxesMetadataList

property base_axes_metadata: list[abtem.core.axes.AxisMetadata]

List of AxisMetadata for the base axes.

Return type

list[AxisMetadata]

property base_shape: tuple[int, ...]

Shape of the base axes of the potential.

Return type

tuple[int, ...]

property box: tuple[float, float, float]

The extent of the potential in x, y and z.

Return type

tuple[float, float, float]

build(first_slice=0, last_slice=None, max_batch=1, lazy=None)

Build 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

• max_batch (int or str, optional) – Maximum number of slices to calculate in task. Default is 1.

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

Returns

potential_array – The built potential as an array.

Return type

PotentialArray

copy()

Make a copy.

property device: str

The device where the potential is created.

Return type

str

property ensemble_axes_metadata: List[abtem.core.axes.AxisMetadata]

List of AxisMetadata of the ensemble axes.

Return type

List[AxisMetadata]

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_shape

Shape of the ensemble axes.

property exit_planes: tuple[int]

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

Return type

tuple[int]

property exit_thicknesses: tuple[float]

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

Return type

tuple[float]

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

Extent of grid for each dimension in Ångstrom.

Return type

tuple[float] | tuple[float, float] | tuple[float, …]

generate_blocks(chunks=1)

Generate chunks of the ensemble.

Parameters

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

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.

Returns

slices – Generator for the array of slices.

Return type

generator of np.ndarray

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

Number of grid points for each dimension.

Return type

tuple[int] | tuple[int, int] | tuple[int, …]

property grid: abtem.core.grid.Grid

Simulation grid.

Return type

Grid

match_grid(other, check_match=False)

Match the grid to another object with a Grid.

property num_exit_planes: int

Number of exit planes.

Return type

int

property num_frozen_phonons

Number of frozen phonons in the ensemble of potentials.

property num_slices: int

Number of projected potential slices.

Return type

int

property origin: tuple[float, float, float]

The origin relative to the provided atoms mapped to the origin of the potential.

Return type

tuple[float, float, float]

property periodic: bool

Specifies whether the potential is periodic.

Return type

bool

property plane: str

The plane relative to the atoms mapped to xy plane of the potential, i.e. the plane is perpendicular to the propagation direction.

Return type

str

project()

Sum of the potential slices as an image.

Returns

projected – The projected potential.

Return type

Images

property reciprocal_space_sampling: tuple[float] | tuple[float, float] | tuple[float, ...]

Reciprocal-space sampling in reciprocal Ångstrom.

Return type

tuple[float] | tuple[float, float] | tuple[float, …]

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

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

Return type

tuple[float] | tuple[float, float] | tuple[float, …]

select_block(index, chunks)

Select a block from the ensemble.

Parameters

• index (tuple of ints) – Index of selected block.

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

property shape

Shape of the ensemble.

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 [Å].

Return type

list[tuple[float, float]]

property slice_thickness: tuple[float, ...]

Slice thicknesses for each slice.

Return type

tuple[float, ...]

property thickness: float

Thickness of the potential [Å].

Return type

float

to_images()

Converts the potential to an ensemble of images.

Returns

image_ensemble – The potential slices as images.

Return type

Images