abtem.distributions

Module for describing distributions of simulation parameters.

Module Contents

Classes

BaseDistribution	Base object for defining distributions of simulation parameters.
DistributionFromValues	Distribution defined by user-defined values and weights.
EnsembleFromDistributions	Base object for ensembles based on distributions.
MultidimensionalDistribution	A multidimensional distribution composed of multiple lower-dimensional distributions.

Functions

from_values	Return a distribution from user-defined values and weights.
gaussian	Return a distribution with values weighted according to a (multidimensional) Gaussian distribution. The values are evenly spaced within a given truncation of the Gaussian distribution. As an example, this distribution may be used for simulating focal spread.
lorentzian	Return a distribution with values weighted according to a (multidimensional) Lorentzian (Cauchy) distribution. The values are evenly spaced within a given truncation of the distribution. As an example, this distribution may be used for simulating focal spread due to an energy-loss spectrum with Lorentzian tails.
pseudo_voigtian	Return a distribution with values weighted according to a (multidimensional) pseudo-Voigtian distribution, which is a weighted linear sum of a Gaussian and a Lorentzian (not their convolution). The values are evenly spaced within a given truncation of the distribution.
tuple_range_except
uniform	Return a distribution with uniformly weighted values evenly spaced over a specified interval. As an example, this distribution may be used for simulating a focal series.
validate_distribution	param distribution: The input distribution to be validated. type distribution: BaseDistribution or Iterable or Number returns: The validated distribution. If the input distribution is already a valid distribution, it is returned as is. If the input distribution is a single number, it is returned unchanged. If the input distribution is an ndarray with shape (0,), its single element is returned. If the input distribution is a tuple, list, or ndarray, it is converted to an ndarray and wrapped into a DistributionFromValues object where each value has equal weight. Otherwise, a ValueError is raised. rtype: BaseDistribution or Number raises ValueError: If the input distribution is not a valid distribution or .
voigtian	Return a distribution with values weighted according to a (multidimensional) Voigtian distribution, which is the convolution of a Gaussian and a Lorentzian. The values are evenly spaced within a given truncation of the distribution. As an example, this distribution may be used for simulating focal spread due to an energy-loss spectrum with both Gaussian and Lorentzian contributions.

API

class abtem.distributions.BaseDistribution

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

Base object for defining distributions of simulation parameters.

abstract property dimensions: int

The number of dimensions in the distribution.

abstract divide(...) → ndarray | dask.array.Array

Divide the distribution into chunks.

abstract property ensemble_mean: bool

Calculate the mean of the ensemble.

abstract property shape: tuple[int, ...]

The shape of the distribution parameters.

abstract property values: ndarray

Scalar values representing the distribution.

abstract property weights: ndarray

Weight of each of distribution value.

class abtem.distributions.DistributionFromValues(...)

Bases: abtem.distributions.BaseDistribution

Distribution defined by user-defined values and weights.

Parameters:

• values (ndarray) – The values of the distribution.

• weights (ndarray, optional) – The values of the weights. If None, all weights are set to 1.

• ensemble_mean (bool, optional) – If True, the mean of an ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept.

Initialization

combine(...) → MultidimensionalDistribution

Combine distribution with another distribution to produce a higher-dimensional distribution.

Parameters:

other (DistributionFromValues) – The distribution to combine this distribution with.

Returns:

combined_distribution – Higher-dimensional combined distribution.

Return type:

MultidimensionalDistribution

property dimensions: int

divide(...) → ndarray | dask.array.Array

property ensemble_mean: bool

property shape: tuple[int]

property values: ndarray

property weights: ndarray

class abtem.distributions.EnsembleFromDistributions(...)

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

Base object for ensembles based on distributions.

Parameters:

distributions (tuple of str, optional) – Names of properties that may be described by a distribution.

Initialization

property ensemble_shape: tuple[int, ...]

class abtem.distributions.MultidimensionalDistribution(...)

Bases: abtem.distributions.BaseDistribution

A multidimensional distribution composed of multiple lower-dimensional distributions.

Parameters:

distributions (list of BaseDistribution) – The lower-dimensional distributions composed into a higher-dimensional distribution.

Initialization

property dimensions: int

property distributions

The lower dimensional distributions making up this distribution.

divide(...) → ndarray | dask.array.Array

property ensemble_mean: bool

property shape: tuple[int, ...]

property values: ndarray

property weights: ndarray

abtem.distributions.from_values(...) → DistributionFromValues

Return a distribution from user-defined values and weights.

Parameters:

• values (sequence of int or float) – The scalar values of the parameters.

