Potentials

Module to calculate potentials using the independent atom model.

class abtem.potentials.AbstractPotential(precalculate)[source]

Potential abstract base class

Base class common for all potentials.

check_slice_idx(i)[source]

Raises an error if i is greater than the number of slices.

copy()[source]

Make a copy.

property extent

Grid extent in each dimension [Å].

abstract generate_slices(first_slice=0, last_slice=None, max_batch=1)[source]

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)[source]

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

abstract get_slice_thickness(i)[source]

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

property gpts

Number of grid points in each dimension.

abstract property num_slices

The number of projected potential slices.

property sampling

Grid sampling in each dimension [1 / Å].

class abtem.potentials.AbstractPotentialBuilder(precalculate=True, device='cpu', storage='cpu')[source]

Potential builder abstract class.

build(first_slice=0, last_slice=None, energy=None, max_batch=None, pbar=False)[source]

Precalcaulate the potential as a potential array.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • energy (float) – Electron energy [eV]. If given, the transmission functions will be returned.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

  • pbar (bool) – If true, show progress bar.

Returns

Return type

PotentialArray object

check_slice_idx(i)

Raises an error if i is greater than the number of slices.

copy()

Make a copy.

property extent

Grid extent in each dimension [Å].

abstract generate_slices(first_slice=0, last_slice=None, max_batch=1)

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

abstract get_slice_thickness(i)

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

property gpts

Number of grid points in each dimension.

abstract property num_slices

The number of projected potential slices.

property sampling

Grid sampling in each dimension [1 / Å].

class abtem.potentials.CrystalPotential(potential_unit, repetitions, num_frozen_phonon_configs=1)[source]

Crystal potential object

The crystal potential may be used to represent a potential consisting of a repeating unit. This may allow calculations to be performed with lower memory and computational cost.

The crystal potential has an additional function in conjunction with frozen phonon calculations. The number of frozen phonon configurations are not given by the FrozenPhonon objects, rather the ensemble of frozen phonon potentials represented by a potential with frozen phonons represent a collection of units, which will be assembled randomly to represent a random potential. The number of frozen phonon configurations should be given explicitely. This may save computational cost since a smaller number of units can be combined to a larger frozen phonon ensemble.

Parameters

  • potential_unit (AbstractPotential) – The potential unit that repeated will create the full potential.

  • repetitions (three int) – The repetitions of the potential in x, y and z.

  • num_frozen_phonon_configs (int) – Number of frozen phonon configurations.

check_slice_idx(i)

Raises an error if i is greater than the number of slices.

copy()

Make a copy.

property extent

Grid extent in each dimension [Å].

generate_slices(first_slice=0, last_slice=None, max_batch=1)[source]

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)[source]

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

get_slice_thickness(i)[source]

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

Return type

float

property gpts

Number of grid points in each dimension.

property num_slices

The number of projected potential slices.

Return type

int

property sampling

Grid sampling in each dimension [1 / Å].

class abtem.potentials.Potential(atoms=None, gpts=None, sampling=None, slice_thickness=0.5, parametrization='lobato', projection='finite', cutoff_tolerance=0.001, device='cpu', precalculate=True, z_periodic=True, plane='xy', storage=None)[source]

Potential object.

The potential object is used to calculate the electrostatic potential of a set of atoms represented by an ASE atoms object. The potential is calculated with the Independent Atom Model (IAM) using a user-defined parametrization of the atomic potentials.

