From b297cc42843b05bd643256689e77d36ad687f793 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mos=C3=A8=20Giordano?= Date: Sun, 27 Mar 2022 23:31:06 +0100 Subject: [PATCH] [Random] Document `default_rng` and remove references to `GLOBAL_RNG` (#44733) * [Random] Document `default_rng` and remove references to `GLOBAL_RNG` * [Random] Remove last references to `GLOBAL_RNG` in `seed!` docstring While the method does use `GLOBAL_RNG` by default, that's an implementation detail, and it eventually uses `default_rng()` internally. --- stdlib/Random/docs/src/index.md | 1 + stdlib/Random/src/RNGs.jl | 13 +++++++++++++ stdlib/Random/src/Random.jl | 8 ++++---- stdlib/Random/src/misc.jl | 20 ++++++++++---------- stdlib/Random/src/normal.jl | 8 ++++---- 5 files changed, 32 insertions(+), 18 deletions(-) diff --git a/stdlib/Random/docs/src/index.md b/stdlib/Random/docs/src/index.md index 059cd8f600e7d..0f7636cf2444f 100644 --- a/stdlib/Random/docs/src/index.md +++ b/stdlib/Random/docs/src/index.md @@ -70,6 +70,7 @@ Random.shuffle! ## Generators (creation and seeding) ```@docs +Random.default_rng Random.seed! Random.AbstractRNG Random.TaskLocalRNG diff --git a/stdlib/Random/src/RNGs.jl b/stdlib/Random/src/RNGs.jl index a50f633e68a9c..5a33cb97a36f0 100644 --- a/stdlib/Random/src/RNGs.jl +++ b/stdlib/Random/src/RNGs.jl @@ -355,6 +355,19 @@ end # GLOBAL_RNG currently uses TaskLocalRNG typeof_rng(::_GLOBAL_RNG) = TaskLocalRNG +""" + default_rng() -> rng + +Return the default global random number generator (RNG). + +!!! note + What the default RNG is is an implementation detail. Across different versions of + Julia, you should not expect the default RNG to be always the same, nor that it will + return the same stream of random numbers for a given seed. + +!!! compat "Julia 1.3" + This function was introduced in Julia 1.3. +""" @inline default_rng() = TaskLocalRNG() @inline default_rng(tid::Int) = TaskLocalRNG() diff --git a/stdlib/Random/src/Random.jl b/stdlib/Random/src/Random.jl index 432fab1638dda..e3cd5f7905787 100644 --- a/stdlib/Random/src/Random.jl +++ b/stdlib/Random/src/Random.jl @@ -307,7 +307,7 @@ include("XoshiroSimd.jl") ## rand & rand! & seed! docstrings """ - rand([rng=GLOBAL_RNG], [S], [dims...]) + rand([rng=default_rng()], [S], [dims...]) Pick a random element or array of random elements from the set of values specified by `S`; `S` can be @@ -359,7 +359,7 @@ julia> rand(Float64, (2, 3)) rand """ - rand!([rng=GLOBAL_RNG], A, [S=eltype(A)]) + rand!([rng=default_rng()], A, [S=eltype(A)]) Populate the array `A` with random values. If `S` is specified (`S` can be a type or a collection, cf. [`rand`](@ref) for details), @@ -383,8 +383,8 @@ julia> rand!(rng, zeros(5)) rand! """ - seed!([rng=GLOBAL_RNG], seed) -> rng - seed!([rng=GLOBAL_RNG]) -> rng + seed!([rng=default_rng()], seed) -> rng + seed!([rng=default_rng()]) -> rng Reseed the random number generator: `rng` will give a reproducible sequence of numbers if and only if a `seed` is provided. Some RNGs diff --git a/stdlib/Random/src/misc.jl b/stdlib/Random/src/misc.jl index 0d6e06c444a09..ab6c796e5f539 100644 --- a/stdlib/Random/src/misc.jl +++ b/stdlib/Random/src/misc.jl @@ -11,7 +11,7 @@ function rand!(rng::AbstractRNG, B::BitArray, ::SamplerType{Bool}) end """ - bitrand([rng=GLOBAL_RNG], [dims...]) + bitrand([rng=default_rng()], [dims...]) Generate a `BitArray` of random boolean values. @@ -43,7 +43,7 @@ bitrand(dims::Integer...) = rand!(BitArray(undef, convert(Dims, dims))) ## randstring (often useful for temporary filenames/dirnames) """ - randstring([rng=GLOBAL_RNG], [chars], [len=8]) + randstring([rng=default_rng()], [chars], [len=8]) Create a random string of length `len`, consisting of characters from `chars`, which defaults to the set of upper- and lower-case letters @@ -126,7 +126,7 @@ function randsubseq!(r::AbstractRNG, S::AbstractArray, A::AbstractArray, p::Real end """ - randsubseq!([rng=GLOBAL_RNG,] S, A, p) + randsubseq!([rng=default_rng(),] S, A, p) Like [`randsubseq`](@ref), but the results are stored in `S` (which is resized as needed). @@ -154,7 +154,7 @@ randsubseq(r::AbstractRNG, A::AbstractArray{T}, p::Real) where {T} = randsubseq!(r, T[], A, p) """ - randsubseq([rng=GLOBAL_RNG,] A, p) -> Vector + randsubseq([rng=default_rng(),] A, p) -> Vector Return a vector consisting of a random subsequence of the given array `A`, where each element of `A` is included (in order) with independent probability `p`. (Complexity is @@ -182,7 +182,7 @@ ltm52(n::Int, mask::Int=nextpow(2, n)-1) = LessThan(n-1, Masked(mask, UInt52Raw( ## shuffle & shuffle! """ - shuffle!([rng=GLOBAL_RNG,] v::AbstractArray) + shuffle!([rng=default_rng(),] v::AbstractArray) In-place version of [`shuffle`](@ref): randomly permute `v` in-place, optionally supplying the random-number generator `rng`. @@ -228,7 +228,7 @@ end shuffle!(a::AbstractArray) = shuffle!(default_rng(), a) """ - shuffle([rng=GLOBAL_RNG,] v::AbstractArray) + shuffle([rng=default_rng(),] v::AbstractArray) Return a randomly permuted copy of `v`. The optional `rng` argument specifies a random number generator (see [Random Numbers](@ref)). @@ -260,7 +260,7 @@ shuffle(a::AbstractArray) = shuffle(default_rng(), a) ## randperm & randperm! """ - randperm([rng=GLOBAL_RNG,] n::Integer) + randperm([rng=default_rng(),] n::Integer) Construct a random permutation of length `n`. The optional `rng` argument specifies a random number generator (see [Random @@ -288,7 +288,7 @@ randperm(r::AbstractRNG, n::T) where {T <: Integer} = randperm!(r, Vector{T}(und randperm(n::Integer) = randperm(default_rng(), n) """ - randperm!([rng=GLOBAL_RNG,] A::Array{<:Integer}) + randperm!([rng=default_rng(),] A::Array{<:Integer}) Construct in `A` a random permutation of length `length(A)`. The optional `rng` argument specifies a random number generator (see @@ -328,7 +328,7 @@ randperm!(a::Array{<:Integer}) = randperm!(default_rng(), a) ## randcycle & randcycle! """ - randcycle([rng=GLOBAL_RNG,] n::Integer) + randcycle([rng=default_rng(),] n::Integer) Construct a random cyclic permutation of length `n`. The optional `rng` argument specifies a random number generator, see [Random Numbers](@ref). @@ -354,7 +354,7 @@ randcycle(r::AbstractRNG, n::T) where {T <: Integer} = randcycle!(r, Vector{T}(u randcycle(n::Integer) = randcycle(default_rng(), n) """ - randcycle!([rng=GLOBAL_RNG,] A::Array{<:Integer}) + randcycle!([rng=default_rng(),] A::Array{<:Integer}) Construct in `A` a random cyclic permutation of length `length(A)`. The optional `rng` argument specifies a random number generator, see diff --git a/stdlib/Random/src/normal.jl b/stdlib/Random/src/normal.jl index 6bb4cd2c36ce8..d7fe94f58fa57 100644 --- a/stdlib/Random/src/normal.jl +++ b/stdlib/Random/src/normal.jl @@ -10,7 +10,7 @@ ## randn """ - randn([rng=GLOBAL_RNG], [T=Float64], [dims...]) + randn([rng=default_rng()], [T=Float64], [dims...]) Generate a normally-distributed random number of type `T` with mean 0 and standard deviation 1. @@ -93,7 +93,7 @@ randn(rng::AbstractRNG, ::Type{Complex{T}}) where {T<:AbstractFloat} = ## randexp """ - randexp([rng=GLOBAL_RNG], [T=Float64], [dims...]) + randexp([rng=default_rng()], [T=Float64], [dims...]) Generate a random number of type `T` according to the exponential distribution with scale 1. @@ -141,7 +141,7 @@ end ## arrays & other scalar methods """ - randn!([rng=GLOBAL_RNG], A::AbstractArray) -> A + randn!([rng=default_rng()], A::AbstractArray) -> A Fill the array `A` with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the [`rand`](@ref) function. @@ -162,7 +162,7 @@ julia> randn!(rng, zeros(5)) function randn! end """ - randexp!([rng=GLOBAL_RNG], A::AbstractArray) -> A + randexp!([rng=default_rng()], A::AbstractArray) -> A Fill the array `A` with random numbers following the exponential distribution (with scale 1).