expand rand/randn convenience APIs and align docs/tests. Move randn open-interval helpers into utilities.jl and switch naming of internals. Simplify rand!/randn! wrappers and add convenience constructors for omitted rng, backend, or type, with backend-dependent defaults (Float64 on CPU, Float32 otherwise). Add explicit zero-arg guards so rand()/randn() require at least one dimension. Update rand.md with concise convenience semantics and examples, including type-only no-rng calls, plus doc entries for rand/randn. Expand tests to cover default-type dispatch, CPU fallback routes, typed no-rng overloads, and invalid-signature/kwarg throw behavior while preserving deterministic CounterRNG offset progression.

Author: fjbarter

docs/src/api/rand.md

@@ -3,6 +3,10 @@
 Counter-based random generation for CPU and GPU backends with deterministic stream behavior for
 fixed `seed`, algorithm, and call sequence.
 
+Both in-place and allocation forms are supported:
+- Uniform: `AK.rand!`, `AK.rand`
+- Standard normal: `AK.randn!`, `AK.randn`
+
 `CounterRNG` carries an internal `offset` (starting at `0`) that advances by `length(v)` on each
 `AK.rand!(rng, v)` call. This means chunked fills are stream-consistent:
 - filling `100` then `100` elements yields the same `200` values as one `200`-element fill.
@@ -16,9 +20,16 @@ Use an explicit `CounterRNG` when reproducibility is required. For
 convenience,
 `AK.rand!(v)` creates a fresh `CounterRNG()` on each call using one auto-seeded
 `Base.rand(UInt64)` draw, so repeated calls produce different outputs unless Random.seed!() is used.
+Likewise, `AK.rand(backend, args...)` creates a fresh auto-seeded `CounterRNG()` on each call.
 
 `AK.reset!(rng::AK.CounterRNG)` rewinds `rng.offset` to `0x0`.
 
+Allocation convenience:
+- Canonical forms are `AK.rand(rng, backend, T, dims...)` and `AK.randn(rng, backend, T, dims...)`.
+- Defaults are shared: omit `rng` -> fresh `CounterRNG()`; omit `backend` -> CPU backend; omit `T` -> `Float64` on CPU backend and `Float32` otherwise.
+- Common shorthands include `AK.rand(dims...)`, `AK.rand(T, dims...)`, `AK.rand(backend, dims...)`, and the corresponding `AK.randn(...)` variants.
+- For explicit `rng`, both `AK.rand` and `AK.randn` advance `rng.offset` by `prod(dims)`.
+
 Custom algorithms:
 - Define an algorithm type `MyAlg <: AK.CounterRNGAlgorithm`.
 - Implement typed `rand_uint` methods:
@@ -39,6 +50,9 @@ Supported element types:
 
 `AK.randn!` uses Box-Muller with open-interval uniforms in `(0, 1)` from a branch-free midpoint mapping.
 
+`AK.randn!(v)` and `AK.randn(backend, args...)` create a fresh auto-seeded `CounterRNG()` on each
+call, so repeated calls produce different outputs unless `Random.seed!()` is used.
+
 The core of the random number generation produces either a `UInt32` or `UInt64` depending on the width of the requested element type.
 That `UInt` is then either:
 - Unsigned integers: returned as-is or truncated if necessary.
@@ -72,6 +86,7 @@ Examples:
 ```julia
 import AcceleratedKernels as AK
 using oneAPI
+using ROCArray
 
 # Reproducible
 rng = AK.CounterRNG(0x12345678; alg=AK.Philox())
@@ -88,15 +103,27 @@ AK.rand!(rng, v2)
 y = oneArray{Float32}(undef, 1024)
 AK.rand!(y)
 
-# Standard normal samples
-z = oneArray{Float32}(undef, 1024)
+# Allocation form
+y_cpu_auto = AK.rand(1024)                               # defaults to CPU, Vector{Float64}
+y_oneArray = AK.rand(oneAPIBackend(), Float32, 1024)     # fresh RNG, allocate and fill oneArray
+y_cpu_typed = AK.rand(rng, Float16, 1024)                # CPU backend, explicit type, explicit RNG
+
+# Standard normal filling
+z = ROCArray{Float32}(undef, 1024)
 AK.randn!(rng, z)
+
+# Standard normal allocation form
+z_cpu_auto = AK.randn(1024)                              # defaults to CPU, Vector{Float64}
+z_ROCArray = AK.randn(oneAPIBackend(), 1024)             # allocate and fill ROCArray{Float32}
+z_cpu_typed = AK.randn(rng, Float16, 1024)               # CPU backend, explicit type, explicit RNG
 ```
 
 ```@docs
 AcceleratedKernels.CounterRNG
 AcceleratedKernels.CounterRNGAlgorithm
 AcceleratedKernels.reset!
 AcceleratedKernels.rand!
+AcceleratedKernels.rand
 AcceleratedKernels.randn!
+AcceleratedKernels.randn
 ```