• weights (sequence of float, optional) – The scalar values of the weights (default is None).

• ensemble_mean (bool, optional) – If True, the mean of an ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept.

abtem.distributions.gaussian(...) → MultidimensionalDistribution

Return a distribution with values weighted according to a (multidimensional) Gaussian distribution. The values are evenly spaced within a given truncation of the Gaussian distribution. As an example, this distribution may be used for simulating focal spread.

Parameters:

• standard_deviation (float or tuple of float) – The standard deviation of the distribution. The standard deviations may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• num_samples (int) – Number of samples uniformly spaced samples. The samples may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• center (float or tuple of float) – The center of the Gaussian distribution (default is 0.0). The center may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• dimension (int, optional) – Number of dimensions of the Gaussian distribution.

• ensemble_mean (bool, optional) – If True, the mean of ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept. Default is True.

• sampling_limit (float, optional) – Truncate the distribution at this many standard deviations (default is 3.0).

• normalize (str, optional) – Specifies whether to normalize the ‘intensity’ (default) or ‘amplitude’.

Notes

The Gaussian distribution is parameterized by its standard deviation σ (standard_deviation). The corresponding full-width at half-maximum is FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ.

Note that the Lorentzian and Voigt distributions use the half-width at half-maximum (HWHM) γ as their width parameter, so for the same FWHM one needs γ = FWHM / 2 but σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

abtem.distributions.lorentzian(...) → MultidimensionalDistribution

Return a distribution with values weighted according to a (multidimensional) Lorentzian (Cauchy) distribution. The values are evenly spaced within a given truncation of the distribution. As an example, this distribution may be used for simulating focal spread due to an energy-loss spectrum with Lorentzian tails.

Parameters:

• half_width (float or tuple of float) – The half-width at half-maximum (HWHM) of the distribution. The half-widths may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• num_samples (int or tuple of int) – Number of evenly spaced samples. The number of samples may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• dimension (int, optional) – Number of dimensions of the distribution.

• center (float or tuple of float) – The center of the distribution (default is 0.0). The center may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• ensemble_mean (bool or tuple of bool, optional) – If True, the mean of the ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept. Default is True.

• sampling_limit (float or tuple of float, optional) – Truncate the distribution at this many half-widths (default is 10.0). The Lorentzian has heavier tails than the Gaussian, so a larger truncation is recommended.

• normalize (str, optional) – Specifies whether to normalize the ‘intensity’ (default) or ‘amplitude’.

Notes

The Lorentzian distribution is parameterized by its half-width at half-maximum (HWHM) γ (half_width). The corresponding full-width at half-maximum is FWHM_L = 2γ.

Note that the Gaussian distribution uses the standard deviation σ as its width parameter. For the same FWHM one needs γ = FWHM / 2 but σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

The Lorentzian source-size model is described in Nguyen et al. (2014).

References

D.T. Nguyen, S.D. Findlay, J. Etheridge, “The spatial coherence function

in scanning transmission electron microscopy and spectroscopy”, Ultramicroscopy 146, 6–16 (2014). https://doi.org/10.1016/j.ultramic.2014.04.008

abtem.distributions.pseudo_voigtian(...) → MultidimensionalDistribution

Return a distribution with values weighted according to a (multidimensional) pseudo-Voigtian distribution, which is a weighted linear sum of a Gaussian and a Lorentzian (not their convolution). The values are evenly spaced within a given truncation of the distribution.

The pseudo-Voigt model was proposed by Nguyen et al. (2014) to describe the spatial coherence function in STEM. See voigtian() for the true convolution (exact Voigt profile).

Parameters:

• gaussian_sigma (float or tuple of float) – The standard deviation (σ) of the Gaussian component. May be given for each axis as a tuple, or as a single number equal for all axes.

• lorentzian_gamma (float or tuple of float) – The half-width at half-maximum (HWHM, γ) of the Lorentzian component. May be given for each axis as a tuple, or as a single number equal for all axes.

• eta (float or tuple of float) – The Lorentzian mixing fraction η ∈ [0, 1]. η = 0 gives a pure Gaussian; η = 1 gives a pure Lorentzian. May be given for each axis as a tuple, or as a single number equal for all axes.

• num_samples (int or tuple of int) – Number of evenly spaced samples. May be given for each axis as a tuple, or as a single number equal for all axes.

• dimension (int, optional) – Number of dimensions of the distribution.

• center (float or tuple of float) – The center of the distribution (default is 0.0). May be given for each axis as a tuple, or as a single number equal for all axes.

• ensemble_mean (bool or tuple of bool, optional) – If True, the mean of the ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept. Default is True.

