SurfaceTopography.Generic package

Submodules

SurfaceTopography.Generic.Curvature module

Scale-dependent slope

SurfaceTopography.Generic.Curvature.scale_dependent_curvature_from_profile(topography, **kwargs)

Compute the one-dimensional scale-dependent curvature.

The scale-dependent curvature is given by

\begin{equation} h_\text{rms}^{\prime\prime}(\lambda) = \left[8A(\lambda) - 2A(2\lambda)\right]^{1/2}/\lambda^2 \end{equation}

where \(A(\lambda)\) is the autocorrelation function.

Parameters:

topography (SurfaceTopography.Topography or SurfaceTopography.UniformLineScan) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_profile

Returns:

r (array) – Distances. (Units: length)
curvature (array) – Curvature. (Units: 1/length)

SurfaceTopography.Generic.Curvature.scale_dependent_curvature_from_area(topography, **kwargs)

Compute the two-dimensional, radially averaged scale-dependent curvature.

The scale-dependent curvature is given by

\begin{equation} h_\text{rms}^{\prime\prime}(\lambda) = 4\left[8A(\lambda/2) - 2A(\lambda)\right]^{1/2}/\lambda^2 \end{equation}

where \(A(\lambda)\) is the autocorrelation function.

Parameters:

topography (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_area

Returns:

r (array) – Distances. (Units: length)
curvature (array) – Curvature. (Units: 1/length)

SurfaceTopography.Generic.Fractional module

SurfaceTopography.Generic.Fractional.variance_half_derivative_via_autocorrelation_from_area(topography, **kwargs)

Parameters:

topography (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_area or autocorrelation_from_profile

SurfaceTopography.Generic.Fractional.variance_half_derivative_via_autocorrelation_from_profile(topography, **kwargs)

Parameters:

topography (SurfaceTopography or UniformLineScan or Container) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_area or autocorrelation_from_profile

SurfaceTopography.Generic.Fractional.variance_half_derivative_via_scale_dependent_slope(r, slope)

Parameters:

r (array) – Distances. (Units: length)
slope (array) – Slope. (Units: dimensionless)

Returns:

float
variance of the half derivative (Units (length))

SurfaceTopography.Generic.Fractional.container_variance_half_derivative_from_autocorrelation(container, scale_dependent=False, **kwargs)

The scale-dependence is introduced by considering only the ACF below the distance scale.

This is the definition of scale-dependent elastic energy as in Wang and Müser equation 44

see container.autocorrelation concerning further arguments

Returns:

if scale_dependent
r (array of floats)
distance scale
variance_half_derivative (array of floats)

SurfaceTopography.Generic.Moments module

Computation of moments of a discrete curve, e.g. the PSD

The example below computes the PSD of a surface topography and integrates it to obtain the RMS height.

>>> from SurfaceTopography.Generation import fourier_synthesis
>>> t = fourier_synthesis((256, 256), (256,256), hurst=0.8, rms_height=1, short_cutoff=4, long_cutoff=64)
>>> hrms = t.rms_height_from_profile()
>>> hrms_from_psd = np.sqrt(compute_1d_moment(,)
>>> assert abs(hrms_from_psd / hrms - 1)  < 0.1

However, because the averaging of the PSD before integration introduces errors, it is better to sum directly the raw spectum, see the methods integrate_psd of the topographies and the container.

SurfaceTopography.Generic.Moments.compute_1d_moment(x, y, order=1, cumulative=False)

Computes the moment of order \(\alpha\)

\[m_\alpha = \int dx y x^{\alpha}\]

using trapezoidal interpolation of the integrand

Parameters:

x: np.ndarray: sample points
y: np.ndarray: values of the function sampled at x
order: float, default=1: order of the moment
cumulative: bool, default=True: if True returns the cumulative value of this integral for each x (uses cumulative_trapezoid instead of trapezoid)

returns:

If cumulative is False (Default)
integral (float)
If cumulative is True
integral (np.ndarray of length)

SurfaceTopography.Generic.Moments.compute_iso_moment(x, y, order=1, cumulative=False)

Computes the moment of order \(\alpha\) of the 2D isotropic funtion \(y_{2D}(x)\)

\(y\) is the 1D representation of the isotropic function \(y_{2D}(x_1, x_2) = y(|\vec x|)\)

\[m_\alpha = \int dx_1 dx_2 y_{2D}(x_1, x_2) |\vec x|^{\alpha} = 2\pi \int dx y(x) x^{\alpha + 1}\]

using trapezoidal interpolation of the integrand

Parameters:

x: np.ndarray: sample points
y: np.ndarray: values of the function sampled at x
order: float, default=1: order of the moment
cumulative: bool, default=True: if True returns the cumulative value of this integral for each x (uses cumulative_trapezoid instead of trapezoid)

returns:

If cumulative is False (Default)
integral (float)
If cumulative is True
integral (np.ndarray of length)

SurfaceTopography.Generic.ReliabilityCutoff module

Automatic determination of the reliability of the underyling data

SurfaceTopography.Generic.ReliabilityCutoff.short_reliability_cutoff(self, other_cutoff=None)

Determine down to which distance scale the data is reliable, i.e. below which distance it may be affected by instrumental artifacts. Currently supported are tip radius artifacts and a user specified resolution.

Returns:: short_cutoff – All data below this length scale is unreliable. For tip radius analysis, this is the length of the stencil for the second derivative used to compute the reliability cutoff.
Return type:: float

SurfaceTopography.Generic.RobustStatistics module

Robust statistics (median, median absolute deviation, etc.) for topography data.

SurfaceTopography.Generic.RobustStatistics.bisect(bearing_area, target_area, rtol=1e-06)

Find the root of a function using the bisection method.

Parameters:

bearing_area (UniformBearingArea or NonuniformBearingArea) – Instance of bearing area class.
target_area (float) – Target bearing area.
rtol (float) – Relative tolerance for the root with respect to the initial bounds.

Returns:

root – Height where the bearing area is equal to target_area.

Return type:

float

SurfaceTopography.Generic.RobustStatistics.median(self)

Compute the median height of the topography.

Parameters:: self (HeightContainer) – Topography or line scan container object.
Returns:: median – Median height.
Return type:: float

SurfaceTopography.Generic.RobustStatistics.mad_height(self, percentile=np.float64(0.15865525393145707))

Compute the median-absolute-deviation of the height.

Parameters:

self (HeightContainer) – Topography or line scan container object.
percentile (float) – Fraction of the bearing area that should be considered for the deviation. (Default: One standard deviation)

Returns:

mad_height – Median absolute deviation of the height.

Return type:

float

SurfaceTopography.Generic.RobustStatistics.mad_polyfit(self, nb_coeffs)

Find the polynomial that minimizes the median absolute deviation.

Parameters:

self (HeightContainer) – Topography or line scan container object.
nb_coeffs (int) – Number of coefficients to be fitted.

SurfaceTopography.Generic.ScaleDependentStatistics module

SurfaceTopography.Generic.ScaleDependentStatistics.scale_dependent_statistical_property(self, func, n=1, scale_factor=None, distance=None, reliable=True, interpolation='linear', progress_callback=None, collocation='log', nb_points=None, nb_points_per_decade=10, threshold=4)

Compute statistical properties of a uniform topography at specific scales. The scale is specified either by scale_factors or distance. These properties are statistics of derivatives carried out at specific scales, as computed using the derivative pipeline function.

The specific statistical properties is computed by the func argument. The output of func needs to be homogeneous, i.e. if an array is returned, this array must have the same size independent of the derivative data that is fed into func.

Parameters:

self (Topography or UniformLineScan) – Topogaphy or line scan.
func (callable) –
The function that computes the statistical properties:

func(dx, dy=None) -> np.ndarray

A function taking the derivative in x-direction and optionally the derivative in y-direction (only for topographies, i.e. maps). The function needs to be able to ignore the second argument as a container can be a mixture of topographies and line scans. The function can return a scalar value or an array, but the array size must be fixed.
n (int, optional) – Order of derivative. (Default: 1)
scale_factor (float or np.ndarray) – Scale factor for rescaling the finite differences stencil. A scale factor of unity means the derivative is computed at the size of the individual pixel.
distance (float or np.ndarray) – Characteristic distances at which the derivatives are computed. This is the overall length of the underlying stencil of lowest truncation order, not the effective grid spacing used by this stencil. (The corresponding scale factor is then given by distance / (n * px) where n is the order of the derivative and px the grid spacing.) If this is an array, then the statistical property is computed at each of these distances.
reliable (bool, optional) – Only incorporate data deemed reliable. (Default: True)
interpolation (str, optional) – Interpolation method to use for computing derivatives at distances that do not equal an integer multiple of the grid spacing. Use ‘linear’ for a local liner interpolation or ‘fourier’ for global Fourier interpolation. Note that Fourier interpolation carries large errors for nonperiodic topographies and should be used with care. (Default: ‘linear’)
progress_callback (func, optional) – Function taking iteration and the total number of iterations as arguments for progress reporting. (Default: None)
collocation ({'log', 'quadratic', 'linear', array_like}, optional) – Automatic computation of sampling grid if neigther scale_factor nor distance is specified. Specifying ‘log’ yields collocation points equally spaced on a log scale, ‘quadratic’ yields bins with similar number of data points and ‘linear’ yields linear bins. (Default: ‘log’)
nb_points (int, optional) – Number of points for automatic sampling grid. Bins are automatically determined if set to None. (Default: None)
nb_points_per_decade (int, optional) – Number of points per decade for log-spaced collocation points. (Default: None)
threshold (int, optional) – Defines the minimal amount of data points of the probability distribution to calculate the statistical properties with func and returns a np.nan if the value is below the threshold. E.g. the scipy.stats.kstat function needs at least 4 data points to calculate the 4th cumulant function, otherwise it returns nan or inf (Default: 4)

Returns:

statistical_fingerprint – Array containing the result of func

Return type:

np.ndarray or list of np.ndarray

Examples

This example yields the the scale-dependent derivative (equivalent to the autocorrelation function divided by the distance) in the x-direction:

>>> distances, A = t.autocorrelation_from_profile(resampling_method=None)
>>> s = t.scale_dependent_statistical_property(lambda x, y=None: np.var(x), distance=distances[1::20])
>>> np.testing.assert_allclose(2 * A[1::20] / distances[1::20] ** 2, s)

SurfaceTopography.Generic.ScanningProbe module

Analysis functions related to scanning-probe microscopy

SurfaceTopography.Generic.ScanningProbe.scanning_probe_reliability_cutoff(self, tip_radius, safety_factor=0.5, xtol=2e-12, rtol=1e-08)

Estimate a length scale below which tip radius artifacts affect the measured data. See: 10.1016/j.apsadv.2021.100190

Parameters:

self (Topography or UniformLineScan) – Topogaphy or line scan.
tip_radius (float) – Tip radius.
safety_factor (float, optional) – Tip radius artifacts are expected to play a role for scales below which the minimum scale-dependent curvature drops below -safety_factor/radius. The safety_factor should be on the order of 1. In 10.1016/j.apsadv.2021.100190 a factor of 1/2 is estimated based on synthetic (simulated) data. (Default: 1/2)
xtol (float, optional) – Absolute tolerance for bracketing search. (Default: 2e-12)
rtol (float, optional) – Relative tolerance for bracketing search. (Default: 1e-8)

Returns:

reliability_cutoff – Length scale below which data is affected by tip radius artifacts. Note that this is the length of the stencil for the second derivative used to compute the reliability cutoff.

Return type:

float

SurfaceTopography.Generic.Slope module

Scale-dependent slope

SurfaceTopography.Generic.Slope.scale_dependent_slope_from_profile(topography, **kwargs)

Compute the one-dimensional scale-dependent slope.

The scale-dependent slope is given by

\begin{equation} h_\text{rms}^\prime(\lambda) = \left[2A(\lambda)\right]^{1/2}/\lambda \end{equation}

where \(A(\lambda)\) is the autocorrelation function.

Parameters:

topography (SurfaceTopography.Topography or SurfaceTopography.UniformLineScan) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_profile

Returns:

r (array) – Distances. (Units: length)
slope (array) – Slope. (Units: dimensionless)

SurfaceTopography.Generic.Slope.scale_dependent_slope_from_area(topography, **kwargs)

Compute the two-dimensional, radially averaged scale-dependent slope.

The scale-dependent slope is given by

\begin{equation} h_\text{rms}^\prime(\lambda) = \left[2A(\lambda)\right]^{1/2}/\lambda \end{equation}

where \(A(\lambda)\) is the autocorrelation function.

Parameters:

topography (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map
**kwargs (dict) – Additional keyword parameters are passed on to autocorrelation_from_area

Returns:

r (array) – Distances. (Units: length)
slope (array) – Slope. (Units: dimensionless)

Module contents

Module containing generic functions that work for both uniform and nonuniform topographies