Skip to content

Add dpnp.random.Generator on the oneMKL device RNG API - #3157

Open
ndgrigorian wants to merge 15 commits into
masterfrom
feature/device-rng-generator
Open

ndgrigorian wants to merge 15 commits into
masterfrom
feature/device-rng-generator

Conversation

@ndgrigorian

@ndgrigorian ndgrigorian commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

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 Generator API, with only the base distributions

The new dpnp.libtensor._rng_impl extension 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 ULP

Adds

  • dpnp.random.Generator with random, uniform, standard_normal, normal and spawn, and default_rng; with usm_type=None (the default) the samples take the coerced USM type of the array parameters
  • dpnp.random.BitGenerator (with random_raw, spawn, state and lock), SeedSequence (NumPy's) and the Philox4x3210 bit generator on oneMKL's device philox4x32x10
  • Strided and blocked sample layouts; the blocked layout generates the words of a work-item in one engine call and is used on GPUs, giving the same values

The legacy RandomState and the module-level functions are untouched until later in the series

Series:

  1. Add dpnp.random.Generator on the oneMKL device RNG API #3157 (this PR): framework, Philox4x3210 and the base distributions
  2. Add continuous distributions to dpnp.random.Generator #3158: Continuous distributions
  3. Add discrete distributions to dpnp.random.Generator #3159: Discrete distributions
  4. Add multivariate distributions and permutations to dpnp.random.Generator #3160: Multivariate distributions and permutations
  5. Add PCG64DXSM and MRG32k3a bit generators to dpnp.random #3161: PCG64DXSM and MRG32k3a bit generators
  6. Reimplement dpnp.random.RandomState on the device RNG #3162: RandomState and the module functions on the device RNG
  7. Remove the legacy backend RNG #3163: Removal of the legacy backend RNG
  • Have you provided a meaningful PR description?
  • Have you added a test, reproducer or referred to an issue with a reproducer?
  • Have you tested your changes locally for CPU and GPU devices?
  • Have you made sure that new changes do not introduce compiler warnings?
  • Have you checked performance impact of proposed changes?
  • Have you added documentation for your changes, if necessary?
  • Have you added your changes to the changelog?

@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

View rendered docs @ https://intelpython.github.io/dpnp/pull/3157/index.html

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Array API standard conformance tests for dpnp=0.22.0dev2=np2py314h8d9cdd5_21 ran successfully.
Passed: 1491
Failed: 0
Skipped: 6

@coveralls

coveralls commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Status

coverage: 84.403% (+0.1%) from 84.269% — feature/device-rng-generator into master

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
@antonwolfy antonwolfy added this to the 0.22.0 release milestone Nov 6, 2026
@antonwolfy

This comment was marked as off-topic.

@antonwolfy antonwolfy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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, lock deadlock (_bit_generator.py:110). New evidence: a thread running with bg.lock: bg.state was still alive after a 3 s join.
  • Copilot, random_raw(output=False) rewind (_bit_generator.py:242). New evidence: random_raw(16), then random_raw(-16, output=False), then random_raw(16) returns the same 16 values, while NumPy's Philox.random_raw(-16, output=False) leaves the counter unchanged. random_raw((2, -8), output=False) rewinds too, and random_raw((2**40, 2**40), output=False) wraps numpy.prod to 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 uniform range (_generator.py:129). New evidence: uniform(-3e38, 3e38, size=1000, dtype=numpy.float32) returns 1000 infs.

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 new test_sycl_queue.py and test_usm_type.py tests, third_party/cupy/random_tests/ as shipped, test_random.py and test_random_state.py pass 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_raw bit 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 and output=False. random and uniform match 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 spawn children, 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_normal and normal, 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:

  1. uniform skips 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 raises OverflowError: Range exceeds valid bounds. _check_arrays (_generator.py:142-152) returns None for every parameter as soon as one is a device array, while normal checks 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.
  2. The output ignores the parameters' USM type, and the new dpnp/AGENTS.md line says something else about temporaries. normal(dpnp.zeros(4, usm_type="shared"), 1.0).usm_type is "device". The line says "Temporaries take the output's usm_type", but _to_kernel_param (_generator.py:360) calls dpnp.asarray without usm_type, so a parameter given as a list becomes a "device" array even with usm_type="shared". Suggestion: pass usm_type=usm_type there, and either follow the inputs' USM type as other dpnp functions do or list the keyword-only rule under "Differences from NumPy".
  3. The method docstrings don't describe dtype, usm_type and out. They appear only as one-line Limitations, and the methods have no Parameters, Returns or Examples, unlike the legacy dpnp.random.uniform. random.rst doesn't list Generator.spawn, Generator.bit_generator, BitGenerator.random_raw or BitGenerator.state, and the device text at _bit_generator.py:87 refers to dpctl.tensor.Device, which is dpnp.tensor.Device elsewhere in dpnp now.
  4. Nits:
    • Nit: the _random_raw doc string (uniform.cpp:46-47) says "low half first", but BitGen::next_uint64 returns (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) that UniformSampler has, so loc + scale * z may 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: pickle and copy.deepcopy of a Generator or a BitGenerator fail with TypeError (from the SyclQueue and the Lock), and advance/jumped are absent; NumPy has all of them. Worth a line under "Differences from NumPy" until a follow-up adds them.

Checked, no issues

  • Engine setup: {key, counter_lo, counter_hi + w} maps to oneMKL's key k0/k1 and counter c0-c3 the way _launch assumes, and one generate on philox4x32x10<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_alive holds 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 and None checks, broadcasting and the ExecutionPlacementError cases match NumPy.
  • Statistical tests: the mean and variance checks of test_moments gave 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.

Comment thread doc/reference/random.rst Resolved
Comment thread dpnp/tests/AGENTS.md Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
@ndgrigorian
ndgrigorian force-pushed the feature/device-rng-generator branch from 9fef498 to 1bd3cee Compare November 6, 2026 14:58
@ndgrigorian

Copy link
Copy Markdown
Collaborator Author

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:

  1. uniform host checks next to device parameters: a host bound that isn't finite (in float64 or in the sampling dtype) now raises OverflowError even when the other bound is on the device (test_uniform_device_and_host_bounds).
  2. USM type: the Generator methods now default to usm_type=None, so the output and the temporaries take the coerced USM type of the array parameters (and out), or "device" when there are none; an explicit usm_type still wins. _to_kernel_param passes it to dpnp.asarray. This is documented in the class docstring and in "Differences from NumPy", and tested in test_usm_type.py::test_generator_coerced_usm_type. It applies to every method up the stack.
  3. Docstrings: random, uniform, standard_normal and normal now have Parameters, Returns, Limitations and Examples. random.rst lists Generator.bit_generator, Generator.spawn, BitGenerator.random_raw, BitGenerator.spawn and BitGenerator.state, and dpctl.tensor.Device is now dpnp.tensor.Device. The methods of the later PRs still have the short form; I'll expand them in those PRs.
  4. Nits: the _random_raw doc now says "high half first", NormalSampler has fp contract(off), and pickling, copying and advance/jumped are listed under "Differences from NumPy" (PCG64DXSM in Add PCG64DXSM and MRG32k3a bit generators to dpnp.random #3161 has advance and jumped). I couldn't run make spelling here, so known_words.txt only gains the words I could identify (BitGenerator, Philox, reentrant, SeedSequence, strided, ziggurat). If you share your list of 41, I'll add the rest.

The six PRs above are rebased onto this one, carrying the changes where they apply: usm_type=None for every method, out overlap copies and the per-PR CuPy unskips.

@antonwolfy

Copy link
Copy Markdown
Contributor

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 antonwolfy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread dpnp/tests/test_random_generator.py Resolved
Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread doc/reference/random.rst Resolved
Comment thread doc/known_words.txt Resolved
Comment thread dpnp/tests/test_random_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread doc/reference/random.rst Resolved
Comment thread dpnp/random/_bit_generator.py Resolved
Comment thread dpnp/random/_generator.py Resolved
Comment thread doc/reference/random.rst Resolved
Comment thread dpnp/tests/test_random_generator.py Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread dpnp/random/_generator.py Resolved

@antonwolfy antonwolfy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 RandomState from 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's Generator(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 the SequentialOrderManager bookkeeping, the extension call with its keep-alive host task, and the NumPy shape checks, which run for scalar parameters too.
  • -fno-fast-math costs 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.

Comment thread dpnp/random/_generator.py Resolved
Comment thread doc/reference/random.rst Resolved
Comment thread dpnp/tests/test_random_generator.py Resolved
Comment thread dpnp/tests/test_random_generator.py Resolved
@ndgrigorian
ndgrigorian force-pushed the feature/device-rng-generator branch from 9f9f13e to 88c286e Compare November 8, 2026 21:54
Comment thread dpnp/random/_bit_generator.py Resolved
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.

@antonwolfy antonwolfy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs of the head checked against NumPy 2.5.5.

Comment on lines +284 to +289
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.

@antonwolfy antonwolfy Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread dpnp/random/_generator.py
Default: ``0.0``.
high : {float, array_like of floats, dpnp.ndarray, usm_ndarray}, \
optional
The upper bound of the output interval.

@antonwolfy antonwolfy Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Comment thread dpnp/random/_generator.py
Comment on lines +791 to +793
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

@antonwolfy antonwolfy Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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`.

Comment on lines +310 to +323
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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`.

Comment thread doc/reference/random.rst
BitGenerator.state
BitGenerator.sycl_device
BitGenerator.sycl_queue
Philox4x3210

@antonwolfy antonwolfy Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
Philox4x3210
Philox4x3210
Philox4x3210.state

@vlad-perevezentsev vlad-perevezentsev left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 antonwolfy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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, random and uniform are 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 uniform stream 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_ks fires 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_samples always 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];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_normal runs the same kernel with scalars, so float64 standard_normal is 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 bool template parameter of Param and the samplers keeps round 3's ptr ? ptr[i] : value for launches without a cyclic parameter;
  • the host dispatches on period != 0;
  • the cost is a second instantiation of the normal and uniform kernels.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_range passes high as a numpy.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.

Suggested change
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)

Comment on lines +114 to +115
// Adapts a oneMKL device engine to the next_uint32/next_uint64/next_float/
// next_double interface NumPy's distribution algorithms are written against.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
// 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.

Comment on lines +803 to +809

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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 branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants