FEATURE: random number generation functions

* Moved old rand* functions to random module
* New object `RandomEngine` is added
* Additional random number generation functions that use RandomEngine
  object are added.

Author: 9prady9

src/data/mod.rs

@@ -38,12 +38,6 @@ extern {
     fn af_iota(out: MutAfArray, ndims: c_uint, dims: *const DimT,
                t_ndims: c_uint, tdims: *const DimT, afdtype: uint8_t) -> c_int;
 
-    fn af_randu(out: MutAfArray, ndims: c_uint, dims: *const DimT, afdtype: uint8_t) -> c_int;
-    fn af_randn(out: MutAfArray, ndims: c_uint, dims: *const DimT, afdtype: uint8_t) -> c_int;
-
-    fn af_set_seed(seed: Uintl) -> c_int;
-    fn af_get_seed(seed: *mut Uintl) -> c_int;
-
     fn af_identity(out: MutAfArray, ndims: c_uint, dims: *const DimT, afdtype: uint8_t) -> c_int;
     fn af_diag_create(out: MutAfArray, arr: AfArray, num: c_int) -> c_int;
     fn af_diag_extract(out: MutAfArray, arr: AfArray, num: c_int) -> c_int;
@@ -250,55 +244,28 @@ pub fn iota<T: HasAfEnum>(dims: Dim4, tdims: Dim4) -> Array {
     }
 }
 
-/// Set seed for random number generation
-pub fn set_seed(seed: u64) {
-    unsafe {
-        let err_val = af_set_seed(seed as Uintl);
-        HANDLE_ERROR(AfError::from(err_val));
-    }
-}
-
-/// Get the seed of random number generator
+/// Create an identity array with 1's in diagonal
+///
+/// # Parameters
+///
+/// - `dims` is the output Array dimensions
+///
+/// # Return Values
+///
+/// Identity matrix
 #[allow(unused_mut)]
