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.
- qmc_sampler-3.0.0/.gitignore +13 -0
- qmc_sampler-3.0.0/PKG-INFO +114 -0
- qmc_sampler-3.0.0/README.md +96 -0
- {qmc_sampler-2.0.2 → qmc_sampler-3.0.0}/pyproject.toml +49 -43
- qmc_sampler-3.0.0/src/qmc_sampler/__init__.py +37 -0
- qmc_sampler-3.0.0/src/qmc_sampler/_backend.py +343 -0
- qmc_sampler-3.0.0/src/qmc_sampler/_lattice.py +147 -0
- qmc_sampler-3.0.0/src/qmc_sampler/_structure_factor.py +175 -0
- qmc_sampler-3.0.0/src/qmc_sampler/_viz.py +214 -0
- {qmc_sampler-2.0.2 → qmc_sampler-3.0.0}/src/qmc_sampler/qmc_geom.py +341 -341
- {qmc_sampler-2.0.2 → qmc_sampler-3.0.0}/src/qmc_sampler/qmc_sampler.py +186 -217
- qmc_sampler-2.0.2/.gitignore +0 -6
- qmc_sampler-2.0.2/PKG-INFO +0 -95
- qmc_sampler-2.0.2/README.md +0 -83
- qmc_sampler-2.0.2/src/qmc_sampler/__init__.py +0 -41
|
@@ -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
|
+
[](https://pypi.org/project/qmc-sampler/)
|
|
22
|
+
[](https://github.com/For-a-few-DPPs-more/qmc-sampler)
|
|
23
|
+
[](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
|
+
[](https://pypi.org/project/qmc-sampler/)
|
|
4
|
+
[](https://github.com/For-a-few-DPPs-more/qmc-sampler)
|
|
5
|
+
[](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 = "
|
|
9
|
-
description = "QMC
|
|
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
|
-
"
|
|
25
|
-
"scipy",
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
[
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
[
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
]
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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"
|