Skip to content

Commit 6c3ff46

Browse files
committed
Add dpnp.random.Generator on the oneMKL device RNG API
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.
1 parent 5fe9609 commit 6c3ff46

23 files changed

Lines changed: 2878 additions & 9 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010

1111
* Added support for boolean input in `dpnp.positive` and the `+` operator of `dpnp.ndarray` [#3128](https://github.com/IntelPython/dpnp/pull/3128)
1212
* Added `dpnp.top_k` to return the `k` largest or smallest elements and their indices along an axis, with a `sorted` keyword to return them in sorted order [#3133](https://github.com/IntelPython/dpnp/pull/3133)
13+
* Added the `dpnp.random.Generator` API with `default_rng`, `BitGenerator`, `SeedSequence` and the `Philox4x3210` bit generator, sampling on the device with the oneMKL device RNG API [#3157](https://github.com/IntelPython/dpnp/pull/3157)
1314

1415
### Changed
1516

‎doc/reference/random.rst‎

Lines changed: 84 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,90 @@
33
Random sampling (:mod:`dpnp.random`)
44
====================================
55

6+
.. hint:: `NumPy API Reference: Random sampling <https://numpy.org/doc/stable/reference/random/index.html>`_
7+
8+
DPNP draws random numbers on the SYCL device, with the counter-based
9+
Philox4x32x10 generator of the oneMKL device RNG API. It provides the
10+
:class:`Generator` API of NumPy, recommended for new code. The legacy
11+
:class:`RandomState` API and the module-level functions still use the
12+
host-side oneMKL RNG.
13+
14+
.. code-block:: python
15+
16+
import dpnp
17+
18+
rng = dpnp.random.default_rng(seed=42)
19+
x = rng.standard_normal((3, 4)) # on the default device
20+
y = rng.random(5, usm_type="shared")
21+
22+
rng = dpnp.random.default_rng(42, device="cpu")
23+
24+
A generator draws all its samples on one SYCL queue, chosen with the
25+
``device`` or ``sycl_queue`` keyword when it is created, and the samples
26+
depend only on the seed, not on the device. All samples are
27+
:class:`dpnp.ndarray`, zero-dimensional when ``size`` is ``None``.
28+
29+
Differences from NumPy
30+
----------------------
31+
32+
* The same seed gives the same stream on every device.
33+
The streams differ from NumPy's.
34+
* The floating-point distributions take a ``dtype`` keyword, as in CuPy,
35+
which defaults to the default floating-point type of the device. All
36+
methods take a ``usm_type`` keyword.
37+
* Parameters on the host (Python scalars, lists and NumPy arrays) are
38+
checked as in NumPy. Parameters in :class:`dpnp.ndarray` are
39+
not, since that would wait for the device.
40+
Invalid ones give undefined values, such as NaN.
41+
42+
Random Generator
43+
----------------
44+
45+
.. autosummary::
46+
:toctree: generated/
47+
:nosignatures:
48+
49+
default_rng
50+
Generator
51+
52+
Simple random data
53+
^^^^^^^^^^^^^^^^^^
54+
55+
.. autosummary::
56+
:toctree: generated/
57+
:nosignatures:
58+
59+
Generator.random
60+
61+
Distributions
62+
^^^^^^^^^^^^^
63+
64+
.. autosummary::
65+
:toctree: generated/
66+
:nosignatures:
67+
68+
Generator.normal
69+
Generator.standard_normal
70+
Generator.uniform
71+
72+
Bit generators
73+
--------------
74+
75+
.. autosummary::
76+
:toctree: generated/
77+
:nosignatures:
78+
79+
BitGenerator
80+
Philox4x3210
81+
SeedSequence
82+
83+
Legacy random generation
84+
------------------------
85+
686
.. hint:: `NumPy API Reference: Legacy random generation <https://numpy.org/doc/stable/reference/random/legacy.html>`_
787

888
Simple random data
9-
------------------
89+
^^^^^^^^^^^^^^^^^^
1090

1191
.. autosummary::
1292
:toctree: generated/
@@ -23,9 +103,8 @@ Simple random data
23103
choice
24104
bytes
25105

26-
27106
Permutations
28-
------------
107+
^^^^^^^^^^^^
29108

30109
.. autosummary::
31110
:toctree: generated/
@@ -34,9 +113,8 @@ Permutations
34113
shuffle
35114
permutation
36115

37-
38116
Distributions
39-
-------------
117+
^^^^^^^^^^^^^
40118

41119
.. autosummary::
42120
:toctree: generated/
@@ -78,9 +156,8 @@ Distributions
78156
weibull
79157
zipf
80158

81-
82159
Random generator
83-
----------------
160+
^^^^^^^^^^^^^^^^
84161

85162
.. autosummary::
86163
:toctree: generated/

‎dpnp/AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
- `dpnp_algo/dpnp_elementwise_common.py`: ufunc wrapper classes (`DPNPUnaryFunc`, `DPNPBinaryFunc`, two-output and specialised variants)
77
- `dpnp_utils/`: shared helpers (`get_usm_allocations`, `map_dtype_to_device`, reduction wrappers)
88
- `linalg/`, `fft/`, `random/`, `scipy/`, `lib/`: subpackages, each exporting through its own `__init__.py`
9+
- `random/`: `_bit_generator.py` (`BitGenerator`, `Philox4x3210`; `SeedSequence` is NumPy's) and `_generator.py` (`Generator`, which implements every distribution). The kernels are in `dpnp.libtensor._rng_impl`.
910
- Legacy, don't extend: the Cython `dpnp_algo` path and `dpnp_backend_c` (still used by `dpnp.partition` and `dpnp.random`), and the NumPy fallback `call_origin`. New kernels go into `dpnp/libtensor` (see `dpnp/libtensor/AGENTS.md`).
1011

1112
## Adding a Public Function
@@ -20,6 +21,7 @@
2021
- Extension calls are ordered with `_manager = dpctl.utils.SequentialOrderManager[exec_q]`: pass `depends=_manager.submitted_events`, then `_manager.add_event_pair(ht_ev, ev)`. Don't add blocking waits.
2122
- Use `dpnp.default_float_type(...)` or `map_dtype_to_device(...)` for the default float type.
2223
- Deprecated ufuncs use `DPNPDeprecatedUnaryFunc(..., deprecated_msg=...)`.
24+
- A `dpnp.random` distribution is a `Generator` method: it calls `self._check_queues(...)` on its array parameters (raises `ExecutionPlacementError`), checks host parameters as NumPy does, and draws through `_cont` or `_float_sample` into `BitGenerator._fill`. Parameters on the device are not checked, as the check waits for the device. Temporaries take the output's `usm_type`.
2325
- Unsupported NumPy keywords raise `NotImplementedError` (`dpnp.check_limitations`) and are listed under `Limitations` in the docstring.
2426
- The Array API spec version is set in three places that change together: `__array_api_version__` in `dpnp/tensor/_array_api.py`, `ARRAY_API_TESTS_VERSION` in `.github/workflows/conda-package.yml` and `doc/reference/array_api.rst` (plus the version test in `dpnp/tests/test_ndarray.py`). Inspection utilities come from `__array_namespace_info__` in `dpnp_array_api_info.py`.
2527
- `dpnp.tensor` replaces `dpctl.tensor`, which no longer exists here; `SyclQueue`, `SyclDevice`, `dpctl.memory` and `SequentialOrderManager` still come from `dpctl`.

‎dpnp/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,7 @@ add_subdirectory(libtensor/source)
229229
add_subdirectory(libtensor/extensions/blas)
230230
add_subdirectory(libtensor/extensions/fft)
231231
add_subdirectory(libtensor/extensions/lapack)
232+
add_subdirectory(libtensor/extensions/rng)
232233
add_subdirectory(libtensor/extensions/vm)
233234
add_subdirectory(libtensor/extensions/sparse)
234235

‎dpnp/libtensor/AGENTS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Layout
44
- `include/kernels/`: header-only SYCL kernels in namespaces under `dpnp::tensor::kernels`; `include/utils/`: type dispatch, type, offset and memory-overlap helpers (`type_dispatch.hpp`, `type_dispatch_building.hpp`, `type_utils.hpp`, `memory_overlap.hpp`, ...); `include/ext/`: dispatch helpers (`init_dispatch_vector`, `init_dispatch_table`, `DispatchTable`) and validation helpers (`validation_utils.hpp`). The headers ship with dpnp; `dpnp.get_include()` and `python -m dpnp --tensor-include-dir` return `include/`.
55
- `source/`: bindings built by `source/CMakeLists.txt` into `_tensor_impl`, `_tensor_elementwise_impl`, `_tensor_reductions_impl`, `_tensor_sorting_impl`, `_tensor_accumulation_impl`, `_tensor_linalg_impl`, `_statistics_impl` and `_window_impl`. The functions dpnp adds beyond the Array API are listed in the `_dpnp_*_sources` variables there and compiled into the same modules.
6-
- `extensions/{blas,fft,lapack,sparse,vm}/`: oneMKL/oneMath extensions, one module `_<name>_impl` per directory.
6+
- `extensions/{blas,fft,lapack,rng,sparse,vm}/`: oneMKL/oneMath extensions, one module `_<name>_impl` per directory.
77
- Every module installs into `dpnp/libtensor` and is imported as `dpnp.libtensor._<name>_impl`. A new kernel goes into `source/` and an existing module; only code that needs oneMKL gets a new extension.
88

99
## Adding a ufunc Kernel (model: `fabs`)
@@ -21,8 +21,9 @@ A new extension's `CMakeLists.txt` lists its sources and calls `build_dpnp_pybin
2121
- Validate inputs before launching: queue compatibility, contiguity, writability, memory overlap (including the same logical tensor), dtype and ndim. Reuse the helpers neighbouring files use: `check_queue`, `check_c_contig`, `check_no_overlap`, `check_writable` from `include/ext/validation_utils.hpp` (`putmask`, `statistics`, `isclose`, `interpolate`), or `dpnp::utils::queues_are_compatible`, `dpnp::tensor::overlap::MemoryOverlap` and `dpnp::tensor::validation::CheckWritable` (extensions and the Array API functions). Don't silently accept strided input.
2222
- Throw `py::value_error` for bad arguments and `std::runtime_error` for internal failures; catch oneMKL and SYCL exceptions and rethrow them.
2323
- Guard double, complex<double> and half with `dpnp::tensor::type_utils::validate_type_for_device<T>(q)`; don't use double literals or casts in kernels that must run without fp64.
24-
- `blas`, `fft`, `lapack` and `sparse` build against either oneMKL or oneMath (`USE_ONEMATH`); `vm` has kernels only with oneMKL: with oneMath it builds empty and `_is_available()` returns `False`.
24+
- `blas`, `fft`, `lapack` and `sparse` build against either oneMKL or oneMath (`USE_ONEMATH`); `vm` has kernels only with oneMKL: with oneMath it builds empty and `_is_available()` returns `False`; `rng` uses the header-only oneMKL device RNG API and links no oneMKL library.
2525
- Release the GIL around blocking oneMKL calls (`py::gil_scoped_release`).
26+
- `rng` values depend only on the engine state and the number of elements, never on the device or the layout chosen for it (`extensions/rng/kernels/sample.hpp`); each engine's `items_per_work_item` (`kernels/engines.hpp`) is part of its stream definition.
2627
- An extension whose kernels may be launched over more than `INT_MAX` work-items passes `LARGE_RANGES` to `build_dpnp_pybind11_ext`, which adds `-fno-sycl-id-queries-fit-in-int` at compile and link time (DPC++ 2026.2 and later need it at link time). `source/CMakeLists.txt` and `dpnp_backend_c` pass it to both `target_compile_options` and `target_link_options`.
2728
- clang-format 23 formats C++ (`.clang-format`: LLVM base, 4-space indent, 80 columns); gersemi formats CMake at 88 columns, except `dpnp/backend/cmake/Modules/`.
2829

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# -*- coding: utf-8 -*-
2+
# *****************************************************************************
3+
# Copyright (c) 2026, Intel Corporation
4+
# All rights reserved.
5+
#
6+
# Redistribution and use in source and binary forms, with or without
7+
# modification, are permitted provided that the following conditions are met:
8+
# - Redistributions of source code must retain the above copyright notice,
9+
# this list of conditions and the following disclaimer.
10+
# - Redistributions in binary form must reproduce the above copyright notice,
11+
# this list of conditions and the following disclaimer in the documentation
12+
# and/or other materials provided with the distribution.
13+
# - Neither the name of the copyright holder nor the names of its contributors
14+
# may be used to endorse or promote products derived from this software
15+
# without specific prior written permission.
16+
#
17+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20+
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
21+
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22+
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23+
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24+
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25+
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26+
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
27+
# THE POSSIBILITY OF SUCH DAMAGE.
28+
# *****************************************************************************
29+
30+
set(python_module_name _rng_impl)
31+
set(_module_src
32+
${CMAKE_CURRENT_SOURCE_DIR}/normal.cpp
33+
${CMAKE_CURRENT_SOURCE_DIR}/rng_py.cpp
34+
${CMAKE_CURRENT_SOURCE_DIR}/sample.cpp
35+
${CMAKE_CURRENT_SOURCE_DIR}/uniform.cpp
36+
)
37+
38+
build_dpnp_pybind11_ext(
39+
${python_module_name}
40+
SOURCES ${_module_src}
41+
)
42+
43+
# oneMKL device RNG API is header-only, so no oneMKL library is linked
44+
target_include_directories(
45+
${python_module_name}
46+
SYSTEM
47+
PRIVATE $<TARGET_PROPERTY:MKL::MKL_SYCL,INTERFACE_INCLUDE_DIRECTORIES>
48+
)

0 commit comments

Comments
 (0)