SurfaceTopography.Uniform package

Submodules

SurfaceTopography.Uniform.Autocorrelation module

Height-difference autocorrelation functions

SurfaceTopography.Uniform.BearingArea module

Bearing area curve, also known as Abbott-Firestone curve or cumulative distribution function of the surface heights.

class SurfaceTopography.Uniform.BearingArea.UniformBearingArea

Bases: object

bounds(heights)

Compute bounds on the bearing area for a specific height. These bounds can be computed O(log(N)) time, where N is the number of elements in the line scan.

Parameters:

heights (float or np.ndarray) – Heights for which to compute the bearing area.

Returns:

  • lower_bound (float or np.ndarray) – Lower bound on fractional area above a threshold height.

  • upper_bound (float or np.ndarray) – Upper bound on fractional area above a threshold height.

property min
property max
class SurfaceTopography.Uniform.BearingArea.Uniform1DBearingArea(h, is_periodic)

Bases: UniformBearingArea

Accelerated bearing area calculation for uniform line scans.

__init__(h, is_periodic)
class SurfaceTopography.Uniform.BearingArea.Uniform2DBearingArea(h, is_periodic)

Bases: UniformBearingArea

Accelerated bearing area calculation for topographies.

__init__(h, is_periodic)
SurfaceTopography.Uniform.BearingArea.bearing_area(self, heights=None)

Compute the bearing area for a specific height.

The bearing area as a function of height is also known as the Abbott-Firestone curve. If expressed as a fractional area, it is the cumulative distribution function of the surface heights. This function returns this fractional area.

Parameters:

  • self (UniformLineScan or Topography) – Topography or line scan container object.

  • heights (float or np.ndarray, optional) – Heights for which to compute the bearing area. (Default: None)

Returns:

  • fractional_area (float or np.ndarray) – Fractional area above the threshold height, if height is given.

  • bearing_area (Uniform1DBearingArea or Uniform2DBearingArea) – Instance of a class that caches the bearing area calculation.

SurfaceTopography.Uniform.Converters module

Utility function for conversion between uniform and nonuniform representations.

class SurfaceTopography.Uniform.Converters.WrapAsNonuniformLineScan(topography, info={})

Bases: DecoratedNonuniformTopography

Wrap a uniform topography into a nonuniform one.

__init__(topography, info={})
Parameters:

  • topography (NonuniformLineScan) – SurfaceTopography to wrap.

  • info (dict) – Additional entries for the info dictionary.

property dim

Returns 1 for line scans and 2 for topography maps.

property physical_sizes

Return the physical sizes of the topography.

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property nb_grid_pts
property x_range
positions()

Returns array containing the lateral positions.

heights()

Returns array containing the topography data.

SurfaceTopography.Uniform.Derivative module

Compute derivatives of uniform line scans and topographies

SurfaceTopography.Uniform.Derivative.trim_nonperiodic(arr, scale_factor, op)

Trim the outer edges of an array that contains derivatives computed under the assumption of periodicity. (These values at the outer edge will simply be wrong.)

Parameters:

  • arr (np.ndarray) – Array to be trimmed.

  • scale_factor (int, optional) – Integer factor that scales the stencil difference.

  • op (muFFT.DiscreteDerivative) – Derivative operator that contains information about the size of the stencil.

SurfaceTopography.Uniform.Derivative.derivative(self, n, scale_factor=None, distance=None, operator=None, periodic=None, mask_function=None, interpolation='linear', progress_callback=None)

