rfgen 0.1.0__py3-none-any.whl

rfgen/__init__.py

@@ -0,0 +1,98 @@
+"""
+rfgen - Periodic Gaussian Random Field Generation and Analysis.
+
+A Python package for generating and analyzing periodic Gaussian random fields
+using spectral (Fourier) methods.
+
+Features
+--------
+- Self-affine (power-law) spectrum generation
+- Matérn covariance spectrum generation
+- Both filtered white noise and ideal spectrum methods
+- Fast autocorrelation and PSD computation
+- Spectral moment analysis
+
+Quick Start
+-----------
+>>> import numpy as np
+>>> from rfgen import selfaffine_field
+>>> rng = np.random.default_rng(42)
+>>> field = selfaffine_field(dim=2, N=256, Hurst=0.8, rng=rng)
+
+References
+----------
+Hu, Y.Z. and Tonder, K., 1992. Simulation of 3-D random rough surface by 2-D
+digital filter and Fourier analysis. International Journal of Machine Tools
+and Manufacture, 32(1-2), pp.83-90. DOI: 10.1016/0890-6955(92)90064-N
+
+Author
+------
+Vladislav Yastrebov, CNRS, Mines Paris - PSL, Centre des matériaux
+
+License
+-------
+BSD-3-Clause
+"""
+
+__version__ = "0.1.0"
+__author__ = "Vladislav Yastrebov"
+
+# Main generators
+from .generators import (
+    selfaffine_field,
+    matern_field,
+    matern_spectrum,
+)
+
+# Analysis tools
+from .analysis import (
+    # Autocorrelation
+    autocorrelation_1d,
+    autocorrelation_2d,
+    autocorrelation_nd,
+    correlation_length,
+    integral_correlation_length,
+    # Spectrum
+    psd_1d,
+    psd_2d,
+    psd_radial_average,
+    psd_along_axis,
+    fit_power_law,
+    estimate_hurst_exponent,
+    # Moments
+    spectral_moment,
+    spectral_moment_1d,
+    compute_standard_moments,
+    nayak_parameter,
+    rms_quantities,
+    summit_density_estimate,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Generators
+    "selfaffine_field",
+    "matern_field",
+    "matern_spectrum",
+    # Autocorrelation
+    "autocorrelation_1d",
+    "autocorrelation_2d",
+    "autocorrelation_nd",
+    "correlation_length",
+    "integral_correlation_length",
+    # Spectrum
+    "psd_1d",
+    "psd_2d",
+    "psd_radial_average",
+    "psd_along_axis",
+    "fit_power_law",
+    "estimate_hurst_exponent",
+    # Moments
+    "spectral_moment",
+    "spectral_moment_1d",
+    "compute_standard_moments",
+    "nayak_parameter",
+    "rms_quantities",
+    "summit_density_estimate",
+]

rfgen/analysis/__init__.py

@@ -0,0 +1,56 @@
+"""
+Analysis tools for random fields.
+
+This module provides functions for analyzing random fields:
+
+- Autocorrelation functions (1D, 2D, N-D)
+- Power spectral density computation
+- Spectral moments and derived quantities
+"""
+
+from .autocorrelation import (
+    autocorrelation_1d,
+    autocorrelation_2d,
+    autocorrelation_nd,
+    correlation_length,
+    integral_correlation_length,
+)
+from .spectrum import (
+    psd_1d,
+    psd_2d,
+    psd_radial_average,
+    psd_along_axis,
+    fit_power_law,
+    estimate_hurst_exponent,
+)
+from .moments import (
+    spectral_moment,
+    spectral_moment_1d,
+    compute_standard_moments,
+    nayak_parameter,
+    rms_quantities,
+    summit_density_estimate,
+)
+
+__all__ = [
+    # Autocorrelation
+    "autocorrelation_1d",
+    "autocorrelation_2d",
+    "autocorrelation_nd",
+    "correlation_length",
+    "integral_correlation_length",
+    # Spectrum
+    "psd_1d",
+    "psd_2d",
+    "psd_radial_average",
+    "psd_along_axis",
+    "fit_power_law",
+    "estimate_hurst_exponent",
+    # Moments
+    "spectral_moment",
+    "spectral_moment_1d",
+    "compute_standard_moments",
+    "nayak_parameter",
+    "rms_quantities",
+    "summit_density_estimate",
+]

