qmc-sampler 2.0.2__tar.gz → 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.pyc
3
+ dist/
4
+ build/
5
+ data/*
6
+ !data/README.md
7
+ new_data/*
8
+ !new_data/README.md
9
+ mirror_data/*
10
+ !mirror_data/README.md
11
+ !mirror_data/SHA256SUMS.txt
12
+ *test.ipynb
13
+ *.egg-info/
@@ -0,0 +1,114 @@
1
+ Metadata-Version: 2.5
2
+ Name: qmc-sampler
3
+ Version: 3.0.0
4
+ Summary: QMC point sets by spectral optimisation (L2, L1 and WD exclusion regions)
5
+ Project-URL: Repository, https://github.com/For-a-few-DPPs-more/hyperuniform-samplers
6
+ License: MIT
7
+ Keywords: NUFFT,QMC,hyperuniformity,point sampling,quasi-Monte Carlo,wrap-around discrepancy
8
+ Requires-Python: >=3.9
9
+ Requires-Dist: matplotlib
10
+ Requires-Dist: numpy
11
+ Requires-Dist: pykeops
12
+ Requires-Dist: scipy
13
+ Provides-Extra: finufft
14
+ Requires-Dist: finufft; extra == 'finufft'
15
+ Provides-Extra: torch
16
+ Requires-Dist: torch; extra == 'torch'
17
+ Description-Content-Type: text/markdown
18
+
19
+ # qmc-sampler
20
+
21
+ [![PyPI](https://img.shields.io/pypi/v/qmc-sampler)](https://pypi.org/project/qmc-sampler/)
22
+ [![GitHub](https://img.shields.io/badge/GitHub-hyperuniform-samplers-blue?logo=github)](https://github.com/For-a-few-DPPs-more/qmc-sampler)
23
+ [![Dataset](https://zenodo.org/badge/DOI/10.5281/zenodo.23605844.svg)](https://doi.org/10.5281/zenodo.23605844)
24
+
25
+ **Quasi-Monte Carlo point sampling from spectral optimisation.**
26
+
27
+ `qmc-sampler` provides several sampling methods for generating quasi-Monte Carlo (QMC) point sets, by minimising the spectral loss over all wave vectors within an exclusion region. 3 kinds of exclusion regions, with different geometrical shape, are available: l2, l1, wd. It was used to generate an extensive dataset of hyperuniform samples, published on [Zenodo](https://doi.org/10.5281/zenodo.23605844).
28
+
29
+ ## Installation
30
+
31
+ Install from PyPI:
32
+
33
+ ```bash
34
+ pip install qmc-sampler
35
+ ```
36
+
37
+ ## Available sampling methods
38
+
39
+ The package provides three sampling methods:
40
+
41
+ - **`sample_l2(N, D, **kwargs)`** — uses a classical isotropic L_2-ball as the spectral exclusion region.
42
+ - **`sample_l1(N, D, **kwargs)`** — uses an L_1-ball, producing an anisotropic spectral exclusion region that can be useful when exploiting low effective dimensionality.
43
+ - **`sample_wd(N, D, **kwargs)`** — uses the wrap-around discrepancy (WD), a criterion designed to further exploit low-effective-dimensionality structure.
44
+
45
+ Here, `N` denotes the number of points and `D` the dimension.
46
+
47
+ ## Basic usage
48
+
49
+ ```python
50
+ from qmc_sampler import sample_l1, sample_l2, sample_wd
51
+
52
+ N = 1000
53
+ D = 2
54
+
55
+ points_l2 = sample_l2(N, D)
56
+ points_l1 = sample_l1(N, D)
57
+ points_wd = sample_wd(N, D)
58
+
59
+ ```
60
+
61
+ Additional keyword arguments e.g. "Chi = 0.4" can be passed to the sampling functions and forwarded to the underlying implementation.
62
+
63
+ ## Backends (KeOps, torch, FINUFFT)
64
+
65
+ All heavy computations go through one of three backends, which the user can controll.
66
+ e.g., to use the finufft backend in 2D and 3D:
67
+
68
+ ```bash
69
+ pip install finufft # or: pip install "qmc-sampler[finufft]"
70
+ ```
71
+
72
+ ```python
73
+ import qmc_sampler
74
+
75
+ qmc_sampler.select_backend(dimensions={2, 3}, backend="finufft")
76
+ ```
77
+
78
+ | backend | method | complexity | dimensions | accuracy |
79
+ |-------------|----------------------------------|---------------------|------------|--------------------------------------------|
80
+ | `"keops"` | direct sums, pykeops (GPU if available) | O(N M) | any | exact up to machine precision |
81
+ | `"torch"` | direct sums, torch (cuda if available) | O(N M) | any | exact up to machine precision |
82
+ | `"finufft"` | non-uniform FFT | O(N log N + M) | D <= 3 | relative tolerance 1e-4 (float32), 1e-8 (float64) |
83
+
84
+ Here `M` is the number of wave vectors, which grows like `N`.
85
+
86
+ **By default, FINUFFT is not enabled**: the backend is `"keops"` if pykeops is available, otherwise
87
+ `"torch"`, and `"finufft"` only if neither is installed. This guarantees that, unless you ask
88
+ otherwise, every Fourier sum is computed exactly, up to machine precision.
89
+
90
+ **FINUFFT is nevertheless strongly recommended in 2D and 3D**: it reduces the cost of each
91
+ iteration from O(N^2) to O(N log N), which typically makes sampling one to several orders of
92
+ magnitude faster, and makes large `N` reachable. Enable it manually:
93
+
94
+ ## Plotting utilities
95
+
96
+ The package also exposes plotting functions (adapted from `blue_sampler`):
97
+
98
+ ```python
99
+ from qmc_sampler import plot, plot_structure_factor
100
+
101
+ plot(...)
102
+ plot_structure_factor(...)
103
+ ```
104
+
105
+ Like the samplers, `plot_structure_factor` uses the backend selected for the dimension of the points (see above).
106
+
107
+ ## Links
108
+
109
+ - **Github source:** [repository](https://github.com/For-a-few-DPPs-more/hyperuniform-samplers)
110
+ - **pipy:** [package](https://pypi.org/project/qmc-sampler/)
111
+
112
+ ## License
113
+
114
+ MIT
@@ -0,0 +1,96 @@
1
+ # qmc-sampler
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/qmc-sampler)](https://pypi.org/project/qmc-sampler/)
4
+ [![GitHub](https://img.shields.io/badge/GitHub-hyperuniform-samplers-blue?logo=github)](https://github.com/For-a-few-DPPs-more/qmc-sampler)
5
+ [![Dataset](https://zenodo.org/badge/DOI/10.5281/zenodo.23605844.svg)](https://doi.org/10.5281/zenodo.23605844)
6
+
7
+ **Quasi-Monte Carlo point sampling from spectral optimisation.**
8
+
9
+ `qmc-sampler` provides several sampling methods for generating quasi-Monte Carlo (QMC) point sets, by minimising the spectral loss over all wave vectors within an exclusion region. 3 kinds of exclusion regions, with different geometrical shape, are available: l2, l1, wd. It was used to generate an extensive dataset of hyperuniform samples, published on [Zenodo](https://doi.org/10.5281/zenodo.23605844).
10
+
11
+ ## Installation
12
+
13
+ Install from PyPI:
14
+
15
+ ```bash
16
+ pip install qmc-sampler
17
+ ```
18
+
19
+ ## Available sampling methods
20
+
21
+ The package provides three sampling methods:
22
+
23
+ - **`sample_l2(N, D, **kwargs)`** — uses a classical isotropic L_2-ball as the spectral exclusion region.
24
+ - **`sample_l1(N, D, **kwargs)`** — uses an L_1-ball, producing an anisotropic spectral exclusion region that can be useful when exploiting low effective dimensionality.
25
+ - **`sample_wd(N, D, **kwargs)`** — uses the wrap-around discrepancy (WD), a criterion designed to further exploit low-effective-dimensionality structure.
26
+
27
+ Here, `N` denotes the number of points and `D` the dimension.
28
+
29
+ ## Basic usage
30
+
31
+ ```python
32
+ from qmc_sampler import sample_l1, sample_l2, sample_wd
33
+
34
+ N = 1000
35
+ D = 2
36
+
37
+ points_l2 = sample_l2(N, D)
38
+ points_l1 = sample_l1(N, D)
39
+ points_wd = sample_wd(N, D)
40
+
41
+ ```
42
+
43
+ Additional keyword arguments e.g. "Chi = 0.4" can be passed to the sampling functions and forwarded to the underlying implementation.
44
+
45
+ ## Backends (KeOps, torch, FINUFFT)
46
+
47
+ All heavy computations go through one of three backends, which the user can controll.
48
+ e.g., to use the finufft backend in 2D and 3D:
49
+
50
+ ```bash
51
+ pip install finufft # or: pip install "qmc-sampler[finufft]"
52
+ ```
53
+
54
+ ```python
55
+ import qmc_sampler
56
+
57
+ qmc_sampler.select_backend(dimensions={2, 3}, backend="finufft")
58
+ ```
59
+
60
+ | backend | method | complexity | dimensions | accuracy |
61
+ |-------------|----------------------------------|---------------------|------------|--------------------------------------------|
62
+ | `"keops"` | direct sums, pykeops (GPU if available) | O(N M) | any | exact up to machine precision |
63
+ | `"torch"` | direct sums, torch (cuda if available) | O(N M) | any | exact up to machine precision |
64
+ | `"finufft"` | non-uniform FFT | O(N log N + M) | D <= 3 | relative tolerance 1e-4 (float32), 1e-8 (float64) |
65
+
66
+ Here `M` is the number of wave vectors, which grows like `N`.
67
+
68
+ **By default, FINUFFT is not enabled**: the backend is `"keops"` if pykeops is available, otherwise
69
+ `"torch"`, and `"finufft"` only if neither is installed. This guarantees that, unless you ask
70
+ otherwise, every Fourier sum is computed exactly, up to machine precision.
71
+
72
+ **FINUFFT is nevertheless strongly recommended in 2D and 3D**: it reduces the cost of each
73
+ iteration from O(N^2) to O(N log N), which typically makes sampling one to several orders of
74
+ magnitude faster, and makes large `N` reachable. Enable it manually:
75
+
76
+ ## Plotting utilities
77
+
78
+ The package also exposes plotting functions (adapted from `blue_sampler`):
79
+
80
+ ```python
81
+ from qmc_sampler import plot, plot_structure_factor
82
+
83
+ plot(...)
84
+ plot_structure_factor(...)
85
+ ```
86
+
87
+ Like the samplers, `plot_structure_factor` uses the backend selected for the dimension of the points (see above).
88
+
89
+ ## Links
90
+
91
+ - **Github source:** [repository](https://github.com/For-a-few-DPPs-more/hyperuniform-samplers)
92
+ - **pipy:** [package](https://pypi.org/project/qmc-sampler/)
93
+
94
+ ## License
95
+
96
+ MIT
@@ -1,43 +1,49 @@
1
-
2
- [build-system]
3
- requires = ["hatchling>=1.26"]
4
- build-backend = "hatchling.build"
5
-
6
- [project]
7
- name = "qmc-sampler"
8
- version = "2.0.2"
9
- description = "QMC sampling methods based on blue_sampler"
10
- readme = "README.md"
11
- license = { text = "MIT" }
12
- requires-python = ">=3.9"
13
-
14
- keywords = [
15
- "QMC",
16
- "quasi-Monte Carlo",
17
- "point sampling",
18
- "hyperuniformity",
19
- "wrap-around discrepancy",
20
- "NUFFT",
21
- ]
22
-
23
- dependencies = [
24
- "blue-sampler[keops]",
25
- "scipy",
26
- ]
27
-
28
- [project.urls]
29
- Repository = "https://github.com/For-a-few-DPPs-more/hyperuniform-samplers"
30
-
31
- [tool.hatch.build.targets.wheel]
32
- packages = ["src/qmc_sampler"]
33
-
34
- [tool.hatch.build]
35
- exclude = [
36
- "**/*.ipynb",
37
- "**/*.jpg",
38
- "**/*.png",
39
- "**/__pycache__",
40
- ]
41
-
42
- [tool.ruff]
43
- line-length = 100
1
+
2
+ [build-system]
3
+ requires = ["hatchling>=1.26"]
4
+ build-backend = "hatchling.build"
5
+
6
+ [project]
7
+ name = "qmc-sampler"
8
+ version = "3.0.0"
9
+ description = "QMC point sets by spectral optimisation (L2, L1 and WD exclusion regions)"
10
+ readme = "README.md"
11
+ license = { text = "MIT" }
12
+ requires-python = ">=3.9"
13
+
14
+ keywords = [
15
+ "QMC",
16
+ "quasi-Monte Carlo",
17
+ "point sampling",
18
+ "hyperuniformity",
19
+ "wrap-around discrepancy",
20
+ "NUFFT",
21
+ ]
22
+
23
+ dependencies = [
24
+ "numpy",
25
+ "scipy",
26
+ "matplotlib",
27
+ "pykeops",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ finufft = ["finufft"]
32
+ torch = ["torch"]
33
+
34
+ [project.urls]
35
+ Repository = "https://github.com/For-a-few-DPPs-more/hyperuniform-samplers"
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/qmc_sampler"]
39
+
40
+ [tool.hatch.build]
41
+ exclude = [
42
+ "**/*.ipynb",
43
+ "**/*.jpg",
44
+ "**/*.png",
45
+ "**/__pycache__",
46
+ ]
47
+
48
+ [tool.ruff]
49
+ line-length = 100
@@ -0,0 +1,37 @@
1
+ MESSAGE = """
2
+ qmc_sampler: QMC point sets by spectral optimisation, see
3
+ https://github.com/For-a-few-DPPs-more/Recursive-Gaussian-Blue-Noise/src/qmc_sampler (sampler)
4
+ https://github.com/For-a-few-DPPs-more/hyperuniform-samplers (datasets)
5
+
6
+ Available methods:
7
+ - sample_l2: uses a classical isotropic L2-ball as the spectral exclusion region.
8
+ - sample_l1: uses an L1-ball, which is anisotropic and can be useful for QMC
9
+ in settings with low effective dimensionality.
10
+ - sample_wd: uses the wrap-around discrepancy, further exploiting the
11
+ low-effective-dimensionality assumption.
12
+
13
+ Backends: keops (default if available), torch, finufft (D <= 3, O(N log N) instead of O(N^2)).
14
+ finufft is not enabled by default (exact sums up to machine precision), but is strongly
15
+ recommended in 2D / 3D:
16
+ pip install finufft
17
+ qmc_sampler.select_backend(dimensions={2, 3}, backend="finufft")
18
+ """
19
+
20
+ print(MESSAGE)
21
+
22
+
23
+ from ._backend import available_backends, get_backend, select_backend
24
+ from ._viz import plot, plot_structure_factor
25
+ from .qmc_sampler import sample_l1, sample_l2, sample_wd
26
+
27
+ __all__ = [
28
+ "sample_l1",
29
+ "sample_l2",
30
+ "sample_wd",
31
+ "plot",
32
+ "plot_structure_factor",
33
+ "select_backend",
34
+ "get_backend",
35
+ "available_backends",
36
+ ]
37
+ __version__ = "3.0.0"