-pub fn get_seed() -> u64 {
+pub fn identity<T: HasAfEnum>(dims: Dim4) -> Array {
     unsafe {
-        let mut temp: u64 = 0;
-        let err_val = af_get_seed(&mut temp as *mut Uintl);
+        let aftype = T::get_af_dtype();
+        let mut temp: i64 = 0;
+        let err_val = af_identity(&mut temp as MutAfArray,
+                                  dims.ndims() as c_uint, dims.get().as_ptr() as *const DimT,
+                                  aftype as uint8_t);
         HANDLE_ERROR(AfError::from(err_val));
-        temp
+        Array::from(temp)
     }
 }
 
-macro_rules! data_gen_def {
-    ($doc_str: expr, $fn_name:ident, $ffi_name: ident) => (
-        #[doc=$doc_str]
-        ///
-        ///# Parameters
-        ///
-        /// - `dims` is the output dimensions
-        ///
-        ///# Return Values
-        ///
-        /// An Array with modified data.
-        #[allow(unused_mut)]
-        pub fn $fn_name<T: HasAfEnum>(dims: Dim4) -> Array {
-            unsafe {
-                let aftype = T::get_af_dtype();
-                let mut temp: i64 = 0;
-                let err_val = $ffi_name(&mut temp as MutAfArray,
-                                        dims.ndims() as c_uint, dims.get().as_ptr() as *const DimT,
-                                        aftype as uint8_t);
-                HANDLE_ERROR(AfError::from(err_val));
-                Array::from(temp)
-            }
-        }
-    )
-}
-
-data_gen_def!("Create random numbers from uniform distribution", randu, af_randu);
-data_gen_def!("Create random numbers from normal distribution", randn, af_randn);
-data_gen_def!("Create an identity array with 1's in diagonal", identity, af_identity);
-
 /// Create a diagonal matrix
 ///
 /// # Parameters

src/defines.rs

@@ -380,3 +380,20 @@ pub enum BinaryOp {
     MIN = 2,
     MAX = 3
 }
+
+/// Random engine types
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum RandomEngineType {
+    ///Philox variant with N=4, W=32 and Rounds=10
+    PHILOX_4X32_10      = 100,
+    ///Threefry variant with N=2, W=32 and Rounds=16
+    THREEFRY_2X32_16    = 200,
+    ///Mersenne variant with MEXP = 11213
+    MERSENNE_GP11213    = 300
+}
+
+pub const PHILOX   : RandomEngineType = RandomEngineType::PHILOX_4X32_10;
+pub const THREEFRY : RandomEngineType = RandomEngineType::THREEFRY_2X32_16;
+pub const MERSENNE : RandomEngineType = RandomEngineType::MERSENNE_GP11213;
+pub const DEFAULT_RANDOM_ENGINE : RandomEngineType = PHILOX;

src/lib.rs

@@ -33,7 +33,6 @@ pub use blas::{matmul, dot, transpose, transpose_inplace};
 mod blas;
 
 pub use data::{constant, range, iota};
-pub use data::{set_seed, get_seed, randu, randn};
 pub use data::{identity, diag_create, diag_extract, lower, upper};
 pub use data::{join, join_many, tile};
 pub use data::{reorder, shift, moddims, flat, flip};
@@ -47,7 +46,8 @@ mod device;
 pub use defines::{DType, AfError, Backend, ColorMap, YCCStd, HomographyType};
 pub use defines::{InterpType, BorderType, MatchType, NormType};
 pub use defines::{Connectivity, ConvMode, ConvDomain, ColorSpace, MatProp};
-pub use defines::{MarkerType, MomentType, SparseFormat, BinaryOp};
+pub use defines::{MarkerType, MomentType, SparseFormat, BinaryOp, RandomEngineType};
+pub use defines::{PHILOX, THREEFRY, MERSENNE, DEFAULT_RANDOM_ENGINE};
 mod defines;
 
 pub use dim4::Dim4;
@@ -83,6 +83,11 @@ mod lapack;
 mod macros;
 mod num;
 
+pub use random::RandomEngine;
+pub use random::{set_seed, get_seed, randu, randn, random_uniform, random_normal};
+pub use random::{get_default_random_engine, set_default_random_engine_type};
+mod random;
+
 pub use signal::{approx1, approx2, set_fft_plan_cache_size};
 pub use signal::{fft, fft2, fft3, ifft, ifft2, ifft3};
 pub use signal::{fft_r2c, fft2_r2c, fft3_r2c, fft_c2r, fft2_c2r, fft3_c2r};

src/random/mod.rs

@@ -0,0 +1,260 @@
+extern crate libc;
+
+use array::Array;
+use dim4::Dim4;
+use defines::{AfError, RandomEngineType};
+use error::HANDLE_ERROR;
+use self::libc::{uint8_t, c_int, c_uint, c_ulong};
+use util::HasAfEnum;
+
+type MutAfArray = *mut self::libc::c_longlong;
+type AfArray    = self::libc::c_longlong;
+type MutRandEngine = *mut self::libc::c_longlong;
+type RandEngine    = self::libc::c_longlong;
+type DimT    = self::libc::c_longlong;
+type Intl    = self::libc::c_longlong;
+type Uintl   = self::libc::c_ulonglong;
+
+#[allow(dead_code)]
+extern {
+    fn af_set_seed(seed: Uintl) -> c_int;
+    fn af_get_seed(seed: *mut Uintl) -> c_int;
+
+    fn af_randu(out: MutAfArray, ndims: c_uint, dims: *const DimT, afdtype: uint8_t) -> c_int;
+    fn af_randn(out: MutAfArray, ndims: c_uint, dims: *const DimT, afdtype: uint8_t) -> c_int;
+
+    fn af_create_random_engine(engine: MutRandEngine, rtype: uint8_t, seed: Uintl) -> c_int;
+    fn af_retain_random_engine(engine: MutRandEngine, inputEngine: RandEngine) -> c_int;
+    fn af_random_engine_set_type(engine: MutRandEngine, rtpye: uint8_t) -> c_int;
+    fn af_random_engine_get_type(rtype: *mut uint8_t, engine: RandEngine) -> c_int;
+    fn af_random_engine_set_seed(engine: MutRandEngine, seed: Uintl) -> c_int;
+    fn af_random_engine_get_seed(seed: *mut Uintl, engine: RandEngine) -> c_int;
+    fn af_release_random_engine(engine: RandEngine) -> c_int;
+
+    fn af_get_default_random_engine(engine: MutRandEngine) -> c_int;
+    fn af_set_default_random_engine_type(rtype: uint8_t) -> c_int;
+
+    fn af_random_uniform(out: MutAfArray, ndims: c_uint, dims: *const DimT,
+                         aftype: uint8_t, engine: RandEngine) -> c_int;
+    fn af_random_normal(out: MutAfArray, ndims: c_uint, dims: *const DimT,
+                        aftype: uint8_t, engine: RandEngine) -> c_int;
+}
+
+/// Set seed for random number generation
+pub fn set_seed(seed: u64) {
+    unsafe {
+        let err_val = af_set_seed(seed as Uintl);
+        HANDLE_ERROR(AfError::from(err_val));
+    }
+}
+
+/// Get the seed of random number generator
+#[allow(unused_mut)]
+pub fn get_seed() -> u64 {
+    unsafe {
+        let mut temp: u64 = 0;
+        let err_val = af_get_seed(&mut temp as *mut Uintl);
+        HANDLE_ERROR(AfError::from(err_val));
+        temp
+    }
+}
+
+macro_rules! data_gen_def {
+    ($doc_str: expr, $fn_name:ident, $ffi_name: ident) => (
+        #[doc=$doc_str]
+        ///
+        ///# Parameters
+        ///
+        /// - `dims` is the output dimensions
+        ///
+        ///# Return Values
+        ///
+        /// An Array with random values.
+        #[allow(unused_mut)]
+        pub fn $fn_name<T: HasAfEnum>(dims: Dim4) -> Array {
+            unsafe {
+                let aftype = T::get_af_dtype();
+                let mut temp: i64 = 0;
+                let err_val = $ffi_name(&mut temp as MutAfArray,
+                                        dims.ndims() as c_uint, dims.get().as_ptr() as *const DimT,
+                                        aftype as uint8_t);
+                HANDLE_ERROR(AfError::from(err_val));
+                Array::from(temp)
+            }
+        }
+    )
+}
+
+data_gen_def!("Create random numbers from uniform distribution", randu, af_randu);
+data_gen_def!("Create random numbers from normal distribution", randn, af_randn);
+
+/// Random number generator engine
+///
+/// This is a wrapper for ArrayFire's native random number generator engine.
+pub struct RandomEngine {
+    handle: i64,
+}
+
+/// Used for creating RandomEngine object from native resource id
+impl From<i64> for RandomEngine {
+    fn from(t: i64) -> RandomEngine {
+        RandomEngine {handle: t}
+    }
+}
+
+impl RandomEngine {
+    /// Create a new random engine object
+    ///
+    /// # Parameters
+    ///
+    /// - `rengine` can be value of [RandomEngineType](./enum.RandomEngineType.html) enum.
+    /// - `seed` is the initial seed value
+    ///
+    /// # Return Values
+    ///
+    /// A object of type RandomEngine
+    pub fn new(rengine: RandomEngineType, seed: Option<u64>) -> RandomEngine {
+        unsafe {
+            let mut temp: i64 = 0;
+            let err_val = af_create_random_engine(&mut temp as MutRandEngine, rengine as uint8_t,
+                                                  match seed {Some(s) => s, None => 0} as c_ulong);
+            HANDLE_ERROR(AfError::from(err_val));
+            RandomEngine::from(temp)
+        }
+    }
+
+    /// Get random engine type
+    pub fn get_type(&self) -> RandomEngineType {
+        unsafe {
+            let mut temp: u8 = 0;
+            let err_val = af_random_engine_get_type(&mut temp as *mut uint8_t,
+                                                    self.handle as RandEngine);
+            HANDLE_ERROR(AfError::from(err_val));
+            RandomEngineType::from(temp as i32)
+        }
+    }
+
+    /// Get random engine type
+    pub fn set_type(&mut self, engine_type: RandomEngineType) {
+        unsafe {
+            let err_val = af_random_engine_set_type(&mut self.handle as MutRandEngine,
+                                                    engine_type as uint8_t);
+            HANDLE_ERROR(AfError::from(err_val));
+        }
+    }
+
+    /// Set seed for random engine
+    pub fn set_seed(&mut self, seed: u64) {
+        unsafe {
+            let err_val = af_random_engine_set_seed(&mut self.handle as MutRandEngine,
+                                                    seed as Uintl);
+            HANDLE_ERROR(AfError::from(err_val));
+        }
+    }
+
+    /// Get seed of the random engine
+    pub fn get_seed(&self) -> u64 {
+        unsafe {
+            let mut seed: u64 = 0;
+            let err_val = af_random_engine_get_seed(&mut seed as *mut Uintl, self.handle as RandEngine);
+            HANDLE_ERROR(AfError::from(err_val));
+            seed
+        }
+    }
+
+    /// Returns the native FFI handle for Rust object `RandomEngine`
+    pub fn get(&self) -> i64 {
+        self.handle
+    }
+}
+
+/// Increment reference count of RandomEngine's native resource
+impl Clone for RandomEngine {
+    fn clone(&self) -> RandomEngine {
+        unsafe {
+            let mut temp: i64 = 0;
+            let err_val = af_retain_random_engine(&mut temp as MutRandEngine, self.handle as RandEngine);
+            HANDLE_ERROR(AfError::from(err_val));
+            RandomEngine::from(temp)
+        }
+    }
+}
+
+/// Free RandomEngine's native resource
+impl Drop for RandomEngine {
+    fn drop(&mut self) {
+        unsafe {
+            let err_val = af_release_random_engine(self.handle as RandEngine);
+            HANDLE_ERROR(AfError::from(err_val));
+        }
+    }
+}
+
+/// Get default random engine
+pub fn get_default_random_engine() -> RandomEngine {
+    unsafe {
+        let mut temp : i64 = 0;
+        let mut err_val = af_get_default_random_engine(&mut temp as MutRandEngine);
+        HANDLE_ERROR(AfError::from(err_val));
+        let mut handle : i64 = 0;
+        err_val = af_retain_random_engine(&mut handle as MutRandEngine, temp as RandEngine);
+        HANDLE_ERROR(AfError::from(err_val));
+        RandomEngine::from(handle)
+    }
+}
+
+/// Set the random engine type for default random number generator
+///
+/// # Parameters
+///
+/// - `rtype` can take one of the values of enum [RandomEngineType](./enum.RandomEngineType.html)
+pub fn set_default_random_engine_type(rtype: RandomEngineType) {
+    unsafe {
+        let err_val = af_set_default_random_engine_type(rtype as uint8_t);
+        HANDLE_ERROR(AfError::from(err_val));
+    }
+}
+
+/// Generate array of uniform numbers using a random engine
+///
+/// # Parameters
+///
+/// - `dims` is output array dimensions
+/// - `engine` is an object of type [RandomEngine](./struct.RandomEngine.html)
+///
+/// # Return Values
+///
+/// An Array with uniform numbers generated using random engine
+pub fn random_uniform<T: HasAfEnum>(dims: Dim4, engine: RandomEngine) -> Array {
+    unsafe {
+        let aftype = T::get_af_dtype();
+        let mut temp : i64 = 0;
+        let err_val = af_random_uniform(&mut temp as MutAfArray,
+                                        dims.ndims() as c_uint, dims.get().as_ptr() as *const DimT,
+                                        aftype as uint8_t, engine.get() as RandEngine);
+        HANDLE_ERROR(AfError::from(err_val));
+        Array::from(temp)
+    }
+}
+
+/// Generate array of normal numbers using a random engine
+///
+/// # Parameters
+///
+/// - `dims` is output array dimensions
+/// - `engine` is an object of type [RandomEngine](./struct.RandomEngine.html)
+///
+/// # Return Values
+///
+/// An Array with normal numbers generated using random engine
+pub fn random_normal<T: HasAfEnum>(dims: Dim4, engine: RandomEngine) -> Array {
+    unsafe {
+        let aftype = T::get_af_dtype();
+        let mut temp : i64 = 0;
+        let err_val = af_random_normal(&mut temp as MutAfArray,
+                                       dims.ndims() as c_uint, dims.get().as_ptr() as *const DimT,
+                                       aftype as uint8_t, engine.get() as RandEngine);
+        HANDLE_ERROR(AfError::from(err_val));
+        Array::from(temp)
+    }
+}