Parameters

  • atoms (Atoms or FrozenPhonons object) – Atoms or FrozenPhonons defining the atomic configuration(s) used in the IAM of the electrostatic potential(s).

  • gpts (one or two int, optional) – Number of grid points describing each slice of the potential.

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

  • slice_thickness (float, optional) – Thickness of the potential slices in Å for calculating the number of slices used by the multislice algorithm. Default is 0.5 Å.

  • parametrization ('lobato' or 'kirkland', optional) – The potential parametrization describes the radial dependence of the potential for each element. Two of the most accurate parametrizations are available by Lobato et. al. and Kirkland. The abTEM default is ‘lobato’. See the citation guide for references.

  • projection ('finite' or 'infinite') – If ‘finite’ the 3d potential is numerically integrated between the slice boundaries. If ‘infinite’ the infinite potential projection of each atom will be assigned to a single slice.

  • cutoff_tolerance (float, optional) – The error tolerance used for deciding the radial cutoff distance of the potential [eV / e]. The cutoff is only relevant for potentials using the ‘finite’ projection scheme.

  • device (str, optional) – The device used for calculating the potential. The default is ‘cpu’.

  • precalculate (bool) – If True, precalculate the potential else the potential will be calculated on-the-fly and immediately discarded. Default is True.

  • storage (str, optional) – The device on which to store the created potential. The default is ‘None’, defaulting to the chosen device.

property atoms

Atoms object defining the atomic configuration.

build(first_slice=0, last_slice=None, energy=None, max_batch=None, pbar=False)

Precalcaulate the potential as a potential array.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • energy (float) – Electron energy [eV]. If given, the transmission functions will be returned.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

  • pbar (bool) – If true, show progress bar.

Returns

Return type

PotentialArray object

check_slice_idx(i)

Raises an error if i is greater than the number of slices.

copy()

Make a copy.

property cutoff_tolerance

The error tolerance used for deciding the radial cutoff distance of the potential [eV / e].

property extent

Grid extent in each dimension [Å].

property frozen_phonons

FrozenPhonons object defining the atomic configuration(s).

property function

The potential function of the parametrization.

generate_frozen_phonon_potentials(pbar=True)[source]

Function to generate scattering potentials for a set of frozen phonon configurations.

Parameters

pbar (bool, optional) – Display a progress bar. Default is True.

Returns

Generator of potentials.

Return type

generator

generate_slices(first_slice=0, last_slice=None, max_batch=1)[source]

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

get_cutoff(number)[source]

Cutoff distance for atomic number given an error tolerance.

Parameters

number (int) – Atomic number.

Returns

cutoff – The potential cutoff.

Return type

float

get_integrator(number)[source]

Potential integrator for atomic number.

Parameters

number (int) – Atomic number.

Returns

Return type

PotentialIntegrator object

get_slice_thickness(i)[source]

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

Return type

float

get_tapered_function(number)[source]

Tapered potential function for atomic number.

Parameters

number (int) – Atomic number.

Returns

Return type

callable

property gpts

Number of grid points in each dimension.

property num_slices

The number of projected potential slices.

property parameters

The parameters of the potential parametrization.

property parametrization

The potential parametrization.

property projection

The projection method.

property sampling

Grid sampling in each dimension [1 / Å].

property slice_thickness

The thickness of the projected potential slices.

class abtem.potentials.PotentialArray(array, slice_thicknesses, extent=None, sampling=None)[source]

Potential array object

The potential array represents slices of the electrostatic potential as an array.

Parameters

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

  • slice_thicknesses (float) – The thicknesses of potential slices in Å. 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 / Å].

property array

The potential array.

as_transmission_function(energy, in_place=True, max_batch=1, antialias_filter=None)[source]

Calculate the transmission functions for a specific energy.

Parameters

energy (float) – Electron energy [eV].

Returns

Return type

TransmissionFunction object

check_slice_idx(i)

Raises an error if i is greater than the number of slices.

copy()

Make a copy.

property extent

Grid extent in each dimension [Å].

generate_slices(first_slice=0, last_slice=None, max_batch=1)[source]

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

get_slice_thickness(i)[source]

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

property gpts

Number of grid points in each dimension.

property num_slices

The number of projected potential slices.

project()[source]

Create a 2d measurement of the projected potential.

Returns

Return type

Measurement

classmethod read(path)[source]

Read potentia from hdf5 file.

Parameters

path (str) – The file to read.

Returns

Return type

PotentialArray object

property sampling

Grid sampling in each dimension [1 / Å].

tile(tile)[source]

Tile the potential.

Parameters

