GitHub - For-a-few-DPPs-more/hyperuniform-samplers: Hyperuniform Point Clouds Database Hyperuniform point clouds (e.g. stealthy point clouds, or blue noise) on the unit hypercube [0,1)ᴰ, sampled with the qmc-sampler Python package.

GitHub

6 min read Original article ↗

DOI GitHub Home

This is the GitHub companion repository of the Hyperuniform samples database stored on Zenodo. The database contains hyperuniform point clouds (e.g. blue noise) on the unit hypercube [0,1)ᴰ.

2D example (the N = 1024, D = 2 point clouds (l2) of this database) :

2D example, N = 1024, l2

Installation

Quick Start

First clone this repository:

git clone https://github.com/For-a-few-DPPs-more/hyperuniform-samplers.git
cd hyperuniform-samplers

Then, from the terminal, load the full database and generate a new randomized point cloud:

python src/load_data.py --dim all --ball all
python src/new_data.py --dim 2 --npoints 1024 --ball l2 --seed 42

Or from a notebook: see quick_start.ipynb and follow the instructions.

Data characteristics

  • Format: HDF5 (Python, C++, MATLAB, Julia, R, ...).
  • Size: ≈ 500 MB by default, ≈ 3.2 GB with the large point clouds (see note below).
  • Number of points: native N = 2¹⁰ to 2¹⁷ (powers of 2); up to N = 2²⁴ with tiling.
  • Dimension: native D = 2 to 16, plus D = 20, 24, 28 and D = 32; any 2 ≤ D ≤ 32 with projection.

Note: Large storage. In low dimensions (D ≤ 4), the Zenodo database provides additional, much larger point clouds, to be downloaded manually (larges.zip, 2.7 GB). They go up to N = 2²⁷ ≈ 134 million points in 2D, 2²⁵ ≈ 34 million in 3D and 2²¹ ≈ 2 million in 4D.

ND_coverage

Sampling method

The samples were generated by spectral optimisation (non-uniform Fourier transform) with the qmc-sampler python package: the sampling algorithm select a spectral exclusion set, initialise the point cloud with random i.i.d points on the unit hypercube, then run a gradient descent on the Fourier loss, then complete the optimisation with a quasi-newton finishing to reach a nearly minimal configuration S(k) ≤ 10⁻¹⁰ (at float32 precision, the true theoreticall minimum is around S(k) ≤ 10⁻¹2 / 10⁻¹3). Each resulting point cloud comes in two versions:

  • l2: stealthy scattering intensity S(k) ≤ 10⁻¹⁰ in a standard Euclidean ball (thus, an "l2" ball) of wave vectors |k| ≤ cst ;
  • wd: stealthy scattering intensity S(k) ≤ 10⁻¹⁰ in an exclusion set defined as r(k) >= cst, where r(k) is the fourier decomposition of the wrap-around discrepancy (thus, "wd" which stand for wrap-around discrepancy);

Note that l2 is isotropic (rotation invariant), which is good for blue noise properties, and wd has a stary, axis oriented shape which is good for qmc integration on low effective dimensional integrands:

exclusion_regions

All details for reproducibility are in SAMPLING.md.

Guarantees

Stealthiness

For a wave vector k = (k₁, ..., k_D) with integer components, let define the scattering intensity S(k) as:

S(k) = |Σⱼ exp(2iπ ⟨k, xⱼ⟩)|² / N

A near-zero S(k), as here for the provided samples (S(k) ≤ 10⁻¹⁰ on the exclusion set) means that the Monte Carlo integration error is controlled for the low-frequency test function x ↦ exp(2iπ ⟨k, x⟩). The number of such controlled wave vectors is 2 * Chi * (N -1) * D where Chi is an hyperparametter that we set to 0.43 (common choices are 0.3 and 0.4, see for exemple Morse et al. (2023) ) and the factor 2 comes from the symmetry S(k) = S(-k).

Following plots show the values of S(k) for the 2 ball families, 1. as a power spectrum map (kx, ky) ↦ S(k) for 2d point clouds only and 2. as a radial |k| ↦ S(k) curve (average over radial bins) for all dimensions D = 2 to 16 :

  • (kx, ky) ↦ S(k) power spectrums

all χ, N = 8192, D = 2

power spectrum

  • |k| ↦ S(k) curves

l2 ball, N = 1024, D = 2 to 16

l2

wd ball, N = 1024, D = 2 to 16

wd

Randomisability

Spectral optimisation enforces periodic boundary conditions, so a sample can be randomised by a simple shift:

X_new = (X - s) mod 1, s drawn uniformly in [0,1]^D

Extensibility

src/load_data.py downloads the samples with 2¹⁰ ≤ N ≤ 2¹⁷ and D = 2 to 16, 20, 24, 28, 32. Other (N, D) shapes are produced on the fly by src/new_data.py, at a controlled loss of quality:

  • Tiling (more points): copies of the periodic point cloud are combined into a larger one, up to N = 2²⁴. The stealthiness degrades proportionally to the increase in points:

    sup S_t(k) = sup S(k) × N_t / N

    where N is the original number of points and N_t the number after tiling. See TILING.md.

    Tiling effect

    ⚠️ Warning : The tiling procedure implemented here relies on 45° rotations of the points, except for certain special powers-of-two number of points. Tiling should therefore be used with caution for non-isotropic (WD) hyperuniform samples, as it will break axial alignment.

  • Projection (lower dimension): 17 ≤ D_proj ≤ 19 is projected from D = 20, 21 ≤ D_proj ≤ 23 from D = 24 and so on. ⚠️ Projection also comes with additional caveats, see PROJECTION.md.

Use cases

  • Rendering and blue noise: anti-aliasing, path tracing, dithering, denoising textures.
  • Spatial sampling: isotropic particle initialisation (SPH, molecular dynamics) with periodic boundary conditions.
  • Monte Carlo / QMC integration: especially for periodic or smooth integrands, see BENCHMARK.md for discrepancy comparison with Sobol and Halton sequences. Random shifts give independent replicas for error bars
  • Machine learning and design of experiments: initial designs, uncertainty quantification.
  • Hyperuniformity research: reference data to study structure factors and to benchmark new samplers.

Note - adaptative sampling Although this database contains only uniform samples, spectral methods proposed in SAMPLING.md support adaptative sampling, by passing a target distribution to the sampler. This could be of use for importance sampling or when one require well distributed points, but under a specific spatial distribution.

Acknowledgements

GPU kernel reductions rely on PyKeOps:

Charlier, Feydy, Glaunès, Collin, Durif, "Kernel Operations on the GPU, with Autodiff, without Memory Overflows", JMLR 22(74), 2021.

The large 2D and 3D point clouds rely on FINUFFT:

Barnett, Magland, af Klinteberg, "A parallel non-uniform fast Fourier transform library based on an exponential of semicircle kernel", SIAM J. Sci. Comput. 41(5), 2019.

Citation

If you use this database, you can cite it as:

@dataset{bardenet_lachiezerey_decacqueray_2026_hyperuniform,
  author    = {Bardenet, Rémi and Lachièze-Rey, Raphaël and de Cacqueray, Armand},
  title     = {Hyperuniform samples (stealthy point clouds)},
  year      = {2026},
  publisher = {Zenodo},
  version   = {v5},
  doi       = {10.5281/zenodo.23244509},
  url       = {https://doi.org/10.5281/zenodo.23244509}
}

Licence

The database and the source code are free to use under the MIT licence.