Formatting and minor fixes

Author: antonwolfy

dpnp/backend/src/dpnp_random_state.hpp

@@ -32,26 +32,40 @@
 
 namespace mkl_rng = oneapi::mkl::rng;
 
+// Structure storing MKL engine for MT199374x32x10 algorithm
 struct mt19937_struct
 {
     mkl_rng::mt19937* engine;
 };
 
-void MT19937_InitScalarSeed(mt19937_struct *mt19937, DPCTLSyclQueueRef QRef, uint32_t seed=1)
+/**
+ * @brief Create a MKL engine from scalar seed
+ *
+ * Invoke a common seed initialization of the engine for MT199374x32x10 algorithm.
+ */
+void MT19937_InitScalarSeed(mt19937_struct *mt19937, DPCTLSyclQueueRef q_ref, uint32_t seed = 1)
 {
-    sycl::queue q = *(reinterpret_cast<sycl::queue *>(QRef));
+    sycl::queue q = *(reinterpret_cast<sycl::queue *>(q_ref));
     mt19937->engine = new mkl_rng::mt19937(q, seed);
     return;
 }
 
-void MT19937_InitVectorSeed(mt19937_struct *mt19937, DPCTLSyclQueueRef QRef, uint32_t * seed, unsigned int n) {
-    sycl::queue q = *(reinterpret_cast<sycl::queue *>(QRef));
+/**
+ * @brief Create a MKL engine from seed vector
+ *
+ * Invoke an extended seed initialization of the engine for MT199374x32x10 algorithm.
+ *
+ * @note the vector size is limited by length=3
+ */
+void MT19937_InitVectorSeed(mt19937_struct *mt19937, DPCTLSyclQueueRef q_ref, uint32_t * seed, unsigned int n) {
+    sycl::queue q = *(reinterpret_cast<sycl::queue *>(q_ref));
 
     switch (n) {
         case 1: mt19937->engine = new mkl_rng::mt19937(q, {seed[0]}); break;
         case 2: mt19937->engine = new mkl_rng::mt19937(q, {seed[0], seed[1]}); break;
         case 3: mt19937->engine = new mkl_rng::mt19937(q, {seed[0], seed[1], seed[2]}); break;
         default:
+        // TODO need to get rid of the limitation for seed vector length
         throw std::runtime_error("Too long seed vector");
     }
     return;

dpnp/random/dpnp_algo_random.pyx

@@ -1,7 +1,7 @@
 # cython: language_level=3
 # -*- coding: utf-8 -*-
 # *****************************************************************************
-# Copyright (c) 2016-2020, Intel Corporation
+# Copyright (c) 2016-2022, Intel Corporation
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -287,59 +287,73 @@ cdef extern from "dpnp_random_state.hpp":
 
 
 cdef class MT19937:
-    """Class storing MKL engine for MT199374x32x10 algorithm
     """
+    Class storing MKL engine for MT199374x32x10 algorithm.
+    """
+
     cdef mt19937_struct mt19937
-    cdef c_dpctl.DPCTLSyclQueueRef QRef
-    cdef c_dpctl.SyclQueue Queue
+    cdef c_dpctl.DPCTLSyclQueueRef q_ref
+    cdef c_dpctl.SyclQueue q
 
     def __cinit__(self, seed, sycl_queue=None):
         cdef bint is_vector_seed = False
         cdef uint32_t scalar_seed = 0
         cdef unsigned int vector_seed_len = 0
         cdef unsigned int *vector_seed = NULL
 
-        self.QRef = NULL
+        self.q_ref = NULL
         if sycl_queue is None:
             sycl_queue = dpctl.SyclQueue()
-        if not isinstance(sycl_queue, dpctl.SyclQueue):
-            raise TypeError
 
-        if isinstance(seed, int):
+        # keep a refference on SYCL queue
+        self.q = <c_dpctl.SyclQueue> sycl_queue
+        self.q_ref = c_dpctl.DPCTLQueue_Copy((self.q).get_queue_ref())
+        if (self.q_ref is NULL):
+            raise ValueError("SyclQueue copy failed")
+
+        # get a scalar seed value or a vector of seeds
+        if isinstance(seed, int) and seed >= 0:
             scalar_seed = <uint32_t> seed
         elif isinstance(seed, (list, tuple)):
             is_vector_seed = True
             vector_seed_len = len(seed)
+            if vector_seed_len > 3:
+                raise ValueError(
+                    f"{vector_seed_len} length of seed vector isn't supported, "
+                    "the length is limited by 3")
+
             vector_seed = <uint32_t *> malloc(vector_seed_len * sizeof(uint32_t))
             if (not vector_seed):
-                raise MemoryError
+                raise MemoryError(f"Could not allocate memory for seed vector of length {vector_seed_len}")
 
+            # convert input seed's type to uint32_t one (expected in MKL function)
             try:
                 for i in range(vector_seed_len):
                     vector_seed[i] = <uint32_t> seed[i]
             except (ValueError, TypeError) as e:
                 free(vector_seed)
                 raise e
         else:
-            raise TypeError("Seed must be an uint32_t, or a sequence of uint32_t elements")
+            raise TypeError("Seed must be an unsigned int, or a sequence of unsigned int elements")
 
-        self.Queue = <c_dpctl.SyclQueue> sycl_queue
-        self.QRef = c_dpctl.DPCTLQueue_Copy((self.Queue).get_queue_ref())
         if is_vector_seed:
-            MT19937_InitVectorSeed(&self.mt19937, self.QRef, vector_seed, vector_seed_len)
+            MT19937_InitVectorSeed(&self.mt19937, self.q_ref, vector_seed, vector_seed_len)
             free(vector_seed)
         else:
-            MT19937_InitScalarSeed(&self.mt19937, self.QRef, scalar_seed)
+            MT19937_InitScalarSeed(&self.mt19937, self.q_ref, scalar_seed)
 
     def __dealloc__(self):
         MT19937_Delete(&self.mt19937)
-        c_dpctl.DPCTLQueue_Delete(self.QRef)
+        c_dpctl.DPCTLQueue_Delete(self.q_ref)
 
-    cdef mt19937_struct * mt19937(self):
+    cdef mt19937_struct * get_mt19937(self):
         return &self.mt19937
 
+    cdef c_dpctl.SyclQueue get_queue(self):
+        return self.q
+
     cdef c_dpctl.DPCTLSyclQueueRef get_queue_ref(self):
-        return self.QRef
+        return self.q_ref
 
     cpdef utils.dpnp_descriptor uniform(self, low, high, size, dtype, usm_type):
         cdef shape_type_c result_shape
@@ -365,11 +379,11 @@ cdef class MT19937:
                                                 None,
                                                 device=None,
                                                 usm_type=usm_type,
-                                                sycl_queue=self.Queue)
+                                                sycl_queue=self.get_queue())
 
         func = <fptr_dpnp_rng_uniform_c_1out_t > kernel_data.ptr
         # call FPTR function
-        event_ref = func(self.QRef, result.get_data(), low, high, result.size, &self.mt19937, NULL)
+        event_ref = func(self.get_queue_ref(), result.get_data(), low, high, result.size, self.get_mt19937(), NULL)
 
         with nogil: c_dpctl.DPCTLEvent_WaitAndThrow(event_ref)
         c_dpctl.DPCTLEvent_Delete(event_ref)

dpnp/random/dpnp_iface_random.py

@@ -99,10 +99,28 @@
 
 
 class RandomState:
-    def __init__(self, seed, sycl_queue=None):
+    """
+    A container for the Mersenne Twister pseudo-random number generator.
+
+    For full documentation refer to :obj:`numpy.random.RandomState`.
+    """
+
+    def __init__(self, seed=1, sycl_queue=None):
+        if seed is None:
+            seed = 1
+
         self.random_state = MT19937(seed, sycl_queue)
 
     def uniform(self, low=0.0, high=1.0, size=None, dtype=numpy.float64, usm_type="device"):
+        """
+        Draw samples from a uniform distribution.
+
+        Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high).
+        In other words, any value within the given interval is equally likely to be drawn by uniform.
+
+        For full documentation refer to :obj:`numpy.random.RandomState.uniform`.
+        """
+
         if not use_origin_backend(low):
             if not dpnp.isscalar(low):
                 pass

tests/test_sycl_queue.py

@@ -220,22 +220,24 @@ def test_broadcasting(func, data1, data2, device):
 
 
 @pytest.mark.parametrize("usm_type",
-                        ["host", "device", "shared"])
-def test_uniform(usm_type):
+                         ["host", "device", "shared"])
+@pytest.mark.parametrize("size",
+                         [None, (), 3, (2, 1), (4, 2, 5)],
+                         ids=['None', '()', '3', '(2,1)', '(4,2,5)'])
+def test_uniform(usm_type, size):
     low = 1.0
     high = 2.0
-    size = 3
     res = dpnp.random.uniform(low, high, size=size, usm_type=usm_type)
 
     res_usm_type = res.get_array().usm_type
     assert usm_type == res_usm_type
 
 
 @pytest.mark.parametrize("usm_type",
-                        ["host", "device", "shared"])
+                         ["host", "device", "shared"])
 @pytest.mark.parametrize("seed",
-                        [123, (12, 58), [134, 99], (147, 56, 896), [1, 654, 78]],
-                        ids=['123', '(12, 58)', '[134, 99]', '(147, 56, 896)', '[1, 654, 78]'])
+                         [None, (), 123, (12, 58), (147, 56, 896), [1, 654, 78]],
+                         ids=['None', '()', '123', '(12,58)', '(147,56,896)', '[1,654,78]'])
 def test_rs_uniform(usm_type, seed):
     seed = 123
     sycl_queue = dpctl.SyclQueue()