• sampling_limit (float or tuple of float, optional) – Truncate the distribution at this many widths (default is 10.0). The effective width is max(σ, γ), so the range is sampling_limit·max(σ, γ) on each side of the center.

• normalize (str, optional) – Specifies whether to normalize the ‘intensity’ (default) or ‘amplitude’.

Notes

The pseudo-Voigt profile is

PV(x) = (1 - η) · G(x; σ) + η · L(x; γ)

where G and L are un-normalized Gaussian and Lorentzian profiles evaluated on the same grid, and the result is normalized before use.

Width parameterization:

• gaussian_sigma (σ): standard deviation; FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ.

• lorentzian_gamma (γ): HWHM; FWHM_L = 2γ.

For the same FWHM, γ = FWHM / 2 whereas σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

References

D.T. Nguyen, S.D. Findlay, J. Etheridge, “The spatial coherence function

in scanning transmission electron microscopy and spectroscopy”, Ultramicroscopy 146, 6–16 (2014). https://doi.org/10.1016/j.ultramic.2014.04.008

abtem.distributions.tuple_range_except(...)

abtem.distributions.uniform(...) → DistributionFromValues

Return a distribution with uniformly weighted values evenly spaced over a specified interval. As an example, this distribution may be used for simulating a focal series.

Parameters:

• low (float) – The lowest value of the distribution.

• high (float) – The highest value of the distribution. If endpoint is set to False, the sequence consists of all but the last of num_samples + 1 evenly spaced samples so that the high value is excluded.

• num_samples (int) – Number of samples in the distribution.

• endpoint (bool)

• ensemble_mean (bool, optional) – If True, the mean of an ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept.

abtem.distributions.validate_distribution(...) → BaseDistribution | float | int

Parameters:

distribution (BaseDistribution or Iterable or Number) – The input distribution to be validated.

Returns:

The validated distribution. If the input distribution is already a valid distribution, it is returned as is. If the input distribution is a single number, it is returned unchanged. If the input distribution is an ndarray with shape (0,), its single element is returned. If the input distribution is a tuple, list, or ndarray, it is converted to an ndarray and wrapped into a DistributionFromValues object where each value has equal weight. Otherwise, a ValueError is raised.

Return type:

BaseDistribution or Number

Raises:

ValueError – If the input distribution is not a valid distribution or .

abtem.distributions.voigtian(...) → MultidimensionalDistribution

Return a distribution with values weighted according to a (multidimensional) Voigtian distribution, which is the convolution of a Gaussian and a Lorentzian. The values are evenly spaced within a given truncation of the distribution. As an example, this distribution may be used for simulating focal spread due to an energy-loss spectrum with both Gaussian and Lorentzian contributions.

Parameters:

• gaussian_sigma (float or tuple of float) – The standard deviation (σ) of the Gaussian component. The standard deviations may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• lorentzian_gamma (float or tuple of float) – The half-width at half-maximum (HWHM, γ) of the Lorentzian component. The half-widths may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• num_samples (int or tuple of int) – Number of evenly spaced samples. The number of samples may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• dimension (int, optional) – Number of dimensions of the distribution.

• center (float or tuple of float) – The center of the distribution (default is 0.0). The center may be given for each axis as a tuple, or as a single number, in which case it is equal for all axes.

• ensemble_mean (bool or tuple of bool, optional) – If True, the mean of the ensemble of measurements defined by the distribution is calculated, otherwise the full ensemble is kept. Default is True.

• sampling_limit (float or tuple of float, optional) – Truncate the distribution at this many Voigt half-widths (default is 5.0). The Voigt HWHM is estimated using the Thompson et al. (1987) approximation.

• normalize (str, optional) – Specifies whether to normalize the ‘intensity’ (default) or ‘amplitude’.

Notes

The Voigt profile is the convolution of a Gaussian and a Lorentzian, with two independent width parameters:

• gaussian_sigma (σ): standard deviation of the Gaussian component; FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ.

• lorentzian_gamma (γ): half-width at half-maximum (HWHM) of the Lorentzian component; FWHM_L = 2γ.

Because the two components use different parameterizations, σ and γ are not directly comparable: for the same FWHM one needs γ = FWHM / 2 but σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

The profile is computed exactly via the Faddeeva function (scipy.special.wofz). The degenerate limits σ → 0 (pure Lorentzian) and γ → 0 (pure Gaussian) are handled analytically.

Note that Nguyen et al. (2014) proposed a pseudo-Voigt (weighted sum of Gaussian and Lorentzian) rather than the true convolution implemented here; see pseudo_voigtian() for that model.