multiples (two or three int) – The number of repetitions of the potential along each axis. If three integers are given the first represents the number of repetitions along the z-axis.

Returns

The tiled potential.

Return type

PotentialArray object

to_hyperspy()[source]

Changes the PotentialArray object to a hyperspy.Signal2D Object.

transmit(waves, conjugate=False)[source]

Transmit a wave function.

Parameters

waves (Waves object) – Wave function to transmit.

Returns

Return type

TransmissionFunction

write(path, format='hdf5', **kwargs)[source]

Write potential to a file.

Parameters

  • path (str) – Path to which the data is saved.

  • format (str) – One of [“hdf5”, “hspy”]. Default is “hdf5”.

  • kwargs – Any of the additional parameters for saving a hyperspy dataset.

class abtem.potentials.PotentialIntegrator(function, r, max_interval, cutoff=None, cache_size=4096, cache_key_decimals=2, tolerance=1e-06)[source]

Perform finite integrals of a radial function along a straight line.

Parameters

  • function (callable) – Radial function to integrate.

  • r (array of float) – The evaluation points of the integrals.

  • cutoff (float, optional) – The radial function is assumed to be zero outside this threshold.

  • cache_size (int, optional) – The maximum number of integrals that will be cached.

  • cache_key_decimals (int, optional) – The number of decimals used in the cache keys.

  • tolerance (float, optional) – The absolute error tolerance of the integrals.

integrate(z, a, b)[source]

Evaulate the integrals of the radial function at the evaluation points.

Parameters

  • a (float) – Lower limit of integrals.

  • b (float) – Upper limit of integrals.

Returns

The evaulated integrals.

Return type

1d array

class abtem.potentials.TransmissionFunction(array, slice_thicknesses, extent=None, sampling=None, energy=None)[source]

Class to describe transmission functions.

property array

The potential array.

as_transmission_function(energy, in_place=True, max_batch=1, antialias_filter=None)[source]

Calculate the transmission functions for a specific energy.

Parameters

energy (float) – Electron energy [eV].

Returns

Return type

TransmissionFunction object

check_slice_idx(i)

Raises an error if i is greater than the number of slices.

copy()

Make a copy.

property energy

Acceleration energy [eV].

property extent

Grid extent in each dimension [Å].

generate_slices(first_slice=0, last_slice=None, max_batch=1)

Generate the potential slices.

Parameters

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

generate_transmission_functions(energy, first_slice=0, last_slice=None, max_batch=1)[source]

Generate the transmission functions one slice at a time.

Parameters

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

  • first_slice (int) – First potential slice to generate.

  • last_slice (int, optional) – Last potential slice generate.

  • max_batch (int) – Maximum number of potential slices calculated in parallel.

Returns

Return type

generator of PotentialArray objects

get_slice_thickness(i)

Get the slice thickness [Å].

Parameters

i (int) – Slice index.

property gpts

Number of grid points in each dimension.

property num_slices

The number of projected potential slices.

project()

Create a 2d measurement of the projected potential.

Returns

Return type

Measurement

classmethod read(path)

Read potentia from hdf5 file.

Parameters

path (str) – The file to read.

Returns

Return type

PotentialArray object

property sampling

Grid sampling in each dimension [1 / Å].

tile(tile)

Tile the potential.

Parameters

multiples (two or three int) – The number of repetitions of the potential along each axis. If three integers are given the first represents the number of repetitions along the z-axis.

Returns

The tiled potential.

Return type

PotentialArray object

to_hyperspy()

Changes the PotentialArray object to a hyperspy.Signal2D Object.

transmit(waves, conjugate=False)[source]

Transmit a wave function.

Parameters

waves (Waves object) – Wave function to transmit.

Returns

Return type

TransmissionFunction

property wavelength

Relativistic wavelength [Å].

write(path, format='hdf5', **kwargs)

Write potential to a file.

Parameters

  • path (str) – Path to which the data is saved.

  • format (str) – One of [“hdf5”, “hspy”]. Default is “hdf5”.

  • kwargs – Any of the additional parameters for saving a hyperspy dataset.