Compute derivative of topography or line scan stored on a uniform grid.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Surface topography object containing height information.

  • n (int) – Order of the derivative.

  • scale_factor (int or list of ints or list of tuples of ints, optional) –

    Integer factor that scales the stencil difference, i.e. specifying 2 will compute the derivative using a discrete step of 2 * px. Either scale_factor or distance can be specified.

    • Single int: Returns a single derivative scaled in all directions with this value

    • List of ints: Returns multiple derivatives, each scaled in all direction with the respective value from the list

    • List of tuples of ints: Each tuple contains a scale factor in the two Cartesian (x- and y-) directions. Return multiple derivatives, scaled with different factors in both directions.

    (Default: None)

  • distance (float or list of floats, optional) – Explicit distance scale for computation of the derivative. Either scale_factor or distance can be specified. Note that the distance specifies the overall length of the stencil of lowest truncation order, not the effective grid spacing used by this stencil. The scale factor is then given by distance / (n * px) where n is the order of the derivative and px the grid spacing. (Default: None)

  • operator (muFFT.Derivative object or tuple of muFFT.Derivative objects, optional) – Derivative operator used to compute the derivative. If unspecified, a simple upwind differences scheme will be applied to compute the derivative. A tuple contains the gradient, i.e. the derivative operators in the Cartesian directions for multidimensional fields. (Default: None)

  • periodic (bool, optional) – Override periodic flag from topography. (Default: None)

  • mask_function (function, optional) – A function that takes as argument the output of FFT.fftfreq and returns a mask that will be multiplied with the Fourier transformed topography. This can be used to implement Fourier filtering before computing the derivative. This only works if interpolation is set to ‘fourier’. (Default: None)

  • interpolation (str, optional) – Interpolation method to use for fractional scale factors. Use ‘linear’ for a local liner interpolation or ‘fourier’ for global Fourier interpolation. Set to ‘disable’ to raise an error when interpolation is necessary. Note that Fourier interpolation carries large errors for nonperiodic topographies and should not be used with windowing. (Default: ‘linear’)

  • progress_callback (func, optional) – Function taking iteration and the total number of iterations as arguments for progress reporting. (Default: None)

Returns:

derivative – Array with derivative values. If dimension of the topography is unity (line scan), then an array of the same shape as the topography is returned. Otherwise, the first array index contains the direction of the derivative. If the topgography is nonperiodic, then all returning array with have shape one less than the input arrays.

Return type:

array or tuple of arrays

SurfaceTopography.Uniform.Derivative.fourier_derivative(self, scale_factor=None, distance=None, mask_function=None)

First derivatives of the fourier interpolation of the topography.

For example in x direction:

\[\left[ \frac{\partial h }{\partial x}\right]_{x_i, y_j} = \frac{1}{2 \pi } \sum_{kl} q_x^k \tilde h_{kl} e^{i (q_x^k x_i + q_y^l y_j}\]

With \(\tilde h_{kl}\) the DFT of the heights :math:``h For even number of points, the interpretation of the components at the Niquist frequency is ambiguous (we are free to choose amplitude or phase) Following (https://math.mit.edu/~stevenj/fft-deriv.pdf), we assume it is cosinusoidal.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Surface topography object containing height information.

  • scale_factor (int or list of ints or list of tuples of ints, optional) –

    Integer factor that scales the stencil difference, i.e. specifying 2 will compute the derivative using a discrete step of 2 * px. Either scale_factor or distance can be specified.

    • Single int: Returns a single derivative scaled in all directions with this value

    • List of ints: Returns multiple derivatives, each scaled in all direction with the respective value from the list

    • List of tuples of ints: Each tuple contains a scale factor in the two Cartesian (x- and y-) directions. Return multiple derivatives, scaled with different factors in both directions.

    (Default: None)

  • distance (float or list of floats, optional) – Explicit distance scale for computation of the derivative. Either scale_factor or distance can be specified. Note that the distance specifies the overall length of the stencil of lowest truncation order, not the effective grid spacing used by this stencil. The scale factor is then given by distance / (n * px) where n is the order of the derivative and px the grid spacing. (Default: None)

  • mask_function (function, optional) – A function that takes as argument the output of FFT.fftfreq and returns a mask that will be multiplied with the Fourier transformed topography. This can be used to implement Fourier filtering before computing the derivative. (Default: None)

Returns:

derivative – Array with derivative values. If dimension of the topography is unity (line scan), then an array of the same shape as the topography is returned. Otherwise, the first array index contains the direction of the derivative. If the topgography is nonperiodic, then all returning array with have shape one less than the input arrays.

Return type:

array or tuple of arrays

SurfaceTopography.Uniform.Detrending module

Helper functions to compute trends of surfaces

SurfaceTopography.Uniform.Detrending.polyfit_line_scan(self, deg)

Compute the detrending plane that, if subtracted, minimizes the rms height.

Parameters:

self (UniformLineScan) – Topography or line scan container object.

SurfaceTopography.Uniform.Detrending.polyfit1_topography(self, full_output=False)

Compute the tilt plane that if subtracted minimizes the rms height of the surface. The tilt plane is parameterized as:

\[p(x, y) = h_0 + m x + n y\]

The values of \(m\), \(n\) and \(h0\) are return by this function.

idea as follows

  1. arr = arr_out + (ň.x + d)/ň_z

  2. arr_out.sum() = 0

3) |ň| = 1 => n_z = sqrt(1 - n_x^2 - n_y^2) (for 2D, but you get the idea)

dofs = n_x, n_y, d = X

solution X_s = arg_min ((arr - ň.x + d)^2).sum()

Parameters:

self (Topography) – Height information.

Returns:

  • m (float) – Slope in x-direction.

  • n (float) – Slope in y-direction.

  • h0 (float) – Mean value.

SurfaceTopography.Uniform.Detrending.polyfit2_topography(self, full_output=False)

Data in arr is interpreted as height information of a tilted and shifted surface.

idea as follows

  1. arr = arr_out + (ň.x + d)/ň_z

  2. arr_out.sum() = 0

3) |ň| = 1 => n_z = sqrt(1 - n_x^2 - n_y^2) (for 2D, but you get the idea)