prototype/rand/Project.toml

@@ -1,8 +1,7 @@
 [deps]
+AMDGPU = "21141c5a-9bdb-4563-92ae-f87d6854732e"
 AcceleratedKernels = "6a4ca0a5-0e36-4168-a932-d9be78d558f1"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 Cthulhu = "f68482b8-f384-11e8-15f7-abe071a5a75f"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
-PProf = "e4faabce-9ead-11e9-39d9-4379958e3056"
-Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

prototype/rand/plot/Project.toml

@@ -48,6 +48,4 @@ display(@benchmark run_cuda_randn!($x_cuda))
 println("\nAK.randn! Philox benchmark (GPU, CuArray{$TestType})")
 display(@benchmark run_ak_randn_gpu!($RNG_PHILOX, $x_philox))
 
-# println("\nAK.randn! benchmark (CPU, Vector{$TestType}, Philox)")
-# display(@benchmark run_ak_randn_cpu!($RNG_PHILOX, $x_cpu))
 

prototype/rand/randn.jl

@@ -11,11 +11,13 @@ const RNG_SPLITMIX = AK.CounterRNG(0x12345678; alg=AK.SplitMix64())
 const RNG_PHILOX = AK.CounterRNG(0x12345678; alg=AK.Philox())
 const RNG_THREEFRY = AK.CounterRNG(0x12345678; alg=AK.Threefry())
 
-x_cuda = CuArray{Float32}(undef, N)
-x_splitmix = CuArray{Float32}(undef, N)
-x_philox = CuArray{Float32}(undef, N)
-x_threefry = CuArray{Float32}(undef, N)
-x_cpu = Vector{Float32}(undef, N)
+TestType = Float32
+
+x_cuda = CuArray{TestType}(undef, N)
+x_splitmix = CuArray{TestType}(undef, N)
+x_philox = CuArray{TestType}(undef, N)
+x_threefry = CuArray{TestType}(undef, N)
+x_cpu = Vector{TestType}(undef, N)
 
 
 function run_cuda_rand!(x)
@@ -43,32 +45,27 @@ is_unit_interval(v) = all(x -> 0.0f0 <= x <= 1.0f0, v)
 
 # warmup compile
 run_cuda_rand!(x_cuda)
-# run_ak_rand_gpu!(RNG_SPLITMIX, x_splitmix)
 run_ak_rand_gpu!(RNG_PHILOX, x_philox)
 run_ak_rand_gpu!(RNG_THREEFRY, x_threefry)
 run_ak_rand_cpu!(RNG_SPLITMIX, x_cpu)
 
 @assert is_unit_interval(Array(x_cuda))
-# @assert is_unit_interval(Array(x_splitmix))
 @assert is_unit_interval(Array(x_philox))
 @assert is_unit_interval(Array(x_threefry))
 @assert is_unit_interval(x_cpu)
 
 println("N = ", N)
 println("CPU threads: ", Threads.nthreads())
 
-println("\nCUDA.rand! benchmark (CuArray{Float32}, in-place)")
+println("\nCUDA.rand! benchmark (CuArray{$TestType}, in-place)")
 display(@benchmark run_cuda_rand!($x_cuda))
 
-# println("\nAK.rand! SplitMix64 benchmark (GPU, CuArray{Float32})")
-# display(@benchmark run_ak_rand_gpu!($RNG_SPLITMIX, $x_splitmix))
-
-println("\nAK.rand! Philox benchmark (GPU, CuArray{Float32})")
+println("\nAK.rand! Philox benchmark (GPU, CuArray{$TestType})")
 display(@benchmark run_ak_rand_gpu!($RNG_PHILOX, $x_philox))
 
-println("\nAK.rand! Threefry benchmark (GPU, CuArray{Float32})")
+println("\nAK.rand! Threefry benchmark (GPU, CuArray{$TestType})")
 display(@benchmark run_ak_rand_gpu!($RNG_THREEFRY, $x_threefry))
 
-println("\nAK.rand! benchmark (CPU, Vector{Float32}, SplitMix64)")
+println("\nAK.rand! benchmark (CPU, Vector{$TestType}, SplitMix64)")
 display(@benchmark run_ak_rand_cpu!($RNG_SPLITMIX, $x_cpu))
 

