random: Base-like APIs for rand, rand!, randn, randn! (#383)

* random: Base-like APIs for rand, rand!, randn, randn!

and deprecate the original APIs

```julia
julia> mx.rand(2, 3)
2×3 mx.NDArray{Float32,2} @ CPU0:
 0.631961  0.324175  0.0762663
 0.285366  0.395292  0.074995

julia> mx.rand(2, 3, low = low, high = high)
2×3 mx.NDArray{Float32,2} @ CPU0:
 7.83884  7.85793  7.64791
 7.68646  8.56082  8.42189
```

```julia
julia> mx.randn(2, 3)
2×3 mx.NDArray{Float32,2} @ CPU0:
 0.962853  0.424535  -0.320123
 0.478113  1.72886    1.72287

julia> mx.randn(2, 3, μ = 100)
2×3 mx.NDArray{Float32,2} @ CPU0:
 99.5635  100.483   99.888
 99.9889  100.533  100.072
```

* fix depwarn

NEWS.md

@@ -208,6 +208,32 @@
     * `arccosh(x)` -> `acosh.(x)`
     * `arctanh(x)` -> `atanh.(x)`
 
+* `rand`, `rand!`, `randn`, `randn!` is more Base-like now (#TBD).
+
+  ```julia
+  julia> mx.rand(2, 3)
+  2×3 mx.NDArray{Float32,2} @ CPU0:
+   0.631961  0.324175  0.0762663
+   0.285366  0.395292  0.074995
+
+  julia> mx.rand(2, 3; low = 1, high = 10)
+  2×3 mx.NDArray{Float32,2} @ CPU0:
+   7.83884  7.85793  7.64791
+   7.68646  8.56082  8.42189
+  ```
+
+  ```julia
+  julia> mx.randn(2, 3)
+  2×3 mx.NDArray{Float32,2} @ CPU0:
+   0.962853  0.424535  -0.320123
+   0.478113  1.72886    1.72287
+
+  julia> mx.randn(2, 3, μ = 100)
+  2×3 mx.NDArray{Float32,2} @ CPU0:
+   99.5635  100.483   99.888
+   99.9889  100.533  100.072
+  ```
+
 # v0.3.0 (2017.11.16)
 
 * Update `libmxnet` to

src/deprecated.jl

@@ -23,3 +23,29 @@
 @deprecate arcsinh(x::NDArray) asinh.(x)
 @deprecate arccosh(x::NDArray) acosh.(x)
 @deprecate arctanh(x::NDArray) atanh.(x)
+
+# @deprecate make `randn` exported accidentially
+# so we make the depwarn manually
+function randn(μ, σ, dims::NTuple{N,Int}, ctx::Context = cpu()) where N
+  warn("mx.randn(μ, σ, dims, ctx = cpu()) is deprecated, use " *
+       "mx.randn(dims...; μ = μ, σ = σ, context = ctx) instead.")
+  mx.randn(dims...; μ = μ, σ = σ, context = ctx)
+end
+
+function randn!(μ, σ, x::NDArray)
+  warn("mx.randn!(μ, σ, x::NDArray) is deprecated, use " *
+       "mx.randn!(x; μ = μ, σ = σ) instead.")
+  randn!(x; μ = μ, σ = σ)
+end
+
+function rand!(low::Real, high::Real, x::NDArray)
+  warn("rand!(low, high, x::NDArray) is deprecated, use " *
+       "rand!(x, low = low, high = high) instead.")
+  rand!(x, low = low, high = high)
+end
+
+function rand(low::Real, high::Real, dims::NTuple{N,Int}, context::Context = cpu()) where N
+  warn("rand!(low, high, dims, x::NDArray, context = cpu()) is deprecated, use " *
+       "rand!(dims..., x; low = low, high = high, context = cpu()) instead.")
+  rand(dims...; low = low, high = high, context = context)
+end

src/initializer.jl

@@ -104,9 +104,8 @@ Construct a `UniformInitializer` with the specified scale.
 """
 UniformInitializer() = UniformInitializer(0.07)
 
-function _init_weight(self :: UniformInitializer, name :: Base.Symbol, array :: NDArray)
-  rand!(-self.scale, self.scale, array)
-end
+_init_weight(i::UniformInitializer, name::Symbol, x::NDArray) =
+  rand!(x, low = -i.scale, high = i.scale)
 
 """
     NormalInitializer
@@ -124,9 +123,8 @@ Construct a `NormalInitializer` with mean `mu` and variance `sigma`.
 """
 NormalInitializer(; mu=0, sigma=0.01) = NormalInitializer(mu, sigma)
 
-function _init_weight(self :: NormalInitializer, name :: Base.Symbol, array :: NDArray)
-  randn!(self.μ, self.σ, array)
-end
+_init_weight(i::NormalInitializer, name::Symbol, x::NDArray) =
+  randn!(x, μ = i.μ, σ = i.σ)
 
 """
     XavierInitializer
@@ -175,8 +173,8 @@ function _init_weight(self :: XavierInitializer, name :: Base.Symbol, array :: N
   σ = √(self.magnitude / factor)
 
   if self.distribution == xv_uniform
-    rand!(-σ, σ, array)
+    rand!(array, low = -σ, high = σ)
   elseif self.distribution == xv_normal
-    randn!(0.0, σ, array)
+    randn!(array; μ = 0.0, σ = σ)
   end
 end

src/random.jl

@@ -1,68 +1,66 @@
 """
-    rand!(low, high, arr::NDArray)
+    rand!(x::NDArray; low = 0, high = 1)
 
 Draw random samples from a uniform distribution.
 Samples are uniformly distributed over the half-open interval [low, high)
 (includes low, but excludes high).
 
-#  Examples
-
 ```julia
-julia> mx.rand(0, 1, mx.zeros(2, 2)) |> copy
-2×2 Array{Float32,2}:
- 0.405374  0.321043
- 0.281153  0.713927
+julia> mx.rand!(empty(2, 3))
+2×3 mx.NDArray{Float32,2} @ CPU0:
+ 0.385748   0.839275  0.444536
+ 0.0879585  0.215928  0.104636
+
+julia> mx.rand!(empty(2, 3), low = 1, high = 10)
+2×3 mx.NDArray{Float32,2} @ CPU0:
+ 6.6385   4.18888  2.07505
+ 8.97283  2.5636   1.95586
 ```
 """
-function rand!(low::Real, high::Real, out::NDArray)
-  _random_uniform(NDArray, low=low, high=high, shape=size(out), out=out)
-end
+rand!(x::NDArray; low = 0, high = 1) =
+  _random_uniform(NDArray, low = low, high = high, shape = size(x), out = x)
 
 """
-    rand(low, high, shape, context=cpu())
+    rand(dims...; low = 0, high = 1, context = cpu())
 
 Draw random samples from a uniform distribution.
 Samples are uniformly distributed over the half-open interval [low, high)
 (includes low, but excludes high).
 
-#  Examples
-
 ```julia
-julia> mx.rand(0, 1, (2, 2)) |> copy
-2×2 Array{Float32,2}:
- 0.405374  0.321043
- 0.281153  0.713927
+julia> mx.rand(2, 2)
+2×2 mx.NDArray{Float32,2} @ CPU0:
+ 0.487866   0.825691
+ 0.0234245  0.794797
+
+julia> mx.rand(2, 2; low = 1, high = 10)
+2×2 mx.NDArray{Float32,2} @ CPU0:
+ 5.5944   5.74281
+ 9.81258  3.58068
 ```
 """
-function rand(low::Real, high::Real, shape::NTuple{N, Int}, ctx::Context=cpu()) where N
-  out = empty(shape, ctx)
-  rand!(low, high, out)
-end
+rand(dims::Int...; low = 0, high = 1, context = cpu()) =
+  rand!(empty(dims, context), low = low, high = high)
 
 """
-    randn!(mean, std, arr::NDArray)
+    randn!(x::NDArray; μ = 0, σ = 1)
 
 Draw random samples from a normal (Gaussian) distribution.
 """
-function randn!(mean::Real, stdvar::Real, out::NDArray)
-  _random_normal(NDArray, loc=mean, scale=stdvar, shape=size(out), out=out)
-end
+randn!(x::NDArray; μ = 0, σ = 1) =
+  _random_normal(NDArray, loc = μ, scale = σ, shape = size(x), out = x)
 
 """
-    randn(mean, std, shape, context=cpu())
+    randn(dims...; μ = 0, σ = 1, context = cpu())
 
 Draw random samples from a normal (Gaussian) distribution.
 """
-function randn(mean::Real, stdvar::Real, shape::NTuple{N,Int}, ctx::Context=cpu()) where N
-  out = empty(shape, ctx)
-  randn!(mean, stdvar, out)
-end
+randn(dims::Int...; μ = 0, σ = 1, context = cpu()) =
+  randn!(empty(dims, context), μ = μ, σ = σ)
 
 """
     srand(seed::Int)
 
 Set the random seed of libmxnet
 """
-function srand(seed_state::Int)
-  @mxcall(:MXRandomSeed, (Cint,), seed_state)
-end
+srand(seed_state::Int) = @mxcall(:MXRandomSeed, (Cint,), seed_state)

test/unittest/random.jl

@@ -9,11 +9,11 @@ function test_uniform()
   low = -10; high = 10
   seed = 123
   mx.srand(seed)
-  ret1 = mx.rand(low, high, dims)
+  ret1 = mx.rand(dims..., low = low, high = high)
 
   mx.srand(seed)
   ret2 = mx.empty(dims)
-  mx.rand!(low, high, ret2)
+  mx.rand!(ret2, low = low, high = high)
 
   @test copy(ret1) == copy(ret2)
   @test abs(mean(copy(ret1)) - (high+low)/2) < 0.1
@@ -26,11 +26,11 @@ function test_gaussian()
   μ = 10; σ = 2
   seed = 456
   mx.srand(seed)
-  ret1 = mx.randn(μ, σ, dims)
+  ret1 = mx.randn(dims..., μ = μ, σ = σ)
 
   mx.srand(seed)
   ret2 = mx.empty(dims)
-  mx.randn!(μ, σ, ret2)
+  mx.randn!(ret2, μ = μ, σ = σ)
 
   @test copy(ret1) == copy(ret2)
   @test abs(mean(copy(ret1)) - μ) < 0.1