rfgen/analysis/autocorrelation.py

@@ -0,0 +1,230 @@
+"""
+Autocorrelation function computation for random fields.
+
+Provides fast FFT-based computation of autocorrelation functions
+for 1D profiles and 2D/3D fields.
+
+Author: Vladislav Yastrebov, CNRS, Mines Paris - PSL, Centre des matériaux
+License: BSD-3-Clause
+"""
+
+import numpy as np
+from numpy.fft import fft, ifft, fft2, ifft2, fftn, ifftn
+
+
+def autocorrelation_1d(signal: np.ndarray, normalize: bool = True) -> np.ndarray:
+    """
+    Compute the autocorrelation function of a 1D signal using FFT.
+
+    Uses the Wiener-Khinchin theorem: the autocorrelation is the inverse
+    Fourier transform of the power spectral density.
+
+    Parameters
+    ----------
+    signal : ndarray
+        1D input signal.
+    normalize : bool, optional
+        If True, normalize so R(0) = 1. Default is True.
+
+    Returns
+    -------
+    R : ndarray
+        Autocorrelation function. Same length as input.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from randomfield.analysis import autocorrelation_1d
+    >>> signal = np.random.randn(1024)
+    >>> R = autocorrelation_1d(signal)
+    >>> R[0]  # Should be 1.0 if normalized
+    1.0
+    """
+    signal = np.asarray(signal)
+    if signal.ndim != 1:
+        raise ValueError(f"Expected 1D array, got shape {signal.shape}")
+
+    N = len(signal)
+    zhat = fft(signal)
+    psd = zhat * np.conj(zhat) / N**2
+    R = np.real(ifft(psd))
+
+    if normalize and R[0] != 0:
+        R = R / R[0]
+
+    return R
+
+
+def autocorrelation_2d(field: np.ndarray, normalize: bool = True) -> np.ndarray:
+    """
+    Compute the 2D autocorrelation function of a field using FFT.
+
+    Uses the Wiener-Khinchin theorem: the autocorrelation is the inverse
+    Fourier transform of the power spectral density.
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field with shape (Ny, Nx).
+    normalize : bool, optional
+        If True, normalize so R(0,0) = 1. Default is True.
+
+    Returns
+    -------
+    R : ndarray
+        2D autocorrelation function. Same shape as input.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from randomfield.analysis import autocorrelation_2d
+    >>> field = np.random.randn(128, 128)
+    >>> R = autocorrelation_2d(field)
+    >>> R[0, 0]  # Should be 1.0 if normalized
+    1.0
+    """
+    field = np.asarray(field)
+    if field.ndim != 2:
+        raise ValueError(f"Expected 2D array, got shape {field.shape}")
+
+    Ny, Nx = field.shape
+    zhat = fft2(field)
+    psd = zhat * np.conj(zhat) / (Nx * Ny) ** 2
+    R = np.real(ifft2(psd))
+
+    if normalize and R[0, 0] != 0:
+        R = R / R[0, 0]
+
+    return R
+
+
+def autocorrelation_nd(field: np.ndarray, normalize: bool = True) -> np.ndarray:
+    """
+    Compute the N-dimensional autocorrelation function using FFT.
+
+    Parameters
+    ----------
+    field : ndarray
+        Input field of any dimension.
+    normalize : bool, optional
+        If True, normalize so R at origin = 1. Default is True.
+
+    Returns
+    -------
+    R : ndarray
+        Autocorrelation function. Same shape as input.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from randomfield.analysis import autocorrelation_nd
+    >>> field = np.random.randn(32, 32, 32)
+    >>> R = autocorrelation_nd(field)
+    >>> R[0, 0, 0]  # Should be 1.0 if normalized
+    1.0
+    """
+    field = np.asarray(field)
+    N_total = field.size
+    zhat = fftn(field)
+    psd = zhat * np.conj(zhat) / N_total**2
+    R = np.real(ifftn(psd))
+
+    if normalize:
+        origin = tuple(0 for _ in range(field.ndim))
+        if R[origin] != 0:
+            R = R / R[origin]
+
+    return R
+
+
+def correlation_length(
+    R: np.ndarray,
+    threshold: float = 0.0,
+    spacing: float = 1.0,
+) -> float:
+    """
+    Estimate the correlation length from an autocorrelation function.
+
+    The correlation length is defined as the distance at which the
+    autocorrelation first drops below the threshold value.
+
+    Parameters
+    ----------
+    R : ndarray
+        1D autocorrelation function (assumed normalized, R[0] = 1).
+    threshold : float, optional
+        Threshold value for determining correlation length. Default is 0.0
+        (first zero crossing).
+    spacing : float, optional
+        Grid spacing for converting index to physical distance. Default is 1.0.
+
+    Returns
+    -------
+    l_corr : float
+        Estimated correlation length.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from randomfield.analysis import autocorrelation_1d, correlation_length
+    >>> from randomfield.generators import periodic_gaussian_random_field
+    >>> field = periodic_gaussian_random_field(dim=1, N=1024, k_low=0.01, k_high=0.3)
+    >>> R = autocorrelation_1d(field)
+    >>> l_corr = correlation_length(R, spacing=1.0/1024)
+    """
+    R = np.asarray(R).flatten()
+
+    # Find first crossing below threshold
+    for i, r in enumerate(R):
+        if r < threshold:
+            # Linear interpolation for better estimate
+            if i > 0:
+                r_prev = R[i - 1]
+                # Interpolate: find x where R(x) = threshold
+                frac = (r_prev - threshold) / (r_prev - r + 1e-30)
+                return (i - 1 + frac) * spacing
+            return i * spacing
+
+    # If never crosses, return half the domain
+    return len(R) * spacing / 2
+
+
+def integral_correlation_length(
+    R: np.ndarray,
+    spacing: float = 1.0,
+) -> float:
+    """
+    Compute the integral correlation length.
+
+    The integral correlation length is defined as:
+        L = ∫₀^∞ R(r) dr
+
+    For discrete data, we integrate up to the first zero crossing
+    to avoid issues with oscillating tails.
+
+    Parameters
+    ----------
+    R : ndarray
+        1D autocorrelation function (assumed normalized, R[0] = 1).
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    L : float
+        Integral correlation length.
+    """
+    R = np.asarray(R).flatten()
+
+    # Find first zero crossing
+    n_integrate = len(R)
+    for i, r in enumerate(R):
+        if r < 0:
+            n_integrate = i
+            break
+
+    # Integrate using trapezoidal rule
+    L = np.trapz(R[:n_integrate], dx=spacing)
+
+    return L
+