prototype/rand/test_rand.jl

@@ -148,13 +148,7 @@ function rand!(
 end
 
 
-function rand!(
-    v::AbstractArray,
-    args...;
-    kwargs...,
-)
-    return rand!(CounterRNG(), v, args...; kwargs...)
-end
+rand!(v::AbstractArray, args...; kwargs...) = rand!(CounterRNG(), v, args...; kwargs...)
 
 
 """
@@ -175,6 +169,11 @@ end
 
 Allocate an array of element type `T` on `backend` with shape `dims`, fill it in-place via
 [`rand!`](@ref), and return it.
+
+Convenience overloads:
+- `rng` omitted: uses a fresh `CounterRNG()`.
+- `backend` omitted: defaults to `CPU_BACKEND`.
+- `T` omitted: defaults by backend (`Float64` on CPU backend, `Float32` otherwise).
 """
 function rand(
     rng::CounterRNG,
@@ -198,21 +197,16 @@ function rand(
 end
 
 
-function rand(
-    backend::Backend,
-    ::Type{T},
-    dims::Integer...;
-    
-    # CPU settings
-    max_tasks::Int=Threads.nthreads(),
-    min_elems::Int=1,
-    prefer_threads::Bool=true,
-
-    # GPU settings
-    block_size::Int=256,
-) where T
-    return rand(
-        CounterRNG(), backend, T, dims...;
-        max_tasks, min_elems, prefer_threads, block_size,
-    )
+function rand(rng::CounterRNG, backend::Backend, dims::Integer...; kwargs...)
+    DefaultScalarType = (backend == CPU_BACKEND) ? Float64 : Float32
+    rand(rng, backend, DefaultScalarType, dims...; kwargs...)
 end
+
+
+rand(rng::CounterRNG, args...; kwargs...) = rand(rng, CPU_BACKEND, args...; kwargs...)
+rand(backend::Backend, args...; kwargs...) = rand(CounterRNG(), backend, args...; kwargs...)
+rand(::Type{T}, dims::Integer...; kwargs...) where {T} = rand(CPU_BACKEND, T, dims...; kwargs...)
+rand(dims::Integer...; kwargs...) = rand(CPU_BACKEND, dims...; kwargs...)
+rand(; kwargs...) = throw(ArgumentError("rand requires at least one dimension"))
+
+

src/rand/rand.jl

@@ -2,76 +2,6 @@ const ALLOWED_RANDN_SCALARS = Union{
     Float16, Float32, Float64
 }
 
-const OPEN01_MAX_MIDPOINT_INDEX_F32 = UInt32(0x00fffffe)
-const OPEN01_MAX_MIDPOINT_INDEX_F64 = UInt64(0x001ffffffffffffe)
-const OPEN01_MIDPOINT_SCALE_F32 = ldexp(Float32(1), -24)
-const OPEN01_MIDPOINT_SCALE_F64 = ldexp(Float64(1), -53)
-
-
-
-
-#=
-The below Float constructions are not duplicates of those in utilities.jl - they are needed to
-ensure an interval of (0, 1) as opposed to [0, 1). Achieving this purely logically with midpoint
-mapping means we can avoid a check for producing a 0 (which would normally cause a redraw).
-Avoiding 0 is essential for Box-Muller due to the logarithm functions.
-=#
-
-
-# Convert random UInt32 bits to Float32 in (0, 1) using midpoint mapping on a 24-bit grid.
-@inline function uint32_to_open_unit_float32_midpoint(u::UInt32)::Float32
-    # `min` keeps the top midpoint below one after Float32 rounding.
-    k = min(u >> 8, OPEN01_MAX_MIDPOINT_INDEX_F32)
-    return (Float32(k) + 0.5f0) * OPEN01_MIDPOINT_SCALE_F32
-end
-
-
-# Convert random UInt64 bits to Float64 in (0, 1) using midpoint mapping on a 53-bit grid.
-@inline function uint64_to_open_unit_float64_midpoint(u::UInt64)::Float64
-    # `min` keeps the top midpoint below one after Float64 rounding.
-    k = min(u >> 11, OPEN01_MAX_MIDPOINT_INDEX_F64)
-    return (Float64(k) + 0.5) * OPEN01_MIDPOINT_SCALE_F64
-end
-
-
-# Float16 path reuses Float32 midpoint sampling for robust math in Box-Muller.
-@inline function rand_open01(
-    seed::UInt64,
-    alg::CounterRNGAlgorithm,
-    counter::UInt64,
-    ::Type{Float16},
-)::Float16
-    return Float16(rand_open01(seed, alg, counter, Float32))
-end
-
-
-@inline function rand_open01(
-    seed::UInt64,
-    alg::CounterRNGAlgorithm,
-    counter::UInt64,
-    ::Type{Float32},
-)::Float32
-    return uint32_to_open_unit_float32_midpoint(rand_uint(seed, alg, counter, UInt32))
-end
-
-
-@inline function rand_open01(
-    seed::UInt64,
-    alg::CounterRNGAlgorithm,
-    counter::UInt64,
-    ::Type{Float64},
-)::Float64
-    return uint64_to_open_unit_float64_midpoint(rand_uint(seed, alg, counter, UInt64))
-end
-
-
-@inline function rand_open01(::UInt64, ::CounterRNGAlgorithm, ::UInt64, ::Type{T}) where {T}
-    throw(ArgumentError(
-        "Unsupported open-interval random type $(T). Supported: $(ALLOWED_RANDN_SCALARS)"
-    ))
-end
-
-
 @inline function randn_pair(
     seed::UInt64,
     alg::CounterRNGAlgorithm,
@@ -90,8 +20,8 @@ end
     ::Type{Float32},
 )::Tuple{Float32, Float32}
     u = rand_uint(seed, alg, pair_counter, UInt64)
-    u1 = uint32_to_open_unit_float32_midpoint(_u32_lo(u))
-    u2 = uint32_to_open_unit_float32_midpoint(_u32_hi(u))
+    u1 = _uint32_to_open_unit_float32_midpoint(_u32_lo(u))
+    u2 = _uint32_to_open_unit_float32_midpoint(_u32_hi(u))
     radius = sqrt(-2.0f0 * log(u1))
     theta = Float32(2pi) * u2
     stheta, ctheta = sincos(theta)
@@ -106,8 +36,8 @@ end
     ::Type{Float64},
 )::Tuple{Float64, Float64}
     c0 = pair_counter << 1
-    u1 = rand_open01(seed, alg, c0, Float64)
-    u2 = rand_open01(seed, alg, c0 + UInt64(1), Float64)
+    u1 = rand_float_open01(seed, alg, c0, Float64)
+    u2 = rand_float_open01(seed, alg, c0 + UInt64(1), Float64)
     radius = sqrt(-2.0 * log(u1))
     theta = Float64(2pi) * u2
     stheta, ctheta = sincos(theta)
@@ -256,13 +186,7 @@ function randn!(
 end
 
 
-function randn!(
-    v::AbstractArray,
-    args...;
-    kwargs...,
-)
-    return randn!(CounterRNG(), v, args...; kwargs...)
-end
+randn!(v::AbstractArray, args...; kwargs...) = randn!(CounterRNG(), v, args...; kwargs...)
 
 
 """
@@ -283,6 +207,11 @@ end
 
 Allocate an array of element type `T` on `backend` with shape `dims`, fill it in-place via
 [`randn!`](@ref), and return it.
+
+Convenience overloads:
+- `rng` omitted: uses a fresh `CounterRNG()`.
+- `backend` omitted: defaults to `CPU_BACKEND`.
+- `T` omitted: defaults by backend (`Float64` on CPU backend, `Float32` otherwise).
 """
 function randn(
     rng::CounterRNG,
@@ -306,21 +235,14 @@ function randn(
 end
 
 
-function randn(
-    backend::Backend,
-    ::Type{T},
-    dims::Integer...;
+function randn(rng::CounterRNG, backend::Backend, dims::Integer...; kwargs...)
+    DefaultScalarType = (backend == CPU_BACKEND) ? Float64 : Float32
+    randn(rng, backend, DefaultScalarType, dims...; kwargs...)
+end
 
-    # CPU settings
-    max_tasks::Int=Threads.nthreads(),
-    min_elems::Int=1,
-    prefer_threads::Bool=true,
 
-    # GPU settings
-    block_size::Int=256,
-) where T
-    return randn(
-        CounterRNG(), backend, T, dims...;
-        max_tasks, min_elems, prefer_threads, block_size,
-    )
-end
+randn(rng::CounterRNG, args...; kwargs...) = randn(rng, CPU_BACKEND, args...; kwargs...)
+randn(backend::Backend, args...; kwargs...) = randn(CounterRNG(), backend, args...; kwargs...)
+randn(::Type{T}, dims::Integer...; kwargs...) where {T} = randn(CPU_BACKEND, T, dims...; kwargs...)
+randn(dims::Integer...; kwargs...) = randn(CPU_BACKEND, dims...; kwargs...)
+randn(; kwargs...) = throw(ArgumentError("randn requires at least one dimension"))