dofs = n_x, n_y, d = X

solution X_s = arg_min ((arr - ň.x + d)^2).sum()

Returns:

coeffs [, location_matrix (if full_output)]

coeffs ordered as follows

{5} + {0} x + {1} y + {2} x^2 + {3} y^2 + {4} xy

SurfaceTopography.Uniform.Detrending.polyfit_topography(self, deg)

Compute the detrending plane that, if subtracted, minimizes the rms height.

Parameters:

self (Topography) – Topography or line scan container object.

SurfaceTopography.Uniform.Detrending.polyfit(self, deg)
class SurfaceTopography.Uniform.Detrending.DetrendedUniformTopography(topography, detrend_mode='height', coeffs=None, info={})

Bases: DecoratedUniformTopography

Remove trends from a topography. This is achieved by fitting polynomials to the topography data to extract trend lines. The resulting topography is then detrended by substracting these trend lines.

Note on periodicity: Detrended Topographies with mode other than ‘center’ will have is_periodic property set to False.

__init__(topography, detrend_mode='height', coeffs=None, info={})

Note on periodicity: Detrended Topographies with mode other than “center” will have is_periodic property set to False.

Parameters:

  • topography (Topography) – SurfaceTopography to be detrended.

  • detrend_mode (str) – ‘center’: center the topography, no trend correction. ‘height’: adjust slope such that rms height is minimized. ‘slope’: adjust slope such that rms slope is minimized. ‘curvature’: adjust slope and curvature such that rms height is minimized. (Default: ‘height’)

  • coeffs (array_like, optional) – Coefficients of the detrending plane. If not given, they are computed from the topography. (Default: None)

property coeffs
property detrend_mode
property is_periodic

SurfaceTopography stays periodic only after detrend mode “center”. Otherwise the detrended SurfaceTopography is non-periodic.

heights()

Computes the combined profile.

stringify_plane(fmt=<function DetrendedUniformTopography.<lambda>>)

Return a string giving the expression for the detrending plane.

property curvatures

Curvature(s) of the fitted plane.

Return type:

\(\rho = 1 / R\) for line scans or tuple \(\rho_{xx}, \rho_{yy}, \rho_{xy}\) for topographies

SurfaceTopography.Uniform.Filtering module

class SurfaceTopography.Uniform.Filtering.WindowedUniformTopography(topography, window=None, direction=None, info={})

Bases: DecoratedUniformTopography

Construct a topography with a window function applied to it.

name = 'windowed_topography'
__init__(topography, window=None, direction=None, info={})
windowstr, optional

Window for eliminating edge effect. See scipy.signal.get_window. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

directionstr, optional

Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. (Default: None)

property window_data
heights()

Computes the windowed topography.

class SurfaceTopography.Uniform.Filtering.FourierFilteredUniformTopography(topography, filter_function=<function FourierFilteredUniformTopography.<lambda>>, isotropic=True, info={})

Bases: DecoratedUniformTopography

name = 'filtered_topography'
__init__(topography, filter_function=<function FourierFilteredUniformTopography.<lambda>>, isotropic=True, info={})
Parameters:

topography (SurfaceTopography) – The parent topography.

property is_filter_isotropic
filter_function(*args)
Parameters:

  • isotropic (if dim = 2 and filter is not) – qx, qy

  • 1 (if dim =) – q

heights()

Returns array containing the topography data.

class SurfaceTopography.Uniform.Filtering.ShortCutTopography(topography, cutoff_wavevector=None, cutoff_wavelength=None, kind='circular step', info={})

Bases: FourierFilteredUniformTopography

