abtem.inelastic.phonons

abtem.inelastic.phonons#

Module to describe the effect of temperature on the atomic positions.

Module Contents#

Classes#

AtomsEnsemble

Frozen phonons based on a molecular dynamics simulation.

BaseFrozenPhonons

Base class for frozen phonons.

DummyFrozenPhonons

Class to allow all potentials to be treated in the same way.

EnergyResolvedAtomsEnsemble

Energy-resolved ensemble of frozen-phonon configurations.

FrozenPhonons

The frozen phonons randomly displace the atomic positions to emulate thermal vibrations.

Functions#

validate_seeds

Data#

Reader

API#

class abtem.inelastic.phonons.AtomsEnsemble(...)[source]#

Bases: abtem.inelastic.phonons.BaseFrozenPhonons

Frozen phonons based on a molecular dynamics simulation.

Parameters:

  • trajectory (list of ASE.Atoms, dask.core.Array, list of dask.Delayed) – Sequence of atoms representing a distribution of atomic configurations.

  • ensemble_mean (True, optional) – If True, the mean of the ensemble of results from a multislice simulation is calculated, otherwise, the result of every frozen phonon is returned.

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

  • cell (Cell, optional)

Initialization

property atoms: ase.Atoms#
property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape: tuple[int, ...]#
mean_squared_deviations() → ndarray[source]#

Squared deviation of the positions of each atom in each direction.

property num_configs: int#
property numbers#

The atomic numbers of the atoms.

randomize(...) → ase.Atoms[source]#
standard_deviations() → ndarray[source]#

Standard deviation of the positions of each atom in each direction.

property trajectory: ndarray | dask.array.core.Array#

Array of atoms representing an ensemble of atomic configurations.

class abtem.inelastic.phonons.BaseFrozenPhonons(...)[source]#

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

Base class for frozen phonons.

Initialization

property atomic_numbers: ndarray#

The unique atomic number of the atoms.

abstract property atoms: ase.Atoms#

Base atomic configuration used for displacements.

property cell: ase.cell.Cell#

The cell of the atoms.

property ensemble_mean#

The mean of the ensemble of results from a multislice simulation is calculated.

abstract property num_configs#

Number of atomic configurations.

abstract randomize(...) → ase.Atoms[source]#

Randomize the atoms.

Parameters:

atoms (Atoms)

class abtem.inelastic.phonons.DummyFrozenPhonons(...)[source]#

Bases: abtem.inelastic.phonons.BaseFrozenPhonons

Class to allow all potentials to be treated in the same way.

Initialization

property atoms#
property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape#
property num_configs#
property numbers#

The atomic numbers of the atoms.

randomize(...) → ase.Atoms[source]#
class abtem.inelastic.phonons.EnergyResolvedAtomsEnsemble(...)[source]#

Bases: abtem.inelastic.phonons.BaseFrozenPhonons

Energy-resolved ensemble of frozen-phonon configurations.

Wraps a 2D array of Atoms objects (n_energies, n_configs) with an EnergyLossAxis and FrozenPhononsAxis as ensemble axes. The energy values typically come from external phonon calculations.

All inner configuration lists must have the same length.

Notes

When running a multi-slice Potential (more than one slice) over this ensemble, prefer projection="finite" over the default projection="infinite". The default assigns each atom to exactly one slice with a hard cutoff and no padding (SliceIndexedAtoms); if the configurations include out-of-plane (z) displacement, an atom sitting near a slice boundary can flip its entire potential contribution between slices across otherwise near-identical configurations, producing spurious discontinuities in the resulting spectra. projection="finite" uses padded slicing (SlicedAtoms) where such atoms blend gradually into the neighbouring slice instead. With a single slice there is no boundary to cross, so this does not arise regardless of projection method.

Parameters:

  • energy_resolved_snapshots (list of lists of ASE Atoms, or 2D numpy.ndarray) – Outer index is energy, inner index is configuration.

  • energies (array-like) – Energy values [eV] corresponding to each outer entry.

  • ensemble_mean (bool, optional) – If True (default), average over frozen-phonon configurations.

  • cell (Cell, optional)

Initialization

property atoms: ase.Atoms#
property energies: ndarray#

Energy values [eV] for each snapshot group.

property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape: tuple[int, ...]#
property num_configs: int#
randomize(...) → ase.Atoms[source]#
property snapshots: ndarray#

2D object array of Atoms (n_energies, n_configs).

class abtem.inelastic.phonons.FrozenPhonons(...)[source]#

Bases: abtem.inelastic.phonons.BaseFrozenPhonons

The frozen phonons randomly displace the atomic positions to emulate thermal vibrations.

Parameters:

  • atoms (ASE.Atoms) – Atomic configuration used for displacements.

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

  • sigmas (float or dict or list) –

    If float, the standard deviation of the displacements is assumed to be identical for all atoms. If dict, a displacement standard deviation should be provided for each species. The atomic species can be specified as atomic number or a symbol, using the ASE standard. If list or array, a displacement standard deviation should be provided for each atom.

    Anistropic displacements may be given by providing a standard deviation for each principal direction. This may be a tuple of three numbers for identical displacements for all atoms. A dict of tuples of three numbers to specify displacements for each species. A list or array with three numbers for each atom.

  • directions (str, optional) – The displacement directions of the atoms as a string; for example ‘xy’ (default) for displacement in the x- and y-direction (i.e. perpendicular to the propagation direction).

  • ensemble_mean (bool, optional) – If True (default), the mean of the ensemble of results from a multislice simulation is calculated, otherwise, the result of every frozen phonon configuration is returned.

  • seed (int or sequence of int) – Seed(s) for the random number generator used to generate the displacements, or one seed for each configuration in the frozen phonon ensemble.

Initialization

property atoms: ase.Atoms#
property directions: str#

The directions of the random displacements.

property ensemble_axes_metadata: list[AxisMetadata]#
property ensemble_shape#
property num_configs: int#
randomize(...) → ase.Atoms[source]#
property seed: tuple[int, ...]#

Random seed for each displacement configuration.

property sigmas: ndarray | dict[str, ndarray]#

Displacement standard deviation for each atom.

to_atoms_ensemble()[source]#

Convert the frozen phonons to an ensemble of atoms.

Returns:

atoms_ensemble

Return type:

AtomsEnsemble

abtem.inelastic.phonons.Reader: Optional[Callable]#

None

abtem.inelastic.phonons.validate_seeds(...) → tuple[int, ...][source]#