Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
e02f76d
Add the PCG64DXSM and MRG32k3a bit generators to dpnp.random
ndgrigorian Nov 4, 2026
2af127e
Apply the Generator review to the PCG64DXSM and MRG32k3a docs and tests
ndgrigorian Nov 7, 2026
98ca8df
Pass dpnp arrays straight to the asserts of the bit generator tests
ndgrigorian Nov 7, 2026
e82fa84
Name oneMath next to oneMKL in the MRG32k3a docs
ndgrigorian Nov 8, 2026
89f4c9f
Keep the bytes role of the PCG64DXSM notes on one line
ndgrigorian Nov 13, 2026
9d64989
Space the PCG64DXSM work-item streams 2**64 steps apart, away from ju…
ndgrigorian Nov 13, 2026
9d2615d
Say that MRG32k3a matches Philox only for large draws
ndgrigorian Nov 13, 2026
4a35dc1
Take the samplers that draw PCG64DXSM in order from the extension
ndgrigorian Nov 13, 2026
32f0b8a
Check uinteger and normalize has_uint32 in the PCG64DXSM state setter
ndgrigorian Nov 13, 2026
96e9eac
Keep the def_sampler comment above def_sampler
ndgrigorian Nov 17, 2026
9834286
Compute the PCG step power with _affine_power
ndgrigorian Nov 17, 2026
25f2af9
Convert the PCG64DXSM state integers as NumPy's Cython setter does
ndgrigorian Nov 17, 2026
eef4522
Name oneMath next to oneMKL in the MRG32k3a adapter comments
ndgrigorian Nov 20, 2026
9f9a494
Merge branch 'feature/device-rng-multivariate' into feature/device-rn…
ndgrigorian Nov 20, 2026
a2f4d98
Merge branch 'feature/device-rng-multivariate' into feature/device-rn…
ndgrigorian Nov 20, 2026
3ceedb8
Merge branch 'feature/device-rng-multivariate' into feature/device-rn…
ndgrigorian Nov 20, 2026
eb74e82
Check the PCG64DXSM state with NumPy's own setter
ndgrigorian Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ This release drops support for Python 3.10, making Python 3.11 the minimum requi
* Added the continuous distributions of `numpy.random.Generator`, such as `gamma`, `beta` and `vonmises`, to `dpnp.random.Generator` [#3158](https://github.com/IntelPython/dpnp/pull/3158)
* Added `integers` and the discrete distributions of `numpy.random.Generator`, such as `poisson`, `binomial` and `hypergeometric`, to `dpnp.random.Generator`, along with `noncentral_chisquare` and `noncentral_f` [#3159](https://github.com/IntelPython/dpnp/pull/3159)
* Added the multivariate distributions, `permutation`, `shuffle`, `permuted`, `choice` and `bytes` to `dpnp.random.Generator` [#3160](https://github.com/IntelPython/dpnp/pull/3160)
* Added the `dpnp.random.PCG64DXSM` bit generator, which matches `numpy.random.PCG64DXSM` for raw values, `random`, `uniform` and `bytes` [#3161](https://github.com/IntelPython/dpnp/pull/3161)
* Added the `dpnp.random.MRG32k3a` bit generator [#3161](https://github.com/IntelPython/dpnp/pull/3161)

### Changed

Expand Down
6 changes: 6 additions & 0 deletions doc/known_words.txt
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,11 @@ Hanning
histogrammed
Hypergeometric
kwargs
Kelton
iaxis
iinfo
Infs
L'Ecuyer
intp
ints
iterable
Expand Down Expand Up @@ -90,17 +92,21 @@ reentrant
representable
resampling
rng
RngStreams
runtimes
scikit
se
SeedSequence
signbit
signum
Simard
sinc
strided
subarray
subarrays
subclasses
substream
substreams
subtype
SyclDevice
SyclQueue
Expand Down
27 changes: 20 additions & 7 deletions doc/reference/random.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@ Random sampling (:mod:`dpnp.random`)

.. hint:: `NumPy API Reference: Random sampling <https://numpy.org/doc/stable/reference/random/index.html>`_

DPNP draws random numbers on the SYCL device, with the counter-based
Philox4x32x10 generator of the oneMKL device RNG API (oneMath's in a
oneMath build). It provides the :class:`Generator` API of NumPy,
DPNP draws random numbers on the SYCL device, by default with the
counter-based Philox4x32x10 generator of the oneMKL device RNG API, or with
NumPy's PCG64DXSM generator or the MRG32k3a generator of the oneMKL device
RNG API. A oneMath build takes Philox4x32x10 and MRG32k3a from oneMath's
device RNG API instead. It provides the :class:`Generator` API of NumPy,
recommended for new code. The legacy :class:`RandomState` API and the
module-level functions still use the host-side oneMKL RNG.

Expand All @@ -28,7 +30,10 @@ A generator draws all its samples on one SYCL queue, chosen with the
Differences from NumPy
----------------------

* The streams differ from NumPy's. For a given seed, output size and data
* The streams differ from NumPy's, except that :class:`PCG64DXSM` gives
NumPy's raw values, :meth:`Generator.random`, :meth:`Generator.uniform`
and :meth:`Generator.bytes`, and can exchange states with
:class:`numpy.random.PCG64DXSM`. For a given seed, output size and data
type, the raw bits and the uniform floats are the same on every device.
The other distributions use transcendental functions, which may round
differently on another device: their samples agree to a few ULP, or
Expand All @@ -37,7 +42,8 @@ Differences from NumPy
precision, as noted below.
* The values depend on the output size: a draw is not a prefix of a
larger one, and two draws of ``n`` values differ from one draw of
``2 * n``. Code splitting its draws into chunks gets other values.
``2 * n``, but for the methods :class:`PCG64DXSM` draws in the order of
its stream. Code splitting its draws into chunks gets other values.
* The floating-point distributions take a ``dtype`` keyword, as in CuPy,
which defaults to the default floating-point type of the device, so on a
device without double precision the same seed gives other values by
Expand Down Expand Up @@ -75,8 +81,9 @@ Differences from NumPy
they are on the host, as the other parameters are.
* :meth:`Generator.shuffle` only accepts an array on the device, a
:class:`dpnp.ndarray` or :class:`dpnp.tensor.usm_ndarray`, as in CuPy.
* Generators and bit generators cannot be pickled or deep-copied, and the
bit generators have no ``advance`` or ``jumped`` method.
* Generators and bit generators cannot be pickled or deep-copied,
and :class:`Philox4x3210` and :class:`MRG32k3a` have no ``advance`` or
``jumped`` method.

Random Generator
----------------
Expand Down Expand Up @@ -184,6 +191,12 @@ Bit generators
BitGenerator.sycl_queue
Philox4x3210
Philox4x3210.state
PCG64DXSM
PCG64DXSM.advance
PCG64DXSM.jumped
PCG64DXSM.state
MRG32k3a
MRG32k3a.state
SeedSequence

Legacy random generation
Expand Down
2 changes: 1 addition & 1 deletion dpnp/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
- `dpnp_algo/dpnp_elementwise_common.py`: ufunc wrapper classes (`DPNPUnaryFunc`, `DPNPBinaryFunc`, two-output and specialised variants)
- `dpnp_utils/`: shared helpers (`get_usm_allocations`, `map_dtype_to_device`, reduction wrappers)
- `linalg/`, `fft/`, `random/`, `scipy/`, `lib/`: subpackages, each exporting through its own `__init__.py`
- `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`.
- `random/`: `_bit_generator.py` (`BitGenerator`, `Philox4x3210`, `PCG64DXSM`, `MRG32k3a`; `SeedSequence` is NumPy's) and `_generator.py` (`Generator`, which implements every distribution). The kernels are in `dpnp.libtensor._rng_impl`.
- 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`).

## Adding a Public Function
Expand Down
72 changes: 68 additions & 4 deletions dpnp/libtensor/extensions/rng/common.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
#include <sycl/sycl.hpp>

#include "dpnp4pybind11.hpp"
#include <pybind11/numpy.h>
#include <pybind11/pybind11.h>
#include <pybind11/stl.h>

Expand Down Expand Up @@ -135,7 +136,7 @@ sycl::event submit_sample(sycl::queue &exec_q,
const std::size_t nelems,
const std::vector<sycl::event> &depends)
{
const std::size_t n_wi = rng_ns::num_work_items<EngineTraitsT>(nelems);
const std::size_t n_wi = rng_ns::num_work_items<EngineTraitsT>(nelems, L);

return exec_q.submit([&](sycl::handler &cgh) {
cgh.depends_on(depends);
Expand All @@ -157,7 +158,12 @@ sycl::event submit_sample_in_layout(sycl::queue &exec_q,
const bool blocked,
const std::vector<sycl::event> &depends)
{
if constexpr (rng_ns::can_draw_blocked<EngineTraitsT, SamplerT>) {
if constexpr (rng_ns::can_draw_sequential<EngineTraitsT, SamplerT>) {
return submit_sample<EngineTraitsT, SamplerT,
rng_ns::Layout::sequential, Cyclic>(
exec_q, state, sampler, res, nelems, depends);
}
else if constexpr (rng_ns::can_draw_blocked<EngineTraitsT, SamplerT>) {
if (blocked) {
return submit_sample<EngineTraitsT, SamplerT,
rng_ns::Layout::blocked, Cyclic>(
Expand Down Expand Up @@ -277,26 +283,48 @@ void init_sample_dispatch_table(sample_dispatch_table_t &table)
{
using ext::common::init_dispatch_vector;

static_assert(rng_ns::num_engines == 1,
static_assert(rng_ns::num_engines == 3,
"Every engine must have a row in the dispatch table");

constexpr int philox = static_cast<int>(rng_ns::engine_id::philox4x32x10);
init_dispatch_vector<sample_fn_ptr_t,
SampleFactoryFor<rng_ns::Philox4x32x10, SamplerT,
SupportedT>::template type>(
table[philox]);

constexpr int pcg = static_cast<int>(rng_ns::engine_id::pcg64dxsm);
init_dispatch_vector<sample_fn_ptr_t,
SampleFactoryFor<rng_ns::PCG64DXSM, SamplerT,
SupportedT>::template type>(
table[pcg]);

constexpr int mrg = static_cast<int>(rng_ns::engine_id::mrg32k3a);
init_dispatch_vector<sample_fn_ptr_t,
SampleFactoryFor<rng_ns::MRG32k3a, SamplerT,
SupportedT>::template type>(
table[mrg]);
}

template <template <typename> class SamplerT>
void init_discrete_dispatch_table(discrete_dispatch_table_t &table)
{
static_assert(rng_ns::num_engines == 1,
static_assert(rng_ns::num_engines == 3,
"Every engine must have a row in the dispatch table");

using Philox = rng_ns::Philox4x32x10;
constexpr int philox = static_cast<int>(rng_ns::engine_id::philox4x32x10);
table[philox][0] = sample_impl<Philox, SamplerT<float>, float>;
table[philox][1] = sample_impl<Philox, SamplerT<double>, double>;

using PCG = rng_ns::PCG64DXSM;
constexpr int pcg = static_cast<int>(rng_ns::engine_id::pcg64dxsm);
table[pcg][0] = sample_impl<PCG, SamplerT<float>, float>;
table[pcg][1] = sample_impl<PCG, SamplerT<double>, double>;

using MRG = rng_ns::MRG32k3a;
constexpr int mrg = static_cast<int>(rng_ns::engine_id::mrg32k3a);
table[mrg][0] = sample_impl<MRG, SamplerT<float>, float>;
table[mrg][1] = sample_impl<MRG, SamplerT<double>, double>;
}

// Looks up the sampler of `result`'s type, and throws if there is none
Expand All @@ -318,6 +346,39 @@ extern std::pair<sycl::event, sycl::event>
const std::vector<sycl::event> &depends,
const sample_fn_ptr_t fn);

template <typename T>
struct TypeTag
{
using type = T;
};
Comment thread
ndgrigorian marked this conversation as resolved.
Resolved

// Records, in the dict halves_per_item of the module, the 32-bit halves of
// raw outputs SamplerT takes per element for each result type that takes a
// fixed number, so that a bit generator drawing its stream in order can
// advance its state as the kernel does
template <template <typename> class SamplerT,
template <typename> class SupportedT,
typename... Ts>
void record_halves_per_item(py::module_ &m, const char *name)
{
if (!py::hasattr(m, "halves_per_item")) {
m.attr("halves_per_item") = py::dict();
}
py::dict halves;
auto add = [&halves](auto tag) {
using T = typename decltype(tag)::type;
if constexpr (SupportedT<T>::value) {
if constexpr (SamplerT<T>::halves_per_item != 0) {
halves[py::dtype::of<T>()] = SamplerT<T>::halves_per_item;
}
}
};
(add(TypeTag<Ts>{}), ...);
if (!halves.empty()) {
m.attr("halves_per_item")[name] = halves;
}
}

// Fills `table` and binds it to the Python function `name`, which takes the
// distribution parameters as a sequence
template <template <typename> class SamplerT,
Expand Down Expand Up @@ -345,6 +406,9 @@ void def_sampler(py::module_ &m,
py::arg("seed"), py::arg("counter_lo"), py::arg("counter_hi"),
py::arg("params"), py::arg("result"),
py::arg("depends") = py::list());

record_halves_per_item<SamplerT, SupportedT, float, double, std::uint32_t,
std::uint64_t>(m, name);
}

// As def_sampler, for a discrete sampler, whose Python function also takes
Expand Down
Loading
Loading