name = 'shortcut_filtered_topography'
__init__(topography, cutoff_wavevector=None, cutoff_wavelength=None, kind='circular step', info={})

Applies a short wavelength cut filter to the topography using fft.

for kind==”circular step” (default), parts of the spectrum with |q| > cutoff_wavevector are set to zero

for kind==”square step”, parts of the spectrum with `q_x > cutoff_wavevector or q_y > cutoff_wavevector ` are set to zero

either cutoff_wavelength or cutoff_wavevector \(= 2 pi /\) cutoff_wavelength have to be provided.

Parameters:

  • topography (Topography)

  • cutoff_wavevector (float)

  • wavevector (highest)

  • cutoff_wavelength (float)

  • wavelength (shortest)

  • kind ({"circular step", "square step"})

Return type:

Topography with filtered heights

Examples

>>> topography.shortcut(cutoff_wavevector=2 * np.pi / l)
>>> topography.shortcut(cutoff_wavelength=l) # equivalent
property cutoff_wavevector
property cutoff_wavelength
class SurfaceTopography.Uniform.Filtering.LongCutTopography(topography, cutoff_wavevector=None, cutoff_wavelength=None, kind='circular step', info={})

Bases: FourierFilteredUniformTopography

name = 'longcut_filtered_topography'
__init__(topography, cutoff_wavevector=None, cutoff_wavelength=None, kind='circular step', info={})

Applies a long wavelength cut filter to the topography using fft.

for kind==”circular step” (default), parts of the spectrum with |q| < cutoff_wavevector are set to zero

for kind==”square step”, parts of the spectrum with `q_x < cutoff_wavevector or q_y < cutoff_wavevector ` are set to zero

either cutoff_wavelength or cutoff_wavevector \(= 2 pi /\) cutoff_wavelength have to be provided.

Parameters:

  • topography (Topography)

  • cutoff_wavevector (float)

  • wavevector (highest)

  • cutoff_wavelength (float)

  • wavelength (shortest)

  • kind ({"circular step", "square step"})

Return type:

Topography with filtered heights

Examples

>>> topography.longcut(cutoff_wavevector=2 * np.pi / l)
>>> topography.longcut(cutoff_wavelength=l) # equivalent
property cutoff_wavevector
property cutoff_wavelength

SurfaceTopography.Uniform.GeometryAnalysis module

Analysis of island geometries

SurfaceTopography.Uniform.GeometryAnalysis.coordination(mask, periodic, stencil=[(1, 0), (0, 1), (-1, 0), (0, -1)])

Return a map with coordination numbers, i.e. the number of neighboring pixels where mask is true.

Parameters:

  • mask (array of bool) – Mask with true/false values (typically indenfying specified regions on a two-dimensional map)

  • periodic (bool) – Mask will be treated as periodic if true.

  • stencil (list of tuples) – Stencil for determining neighborhood. Each entry of the stencil contains relative coordinates of neighboring pixels, i.e. an entry (1, 0) indicates the the pixel to the right is a neighbor.

Returns:

coordination – For each pixel, this array contains the number of neighboring pixels where mask is true.

Return type:

np.ndarray

SurfaceTopography.Uniform.GeometryAnalysis.outer_perimeter_area(c, periodic, stencil=[(1, 0), (0, 1), (-1, 0), (0, -1)])

Return a map where surface points on the outer perimeter are marked.

SurfaceTopography.Uniform.GeometryAnalysis.inner_perimeter_area(c, periodic, stencil=[(1, 0), (0, 1), (-1, 0), (0, -1)])

Return a map where surface points on the inner perimeter are marked.

SurfaceTopography.Uniform.GeometryAnalysis.patch_areas(patch_ids)

Return a list containing patch areas

SurfaceTopography.Uniform.GeometryAnalysis.assign_patch_numbers_profile(mask, periodic)
SurfaceTopography.Uniform.GeometryAnalysis.outer_perimeter_profile(mask, periodic)

SurfaceTopography.Uniform.Imputation module

Filter pipelines for data imputation (filling undefined data points)

class SurfaceTopography.Uniform.Imputation.InterpolateUndefinedDataHarmonic(topography, info={})

Bases: DecoratedUniformTopography

Replace undefined data points by interpolation of neighboring points with harmonic functions (solutions of the Laplace equation).

name = 'interpolate_undefined_data_harmonic'
__init__(topography, info={})
Parameters:

topography (SurfaceTopography) – The parent topography.

property has_undefined_data

By definition, this topography has no undefined data.

heights()

Computes the topography with filled in data points.

SurfaceTopography.Uniform.Imputation.interpolate_undefined_data(self, method='harmonic')

Imputation of undefined data points in topography information that typically occurs in optical measurements.

Parameters:

  • self (SurfaceTopography.Topography or SurfaceTopography.UniformLineScan) – Input topography containing undefined data points.

  • method (str) –

    Imputation methods. Options

    ’harmonic’: Interpolate with harmonic functions

    (Default: ‘harmonic’)

SurfaceTopography.Uniform.Integration module

SurfaceTopography.Uniform.Integration.integrate_psd(self, factor=<function <lambda>>, window=None, reliable=True)
\[m_\alpha = \frac{1}{(2 \pi)^2} \int_{-\infty}^\infty dq_x dq_y factor(q_x, q_y) C^{2D}(q_x, q_y)\]

Discrete

m_alpha = frac{1}{L_x L_y} sum_{q_x, q_y} factor(q_x, q_y) C^{2D}_{q_x, q_y}

Parameters:

factor: function

Function taking as argument the 2 norm of the wavevector (if it accepts only one argument)

func(np.ndarray: q) -> np.ndarray

or the two components of the wavevector qx and qy

func(np.ndarray: qx, np.ndarray:qy) -> np.ndarray

windowstr, optional

Window for eliminating edge effect. See scipy.signal.get_window. (Default: None)

reliablebool, optional

Only return data deemed reliable. (Default: True)

Returns:

weighted_integral: float

SurfaceTopography.Uniform.Integration.integrate_psd_from_profile(self, factor=<function <lambda>>, window=None, reliable=True)

Computes the integral of the 1D PSD weighted by “factor”

Continuum:

\[\frac{1}{2 \pi} \int_0^\infty dq_x factor(q_x) C^{1D}(q_x)\]

Discrete

\[m_\alpha = \frac{1}{L_x} \sum_{q_x} factor(q_x) C^{1D}_{q_x}\]

Parameters:

factor: callable

Function taking as argument the wavevector in the fast scan direction qx

func(np.ndarray: qx) -> np.ndarray

windowstr, optional

Window for eliminating edge effect. See scipy.signal.get_window. (Default: None)

reliablebool, optional

Only return data deemed reliable. (Default: True)

Returns:

weighted_integral: float

SurfaceTopography.Uniform.Integration.moment_power_spectrum(self, order=0, window=None, reliable=True)

Computes

For 2D Topographies, continuum:

\[m_\alpha = \frac{1}{(2 \pi)^2} \int_{-\infty}^\infty dq_x dq_y |q|^{\alpha} C^{2D}(q_x, q_y)\]

Discrete

m_alpha = frac{1}{L_x L_y} sum_{q_x, q_y} |q|^{alpha} C^{2D}_{q_x, q_y}

For line scans, continuum:

\[\frac{1}{2 \pi} \int_0^\infty dq_x |q|^{\alpha} C^{1D}(q_x)\]

Discrete

\[m_\alpha = \frac{1}{L_x} \sum_{q_x} |q|^{\alpha} C^{1D}_{q_x}\]

Parameters:

order: int

order of the moment to compute

windowstr, optional

Window for eliminating edge effect. See scipy.signal.get_window. (Default: None)

reliablebool, optional

Only return data deemed reliable. (Default: True)

SurfaceTopography.Uniform.Interpolation module

SurfaceTopography.Uniform.Interpolation.interpolate_linear(self)

Returns a linear interpolation function based on the topography’s heights. For (2D) topographies, the interpolation is not unique. Each rectangle is split into two triangles that side in the lower left and upper right part of the rectangle.

Note that for nonperiodic line scans/topographies, interpolation only works for positions between 0 and sx - sx/nx - i.e. the interpolated physical domain of the topography is smaller than the nominal domain.

SurfaceTopography.Uniform.Interpolation.interpolate_bicubic(self, derivative='fourier')

Returns a bicubic interpolation function based on the topography’s heights and slopes as obtained using finite-differences (derivative=’fd’) or Fourier derivative (derivative=’fourier’).

Note that for nonperiodic line scans/topographies, interpolation only works for positions between 0 and sx - sx/nx - i.e. the interpolated physical domain of the topography is smaller than the nominal domain.

SurfaceTopography.Uniform.Interpolation.interpolate_fourier(self, nb_grid_pts)

