randompack 0.1.1__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.
- randompack-0.1.1/LICENSE +62 -0
- randompack-0.1.1/PKG-INFO +162 -0
- randompack-0.1.1/README.md +92 -0
- randompack-0.1.1/build-doc.sh +5 -0
- randompack-0.1.1/docs/Makefile +20 -0
- randompack-0.1.1/docs/_static/custom.css +28 -0
- randompack-0.1.1/docs/_templates/XXX.rst +7 -0
- randompack-0.1.1/docs/_templates/autosummary/base.rst +6 -0
- randompack-0.1.1/docs/_templates/autosummary/class.rst +4 -0
- randompack-0.1.1/docs/_templates/method.rst +6 -0
- randompack-0.1.1/docs/conf.py +60 -0
- randompack-0.1.1/docs/index.rst +144 -0
- randompack-0.1.1/docs/make.bat +35 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.beta.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.chi2.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.deserialize.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.duplicate.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.exp.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.f.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.full_mantissa.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.gamma.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.gumbel.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.int.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.lognormal.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.mvn.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.normal.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.pareto.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.pcg64_set_state.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.perm.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.philox_set_state.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.randomize.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.raw.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.rst +5 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.sample.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.seed.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.serialize.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.set_state.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.skew_normal.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.squares_set_state.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.t.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.unif.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.Rng.weibull.rst +7 -0
- randompack-0.1.1/docs/reference/generated/randompack.engines.rst +7 -0
- randompack-0.1.1/docs/reference/index.rst +98 -0
- randompack-0.1.1/examples/TimeDist.py +201 -0
- randompack-0.1.1/examples/TimeRandompack.py +121 -0
- randompack-0.1.1/examples/TimeReturning.py +120 -0
- randompack-0.1.1/meson.build +159 -0
- randompack-0.1.1/meson_options.txt +14 -0
- randompack-0.1.1/pyproject.toml +25 -0
- randompack-0.1.1/randompack/__init__.py +29 -0
- randompack-0.1.1/randompack/_core.c +31398 -0
- randompack-0.1.1/randompack/_core.pxd +103 -0
- randompack-0.1.1/randompack/_core.pyx +1779 -0
- randompack-0.1.1/readme-wheels.txt +47 -0
- randompack-0.1.1/src/BlasGateway.h +138 -0
- randompack-0.1.1/src/License-Random123.txt +29 -0
- randompack-0.1.1/src/avx2.c +215 -0
- randompack-0.1.1/src/blas.f +1967 -0
- randompack-0.1.1/src/blasref.h +103 -0
- randompack-0.1.1/src/buffer_draw.inc +156 -0
- randompack-0.1.1/src/chacha-portable.h +38 -0
- randompack-0.1.1/src/chacha-portable.inc +202 -0
- randompack-0.1.1/src/chachacha.inc +48 -0
- randompack-0.1.1/src/crypto_random.inc +80 -0
- randompack-0.1.1/src/csprng.inc +9 -0
- randompack-0.1.1/src/cwg128.inc +25 -0
- randompack-0.1.1/src/cwg128_64.h +7 -0
- randompack-0.1.1/src/cwg128_emul.inc +59 -0
- randompack-0.1.1/src/distrib_float.inc +189 -0
- randompack-0.1.1/src/distributions.inc +499 -0
- randompack-0.1.1/src/engines.inc +22 -0
- randompack-0.1.1/src/inplace_logexp.c +74 -0
- randompack-0.1.1/src/lapack_dpstrf.f +323 -0
- randompack-0.1.1/src/log_exp.inc +102 -0
- randompack-0.1.1/src/norm_exp.inc +174 -0
- randompack-0.1.1/src/norm_exp_float.inc +127 -0
- randompack-0.1.1/src/openlibm.inc +504 -0
- randompack-0.1.1/src/pcg64.h +8 -0
- randompack-0.1.1/src/pcg64_dxsm.inc +36 -0
- randompack-0.1.1/src/pcg64_dxsm_emul.inc +57 -0
- randompack-0.1.1/src/pcg64_emul.h +9 -0
- randompack-0.1.1/src/philox4x64.inc +81 -0
- randompack-0.1.1/src/printX.h +83 -0
- randompack-0.1.1/src/rand_dble.inc +107 -0
- randompack-0.1.1/src/rand_float.inc +70 -0
- randompack-0.1.1/src/randompack.c +754 -0
- randompack-0.1.1/src/randompack.h +420 -0
- randompack-0.1.1/src/randompack_config.h +155 -0
- randompack-0.1.1/src/randompack_float.inc +190 -0
- randompack-0.1.1/src/randompack_internal.h +80 -0
- randompack-0.1.1/src/randutil.inc +174 -0
- randompack-0.1.1/src/seed_seq_fe128.inc +103 -0
- randompack-0.1.1/src/serializations.inc +28 -0
- randompack-0.1.1/src/sfc64.inc +20 -0
- randompack-0.1.1/src/sleef.c +483 -0
- randompack-0.1.1/src/squares64.inc +77 -0
- randompack-0.1.1/src/x256pp_jump.inc +44 -0
- randompack-0.1.1/src/x256pp_neon_scalar.inc +77 -0
- randompack-0.1.1/src/xoroshiro128pp.inc +15 -0
- randompack-0.1.1/src/xorshift128p.inc +17 -0
- randompack-0.1.1/src/xoshiro256pp.inc +28 -0
- randompack-0.1.1/src/xoshiro256ss.inc +27 -0
- randompack-0.1.1/src/zig_new.h +235 -0
- randompack-0.1.1/src/ziggurat_const_float.h +765 -0
- randompack-0.1.1/src/ziggurat_constants.h +962 -0
- randompack-0.1.1/tests/test_basic.py +41 -0
- randompack-0.1.1/tests/test_continuous.py +171 -0
- randompack-0.1.1/tests/test_discrete.py +56 -0
- randompack-0.1.1/tests/test_state.py +86 -0
randompack-0.1.1/LICENSE
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kristján Jónasson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
THIRD-PARTY NOTICES
|
|
25
|
+
|
|
26
|
+
This software includes or adapts code from the following projects:
|
|
27
|
+
|
|
28
|
+
xoshiro256++ / xoshiro256**
|
|
29
|
+
Blackman, Vigna — https://prng.di.unimi.it/ — Public Domain
|
|
30
|
+
Files: src/xoshiro256pp.inc, src/xoshiro256ss.inc
|
|
31
|
+
|
|
32
|
+
NumPy random distributions
|
|
33
|
+
NumPy — https://github.com/numpy/numpy — BSD-3-Clause
|
|
34
|
+
Files: src/random_standard_norm_exp.inc
|
|
35
|
+
|
|
36
|
+
Random123 (Philox)
|
|
37
|
+
Salmon et al. — https://www.deshawresearch.com/resources_random123.html — BSD
|
|
38
|
+
Files: src/philox4x64.inc (license in src/License-Random123.txt)
|
|
39
|
+
|
|
40
|
+
PCG64-DXSM
|
|
41
|
+
Melissa O’Neill — https://www.pcg-random.org/ — 0BSD (MIT-0)
|
|
42
|
+
Files: src/pcg64_dxsm.inc
|
|
43
|
+
|
|
44
|
+
ChaCha20 portable
|
|
45
|
+
D. J. Bernstein — https://cr.yp.to/chacha.html — CC0
|
|
46
|
+
Files: src/chacha-portable.c, src/chacha-portable.h
|
|
47
|
+
|
|
48
|
+
randutils seed_seq_fe128
|
|
49
|
+
Melissa O’Neill — https://github.com/imneme/pcg-cpp — MIT
|
|
50
|
+
Files: src/seed_seq_fe128.inc, tests/randutils.hpp
|
|
51
|
+
|
|
52
|
+
getopt
|
|
53
|
+
OpenBSD / NetBSD — https://github.com/openbsd/src — BSD-style
|
|
54
|
+
Files: examples/getopt.c, examples/getopt.h
|
|
55
|
+
|
|
56
|
+
AS241 (PPND16 inverse normal)
|
|
57
|
+
Wichura et al. — Public Domain
|
|
58
|
+
Files: tests/TestUtil.c
|
|
59
|
+
|
|
60
|
+
LAPACK routines
|
|
61
|
+
Netlib LAPACK — https://www.netlib.org/lapack/ — BSD-style
|
|
62
|
+
Files: src/lapack_dpstf2.f, src/lapack_dpstrf.f
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: randompack
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
License: MIT License
|
|
5
|
+
|
|
6
|
+
Copyright (c) 2026 Kristján Jónasson
|
|
7
|
+
|
|
8
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
9
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
10
|
+
in the Software without restriction, including without limitation the rights
|
|
11
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
12
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
13
|
+
furnished to do so, subject to the following conditions:
|
|
14
|
+
|
|
15
|
+
The above copyright notice and this permission notice shall be included in all
|
|
16
|
+
copies or substantial portions of the Software.
|
|
17
|
+
|
|
18
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
19
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
20
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
21
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
22
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
23
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
24
|
+
SOFTWARE.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
THIRD-PARTY NOTICES
|
|
28
|
+
|
|
29
|
+
This software includes or adapts code from the following projects:
|
|
30
|
+
|
|
31
|
+
xoshiro256++ / xoshiro256**
|
|
32
|
+
Blackman, Vigna — https://prng.di.unimi.it/ — Public Domain
|
|
33
|
+
Files: src/xoshiro256pp.inc, src/xoshiro256ss.inc
|
|
34
|
+
|
|
35
|
+
NumPy random distributions
|
|
36
|
+
NumPy — https://github.com/numpy/numpy — BSD-3-Clause
|
|
37
|
+
Files: src/random_standard_norm_exp.inc
|
|
38
|
+
|
|
39
|
+
Random123 (Philox)
|
|
40
|
+
Salmon et al. — https://www.deshawresearch.com/resources_random123.html — BSD
|
|
41
|
+
Files: src/philox4x64.inc (license in src/License-Random123.txt)
|
|
42
|
+
|
|
43
|
+
PCG64-DXSM
|
|
44
|
+
Melissa O’Neill — https://www.pcg-random.org/ — 0BSD (MIT-0)
|
|
45
|
+
Files: src/pcg64_dxsm.inc
|
|
46
|
+
|
|
47
|
+
ChaCha20 portable
|
|
48
|
+
D. J. Bernstein — https://cr.yp.to/chacha.html — CC0
|
|
49
|
+
Files: src/chacha-portable.c, src/chacha-portable.h
|
|
50
|
+
|
|
51
|
+
randutils seed_seq_fe128
|
|
52
|
+
Melissa O’Neill — https://github.com/imneme/pcg-cpp — MIT
|
|
53
|
+
Files: src/seed_seq_fe128.inc, tests/randutils.hpp
|
|
54
|
+
|
|
55
|
+
getopt
|
|
56
|
+
OpenBSD / NetBSD — https://github.com/openbsd/src — BSD-style
|
|
57
|
+
Files: examples/getopt.c, examples/getopt.h
|
|
58
|
+
|
|
59
|
+
AS241 (PPND16 inverse normal)
|
|
60
|
+
Wichura et al. — Public Domain
|
|
61
|
+
Files: tests/TestUtil.c
|
|
62
|
+
|
|
63
|
+
LAPACK routines
|
|
64
|
+
Netlib LAPACK — https://www.netlib.org/lapack/ — BSD-style
|
|
65
|
+
Files: src/lapack_dpstf2.f, src/lapack_dpstrf.f
|
|
66
|
+
|
|
67
|
+
Requires-Python: >=3.9
|
|
68
|
+
Requires-Dist: numpy>=1.22
|
|
69
|
+
Description-Content-Type: text/markdown
|
|
70
|
+
|
|
71
|
+
# randompack
|
|
72
|
+
|
|
73
|
+
This package provides Python bindings to the C library Randompack, a random number
|
|
74
|
+
generation toolkit that also includes interfaces for Julia, R, and Fortran. Randompack
|
|
75
|
+
exposes a collection of modern RNG engines, including xoshiro256++/**, PCG64 DXSM, sfc64,
|
|
76
|
+
Philox, and ChaCha20, together with a range of probability distributions, both integer and
|
|
77
|
+
continuous. The library allows matching random draws across platforms and supported
|
|
78
|
+
language interfaces. It provides unbounded and bounded integer draws, permutations,
|
|
79
|
+
sampling without replacement, and 14 continuous distributions, ranging from basic ones
|
|
80
|
+
(uniform, normal, exponential), through commonly used distributions (beta, gamma), to more
|
|
81
|
+
specialized ones (such as skew-normal). Multivariate normal sampling is also supported.
|
|
82
|
+
|
|
83
|
+
Through SIMD instructions on modern CPUs, the inherently fast default engine xoshiro256++
|
|
84
|
+
delivers high throughput for bulk generation, typically providing 3–6× faster performance
|
|
85
|
+
than NumPy for uniform, normal, and exponential draws.
|
|
86
|
+
|
|
87
|
+
For more information, including implementation details, benchmarking results, and
|
|
88
|
+
documentation of engines and distributions, see the main project readme file at
|
|
89
|
+
https://github.com/jonasson2/randompack. The same page also links to DEVELOPMENT.md, which
|
|
90
|
+
contains setup and development instructions, including details specific to the Python
|
|
91
|
+
interface.
|
|
92
|
+
|
|
93
|
+
## Cross platform consistency
|
|
94
|
+
|
|
95
|
+
Given the same engine and seed, samples obtained on different platforms (programming
|
|
96
|
+
language/computer/compiler/OS/architecture) agree. For uniform, normal, exponential, and
|
|
97
|
+
integer distributions the agreement is bit-exact (x == y holds). For the remaining
|
|
98
|
+
distributions, samples agree to within ca. 2 ulp. If the `bitexact` parameter is set to
|
|
99
|
+
`true` the agreement is bit-exact for all distributions.
|
|
100
|
+
|
|
101
|
+
## Usage
|
|
102
|
+
|
|
103
|
+
### Installation, setup, and seeding
|
|
104
|
+
```sh
|
|
105
|
+
pip install randompack
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
import numpy as np
|
|
110
|
+
import randompack
|
|
111
|
+
rng = randompack.Rng() # default engine (x256++simd)
|
|
112
|
+
rng = randompack.Rng("pcg64") # specified engine; rng is randomized by default
|
|
113
|
+
randompack.engines() # list available engines
|
|
114
|
+
rng.seed(123) # deterministic seed
|
|
115
|
+
rng.seed(123, spawn_key=[1, 2]) # independent substreams
|
|
116
|
+
rng.randomize() # seed from system entropy
|
|
117
|
+
rng2 = rng.duplicate() # identical independent copy
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Continuous distributions
|
|
121
|
+
```python
|
|
122
|
+
x = rng.unif(100) # 100 draws from U(0,1)
|
|
123
|
+
y = rng.unif(100, a=2, b=5) # 100 draws from U(2,5)
|
|
124
|
+
s = rng.unif() # scalar draw
|
|
125
|
+
z = rng.normal(5) # 5 standard normal draws
|
|
126
|
+
t = rng.normal(5, mu=2, sigma=3) # 5 draws from N(2,3)
|
|
127
|
+
u = rng.beta(50, a=2, b=5) # 50 draws from the Beta(2,5) distribution
|
|
128
|
+
v = rng.normal(5, dtype=np.float32) # single precision
|
|
129
|
+
rng.unif(out=x) # use shape and data type of x
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Discrete distributions
|
|
133
|
+
```python
|
|
134
|
+
x = rng.int(100, 1, 6) # integers in [1,6] (inclusive)
|
|
135
|
+
p = rng.perm(10) # permutation of 0...9
|
|
136
|
+
s = rng.sample(20, 5) # 5-element sample from 0...19 (without replacement)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Multivariate normal
|
|
140
|
+
```python
|
|
141
|
+
Sigma = np.array([[1.0, 0.2], [0.2, 2.0]])
|
|
142
|
+
X = rng.mvn(100, Sigma) # zero mean
|
|
143
|
+
Y = rng.mvn(50, Sigma, mu=np.array([1.0, 2.0])) # specified mean
|
|
144
|
+
Z = np.zeros((100, 2)) # 2 columns
|
|
145
|
+
rng.mvn(Sigma, out=Z) # Sigma must be 2×2
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### State control and serialization
|
|
149
|
+
```python
|
|
150
|
+
rngx = randompack.Rng("x256**")
|
|
151
|
+
rngp = randompack.Rng("philox")
|
|
152
|
+
rngx.set_state(state=[1,2,3,4]) # general state setter
|
|
153
|
+
rngp.philox_set_state(ctr=[1,2,3,4], key=[4,6]) # engine-specific state setter
|
|
154
|
+
|
|
155
|
+
rngy = randompack.Rng("x256**") # engines must match
|
|
156
|
+
state = rngx.serialize() # copy engine state of rngx
|
|
157
|
+
rngy.deserialize(state) # and put in rngy
|
|
158
|
+
|
|
159
|
+
rng.full_mantissa(True) # enable full 53-bit mantissa (52-bit is default)
|
|
160
|
+
rng = randompack.Rng(bitexact=True) # make agreement across platforms exact
|
|
161
|
+
rng = randompack.Rng("philox", bitexact=True) # exact agreement with specified engine
|
|
162
|
+
```
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# randompack
|
|
2
|
+
|
|
3
|
+
This package provides Python bindings to the C library Randompack, a random number
|
|
4
|
+
generation toolkit that also includes interfaces for Julia, R, and Fortran. Randompack
|
|
5
|
+
exposes a collection of modern RNG engines, including xoshiro256++/**, PCG64 DXSM, sfc64,
|
|
6
|
+
Philox, and ChaCha20, together with a range of probability distributions, both integer and
|
|
7
|
+
continuous. The library allows matching random draws across platforms and supported
|
|
8
|
+
language interfaces. It provides unbounded and bounded integer draws, permutations,
|
|
9
|
+
sampling without replacement, and 14 continuous distributions, ranging from basic ones
|
|
10
|
+
(uniform, normal, exponential), through commonly used distributions (beta, gamma), to more
|
|
11
|
+
specialized ones (such as skew-normal). Multivariate normal sampling is also supported.
|
|
12
|
+
|
|
13
|
+
Through SIMD instructions on modern CPUs, the inherently fast default engine xoshiro256++
|
|
14
|
+
delivers high throughput for bulk generation, typically providing 3–6× faster performance
|
|
15
|
+
than NumPy for uniform, normal, and exponential draws.
|
|
16
|
+
|
|
17
|
+
For more information, including implementation details, benchmarking results, and
|
|
18
|
+
documentation of engines and distributions, see the main project readme file at
|
|
19
|
+
https://github.com/jonasson2/randompack. The same page also links to DEVELOPMENT.md, which
|
|
20
|
+
contains setup and development instructions, including details specific to the Python
|
|
21
|
+
interface.
|
|
22
|
+
|
|
23
|
+
## Cross platform consistency
|
|
24
|
+
|
|
25
|
+
Given the same engine and seed, samples obtained on different platforms (programming
|
|
26
|
+
language/computer/compiler/OS/architecture) agree. For uniform, normal, exponential, and
|
|
27
|
+
integer distributions the agreement is bit-exact (x == y holds). For the remaining
|
|
28
|
+
distributions, samples agree to within ca. 2 ulp. If the `bitexact` parameter is set to
|
|
29
|
+
`true` the agreement is bit-exact for all distributions.
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
### Installation, setup, and seeding
|
|
34
|
+
```sh
|
|
35
|
+
pip install randompack
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
import numpy as np
|
|
40
|
+
import randompack
|
|
41
|
+
rng = randompack.Rng() # default engine (x256++simd)
|
|
42
|
+
rng = randompack.Rng("pcg64") # specified engine; rng is randomized by default
|
|
43
|
+
randompack.engines() # list available engines
|
|
44
|
+
rng.seed(123) # deterministic seed
|
|
45
|
+
rng.seed(123, spawn_key=[1, 2]) # independent substreams
|
|
46
|
+
rng.randomize() # seed from system entropy
|
|
47
|
+
rng2 = rng.duplicate() # identical independent copy
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Continuous distributions
|
|
51
|
+
```python
|
|
52
|
+
x = rng.unif(100) # 100 draws from U(0,1)
|
|
53
|
+
y = rng.unif(100, a=2, b=5) # 100 draws from U(2,5)
|
|
54
|
+
s = rng.unif() # scalar draw
|
|
55
|
+
z = rng.normal(5) # 5 standard normal draws
|
|
56
|
+
t = rng.normal(5, mu=2, sigma=3) # 5 draws from N(2,3)
|
|
57
|
+
u = rng.beta(50, a=2, b=5) # 50 draws from the Beta(2,5) distribution
|
|
58
|
+
v = rng.normal(5, dtype=np.float32) # single precision
|
|
59
|
+
rng.unif(out=x) # use shape and data type of x
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Discrete distributions
|
|
63
|
+
```python
|
|
64
|
+
x = rng.int(100, 1, 6) # integers in [1,6] (inclusive)
|
|
65
|
+
p = rng.perm(10) # permutation of 0...9
|
|
66
|
+
s = rng.sample(20, 5) # 5-element sample from 0...19 (without replacement)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Multivariate normal
|
|
70
|
+
```python
|
|
71
|
+
Sigma = np.array([[1.0, 0.2], [0.2, 2.0]])
|
|
72
|
+
X = rng.mvn(100, Sigma) # zero mean
|
|
73
|
+
Y = rng.mvn(50, Sigma, mu=np.array([1.0, 2.0])) # specified mean
|
|
74
|
+
Z = np.zeros((100, 2)) # 2 columns
|
|
75
|
+
rng.mvn(Sigma, out=Z) # Sigma must be 2×2
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### State control and serialization
|
|
79
|
+
```python
|
|
80
|
+
rngx = randompack.Rng("x256**")
|
|
81
|
+
rngp = randompack.Rng("philox")
|
|
82
|
+
rngx.set_state(state=[1,2,3,4]) # general state setter
|
|
83
|
+
rngp.philox_set_state(ctr=[1,2,3,4], key=[4,6]) # engine-specific state setter
|
|
84
|
+
|
|
85
|
+
rngy = randompack.Rng("x256**") # engines must match
|
|
86
|
+
state = rngx.serialize() # copy engine state of rngx
|
|
87
|
+
rngy.deserialize(state) # and put in rngy
|
|
88
|
+
|
|
89
|
+
rng.full_mantissa(True) # enable full 53-bit mantissa (52-bit is default)
|
|
90
|
+
rng = randompack.Rng(bitexact=True) # make agreement across platforms exact
|
|
91
|
+
rng = randompack.Rng("philox", bitexact=True) # exact agreement with specified engine
|
|
92
|
+
```
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Minimal makefile for Sphinx documentation
|
|
2
|
+
#
|
|
3
|
+
|
|
4
|
+
# You can set these variables from the command line, and also
|
|
5
|
+
# from the environment for the first two.
|
|
6
|
+
SPHINXOPTS ?=
|
|
7
|
+
SPHINXBUILD ?= sphinx-build
|
|
8
|
+
SOURCEDIR = .
|
|
9
|
+
BUILDDIR = _build
|
|
10
|
+
|
|
11
|
+
# Put it first so that "make" without argument is like "make help".
|
|
12
|
+
help:
|
|
13
|
+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
14
|
+
|
|
15
|
+
.PHONY: help Makefile
|
|
16
|
+
|
|
17
|
+
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
18
|
+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
19
|
+
%: Makefile
|
|
20
|
+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
.highlight {
|
|
2
|
+
background: #f6ebcb; /* pale gold */
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
/* Narrow the whole main content area (keeps margins from ballooning) */
|
|
6
|
+
/* Narrow the overall page width (sidebar + content) */
|
|
7
|
+
|
|
8
|
+
article[role="main"] {
|
|
9
|
+
max-width: 650px;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/* Increase font size in code blocks */
|
|
13
|
+
div.highlight pre {
|
|
14
|
+
font-size: 0.9rem;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/* Also affect inline code */
|
|
18
|
+
code.literal {
|
|
19
|
+
font-size: 0.9rem;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/* .page { */
|
|
23
|
+
/* width: 600px !important; */
|
|
24
|
+
/* max-width: 600px !important; */
|
|
25
|
+
/* margin: 0 !important; /\* <-- not centered *\/ */
|
|
26
|
+
/* padding-left: 1rem !important; */
|
|
27
|
+
/* padding-right: 1rem !important; */
|
|
28
|
+
/* } */
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Configuration file for the Sphinx documentation builder.
|
|
2
|
+
#
|
|
3
|
+
# For the full list of built-in configuration values, see the documentation:
|
|
4
|
+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
5
|
+
|
|
6
|
+
# -- Project information -----------------------------------------------------
|
|
7
|
+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
|
8
|
+
|
|
9
|
+
project = 'Randompack'
|
|
10
|
+
copyright = '2026, Kristján Jónasson'
|
|
11
|
+
author = 'Kristján Jónasson'
|
|
12
|
+
|
|
13
|
+
from importlib.metadata import version as _version
|
|
14
|
+
release = _version('randompack')
|
|
15
|
+
version = release
|
|
16
|
+
|
|
17
|
+
# -- General configuration ---------------------------------------------------
|
|
18
|
+
|
|
19
|
+
import os
|
|
20
|
+
import sys
|
|
21
|
+
sys.path.insert(0, os.path.abspath(".."))
|
|
22
|
+
|
|
23
|
+
extensions = [
|
|
24
|
+
"sphinx.ext.autodoc",
|
|
25
|
+
"sphinx.ext.napoleon",
|
|
26
|
+
"sphinx.ext.autosummary",
|
|
27
|
+
"sphinx.ext.viewcode",
|
|
28
|
+
"numpydoc",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
autosummary_generate = True
|
|
32
|
+
numpydoc_show_class_members = False
|
|
33
|
+
autosummary_generate = True
|
|
34
|
+
autosummary_imported_members = True
|
|
35
|
+
add_module_names = False
|
|
36
|
+
autodoc_typehints = "none"
|
|
37
|
+
templates_path = ["_templates"]
|
|
38
|
+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
|
39
|
+
|
|
40
|
+
# -- Options for HTML output -------------------------------------------------
|
|
41
|
+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
|
42
|
+
|
|
43
|
+
html_theme = 'furo'
|
|
44
|
+
|
|
45
|
+
html_theme_options = {
|
|
46
|
+
"sidebar_hide_name": True,
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
html_static_path = ["_static"]
|
|
50
|
+
html_css_files = ["custom.css"]
|
|
51
|
+
|
|
52
|
+
pygments_style = "default"
|
|
53
|
+
pygments_dark_style = "monokai"
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
print("SPHINX srcdir:", os.getcwd())
|
|
57
|
+
print("templates_path:", templates_path)
|
|
58
|
+
print("abs templates:", [os.path.abspath(p) for p in templates_path])
|
|
59
|
+
print("method template exists:",
|
|
60
|
+
os.path.exists(os.path.join(os.path.abspath(templates_path[0]), "autosummary", "method.rst")))
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
Randompack
|
|
2
|
+
==========
|
|
3
|
+
|
|
4
|
+
Randompack is a high-performance random number generation library
|
|
5
|
+
designed for correctness, reproducibility, and cross-language
|
|
6
|
+
consistency. It provides modern random number generators together
|
|
7
|
+
with a wide range of commonly used probability distributions.
|
|
8
|
+
|
|
9
|
+
The Python interface is built on a C11 core shared with the C,
|
|
10
|
+
Fortran, and R bindings. Under the same engine and seed, streams
|
|
11
|
+
are compatible across languages.
|
|
12
|
+
|
|
13
|
+
Quick example
|
|
14
|
+
-------------
|
|
15
|
+
|
|
16
|
+
.. code-block:: python
|
|
17
|
+
|
|
18
|
+
import randompack
|
|
19
|
+
rng = randompack.Rng()
|
|
20
|
+
rng.seed(42)
|
|
21
|
+
x = rng.normal(5)
|
|
22
|
+
|
|
23
|
+
Reproducibility and substreams
|
|
24
|
+
------------------------------
|
|
25
|
+
|
|
26
|
+
Randompack emphasizes deterministic reproducibility. Generators
|
|
27
|
+
may be seeded explicitly and support reproducible construction
|
|
28
|
+
of independent substreams via optional spawn keys.
|
|
29
|
+
|
|
30
|
+
.. code-block:: python
|
|
31
|
+
|
|
32
|
+
import numpy as np, randompack, threading
|
|
33
|
+
|
|
34
|
+
results = [None, None]
|
|
35
|
+
|
|
36
|
+
def worker(i):
|
|
37
|
+
rng = randompack.Rng()
|
|
38
|
+
rng.seed(123, spawn_key=[i])
|
|
39
|
+
results[i] = rng.normal(1000)
|
|
40
|
+
|
|
41
|
+
t0 = threading.Thread(target=worker, args=(0,))
|
|
42
|
+
t1 = threading.Thread(target=worker, args=(1,))
|
|
43
|
+
t0.start(); t1.start()
|
|
44
|
+
t0.join(); t1.join()
|
|
45
|
+
|
|
46
|
+
X = np.array(results) # shape (2, 1000)
|
|
47
|
+
|
|
48
|
+
Engines
|
|
49
|
+
-------
|
|
50
|
+
|
|
51
|
+
Randompack provides several modern random number generators
|
|
52
|
+
("engines"). ChaCha20 is available as a cryptographically secure
|
|
53
|
+
generator. Philox and Squares are counter-based generators; the
|
|
54
|
+
remaining engines are state-based.
|
|
55
|
+
|
|
56
|
+
Available engines include:
|
|
57
|
+
|
|
58
|
+
- ``x256++`` (xoshiro256++)
|
|
59
|
+
- ``x256**`` (xoshiro256**)
|
|
60
|
+
- ``xoro++`` (xoroshiro128++)
|
|
61
|
+
- ``x128+`` (xorshift128+)
|
|
62
|
+
- ``pcg64`` (PCG64 DXSM)
|
|
63
|
+
- ``sfc64`` (sfc64)
|
|
64
|
+
- ``philox`` (Philox-4×64)
|
|
65
|
+
- ``squares`` (Squares64)
|
|
66
|
+
- ``chacha20`` (ChaCha20)
|
|
67
|
+
- ``system`` (OS entropy source)
|
|
68
|
+
|
|
69
|
+
Engine names are case-insensitive.
|
|
70
|
+
|
|
71
|
+
Distributions
|
|
72
|
+
-------------
|
|
73
|
+
|
|
74
|
+
The following distributions are available:
|
|
75
|
+
|
|
76
|
+
- Uniform (continuous)
|
|
77
|
+
- Normal
|
|
78
|
+
- Lognormal
|
|
79
|
+
- Exponential
|
|
80
|
+
- Gamma
|
|
81
|
+
- Beta
|
|
82
|
+
- Chi-square
|
|
83
|
+
- Student’s t
|
|
84
|
+
- F
|
|
85
|
+
- Weibull
|
|
86
|
+
- Gumbel
|
|
87
|
+
- Pareto
|
|
88
|
+
- Skew normal
|
|
89
|
+
- Multivariate normal (float64)
|
|
90
|
+
|
|
91
|
+
In addition, Randompack provides:
|
|
92
|
+
|
|
93
|
+
- Raw bit streams
|
|
94
|
+
- Bounded and interval integers
|
|
95
|
+
- Random permutations
|
|
96
|
+
- Sampling without replacement
|
|
97
|
+
|
|
98
|
+
Continuous distributions are available in both float64 and float32
|
|
99
|
+
precision (unless otherwise noted).
|
|
100
|
+
|
|
101
|
+
Algorithms
|
|
102
|
+
----------
|
|
103
|
+
|
|
104
|
+
Distribution algorithms are implemented directly from their
|
|
105
|
+
standard published descriptions.
|
|
106
|
+
|
|
107
|
+
- Normal and exponential: Ziggurat method (Marsaglia & Tsang, 2000)
|
|
108
|
+
- Gamma: Marsaglia–Tsang method
|
|
109
|
+
- Beta: ratio of independent gamma variates
|
|
110
|
+
- Chi-square: Gamma(ν/2, 2)
|
|
111
|
+
- Student’s t: Normal divided by scaled Gamma
|
|
112
|
+
- F: ratio of scaled Gamma variates
|
|
113
|
+
- Weibull: power transform of exponential
|
|
114
|
+
- Gumbel: double logarithm transform of uniform
|
|
115
|
+
- Pareto: exponential transform
|
|
116
|
+
- Skew normal: Azzalini construction
|
|
117
|
+
- Multivariate normal: Cholesky / pivoted Cholesky factorization
|
|
118
|
+
- Permutation: Fisher–Yates shuffle
|
|
119
|
+
- Sampling without replacement: Floyd’s algorithm and reservoir sampling
|
|
120
|
+
- Integer intervals: Lemire method
|
|
121
|
+
|
|
122
|
+
Verification and testing
|
|
123
|
+
------------------------
|
|
124
|
+
|
|
125
|
+
Correctness of the underlying generators is a central design goal.
|
|
126
|
+
Raw bit streams are compared against authoritative upstream
|
|
127
|
+
reference implementations where available.
|
|
128
|
+
|
|
129
|
+
The test suite checks API behavior and distributional correctness,
|
|
130
|
+
including support containment, statistical balance tests, and
|
|
131
|
+
cross-language reproducibility.
|
|
132
|
+
|
|
133
|
+
External statistical validation via TestU01 and PractRand is supported.
|
|
134
|
+
|
|
135
|
+
API reference
|
|
136
|
+
-------------
|
|
137
|
+
|
|
138
|
+
The complete API reference is generated from the Python
|
|
139
|
+
docstrings and is available below.
|
|
140
|
+
|
|
141
|
+
.. toctree::
|
|
142
|
+
:maxdepth: 2
|
|
143
|
+
|
|
144
|
+
reference/index
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
@ECHO OFF
|
|
2
|
+
|
|
3
|
+
pushd %~dp0
|
|
4
|
+
|
|
5
|
+
REM Command file for Sphinx documentation
|
|
6
|
+
|
|
7
|
+
if "%SPHINXBUILD%" == "" (
|
|
8
|
+
set SPHINXBUILD=sphinx-build
|
|
9
|
+
)
|
|
10
|
+
set SOURCEDIR=.
|
|
11
|
+
set BUILDDIR=_build
|
|
12
|
+
|
|
13
|
+
%SPHINXBUILD% >NUL 2>NUL
|
|
14
|
+
if errorlevel 9009 (
|
|
15
|
+
echo.
|
|
16
|
+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
|
17
|
+
echo.installed, then set the SPHINXBUILD environment variable to point
|
|
18
|
+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
|
19
|
+
echo.may add the Sphinx directory to PATH.
|
|
20
|
+
echo.
|
|
21
|
+
echo.If you don't have Sphinx installed, grab it from
|
|
22
|
+
echo.https://www.sphinx-doc.org/
|
|
23
|
+
exit /b 1
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
if "%1" == "" goto help
|
|
27
|
+
|
|
28
|
+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
|
29
|
+
goto end
|
|
30
|
+
|
|
31
|
+
:help
|
|
32
|
+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
|
33
|
+
|
|
34
|
+
:end
|
|
35
|
+
popd
|