rfgen 0.1.0__tar.gz

rfgen-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2015-2025, Vladislav A. Yastrebov
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

rfgen-0.1.0/MANIFEST.in

@@ -0,0 +1,24 @@
+# Include license and readme
+include LICENSE
+include README.md
+
+# Include pyproject.toml
+include pyproject.toml
+
+# Include all source files
+recursive-include src/rfgen *.py
+recursive-include src/rfgen py.typed
+
+# Include tests
+recursive-include tests *.py
+
+# Include examples
+recursive-include examples *.py
+
+# Exclude compiled files
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store
+global-exclude *.egg-info
+

rfgen-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: rfgen
+Version: 0.1.0
+Summary: Periodic Gaussian random field generation using spectral filtering techniques
+Author-email: Vladislav Yastrebov <vladislav.yastrebov@minesparis.psl.eu>
+Maintainer-email: Vladislav Yastrebov <vladislav.yastrebov@minesparis.psl.eu>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/vyastreb/rfgen
+Project-URL: Repository, https://github.com/vyastreb/rfgen
+Project-URL: Documentation, https://github.com/vyastreb/rfgen#readme
+Project-URL: Issues, https://github.com/vyastreb/rfgen/issues
+Keywords: random field,Gaussian random field,self-affine,Matérn covariance,spectral methods,Fourier filtering,rough surfaces,stochastic fields
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5.0; extra == "plot"
+Provides-Extra: all
+Requires-Dist: rfgen[dev,plot]; extra == "all"
+Dynamic: license-file
+
+# Generator of a periodic random self-affine field
+
+Generate **periodic** 1D/2D/3D self‑affine Gaussian random fields with a prescribed power‑law spectrum in Fourier space. Includes two variants: a "noisy" spectrum (filtered white noise) and an **exact‑magnitude** spectrum with random phases only. C++ and Python implementations.
+
+---
+
+## Project information
+
++ Author: Vladislav A. Yastrebov
++ Affiliation: CNRS, Mines Paris, Centre des Materiaux, Versailles, Paris
++ Date: 2015-2025
++ Licence: BSD 3-Clause 
+
+---
+
+## Description & references
+
+This repository implements (in C++ and Python) the Fourier‑space filtering approach introduced by:
+
+- **Hu, Y.Z.; Tonder, K.** Simulation of 3‑D random rough surface by 2‑D digital filter in Fourier space. *Int. J. Mach. Tools Manufact.* **32** (1992) 83–90. DOI: [10.1016/0890-6955(92)90064-N](https://doi.org/10.1016/0890-6955%2892%2990064-N)
+
+It has been used, e.g., in:
+
+- **Yastrebov, V.A.; Anciaux, G.; Molinari, J.F.** The role of the roughness spectral breadth in elastic contact of rough surfaces. *J. Mech. Phys. Solids* **107** (2017) 469–493. DOI: [10.1016/j.jmps.2017.07.016](https://doi.org/10.1016/j.jmps.2017.07.016), [arXiv:1704.05650](https://arxiv.org/abs/1704.05650)
+
+**Python** also includes a generator with an *idealized spectrum*: Fourier magnitudes match the target exactly; only phases are random.
+
+---
+
+## Features
+
+- Periodic Gaussian random fields in **1D/2D/3D**
+- Self‑affine spectrum with Hurst exponent 
+- **Two methods**:
+  - *Filtered noise:* spectrum follows the target on average
+  - *Prescribed magnitudes:* exact magnitudes, random phases (real field guaranteed via Hermitian symmetry)
+- Configurable spectral band: $k_{\text{low}}, k_{\text{high}}$
+- Optional **PSD plateau** for $0 \le k < k_{\text{low}}$
+- C++ implementation and pure‑NumPy Python implementation
+
+
+
+## C++ usage
+
+### Build
+
+```bash 
+make # build src/* into bin/SURFACE_GENERATOR
+```
+
+### Run
+
+```bash
+./bin/SURFACE_GENERATOR k1 k2 H N seed rms Npdf plateau
+```
+if you do not provide arguments, it will print the arguments it needs.
+
+**Arguments**
+
++ [1] `k1 (int)` -- lower cutoff wavenumber  
++ [2] `k2 (int)` -- upper cutoff wavenumber
++ [3] `H (double)` -- Hurst exponent, $0 < H < 1$
++ [4] `L (int)` -- number of points per size (prefer powers of 2, i.e. 128, 256, 512, etc.)
++ [5] `s (int)` -- seed for the random number generator 
++ [6] `rms (double)` -- standard deviation of heights
++ [7] `Npdf (int)` -- number of bins in pdf data
++ [8] `if_plateau (bool)` -- boolean argument determining whether the power spectral density has a plateau up to k1? (0 - non, 1 -yes)
+
+## Python usage
+
+The Python code lives in `python/RandomField.py` with a simple test in `python/test.py`.
+Import the module (add the folder to `PYTHONPATH` or place it next to your script):
+
+```python
+import numpy as np
+import RandomField as rf
+
+np.random.seed(42)
+N = 1024
+
+random_field = rf.periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N)
+
+ideal_random_field = rf.ideal_periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N)
+
+ideal_random_field_with_plateau = rf.ideal_periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N, plateau = True)
+```
+
+## API(Python)
+
+```
+periodic_gaussian_random_field(dim, N, Hurst, k_low, k_high, plateau=False, verbose=False)
+    -> ndarray
+  - Filtered white noise. The radially averaged PSD follows the target power law.
+
+ideal_periodic_gaussian_random_field(dim, N, Hurst, k_low, k_high, plateau=False, verbose=False)
+    -> ndarray
+  - Exact Fourier magnitudes per bin (target spectrum), random phases only.
+```
+
+**Parameters:**
+
++ `dim` (int): Dimension of the field (1, 2, or 3).
++ `N` (int): number of points per side in the field (N x N for 2D, N x N x N for 3D).
++ `Hurst` (float): Hurst exponent, in the range [0, 1].
++ `k_low` (float): Lower bound of the wavenumber range (k_low > 0), given in $k1/L$.
++ `k_high` (float): Upper bound of the wavenumber range (k_high < 0.5, which represents Nyquist frequency), given in $k2/L$.
++ `plateau` (bool): If True, the power spectrum is flat up to k_low, otherwise all wavenumbers below k_low are set to zero.
++ `verbose` (bool): If True, print the parameters used for generating the random field.
+
+
+## Examples
+
+Random self-affine 2D field with a "noisy" spectrum with a plateau
+
+![Random self-affine 2D field with a "noisy" spectrum](python/RandomField_2D_filtering.png)
+
+Random self-affine 2D field with an "ideal" spectrum with a plateau
+
+![Random self-affine 2D field with an "ideal" spectrum](python/RandomField_2D_ideal.png)
+
+## License
+
++ C++ repository: BSD 3‑Clause.
++ Python module: CC0 
+
+
+
+
+

rfgen-0.1.0/README.md

@@ -0,0 +1,129 @@
+# Generator of a periodic random self-affine field
+
+Generate **periodic** 1D/2D/3D self‑affine Gaussian random fields with a prescribed power‑law spectrum in Fourier space. Includes two variants: a "noisy" spectrum (filtered white noise) and an **exact‑magnitude** spectrum with random phases only. C++ and Python implementations.
+
+---
+
+## Project information
+
++ Author: Vladislav A. Yastrebov
++ Affiliation: CNRS, Mines Paris, Centre des Materiaux, Versailles, Paris
++ Date: 2015-2025
++ Licence: BSD 3-Clause 
+
+---
+
+## Description & references
+
+This repository implements (in C++ and Python) the Fourier‑space filtering approach introduced by:
+
+- **Hu, Y.Z.; Tonder, K.** Simulation of 3‑D random rough surface by 2‑D digital filter in Fourier space. *Int. J. Mach. Tools Manufact.* **32** (1992) 83–90. DOI: [10.1016/0890-6955(92)90064-N](https://doi.org/10.1016/0890-6955%2892%2990064-N)
+
+It has been used, e.g., in:
+
+- **Yastrebov, V.A.; Anciaux, G.; Molinari, J.F.** The role of the roughness spectral breadth in elastic contact of rough surfaces. *J. Mech. Phys. Solids* **107** (2017) 469–493. DOI: [10.1016/j.jmps.2017.07.016](https://doi.org/10.1016/j.jmps.2017.07.016), [arXiv:1704.05650](https://arxiv.org/abs/1704.05650)
+
+**Python** also includes a generator with an *idealized spectrum*: Fourier magnitudes match the target exactly; only phases are random.
+
+---
+
+## Features
+
+- Periodic Gaussian random fields in **1D/2D/3D**
+- Self‑affine spectrum with Hurst exponent 
+- **Two methods**:
+  - *Filtered noise:* spectrum follows the target on average
+  - *Prescribed magnitudes:* exact magnitudes, random phases (real field guaranteed via Hermitian symmetry)
+- Configurable spectral band: $k_{\text{low}}, k_{\text{high}}$
+- Optional **PSD plateau** for $0 \le k < k_{\text{low}}$
+- C++ implementation and pure‑NumPy Python implementation
+
+
+
+## C++ usage
+
+### Build
+
+```bash 
+make # build src/* into bin/SURFACE_GENERATOR
+```
+
+### Run
+
+```bash
+./bin/SURFACE_GENERATOR k1 k2 H N seed rms Npdf plateau
+```
+if you do not provide arguments, it will print the arguments it needs.
+
+**Arguments**
+
++ [1] `k1 (int)` -- lower cutoff wavenumber  
++ [2] `k2 (int)` -- upper cutoff wavenumber
++ [3] `H (double)` -- Hurst exponent, $0 < H < 1$
++ [4] `L (int)` -- number of points per size (prefer powers of 2, i.e. 128, 256, 512, etc.)
++ [5] `s (int)` -- seed for the random number generator 
++ [6] `rms (double)` -- standard deviation of heights
++ [7] `Npdf (int)` -- number of bins in pdf data
++ [8] `if_plateau (bool)` -- boolean argument determining whether the power spectral density has a plateau up to k1? (0 - non, 1 -yes)
+
+## Python usage
+
+The Python code lives in `python/RandomField.py` with a simple test in `python/test.py`.
+Import the module (add the folder to `PYTHONPATH` or place it next to your script):
+
+```python
+import numpy as np
+import RandomField as rf
+
+np.random.seed(42)
+N = 1024
+
+random_field = rf.periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N)
+
+ideal_random_field = rf.ideal_periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N)
+
+ideal_random_field_with_plateau = rf.ideal_periodic_gaussian_random_field(dim = 2, N = N, Hurst = 0.5, k_low = 4 / N, k_high = 128 / N, plateau = True)
+```
+
+## API(Python)
+
+```
+periodic_gaussian_random_field(dim, N, Hurst, k_low, k_high, plateau=False, verbose=False)
+    -> ndarray
+  - Filtered white noise. The radially averaged PSD follows the target power law.
+
+ideal_periodic_gaussian_random_field(dim, N, Hurst, k_low, k_high, plateau=False, verbose=False)
+    -> ndarray
+  - Exact Fourier magnitudes per bin (target spectrum), random phases only.
+```
+
+**Parameters:**
+
++ `dim` (int): Dimension of the field (1, 2, or 3).
++ `N` (int): number of points per side in the field (N x N for 2D, N x N x N for 3D).
++ `Hurst` (float): Hurst exponent, in the range [0, 1].
++ `k_low` (float): Lower bound of the wavenumber range (k_low > 0), given in $k1/L$.
++ `k_high` (float): Upper bound of the wavenumber range (k_high < 0.5, which represents Nyquist frequency), given in $k2/L$.
++ `plateau` (bool): If True, the power spectrum is flat up to k_low, otherwise all wavenumbers below k_low are set to zero.
++ `verbose` (bool): If True, print the parameters used for generating the random field.
+
+
+## Examples
+
+Random self-affine 2D field with a "noisy" spectrum with a plateau
+
+![Random self-affine 2D field with a "noisy" spectrum](python/RandomField_2D_filtering.png)
+
+Random self-affine 2D field with an "ideal" spectrum with a plateau
+
+![Random self-affine 2D field with an "ideal" spectrum](python/RandomField_2D_ideal.png)
+
+## License
+
++ C++ repository: BSD 3‑Clause.
++ Python module: CC0 
+
+
+
+
+

rfgen-0.1.0/examples/analysis_example.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python
+"""
+Example: Random Field Analysis
+
+Demonstrates the analysis tools available in the rfgen package:
+1. Autocorrelation function computation
+2. Power spectral density (PSD) analysis
+3. Spectral moments and derived quantities
+
+Author: Vladislav Yastrebov, CNRS, Mines Paris - PSL
+License: BSD-3-Clause
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from rfgen import (
+    # Generation
+    selfaffine_field,
+    # Autocorrelation
+    autocorrelation_1d,
+    autocorrelation_2d,
+    correlation_length,
+    integral_correlation_length,
+    # Spectrum
+    psd_1d,
+    psd_radial_average,
+    fit_power_law,
+    estimate_hurst_exponent,
+    # Moments
+    compute_standard_moments,
+    nayak_parameter,
+    rms_quantities,
+)
+
+
+def main():
+    # Parameters
+    N = 1024
+    k_low = 4 / N
+    k_high = 256 / N
+    Hurst = 0.7
+    seed = 42
+
+    rng = np.random.default_rng(seed)
+    spacing = 1.0 / N  # Physical spacing
+
+    print("=" * 60)
+    print("Random Field Analysis Example")
+    print("=" * 60)
+    print(f"\nParameters:")
+    print(f"  Grid size: {N}x{N}")
+    print(f"  Hurst exponent (input): {Hurst}")
+    print(f"  k_low = {k_low:.4f}, k_high = {k_high:.4f}")
+
+    # Generate field
+    print("\nGenerating random field...")
+    field = selfaffine_field(
+        dim=2, N=N, Hurst=Hurst, k_low=k_low, k_high=k_high, rng=rng
+    )
+    field -= np.mean(field)
+    field /= np.std(field)
+
+    # Extract a 1D profile
+    profile = field[N // 2, :]
+
+    # --- Autocorrelation Analysis ---
+    print("\n--- Autocorrelation Analysis ---")
+
+    # 1D autocorrelation
+    R_1d = autocorrelation_1d(profile)
+    l_corr = correlation_length(R_1d, threshold=0.0, spacing=spacing)
+    l_int = integral_correlation_length(R_1d, spacing=spacing)
+
+    print(f"  Correlation length (1D profile): {l_corr:.4f}")
+    print(f"  Integral correlation length: {l_int:.4f}")
+
+    # 2D autocorrelation
+    R_2d = autocorrelation_2d(field)
+
+    # --- Power Spectrum Analysis ---
+    print("\n--- Power Spectrum Analysis ---")
+
+    # 1D PSD
+    k_1d, psd_1d_vals = psd_1d(profile, spacing=spacing)
+
+    # Radially averaged 2D PSD
+    k_radial, psd_radial = psd_radial_average(field, spacing=spacing)
+
+    # Fit power law to estimate Hurst exponent
+    H_est, r_sq = estimate_hurst_exponent(field, k_low=k_low, k_high=k_high, spacing=spacing)
+    print(f"  Estimated Hurst exponent: {H_est:.3f}")
+    print(f"  R² of power-law fit: {r_sq:.4f}")
+
+    # Fit PSD directly
+    A, beta, r_sq2 = fit_power_law(k_radial, psd_radial, k_min=k_low, k_max=k_high)
+    print(f"  PSD power-law exponent β: {beta:.3f}")
+    print(f"  (Expected: β = dim + 2H = {2 + 2*Hurst:.3f})")
+
+    # --- Spectral Moments ---
+    print("\n--- Spectral Moments ---")
+
+    moments = compute_standard_moments(field, spacing=spacing)
+    print("  Standard moments:")
+    for name, value in moments.items():
+        print(f"    {name}: {value:.6e}")
+
+    alpha = nayak_parameter(field, spacing=spacing)
+    print(f"\n  Nayak's bandwidth parameter α: {alpha:.3f}")
+
+    rms = rms_quantities(field, spacing=spacing)
+    print("\n  RMS quantities:")
+    for name, value in rms.items():
+        print(f"    {name}: {value:.6e}")
+
+    # --- Plotting ---
+    fig = plt.figure(figsize=(14, 10))
+
+    # 1. Field
+    ax1 = fig.add_subplot(2, 3, 1)
+    im = ax1.imshow(field, cmap="RdYlBu_r", interpolation="bicubic")
+    ax1.set_title(f"Random Field (H = {Hurst})")
+    ax1.set_xlabel("x")
+    ax1.set_ylabel("y")
+    plt.colorbar(im, ax=ax1, shrink=0.8)
+
+    # 2. 1D Profile
+    ax2 = fig.add_subplot(2, 3, 2)
+    x = np.linspace(0, 1, N)
+    ax2.plot(x, profile, "b-", lw=0.5)
+    ax2.set_xlabel("x / L")
+    ax2.set_ylabel("z / σ")
+    ax2.set_title("1D Profile")
+    ax2.set_xlim(0, 1)
+    ax2.grid(True, alpha=0.3)
+
+    # 3. 1D Autocorrelation
+    ax3 = fig.add_subplot(2, 3, 3)
+    dx = np.linspace(0, 0.5, N // 2)
+    ax3.plot(dx, R_1d[: N // 2], "b-", lw=1.5)
+    ax3.axhline(0, color="k", ls="--", lw=0.5)
+    ax3.axvline(l_corr, color="r", ls="--", lw=1, label=f"l* = {l_corr:.3f}")
+    ax3.set_xlabel("Δx / L")
+    ax3.set_ylabel("R(Δx)")
+    ax3.set_title("Autocorrelation Function (1D)")
+    ax3.set_xlim(0, 0.5)
+    ax3.legend()
+    ax3.grid(True, alpha=0.3)
+
+    # 4. 2D Autocorrelation
+    ax4 = fig.add_subplot(2, 3, 4)
+    extent = [0, 0.3, 0, 0.3]
+    n_show = int(0.3 * N)
+    im4 = ax4.imshow(
+        R_2d[:n_show, :n_show],
+        cmap="RdYlBu_r",
+        interpolation="bicubic",
+        extent=extent,
+        origin="lower",
+    )
+    ax4.set_xlabel("Δx / L")
+    ax4.set_ylabel("Δy / L")
+    ax4.set_title("2D Autocorrelation")
+    plt.colorbar(im4, ax=ax4, shrink=0.8)
+
+    # 5. Radial PSD (log-log)
+    ax5 = fig.add_subplot(2, 3, 5)
+    valid = psd_radial > 0
+    ax5.loglog(k_radial[valid], psd_radial[valid], "b.", ms=3, alpha=0.5, label="Data")
+    # Plot fit
+    k_fit = np.logspace(np.log10(k_low), np.log10(k_high), 100)
+    psd_fit = A * k_fit ** (-beta)
+    ax5.loglog(k_fit, psd_fit, "r-", lw=2, label=f"Fit: k^{{-{beta:.2f}}}")
+    ax5.axvline(k_low, color="g", ls=":", label=f"k_low = {k_low:.3f}")
+    ax5.axvline(k_high, color="g", ls=":")
+    ax5.set_xlabel("k")
+    ax5.set_ylabel("PSD(k)")
+    ax5.set_title("Radially Averaged PSD")
+    ax5.legend(fontsize=8)
+    ax5.grid(True, alpha=0.3, which="both")
+
+    # 6. Summary statistics
+    ax6 = fig.add_subplot(2, 3, 6)
+    ax6.axis("off")
+    summary = [
+        f"Input Hurst: {Hurst:.2f}",
+        f"Estimated Hurst: {H_est:.3f}",
+        f"PSD exponent β: {beta:.3f}",
+        f"Correlation length: {l_corr:.4f}",
+        f"Bandwidth α: {alpha:.3f}",
+        "",
+        f"RMS height: {rms['rms_height']:.4f}",
+        f"RMS slope: {rms['rms_slope']:.4f}",
+        f"RMS curvature: {rms['rms_curvature']:.4f}",
+    ]
+    ax6.text(
+        0.1,
+        0.9,
+        "\n".join(summary),
+        transform=ax6.transAxes,
+        fontsize=11,
+        verticalalignment="top",
+        fontfamily="monospace",
+        bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5),
+    )
+    ax6.set_title("Summary Statistics")
+
+    plt.tight_layout()
+    plt.savefig("random_field_analysis.png", dpi=150)
+    plt.show()
+
+    print("\n" + "=" * 60)
+    print("Analysis complete! Figure saved as 'random_field_analysis.png'")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

rfgen-0.1.0/examples/generation_example.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python
+"""
+Example: Random Field Generation
+
+Demonstrates how to generate periodic Gaussian random fields with different
+spectral characteristics:
+1. Self-affine spectrum (power-law)
+2. Matérn covariance spectrum
+3. Filtered white noise vs. ideal spectrum methods (noise parameter)
+
+Author: Vladislav Yastrebov, CNRS, Mines Paris - PSL
+License: BSD-3-Clause
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from rfgen import selfaffine_field, matern_field
+
+
+def plot_field(field, title, ax=None, cmap="RdYlBu_r"):
+    """Helper function to plot a 2D field."""
+    if ax is None:
+        fig, ax = plt.subplots()
+    im = ax.imshow(field, cmap=cmap, interpolation="bicubic")
+    ax.set_title(title)
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    return im
+
+
+def main():
+    # Parameters
+    N = 512  # Grid size
+    k_low = 8 / N  # Lower cutoff wavenumber
+    k_high = 128 / N  # Upper cutoff wavenumber
+    Hurst = 0.7  # Hurst exponent for self-affine
+    seed = 42  # Random seed for reproducibility
+
+    # Create random number generator
+    rng = np.random.default_rng(seed)
+
+    print("Generating random fields...")
+    print(f"  Grid size: {N}x{N}")
+    print(f"  k_low = {k_low:.4f}, k_high = {k_high:.4f}")
+    print(f"  Hurst exponent: {Hurst}")
+
+    # --- Self-affine fields ---
+    # Method 1: Filtered white noise (noise=True, default)
+    field_noise = selfaffine_field(
+        dim=2, N=N, Hurst=Hurst, k_low=k_low, k_high=k_high, noise=True, rng=rng
+    )
+    field_noise /= np.std(field_noise)  # Normalize
+
+    # Method 2: Ideal spectrum with random phase (noise=False)
+    rng2 = np.random.default_rng(seed)  # Reset RNG
+    field_ideal = selfaffine_field(
+        dim=2, N=N, Hurst=Hurst, k_low=k_low, k_high=k_high, noise=False, rng=rng2
+    )
+    field_ideal /= np.std(field_ideal)
+
+    # With plateau (roll-off at low frequencies)
+    rng3 = np.random.default_rng(seed)
+    field_plateau = selfaffine_field(
+        dim=2, N=N, Hurst=Hurst, k_low=k_low, k_high=k_high, plateau=True, rng=rng3
+    )
+    field_plateau /= np.std(field_plateau)
+
+    # --- Matérn fields ---
+    rng4 = np.random.default_rng(seed)
+    field_matern_noise = matern_field(
+        dim=2,
+        N=N,
+        nu=1.5,  # Smoothness parameter
+        correlation_length=0.05,
+        sigma=1.0,
+        k_low=k_low,
+        k_high=k_high,
+        noise=True,  # With spectral noise
+        rng=rng4,
+    )
+    field_matern_noise /= np.std(field_matern_noise)
+
+    rng5 = np.random.default_rng(seed)
+    field_matern_ideal = matern_field(
+        dim=2,
+        N=N,
+        nu=1.5,
+        correlation_length=0.05,
+        sigma=1.0,
+        k_low=k_low,
+        k_high=k_high,
+        noise=False,  # Ideal spectrum
+        rng=rng5,
+    )
+    field_matern_ideal /= np.std(field_matern_ideal)
+
+    # --- Plotting ---
+    fig, axes = plt.subplots(2, 3, figsize=(14, 9))
+
+    # Self-affine fields
+    im1 = plot_field(field_noise, f"Self-affine (noise=True)\nH = {Hurst}", axes[0, 0])
+    im2 = plot_field(field_ideal, f"Self-affine (noise=False)\nH = {Hurst}", axes[0, 1])
+    im3 = plot_field(field_plateau, f"Self-affine (with plateau)\nH = {Hurst}", axes[0, 2])
+
+    # Matérn fields
+    im4 = plot_field(field_matern_noise, "Matérn (noise=True)\nν = 1.5", axes[1, 0])
+    im5 = plot_field(field_matern_ideal, "Matérn (noise=False)\nν = 1.5", axes[1, 1])
+
+    # Hide empty subplot
+    axes[1, 2].axis("off")
+
+    # Add colorbars
+    for ax, im in zip(axes.flat[:5], [im1, im2, im3, im4, im5]):
+        fig.colorbar(im, ax=ax, orientation="horizontal", pad=0.05, shrink=0.8)
+
+    plt.suptitle("Periodic Gaussian Random Fields", fontsize=14, fontweight="bold")
+    plt.tight_layout()
+    plt.savefig("random_fields_comparison.png", dpi=150)
+    plt.show()
+
+    print("\nFields generated successfully!")
+    print("Figure saved as 'random_fields_comparison.png'")
+
+
+if __name__ == "__main__":
+    main()