Interpolates the heights of topography on a finer grid given by nb_grid_pts by padding the fourier spectrum with zeros.

Only 2D implemented.

Note: at the nyquist frequency we use the “minimal-oscillation” interpolation, i.e. we assume a cosine wave (https://math.mit.edu/~stevenj/fft-deriv.pdf).

Parameters:
Return type:

SurfaceTopography with interolated values

class SurfaceTopography.Uniform.Interpolation.MirrorStichedTopography(parent_topography, info={})

Bases: DecoratedUniformTopography

adds mirror images at the top (big y) and at the right (big x) of the topography, making it kind of periodic

__init__(parent_topography, info={})
Parameters:

topography (SurfaceTopography) – The parent topography.

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property physical_sizes

Return the physical sizes of the topography.

property nb_grid_pts
heights()

Returns array containing the topography data.

positions()

Returns array containing the lateral positions.

SurfaceTopography.Uniform.PowerSpectrum module

Power-spectral density for uniform topographies.

SurfaceTopography.Uniform.PowerSpectrum.fftfreq(t, meshgrid=True)

computes and returns the grid of wavevectors corresponding to np.fft.fft

SurfaceTopography.Uniform.PowerSpectrum.wavevectors_norm2(t, meshgrid=True)

SurfaceTopography.Uniform.ScalarParameters module

Functions computing scalar roughness parameters

SurfaceTopography.Uniform.ScalarParameters.Rq(topography)

Compute the root mean square height amplitude of a topography or line scan stored on a uniform grid from individual profiles. (This is the Rq value.)

Parameters:

topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

Returns:

rms_height – Root mean square height value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.Sq(topography)

Compute the root mean square height amplitude of a topography or line scan stored on a uniform grid from the whole areal data. (This is the Sq value.)

Parameters:

topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

Returns:

rms_height – Root mean square height value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.rms_gradient(topography, short_wavelength_cutoff=None, window=None, direction=None)

Compute the root mean square amplitude of the height gradient of a topography stored on a uniform grid. The topography must be two-dimensional (i.e. a topography map).

Parameters:

  • topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • short_wavelength_cutoff (float) – All wavelengths below this cutoff will be set to zero amplitude.

  • window (str, optional) – Window for eliminating edge effect. See scipy.signal.get_window. Only used if short wavelength cutoff is set. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

  • direction (str, optional) – Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. Only used if short wavelength cutoff is set. (Default: None)

Returns:

rms_slope – Root mean square slope value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.Rdq(topography, short_wavelength_cutoff=None, window=None, direction=None)

Compute the root mean square amplitude of the height derivative of a topography or line scan stored on a uniform grid. If the topography is two dimensional (i.e. a topography map), the derivative is computed in the x-direction.

Parameters:

  • topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • short_wavelength_cutoff (float) – All wavelengths below this cutoff will be set to zero amplitude.

  • window (str, optional) – Window for eliminating edge effect. See scipy.signal.get_window. Only used if short wavelength cutoff is set. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

  • direction (str, optional) – Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. Only used if short wavelength cutoff is set. (Default: None)

Returns:

rms_slope – Root mean square slope value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.Rddq(topography, short_wavelength_cutoff=None, window=None, direction=None)

Compute the root mean square amplitude of the second derivative (i.e. the curvature) of a topography or line scan stored on a uniform grid. If the topography is two-dimensional (i.e. a topography map), then the rms curvature is computed only along the x-direction.

Parameters:

  • topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • short_wavelength_cutoff (float) – All wavelengths below this cutoff will be set to zero amplitude.

  • window (str, optional) – Window for eliminating edge effect. See scipy.signal.get_window. Only used if short wavelength cutoff is set. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

  • direction (str, optional) – Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. Only used if short wavelength cutoff is set. (Default: None)

Returns:

rms_curvature – Root mean square curvature value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.rms_laplacian(topography, short_wavelength_cutoff=None, window=None, direction=None)

Compute the root mean square amplitude of the Laplacian (i.e. the sum of second derivatives in x- and y-directions) of a topography on a uniform grid. The topography must be two-dimensional (i.e. a topography map).

Parameters:

  • topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • short_wavelength_cutoff (float) – All wavelengths below this cutoff will be set to zero amplitude.

  • window (str, optional) – Window for eliminating edge effect. See scipy.signal.get_window. Only used if short wavelength cutoff is set. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

  • direction (str, optional) – Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. Only used if short wavelength cutoff is set. (Default: None)

Returns:

rms_laplacian – Root mean square Laplacian value.

Return type:

float

SurfaceTopography.Uniform.ScalarParameters.rms_curvature_from_area(topography, short_wavelength_cutoff=None, window=None, direction=None)

Compute the root mean square amplitude of the curvature of a topography stored on a uniform grid. The topography must be two-dimensional (i.e. a topography map). This function returns half the Laplacian.

Parameters:

  • topography (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • short_wavelength_cutoff (float) – All wavelengths below this cutoff will be set to zero amplitude.

  • window (str, optional) – Window for eliminating edge effect. See scipy.signal.get_window. Only used if short wavelength cutoff is set. (Default: no window for periodic Topographies, “hann” window for nonperiodic Topographies)

  • direction (str, optional) – Direction in which the window is applied. Possible options are ‘x’, ‘y’ and ‘radial’. If set to None, it chooses ‘x’ for line scans and ‘radial’ for topographies. Only used if short wavelength cutoff is set. (Default: None)

Returns:

rms_curvature – Root mean square curvature value.

Return type:

float

SurfaceTopography.Uniform.VariableBandwidth module

Variable bandwidth analysis for uniform topographies

SurfaceTopography.Uniform.VariableBandwidth.checkerboard_detrend_profile(self, subdivisions, order=1, return_plane=False)

Perform tilt correction (and substract mean value) in each individual line section of a checkerboard decomposition of a profile. For topography maps, each horizontal slice is interpreted as a profile and this decomposition is carried out for each slice. The tilt correction minimizes the RMS height within each checkerboard.

The main application of this function is to carry out a variable bandwidth analysis of the surface.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map

  • subdivisions (int) – Number of subdivision, i.e. physical_sizes of the checkerboard.

  • order (int, optional) – Maximum order of the polynomial used for detrending. (Default: 1)

  • return_plane (bool, optional) – Return parameters of the detrending plane. (Default: False)

Returns:

  • arr (np.ndarray) – Array with height information, tilt-corrected within each checkerboard.

  • if return_plane == True

  • parameters (np.ndarray) – Array of leading order subdivisions containing the fit parameters.

SurfaceTopography.Uniform.VariableBandwidth.checkerboard_detrend_area(self, subdivisions, order=1, return_plane=False)

Perform tilt correction (and substract mean value) in each individual rectangle of a checkerboard decomposition of the surface. This is identical to subdividing the surface into individual, nonoverlapping rectangles and performing individual tilt corrections on them. The tilt correction minimizes the RMS height within each checkerboard.

The main application of this function is to carry out a variable bandwidth analysis of the surface.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map

  • subdivisions (tuple) – Number of subdivision per dimension, i.e. physical_sizes of the checkerboard.

  • order (int, optional) – Maximum order of the polynomial used for detrending. (Default: 1)

  • return_plane (bool, optional) – Return parameters of the detrending plane. (Default: False)

Returns:

  • arr (np.ndarray) – Array with height information, tilt-corrected within each checkerboard.

  • if return_plane == True

  • parameters (np.ndarray) – Array of leading order subdivisions containing the fit parameters.

SurfaceTopography.Uniform.VariableBandwidth.variable_bandwidth_from_profile(self, quantities='bh', reliable=True, resampling_method=None, nb_grid_pts_cutoff=4, func=<function <lambda>>)

Perform a variable bandwidth analysis by computing the mean root-mean-square height within increasingly finer subdivisions of the profiles (line scans).

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map or line scan.

  • quantities (str, optional) –

    Specification of return tuple, where each string character stand for specific quantity. Possible quantities are

    • ’m’: Magnification (Unit: dimensionless)

    • ’b’: Bandwidth (Unit: length)

    • ’h’: Statistical property (Unit: default length, see func)

    • ’s’: RMS detrending slope (Unit: dimensionless)

    For example, ‘mbh’ return a tuple with the three entries magnification, bandwidth, rms height. (Default: ‘bh’)

  • reliable (bool, optional) – Only return data deemed reliable. (Default: True)

  • resampling_method (str, optional) – Can only be None for the variable bandwidth analysis. (Default: None)

  • nb_grid_pts_cutoff (int, optional) – Minimum nb_grid_pts to allow for subdivision. The analysis will automatically analyze subdivision down to this nb_grid_pts. (Default: 4)

  • func (callable, optional) – Function that computes a statistical property from an array of heights. (Default is the RMS height: np.sqrt(np.mean(h * h)))

Returns:

  • magnifications (np.ndarray) – Array containing the magnifications.

  • bandwidths (np.ndarray) – Array containing the bandwidths, here the physical sizes of the subdivided topography. For 2D topography maps, this is the mean of the two physical sizes of the subdivided section of the topography.

  • statistical_properties (np.ndarray) – Array containing the rms height corresponding to the respective magnification.

  • rms_slopes (np.ndarray) – Array containing the rms values of the detrending slopes corresponding to the respective magnification.

SurfaceTopography.Uniform.VariableBandwidth.variable_bandwidth_from_area(self, quantities='bh', reliable=True, resampling_method=None, nb_grid_pts_cutoff=4, func=<function <lambda>>)

Perform a variable bandwidth analysis by computing the mean root-mean-square height within increasingly finer subdivisions of the surface topography.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – Container storing the uniform topography map.

  • quantities (str, optional) –

    Specification of return tuple, where each string character stand for specific quantity. Possible quantities are

    • ’m’: Magnification (Unit: dimensionless)

    • ’b’: Bandwidth (Unit: length)

    • ’h’: Statistical property (Unit: default length, see func)

    • ’g’: RMS detrending gradient (Unit: dimensionless)

    For example, ‘mbh’ return a tuple with the three entries magnification, bandwidth, rms height. (Default: ‘bh’)

  • reliable (bool, optional) – Only return data deemed reliable. (Default: True)

  • resampling_method (str, optional) – Can only be None for the variable bandwidth analysis. (Default: None)

  • nb_grid_pts_cutoff (int, optional) – Minimum nb_grid_pts to allow for subdivision. The analysis will automatically analyze subdivision down to this nb_grid_pts. (Default: 4)

  • func (callable, optional) – Function that computes a statistical property from an array of heights. (Default is the RMS height: np.sqrt(np.mean(h * h)))

Returns:

  • magnifications (array) – Array containing the magnifications.

  • bandwidths (array) – Array containing the bandwidths, here the physical sizes of the subdivided topography. For 2D topography maps, this is the mean of the two physical sizes of the subdivided section of the topography.

  • statistical_properties (array) – Array containing the rms height corresponding to the respective magnification.

  • rms_gradients (np.ndarray) – Array containing the rms values of the detrending gradients corresponding to the respective magnification.

SurfaceTopography.Uniform.common module

Bin for small common helper function and classes for uniform topographies.

SurfaceTopography.Uniform.common.bandwidth(self)

Computes lower and upper bound of bandwidth, i.e. of the wavelengths or length scales occurring on a topography. The lower end of the bandwidth is given by the pixel size, the upper end by the physical dimension. For topographies with an aspect ratio that is not unity, this function returns the mean value of the two Cartesian directions.

Returns:

  • lower_bound (float) – Lower bound of the bandwidth.

  • upper_bound (float) – Upper bound of the bandwidth.

SurfaceTopography.Uniform.common.domain_decompose(self, subdomain_locations, nb_subdomain_grid_pts, communicator=None)

Turn a topography that is defined over the whole domain into one that is decomposed for each individual MPI process.

Parameters:

  • self (SurfaceTopography or UniformLineScan) – SurfaceTopography object containing height information.

  • subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.

  • nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process. This is only required if decomposition is set to ‘domain’.

  • communicator (mpi4py communicator or NuMPI stub communicator) – Communicator object. Use communicator from topography object if not present. (Default: None)

  • optional (mpi4py communicator or NuMPI stub communicator) – Communicator object. Use communicator from topography object if not present. (Default: None)

Returns:

decomposed_topography – SurfaceTopography object that now holds only data local the MPI process.

Return type:

array

SurfaceTopography.Uniform.common.plot(topography, subplot_location=111)

Plot an image of the topography using matplotlib.

Parameters:

topography (SurfaceTopography) – Height information

class SurfaceTopography.Uniform.common.FilledTopography(topography, fill_value=-inf, info={})

Bases: DecoratedUniformTopography

__init__(topography, fill_value=-inf, info={})

masked (undefined) data is replaced with fill_value.

Parameters:

  • topography (Topography or UniformLineScan instance)

  • fill_value (float or array of floats) – masked value in topography will be replaced

heights()

Returns array containing the topography data.

property has_undefined_data

Module contents

Module containing all functions operating on nonuniform topographies