Repository navigation
Add dpnp.random.Generator on the oneMKL device RNG API - #3157
ndgrigorian wants to merge 15 commits into
Conversation
dbdb2c8 to
3963d20
Compare
3963d20 to
6c3ff46
Compare
|
View rendered docs @ https://intelpython.github.io/dpnp/pull/3157/index.html |
|
Array API standard conformance tests for dpnp=0.22.0dev2=np2py314h8d9cdd5_21 ran successfully. |
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved RNG correctness issues can deadlock state access, duplicate random streams through races or invalid sizes, and produce incorrect results for large draws or overflowing float32 ranges.
5 open issues
What changed in this PR
Introduces the foundation for device-side random generation through NumPy’s Generator API, the first step in the RNG migration series. Legacy RandomState and module-level functions remain unchanged.
Changes:
- Adds
Generator,default_rng, and Philox bit generators with state management and spawning. - Implements base distributions in a header-only oneMKL device RNG extension, with strided and GPU-optimized blocked sampling.
- Adds API documentation and tests for distributions, reproducibility, queues, and allocation types.
| File | Description |
|---|---|
dpnp/tests/test_usm_type.py |
Tests RNG allocation types. |
dpnp/tests/test_sycl_queue.py |
Tests queue placement and mismatch errors. |
dpnp/tests/test_random_generator.py |
Tests generators, distributions, state, and reproducibility. |
dpnp/tests/AGENTS.md |
Adds RNG testing guidance. |
dpnp/random/_generator.py |
Implements Generator and base distributions. |
dpnp/random/_bit_generator.py |
Implements Philox state, raw draws, and spawning. |
dpnp/random/__init__.py |
Exports the new random APIs. |
dpnp/libtensor/extensions/rng/uniform.cpp |
Registers uniform and raw-bit samplers. |
dpnp/libtensor/extensions/rng/sample.cpp |
Validates inputs and manages sampling lifetimes. |
dpnp/libtensor/extensions/rng/rng_py.cpp |
Defines the Python extension module. |
dpnp/libtensor/extensions/rng/normal.cpp |
Registers the normal sampler. |
dpnp/libtensor/extensions/rng/kernels/samplers.hpp |
Defines distribution sampler adapters. |
dpnp/libtensor/extensions/rng/kernels/sample.hpp |
Implements strided and blocked sampling layouts. |
dpnp/libtensor/extensions/rng/kernels/engines.hpp |
Wraps Philox engines and uniform-bit conversion. |
dpnp/libtensor/extensions/rng/kernels/distributions.hpp |
Implements parameters and Box–Muller sampling. |
dpnp/libtensor/extensions/rng/distributions.hpp |
Declares sampler registration functions. |
dpnp/libtensor/extensions/rng/common.hpp |
Provides dispatch and kernel submission helpers. |
dpnp/libtensor/extensions/rng/CMakeLists.txt |
Configures the header-only RNG extension. |
dpnp/libtensor/AGENTS.md |
Documents RNG architecture and stream invariants. |
dpnp/CMakeLists.txt |
Includes the RNG extension in the build. |
dpnp/AGENTS.md |
Adds Python RNG implementation guidance. |
doc/reference/random.rst |
Documents modern RNG APIs alongside legacy functions. |
CHANGELOG.md |
Records the new device RNG API. |
Review effort: Balanced
This comment was marked as off-topic.
This comment was marked as off-topic.
antonwolfy
left a comment
There was a problem hiding this comment.
The sampling core is right: the stream matches Philox4x32-10 bit for bit on GPU and CPU, and it passes PractRand and TestU01. The problems are at the edges, in the Python layer, the docs and the tests. Copilot's five points all hold; of the inline comments below, I'd fix the overlap check, the device claim in the docs and the skipped CuPy tests before merge.
Open bot points I confirm:
- Copilot,
lockdeadlock (_bit_generator.py:110). New evidence: a thread runningwith bg.lock: bg.statewas still alive after a 3 s join. - Copilot,
random_raw(output=False)rewind (_bit_generator.py:242). New evidence:random_raw(16), thenrandom_raw(-16, output=False), thenrandom_raw(16)returns the same 16 values, while NumPy'sPhilox.random_raw(-16, output=False)leaves the counter unchanged.random_raw((2, -8), output=False)rewinds too, andrandom_raw((2**40, 2**40), output=False)wrapsnumpy.prodto 0 and leaves the state alone. - Copilot, key read after the lock is released (
_bit_generator.py:391). - Copilot,
LARGE_RANGES(rng/CMakeLists.txt:40). It takes more than 1.7e10 elements to reach. - Copilot, float32
uniformrange (_generator.py:129). New evidence:uniform(-3e38, 3e38, size=1000, dtype=numpy.float32)returns 1000infs.
What I ran, on a Panther Lake U iGPU (Level Zero and OpenCL) and the OpenCL CPU device, with the PR built in place:
test_random_generator.py: 102 passed on level_zero:gpu; 100 passed and 2 skipped (the two-device tests) on opencl:cpu. The newtest_sycl_queue.pyandtest_usm_type.pytests,third_party/cupy/random_tests/as shipped,test_random.pyandtest_random_state.pypass on both, with no pytest warnings. The build had no compiler warnings.- A NumPy implementation of Philox4x32-10, checked against the Random123 known-answer vectors, reproduces
random_rawbit for bit in 274 checks on both devices: sizes from 1 to 220+3, a counter carrying into the high word, the wrap at 2128, consecutive calls andoutput=False.randomanduniformmatch its float conversion bit for bit. - PractRand 0.94: 256 GB of the GPU stream with no anomaly. 4-16 GB each, also with none: the CPU stream; keys 0-3 with the same counter, seeds 0-3 and four
spawnchildren, each interleaved by word and by chunk; and streams of 1-, 9- and 17-value calls (built with the reference, which matches the device). - TestU01 1.2.3: SmallCrush passes on the GPU stream, the CPU stream and the interleaved related keys. Crush passes all 144 tests on two seeds; a third seed had p = 6.4e-4 (CouponCollector) and 0.9992 (CollisionPermut), which the other two seeds didn't repeat. BigCrush is still running.
- Distributions, 1e8 draws per case on both devices: KS and chi-square for
random,uniform(ranges up to ±1e30 in float32 and ±1e300 in float64),standard_normalandnormal, in float32 and float64, all in range. Over 6.7e9 normals there is no correlation between the two values of a Box-Muller pair or between neighbouring work-items.
Not inline:
uniformskips the checks of its host parameters when any parameter is on the device.uniform(dpnp.zeros(1), numpy.array([numpy.inf]))returns[inf], where NumPy raisesOverflowError: Range exceeds valid bounds._check_arrays(_generator.py:142-152) returnsNonefor every parameter as soon as one is a device array, whilenormalchecks each parameter on its own (normal(dpnp.zeros(1), -1.0)raises). Suggestion: check that the host parameters are finite even when the range can't be computed on the host.- The output ignores the parameters' USM type, and the new
dpnp/AGENTS.mdline says something else about temporaries.normal(dpnp.zeros(4, usm_type="shared"), 1.0).usm_typeis"device". The line says "Temporaries take the output'susm_type", but_to_kernel_param(_generator.py:360) callsdpnp.asarraywithoutusm_type, so a parameter given as a list becomes a"device"array even withusm_type="shared". Suggestion: passusm_type=usm_typethere, and either follow the inputs' USM type as other dpnp functions do or list the keyword-only rule under "Differences from NumPy". - The method docstrings don't describe
dtype,usm_typeandout. They appear only as one-lineLimitations, and the methods have noParameters,ReturnsorExamples, unlike the legacydpnp.random.uniform.random.rstdoesn't listGenerator.spawn,Generator.bit_generator,BitGenerator.random_raworBitGenerator.state, and thedevicetext at_bit_generator.py:87refers todpctl.tensor.Device, which isdpnp.tensor.Deviceelsewhere in dpnp now. - Nits:
- Nit: the
_random_rawdoc string (uniform.cpp:46-47) says "low half first", butBitGen::next_uint64returns(first_word << 32) | second_word, so the first 32-bit word is the high half. - Nit:
NormalSampler::operator()(kernels/samplers.hpp) lacks the#pragma clang fp contract(off)thatUniformSamplerhas, soloc + scale * zmay become an FMA on one device and not on another (icpx defaults to-ffp-contract=fast-honor-pragmas). - Nit: the Sphinx spelling step reports 41 new words from these docstrings (Philox, BitGenerator, SeedSequence, ziggurat, ...); they belong in
doc/known_words.txt. - Non-blocking:
pickleandcopy.deepcopyof aGeneratoror aBitGeneratorfail withTypeError(from theSyclQueueand theLock), andadvance/jumpedare absent; NumPy has all of them. Worth a line under "Differences from NumPy" until a follow-up adds them.
- Nit: the
Checked, no issues
- Engine setup:
{key, counter_lo, counter_hi + w}maps to oneMKL's key k0/k1 and counter c0-c3 the way_launchassumes, and onegenerateonphilox4x32x10<8>or<16>yields the words of 8 or 16 calls on<1>. Raw and uniform values are bit-identical between the GPU (blocked) and CPU (strided) layouts. - Stream separation: each work-item owns 264 counters, and the carry from the low word keeps the blocks disjoint up to the wrap at 2128.
- Lifetimes and validation:
keep_args_aliveholds the result and the parameters until the kernel ends; the queue, writability, contiguity, size, dtype, engine and seed-length checks are in place. - fp64: the double kernels are guarded and split per kernel, and the float paths use only float literals.
- NumPy parity: size normalisation, dtype handling, the
scale < 0,-0.0, NaN andNonechecks, broadcasting and theExecutionPlacementErrorcases match NumPy. - Statistical tests: the mean and variance checks of
test_momentsgave no failure over 200 other seeds. - CI: GitHub Actions and the required Jenkins lanes are green. The failed Jenkins Windows py3.14 wheel build is an icx out-of-memory crash in
copy_and_cast_usm_to_usm.cpp, which this PR doesn't touch.
9fef498 to
1bd3cee
Compare
|
Thanks for the thorough review. All of the inline points are addressed in cab62a2, with replies on each thread. On the points from the review body:
The six PRs above are rebased onto this one, carrying the changes where they apply: |
|
BigCrush (TestU01 1.2.3) has finished on the GPU stream: all 160 statistics of its 106 tests passed, over 3.57e11 32-bit words. That completes the randomness testing from my review: no battery found a problem with the generator. |
antonwolfy
left a comment
There was a problem hiding this comment.
Re-checked at this head on level_zero:gpu and opencl:cpu: all the earlier points are fixed, and the tests pass on both devices. A few new points inline: the first two are worth fixing, the rest are nits.
There was a problem hiding this comment.
🟡 Changes recommended
Host-parameter uploads still block repeated sampling, and the enabled uniform KS test fails on devices without fp64 because the NumPy reference dtype does not match the sampling dtype.
2 open issues
5 resolved since last review
Review effort: Balanced
antonwolfy
left a comment
There was a problem hiding this comment.
Re-checked at this head on a Panther Lake H (Arc B390, fp64), on level_zero:gpu and opencl:cpu, against master at the merge-base. All the points of the last round are fixed, and the oneMath switch looks right. Both of Copilot's new points hold; I replied on those threads with measurements. A few small points inline.
Tests. The full suite, one pytest process per file, passes on both devices: 94505 passed on level_zero:gpu and 94525 on opencl:cpu, with no failures or crashes. It gives no new warnings: the only one, invalid value encountered in sign from CuPy's test_sign_nan, comes on master too. With both devices visible, test_random_generator.py passes 138 of 138, and the RNG test files pass 20 repeats on both devices.
Build and footprint (clean build, 16 cores, default ninja jobs):
| master | this PR | |
|---|---|---|
| Wall time | 835 s | 837 s |
Peak RSS of one process (ld.lld) |
3.40 GiB | 3.40 GiB |
| Peak RSS of all processes | 9.26 GiB | 9.31 GiB |
| Compiler and CMake warnings, legacy backend included | 0 | 0 |
| Extension modules on disk | 183.4 MiB | 184.3 MiB |
import dpnp |
347 ms, 405 MB RSS | 355 ms, 416 MB RSS |
_rng_impl takes 59 CPU-seconds, is done long before the _tensor_impl link that ends the build, and links no oneMKL library. Most of the import cost is numpy.random and the libcrypto it loads, which _bit_generator.py now imports at import time for SeedSequence.
Performance against the legacy RandomState (MCG59 on the GPU, MT19937 on the CPU), median ms per call for 1e7 samples:
| device | method | Generator float32 | Generator float64 | RandomState float64 |
|---|---|---|---|---|
| level_zero:gpu | random |
0.67 | 1.29 | 0.98 |
| level_zero:gpu | standard_normal |
0.86 | 3.14 | 2.95 |
| level_zero:gpu | normal |
0.96 | 3.21 | 2.95 |
| level_zero:gpu | uniform |
0.86 | 1.33 | 0.96 |
| opencl:cpu | random |
6.5 | 8.6 | 26.6 |
| opencl:cpu | standard_normal |
8.6 | 10.5 | 44.6 |
| opencl:cpu | normal |
8.3 | 10.5 | 45.0 |
| opencl:cpu | uniform |
5.3 | 8.5 | 26.1 |
- On the GPU, float64 runs at 0.6-1.0x of
RandomStatefrom 1e5 to 1e7 samples, since Philox costs more than MCG59. On the CPU the Generator is 2.2-7.6x faster from 1e6 samples up. NumPy'sGenerator(Philox)takes 53-132 ms for the same float64 draws. - A small call (1 to 100 samples) takes 35-63 µs on the GPU and 43-95 µs on the CPU, against 15-23 µs for
RandomState. It is all host time, spread over theSequentialOrderManagerbookkeeping, the extension call with its keep-alive host task, and the NumPy shape checks, which run for scalar parameters too. -fno-fast-mathcosts nothing measurable: without it, the GPU times stay within noise and the CPU is 3-9% slower at 1e8.- The legacy API's timings are unchanged.
Coverage: +0.11% (84.397% to 84.508%). _bit_generator.py is at 100% and _generator.py at 98.9%, missing only the C-contiguous out check left for #3158.
9f9f13e to
88c286e
Compare
Add the dpnp.libtensor._rng_impl extension, which samples on the device from oneMKL's device philox4x32x10 engine, and the Generator API of NumPy on top of it: BitGenerator, Philox4x3210, SeedSequence (NumPy's), default_rng, and the random, uniform, standard_normal and normal methods. A bit generator keeps its state on the host and every launch rebuilds its engines from it, so the values depend only on the seed and the output size, not on the device. The legacy RandomState and module functions are unchanged.
- Make the bit generator lock reentrant and read the Philox key under it - Validate `size` in `random_raw(output=False)` and count values without overflow - Drop the seed sequence of a Philox4x3210 given its key, as NumPy does - Check the `uniform` range in the sampling dtype, and host bounds next to device ones - Raise TypeError for parameters that don't cast to the sampling dtype - Follow the USM type of the array parameters when `usm_type` is None - Accept a usm_ndarray and, for `random` and `standard_normal`, an F-contiguous `out` - Reject a parameter array overlapping the result, and build the module with LARGE_RANGES - Take the float32 Box-Muller u1 from a whole 32-bit word, and keep FMA contraction off in the normal sampler - Correct the device-independence claims, document the output-size dependence, and expand the method docstrings - Enable the CuPy Generator and Philox tests, skipping the classes of later distributions and bit generators
- Build `_rng_impl` with -fno-fast-math, so `uniform` over a tiny range is not reassociated on CPU devices and stays below `high` - Pin the float32 Box-Muller tail with a counter whose u1 word is 6 - Test the `bit_generator` setter error, a dpnp-array seed, `sycl_device`, repr and str, and the base BitGenerator methods - Drop the NumPy notice from the distributions header - Leave the kernel headers of the extensions out of the C++ coverage - Use the `dpnp.empty` text for `device` and `sycl_queue`, describe the `Generator.spawn` parameters, and list the generator properties in the docs - Correct the `random_raw(output=False)`, copying and 32-bit raw output descriptions, and rename the legacy "Random generator" section
The rng extension takes the header-only device RNG API from oneMath, with its include directories, when dpnp is built with oneMath, as the blas, fft, lapack and sparse extensions do.
88c286e to
ef331fa
Compare
antonwolfy
left a comment
There was a problem hiding this comment.
Docs of the head checked against NumPy 2.5.5.
| Unlike NumPy, a zero-dimensional array is returned rather than a | ||
| Python integer when `size` is ``None``. With ``output=False``, the | ||
| state advances by the number of elements of `size`, and an invalid | ||
| `size` raises as it does with ``output=True``. NumPy advances by | ||
| the sum of the dimensions of `size` instead, and not at all when | ||
| that sum is negative. |
There was a problem hiding this comment.
The NumPy half of this note is out of date since NumPy 2.5.5. which makes random_raw(size, output=False) advance by the product of the dimensions of size, and raise ValueError: negative dimensions are not allowed for a negative one.
On 2.5.5, Philox(1).random_raw((2, 3), output=False) advances the state by 6 and random_raw((4, -1), output=False) raises, as here; 2.5.4 and older still sum the dimensions. So my earlier note that NumPy sums them holds only for older NumPy.
| Default: ``0.0``. | ||
| high : {float, array_like of floats, dpnp.ndarray, usm_ndarray}, \ | ||
| optional | ||
| The upper bound of the output interval. |
There was a problem hiding this comment.
Both of NumPy's statements about high hold here. The kernel computes low + (high - low) * u without a fused multiply-add (kernels/samplers.hpp:106), the equation NumPy names, with u up to 1 - 2**-24 in float32, so the result can round up to high. Working through that float32 arithmetic for every u: uniform(1, 2) returns exactly 2.0 for the largest u (about 6 values in 10**8 draws), uniform(100, 101) with probability 3.8e-6, and uniform(1e7, 1e7 + 1) half the time; float64 uniform(1, 2) returns 2.0 for the largest word. NumPy samples only in float64, so float32 makes this far more likely here.
The host path also raises ValueError: high - low < 0 as NumPy does, but the parameter doesn't say so.
| The upper bound of the output interval. | |
| The upper bound of the output interval. All values generated | |
| will be less than `high`, but the high limit may be included in | |
| the result due to floating-point rounding in | |
| ``low + (high - low) * u``, with `u` on [0, 1), and more often in | |
| float32. ``high - low`` must be non-negative. |
| The entropy to seed the bit generator with. A | ||
| :class:`dpnp.random.BitGenerator` is wrapped in a new generator, and | ||
| a :class:`dpnp.random.Generator` is returned unaltered. |
There was a problem hiding this comment.
Nit: the seed text drops two of NumPy's sentences that hold here too. The seed goes to NumPy's SeedSequence (_bit_generator.py:155-160), so None pulls fresh entropy from the OS, and a negative int or array element raises ValueError: expected non-negative integer. NumPy's type list also has RandomState, which NumPy coerces to a Generator; here a RandomState, a NumPy BitGenerator or a NumPy Generator reaches SeedSequence and raises TypeError, which the Limitations could mention.
| The entropy to seed the bit generator with. A | |
| :class:`dpnp.random.BitGenerator` is wrapped in a new generator, and | |
| a :class:`dpnp.random.Generator` is returned unaltered. | |
| The entropy to seed the bit generator with. If ``None``, fresh, | |
| unpredictable entropy is pulled from the OS. An int, or the ints of | |
| an array_like, must be non-negative and are passed to | |
| :class:`dpnp.random.SeedSequence`. A | |
| :class:`dpnp.random.BitGenerator` is wrapped in a new generator, and | |
| a :class:`dpnp.random.Generator` is returned unaltered. |
|
|
||
| def random_raw(self, size=None, output=True, *, usm_type=None): | ||
| """ | ||
| Return raw 64-bit outputs of the bit generator. |
There was a problem hiding this comment.
Nit: no link to NumPy's page, unlike the other methods. numpy.random.BitGenerator.random_raw is in NumPy's intersphinx inventory, so the line resolves; the docs preview of this method has no link to NumPy now.
| Return raw 64-bit outputs of the bit generator. | |
| Return raw 64-bit outputs of the bit generator. | |
| For full documentation refer to | |
| :obj:`numpy.random.BitGenerator.random_raw`. |
| Create new independent child bit generators on the same SYCL queue. | ||
|
|
||
| Children are seeded by :meth:`numpy.random.SeedSequence.spawn` of | ||
| :attr:`seed_seq`. | ||
|
|
||
| Parameters | ||
| ---------- | ||
| n_children : int | ||
| The number of children to create. | ||
|
|
||
| Returns | ||
| ------- | ||
| out : list of BitGenerator | ||
| The child bit generators. |
There was a problem hiding this comment.
Nit: no link to NumPy's page, and no Raises section. NumPy's BitGenerator.spawn documents the TypeError raised when the seed sequence can't spawn, which here happens when a key was given (seed_seq is then None). Generator.spawn raises it too and also has no Raises section.
| Create new independent child bit generators on the same SYCL queue. | |
| Children are seeded by :meth:`numpy.random.SeedSequence.spawn` of | |
| :attr:`seed_seq`. | |
| Parameters | |
| ---------- | |
| n_children : int | |
| The number of children to create. | |
| Returns | |
| ------- | |
| out : list of BitGenerator | |
| The child bit generators. | |
| Create new independent child bit generators on the same SYCL queue. | |
| For full documentation refer to :obj:`numpy.random.BitGenerator.spawn`. | |
| Children are seeded by :meth:`numpy.random.SeedSequence.spawn` of | |
| :attr:`seed_seq`. | |
| Parameters | |
| ---------- | |
| n_children : int | |
| The number of children to create. | |
| Returns | |
| ------- | |
| out : list of BitGenerator | |
| The child bit generators. | |
| Raises | |
| ------ | |
| TypeError | |
| When the underlying seed sequence does not implement spawning, | |
| as when `key` is given to :class:`dpnp.random.Philox4x3210`. |
| BitGenerator.state | ||
| BitGenerator.sycl_device | ||
| BitGenerator.sycl_queue | ||
| Philox4x3210 |
There was a problem hiding this comment.
Nit: Philox4x3210.state isn't listed, so its page isn't linked from anywhere. The class template generates dpnp.random.Philox4x3210.state.html, which holds the only description of the state dictionary (_bit_generator.py:421-427), but neither this page nor the Philox4x3210 page of the docs preview links to it. NumPy lists ~Philox.state on its Philox page.
Neither state docstring says that it can be set too, as NumPy's "Get or set the PRNG state" does.
| Philox4x3210 | |
| Philox4x3210 | |
| Philox4x3210.state |
vlad-perevezentsev
left a comment
There was a problem hiding this comment.
I re-checked the new commit and tested this on GPU and CPU, also on an Iris Xe GPU without fp64, on Windows (Arc B390) and with free-threaded Python 3.14t. The same seed gives the same values on all of them, and the tests pass. Agreed with @antonwolfy on the docstring points.
antonwolfy
left a comment
There was a problem hiding this comment.
Re-checked the 10 new commits on five GPUs and their CPUs: a Data Center GPU Max 1100, an Arc Pro B70, the Panther Lake H and Lunar Lake iGPUs (all with fp64) and an Iris Xe without fp64. I compared the head with the round-3 content rebased onto the same master, so that only these commits differ, and with the head built against oneMath v0.9 and, on the Max 1100, oneMath develop. The cyclic parameters give the same values as the broadcast copies did, run faster and allocate neither copy. Two points inline: float64 normal got slower on the Max 1100 on the paths this change doesn't mean to touch, and a test gap of the new fast path for Python scalars. My docs points are in the earlier review.
Same values. On every device the head gives the same bits as the round-3 content and as the oneMath builds, in 458 cases (259 on the Iris Xe, which has no float64 cases): raw, random, uniform, standard_normal and normal in float32 and float64; scalar, full-size and cyclic parameters; sizes from 1 to 1e6 + 3; counters near 2**32, 2**64, 2**96 and 2**128; spawn; C and F out. They also include a 4 GiB raw stream and 1 GiB each of random, standard_normal and cyclic normal.
- Across the 10 devices, raw,
randomanduniformare bit-identical, with scalar and with array parameters. Normals agree within 4 ULP measured at max(|x|, |y|, 4), and the five GPUs give the same normals bit for bit. - The cyclic read equals
broadcast_to(p, shape).copy()bit for bit in 368 checks per device. They cover 15 shape cases, including the empty one and the (3, 1) fallback, with dpnp,usm_ndarray, NumPy, list, F-order, strided and reversed parameters. - On the Max 1100, PractRand finds no anomaly up to 256 GB in the cyclic
uniformstream or in the raw one, and the cyclic stream passes TestU01 Crush. - Per-column goodness-of-fit checks with distinct parameters per column, K up to 4097, flag nothing on any device: KS against the exact CDF, moments, tails, column-pair and lag-1 correlations, and a two-sample KS against NumPy.
Tests.
- The full suite, one pytest process per file, passes on all 10 devices, the Iris Xe included. The RNG test files pass 20 fresh runs per device, on the oneMath builds too, and so do the doctests.
- The new fp64 skip of
test_uniform_ksfires only on the Iris Xe. - A coverage run on the Max 1100 reaches the GPU-only blocked dispatch in
common.hpp(lines 184-186), which the CPU-only coverage job can't. - Of 7 mutants of the new code, 6 make tests fail on GPU and CPU: a wrong cycle (
ptr[(i / period) % period]), reading only the first element, a full-size parameter read as its first element,_repeats_along_samplesalways true, no constraint check for Python scalars, and the round-3 float64 low-bits mutant, which the new float64 reference test now catches. The seventh is inline.
Performance: a K-element dpnp array parameter broadcast to (2e7 / K, K), normal and uniform, new/old median time over 3 rounds, and the device memory the first call allocates beyond the parameters:
| GPU | float32, K = 2 to 4097 | float64, K = 2 to 4097 | K = 1 | memory, float32 | memory, float64 |
|---|---|---|---|---|---|
| Max 1100 | 0.47-0.49 | 0.47-0.80 | 0.55-0.71 | not reported by the driver | not reported by the driver |
| Arc Pro B70 | 0.47-0.85 | 0.70-0.94 | 0.90-1.52 * | 249 → 96 MiB | 490 → 185 MiB |
| Panther Lake H | 0.53-0.62 | 0.67-0.88 | 0.96-1.04 | 242 → 86 MiB | 473 → 165 MiB |
| Lunar Lake | 0.45-0.56 | 0.56-0.80 | 0.60-0.74 | 241 → 85 MiB | 472 → 164 MiB |
* The B70's times vary by about ±30 % between processes. Interleaved in one process, K = 1 gives 0.93-0.99.
At K = 1 the round-3 code's broadcast copy of a 1-element array was already cheap, so the gain there is mostly the memory. With scalar and full-size parameters, the B70 and both iGPUs show no consistent change: their rounds scatter around 1.0 within the noise. The Max 1100 does show one, see inline.
| if (!ptr) { | ||
| return value; | ||
| } | ||
| return period ? ptr[i % period] : ptr[i]; |
There was a problem hiding this comment.
On the Max 1100, float64 normal got up to 24 % slower with scalar and full-size parameters, the paths this change doesn't mean to touch. Device time of one call with 2e7 samples, round-3 content vs head. It is measured on a profiling queue with dpctl.SyclTimer(device_timer="queue_barrier"), over 4 rounds that alternate the order of the two builds; the range is over the rounds:
| parameters | float64 normal |
float64 uniform |
|---|---|---|
| scalars | 0.875 → 1.002 ms (1.13-1.16) | 0.705 → 0.690 ms (0.97-0.99) |
| full-size, K = 1 | 1.024 → 1.083 ms (1.04-1.06) | 0.983 → 0.941 ms (0.95-0.97) |
| full-size, K = 4097 | 1.176 → 1.445 ms (1.22-1.24) | 1.078 → 1.036 ms (0.96-0.97) |
standard_normalruns the same kernel with scalars, so float64standard_normalis affected too.- This GPU runs driver 25.18 (IGC 2.11). The B70 and the two iGPUs run driver 26.40 (IGC 2.42) and show no consistent change on these paths.
IGC's dump of the kernels on this GPU points at the new branch. Every blocked-layout kernel got larger: NormalSampler<double> from 7265 to 9362 instructions, and both UniformSamplers from about 2000 to 4100. All are still SIMD32 with no GRF spills. The 8-item loop of SampleFunctor is unrolled, and the !ptr and period tests of both parameters are the same for every item. So the compiler likely emits one copy of the loop body per combination of parameter kinds, and the float64 Box-Muller body is by far the largest. I haven't built a variant to confirm it.
One way out is to choose the cyclic read at compile time:
- a
booltemplate parameter ofParamand the samplers keeps round 3'sptr ? ptr[i] : valuefor launches without a cyclic parameter; - the host dispatches on
period != 0; - the cost is a second instantiation of the
normalanduniformkernels.
A cyclic-only variant could also take the modulo in 32 bits when the result has fewer than 2**32 elements. On the Panther Lake H iGPU the cyclic read takes 1.1-1.5x the time of full-size arrays in float32, at every K, K = 1 included.
| def test_array_scale(self): | ||
| scale = dpnp.asarray([1.0, 10.0]) | ||
| res = default_rng(4).normal(0.0, scale, size=(10000, 2)) | ||
| assert_allclose(res.std(axis=0), [1.0, 10.0], rtol=0.05) |
There was a problem hiding this comment.
No test checks that a Python float reaches the kernel unrounded. The new fast path for Python scalars (_PY_SCALARS) converts them on its own, in _as_host_float. A mutant that rounds them through float32 there, numpy.float64(numpy.float32(value)), passes every RNG test on GPU and CPU, for two reasons:
- the Python floats in the tests are exact in float32;
test_uniform_tiny_rangepasseshighas anumpy.float64, which takes the NumPy path.
The test below compares the two paths. It passes at this head and fails under that mutant (100 of 100 values differ), on GPU and CPU.
| assert_allclose(res.std(axis=0), [1.0, 10.0], rtol=0.05) | |
| assert_allclose(res.std(axis=0), [1.0, 10.0], rtol=0.05) | |
| @pytest.mark.skipif(not has_support_aspect64(), reason="fp64 is required") | |
| @pytest.mark.parametrize("method", ["normal", "uniform"]) | |
| def test_python_float_params(self, method): | |
| # Python scalars skip the NumPy checks but keep their float64 value | |
| def draw(a, b): | |
| rng = default_rng(7) | |
| return getattr(rng, method)(a, b, 100, dtype=dpnp.float64) | |
| expected = draw(numpy.float64(0.1), numpy.float64(0.7)) | |
| assert_array_equal(draw(0.1, 0.7), expected) |
| // Adapts a oneMKL device engine to the next_uint32/next_uint64/next_float/ | ||
| // next_double interface NumPy's distribution algorithms are written against. |
There was a problem hiding this comment.
Nit: this comment and the one at line 139 ("for a oneMKL device engine") still name only oneMKL. With USE_ONEMATH the engine is oneMath's (lines 37-49).
| // Adapts a oneMKL device engine to the next_uint32/next_uint64/next_float/ | |
| // next_double interface NumPy's distribution algorithms are written against. | |
| // Adapts a oneMKL or oneMath device engine to the next_uint32/next_uint64/ | |
| // next_float/next_double interface NumPy's distribution algorithms are | |
| // written against. |
|
|
||
| def test_queue(self): | ||
| for dev in _all_devices(): | ||
| rng = default_rng(0, device=dev) | ||
| res = rng.random(3, dtype=dpnp.float32) | ||
| assert res.sycl_device == dev | ||
| assert res.sycl_queue == rng.sycl_queue |
There was a problem hiding this comment.
Nit: test_queue repeats what test_sycl_queue.py checks, which is where compute-follows-data tests go. There, test_generator checks sycl_device and the queue of all four methods on every device of valid_dev, with a user queue too, and test_bit_generator does the same for random_raw and spawn. This test checks only random, and the class's skip drops it whenever a single device is visible, though it needs only one.
test_same_values is an RNG property, not compute-follows-data, so it belongs here. It runs only with two devices in one process, so never in the CPU-only CI. On single-device runs, test_known_answer, test_float64_reference and test_float32_normal_reference already tie every device to the host Philox reference.
| def test_queue(self): | |
| for dev in _all_devices(): | |
| rng = default_rng(0, device=dev) | |
| res = rng.random(3, dtype=dpnp.float32) | |
| assert res.sycl_device == dev | |
| assert res.sycl_queue == rng.sycl_queue |


This PR is the first of a series splitting #3147 into smaller pieces. It adds the new framework for device-side random number generation and NumPy's
GeneratorAPI, with only the base distributionsThe new
dpnp.libtensor._rng_implextension samples on the device using the oneMKL device RNG API (header-only, so no oneMKL RNG library is linked). A bit generator keeps its state on the host, and each kernel launch rebuilds its engines from that state, so sampling never waits on the device. For a given seed, output size and dtype, the raw bits and the uniform floats are the same on every device, and the normal samples agree to a few ULPAdds
dpnp.random.Generatorwithrandom,uniform,standard_normal,normalandspawn, anddefault_rng; withusm_type=None(the default) the samples take the coerced USM type of the array parametersdpnp.random.BitGenerator(withrandom_raw,spawn,stateandlock),SeedSequence(NumPy's) and thePhilox4x3210bit generator on oneMKL's devicephilox4x32x10The legacy
RandomStateand the module-level functions are untouched until later in the seriesSeries:
dpnp.random.Generatoron the oneMKL device RNG API #3157 (this PR): framework,Philox4x3210and the base distributionsdpnp.random.Generator#3158: Continuous distributionsdpnp.random.Generator#3159: Discrete distributionsdpnp.random.Generator#3160: Multivariate distributions and permutationsPCG64DXSMandMRG32k3abit generators todpnp.random#3161:PCG64DXSMandMRG32k3abit generatorsdpnp.random.RandomStateon the device RNG #3162:RandomStateand the module functions on the device RNG