rfgen/analysis/moments.py

@@ -0,0 +1,330 @@
+"""
+Spectral moments computation for random fields.
+
+Spectral moments are important statistical descriptors of random surfaces
+and fields, used in tribology, contact mechanics, and surface metrology.
+
+The spectral moments m_{ij} are defined as:
+    m_{ij} = ∫∫ kx^i * ky^j * Φ(kx, ky) dkx dky
+
+where Φ is the power spectral density.
+
+References:
+    Nayak, P.R., 1971. Random process model of rough surfaces. 
+    Journal of Lubrication Technology, 93(3), pp.398-407.
+    
+    Greenwood, J.A., 1984. A unified theory of surface roughness. 
+    Proceedings of the Royal Society A, 393(1804), pp.133-157.
+
+Author: Vladislav Yastrebov, CNRS, Mines Paris - PSL, Centre des matériaux
+License: BSD-3-Clause
+"""
+
+import numpy as np
+from numpy.fft import fft2, fftfreq
+
+
+def spectral_moment(
+    field: np.ndarray,
+    i: int,
+    j: int,
+    spacing: float = 1.0,
+) -> float:
+    """
+    Compute the spectral moment m_{ij} of a 2D field.
+
+    The spectral moment is defined as:
+        m_{ij} = ∫∫ |kx|^i * |ky|^j * Φ(kx, ky) dkx dky
+
+    where Φ is the power spectral density.
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field.
+    i : int
+        Power of kx (non-negative integer).
+    j : int
+        Power of ky (non-negative integer).
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    m_ij : float
+        The spectral moment m_{ij}.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from randomfield.analysis import spectral_moment
+    >>> from randomfield.generators import periodic_gaussian_random_field
+    >>> field = periodic_gaussian_random_field(N=256, Hurst=0.8)
+    >>> m00 = spectral_moment(field, 0, 0)  # Variance
+    >>> m20 = spectral_moment(field, 2, 0)  # Related to mean square slope in x
+    """
+    field = np.asarray(field)
+    if field.ndim != 2:
+        raise ValueError(f"Expected 2D array, got shape {field.shape}")
+    if i < 0 or j < 0:
+        raise ValueError("Moment indices must be non-negative")
+
+    Ny, Nx = field.shape
+    dk = 1.0 / spacing  # Frequency resolution
+
+    # Compute PSD
+    zhat = fft2(field)
+    psd = np.abs(zhat) ** 2 / (Nx * Ny) ** 2
+
+    # Frequency arrays
+    kx = fftfreq(Nx, d=spacing)
+    ky = fftfreq(Ny, d=spacing)
+    kx_grid, ky_grid = np.meshgrid(kx, ky)
+
+    # Use absolute values for moments (symmetric about origin)
+    kx_power = np.abs(kx_grid) ** i if i > 0 else np.ones_like(kx_grid)
+    ky_power = np.abs(ky_grid) ** j if j > 0 else np.ones_like(ky_grid)
+
+    # Integrate
+    m_ij = np.sum(kx_power * ky_power * psd) * (dk / Nx) * (dk / Ny)
+
+    return float(m_ij)
+
+
+def spectral_moment_1d(
+    signal: np.ndarray,
+    n: int,
+    spacing: float = 1.0,
+) -> float:
+    """
+    Compute the n-th spectral moment of a 1D signal.
+
+    The spectral moment is defined as:
+        m_n = ∫ |k|^n * Φ(k) dk
+
+    Parameters
+    ----------
+    signal : ndarray
+        1D input signal.
+    n : int
+        Order of the moment (non-negative integer).
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    m_n : float
+        The n-th spectral moment.
+    """
+    signal = np.asarray(signal)
+    if signal.ndim != 1:
+        raise ValueError(f"Expected 1D array, got shape {signal.shape}")
+    if n < 0:
+        raise ValueError("Moment order must be non-negative")
+
+    N = len(signal)
+    dk = 1.0 / (N * spacing)
+
+    # Compute PSD
+    zhat = np.fft.fft(signal)
+    psd = np.abs(zhat) ** 2 / N**2
+
+    # Frequencies
+    k = fftfreq(N, d=spacing)
+
+    # Use absolute values
+    k_power = np.abs(k) ** n if n > 0 else np.ones_like(k)
+
+    # Integrate
+    m_n = np.sum(k_power * psd) * dk
+
+    return float(m_n)
+
+
+def compute_standard_moments(
+    field: np.ndarray,
+    spacing: float = 1.0,
+) -> dict[str, float]:
+    """
+    Compute standard spectral moments for a 2D surface.
+
+    Computes m00, m10, m01, m20, m02, m11, m40, m04, m22 which are
+    commonly used in surface roughness characterization.
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field.
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    moments : dict
+        Dictionary with moment names as keys and values.
+
+    Notes
+    -----
+    Physical interpretations:
+    - m00: Variance of the surface heights
+    - m20, m02: Related to mean square slopes
+    - m40, m04: Related to mean square curvatures
+    - m11: Cross-correlation of slopes
+
+    For isotropic surfaces: m20 ≈ m02, m40 ≈ m04.
+    """
+    moments = {}
+
+    # Zero-order moment (variance)
+    moments["m00"] = spectral_moment(field, 0, 0, spacing)
+
+    # First-order moments
+    moments["m10"] = spectral_moment(field, 1, 0, spacing)
+    moments["m01"] = spectral_moment(field, 0, 1, spacing)
+
+    # Second-order moments
+    moments["m20"] = spectral_moment(field, 2, 0, spacing)
+    moments["m02"] = spectral_moment(field, 0, 2, spacing)
+    moments["m11"] = spectral_moment(field, 1, 1, spacing)
+
+    # Fourth-order moments
+    moments["m40"] = spectral_moment(field, 4, 0, spacing)
+    moments["m04"] = spectral_moment(field, 0, 4, spacing)
+    moments["m22"] = spectral_moment(field, 2, 2, spacing)
+
+    return moments
+
+
+def nayak_parameter(field: np.ndarray, spacing: float = 1.0) -> float:
+    """
+    Compute Nayak's bandwidth parameter α.
+
+    The bandwidth parameter is defined as:
+        α = m0 * m4 / m2²
+
+    where m0, m2, m4 are isotropic spectral moments.
+
+    For Gaussian surfaces: α ≥ 1, with α = 1 for a narrow-band surface.
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field.
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    alpha : float
+        Nayak's bandwidth parameter.
+
+    References
+    ----------
+    Nayak, P.R., 1971. Random process model of rough surfaces.
+    Journal of Lubrication Technology, 93(3), pp.398-407.
+    """
+    m00 = spectral_moment(field, 0, 0, spacing)
+    m20 = spectral_moment(field, 2, 0, spacing)
+    m02 = spectral_moment(field, 0, 2, spacing)
+    m40 = spectral_moment(field, 4, 0, spacing)
+    m04 = spectral_moment(field, 0, 4, spacing)
+
+    # Isotropic averages
+    m2 = 0.5 * (m20 + m02)
+    m4 = 0.5 * (m40 + m04)
+
+    if m2 == 0:
+        return np.inf
+
+    alpha = m00 * m4 / m2**2
+
+    return alpha
+
+
+def rms_quantities(field: np.ndarray, spacing: float = 1.0) -> dict[str, float]:
+    """
+    Compute RMS surface quantities from spectral moments.
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field.
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    quantities : dict
+        Dictionary containing:
+        - 'rms_height': RMS height (σ)
+        - 'rms_slope_x': RMS slope in x direction
+        - 'rms_slope_y': RMS slope in y direction
+        - 'rms_slope': Isotropic RMS slope
+        - 'rms_curvature_x': RMS curvature in x direction
+        - 'rms_curvature_y': RMS curvature in y direction
+        - 'rms_curvature': Isotropic RMS curvature
+    """
+    m00 = spectral_moment(field, 0, 0, spacing)
+    m20 = spectral_moment(field, 2, 0, spacing)
+    m02 = spectral_moment(field, 0, 2, spacing)
+    m40 = spectral_moment(field, 4, 0, spacing)
+    m04 = spectral_moment(field, 0, 4, spacing)
+
+    # Prefactor for slopes and curvatures from spectral moments
+    # Slope: ∂z/∂x has PSD = (2πkx)² * Φ(kx,ky)
+    # Curvature: ∂²z/∂x² has PSD = (2πkx)⁴ * Φ(kx,ky)
+    two_pi_sq = (2 * np.pi) ** 2
+    two_pi_4 = (2 * np.pi) ** 4
+
+    quantities = {
+        "rms_height": np.sqrt(m00),
+        "rms_slope_x": np.sqrt(two_pi_sq * m20),
+        "rms_slope_y": np.sqrt(two_pi_sq * m02),
+        "rms_slope": np.sqrt(two_pi_sq * 0.5 * (m20 + m02)),
+        "rms_curvature_x": np.sqrt(two_pi_4 * m40),
+        "rms_curvature_y": np.sqrt(two_pi_4 * m04),
+        "rms_curvature": np.sqrt(two_pi_4 * 0.5 * (m40 + m04)),
+    }
+
+    return quantities
+
+
+def summit_density_estimate(field: np.ndarray, spacing: float = 1.0) -> float:
+    """
+    Estimate the density of summits (local maxima) per unit area.
+
+    Based on random process theory for Gaussian surfaces:
+        D_s = (1 / 6π√3) * √(m4/m2)
+
+    Parameters
+    ----------
+    field : ndarray
+        2D input field.
+    spacing : float, optional
+        Grid spacing. Default is 1.0.
+
+    Returns
+    -------
+    D_s : float
+        Summit density (number per unit area).
+
+    Notes
+    -----
+    This is a statistical estimate valid for isotropic Gaussian surfaces.
+    The actual count of local maxima may differ.
+    """
+    m20 = spectral_moment(field, 2, 0, spacing)
+    m02 = spectral_moment(field, 0, 2, spacing)
+    m40 = spectral_moment(field, 4, 0, spacing)
+    m04 = spectral_moment(field, 0, 4, spacing)
+
+    m2 = 0.5 * (m20 + m02)
+    m4 = 0.5 * (m40 + m04)
+
+    if m2 <= 0:
+        return 0.0
+
+    D_s = (1.0 / (6 * np.pi * np.sqrt(3))) * np.sqrt(m4 / m2)
+
+    return D_s
+