Skip to content

Commit b297cc4

Browse files
authored
[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.
1 parent 19eb307 commit b297cc4

File tree

5 files changed

+32
-18
lines changed

5 files changed

+32
-18
lines changed

stdlib/Random/docs/src/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ Random.shuffle!
7070
## Generators (creation and seeding)
7171

7272
```@docs
73+
Random.default_rng
7374
Random.seed!
7475
Random.AbstractRNG
7576
Random.TaskLocalRNG

stdlib/Random/src/RNGs.jl

+13
Original file line numberDiff line numberDiff line change
@@ -355,6 +355,19 @@ end
355355
# GLOBAL_RNG currently uses TaskLocalRNG
356356
typeof_rng(::_GLOBAL_RNG) = TaskLocalRNG
357357

358+
"""
359+
default_rng() -> rng
360+
361+
Return the default global random number generator (RNG).
362+
363+
!!! note
364+
What the default RNG is is an implementation detail. Across different versions of
365+
Julia, you should not expect the default RNG to be always the same, nor that it will
366+
return the same stream of random numbers for a given seed.
367+
368+
!!! compat "Julia 1.3"
369+
This function was introduced in Julia 1.3.
370+
"""
358371
@inline default_rng() = TaskLocalRNG()
359372
@inline default_rng(tid::Int) = TaskLocalRNG()
360373

stdlib/Random/src/Random.jl

+4-4
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@ include("XoshiroSimd.jl")
307307
## rand & rand! & seed! docstrings
308308

309309
"""
310-
rand([rng=GLOBAL_RNG], [S], [dims...])
310+
rand([rng=default_rng()], [S], [dims...])
311311
312312
Pick a random element or array of random elements from the set of values specified by `S`;
313313
`S` can be
@@ -359,7 +359,7 @@ julia> rand(Float64, (2, 3))
359359
rand
360360

361361
"""
362-
rand!([rng=GLOBAL_RNG], A, [S=eltype(A)])
362+
rand!([rng=default_rng()], A, [S=eltype(A)])
363363
364364
Populate the array `A` with random values. If `S` is specified
365365
(`S` can be a type or a collection, cf. [`rand`](@ref) for details),
@@ -383,8 +383,8 @@ julia> rand!(rng, zeros(5))
383383
rand!
384384

385385
"""
386-
seed!([rng=GLOBAL_RNG], seed) -> rng
387-
seed!([rng=GLOBAL_RNG]) -> rng
386+
seed!([rng=default_rng()], seed) -> rng
387+
seed!([rng=default_rng()]) -> rng
388388
389389
Reseed the random number generator: `rng` will give a reproducible
390390
sequence of numbers if and only if a `seed` is provided. Some RNGs

stdlib/Random/src/misc.jl

+10-10
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ function rand!(rng::AbstractRNG, B::BitArray, ::SamplerType{Bool})
1111
end
1212

1313
"""
14-
bitrand([rng=GLOBAL_RNG], [dims...])
14+
bitrand([rng=default_rng()], [dims...])
1515
1616
Generate a `BitArray` of random boolean values.
1717
@@ -43,7 +43,7 @@ bitrand(dims::Integer...) = rand!(BitArray(undef, convert(Dims, dims)))
4343
## randstring (often useful for temporary filenames/dirnames)
4444

4545
"""
46-
randstring([rng=GLOBAL_RNG], [chars], [len=8])
46+
randstring([rng=default_rng()], [chars], [len=8])
4747
4848
Create a random string of length `len`, consisting of characters from
4949
`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
126126
end
127127

128128
"""
129-
randsubseq!([rng=GLOBAL_RNG,] S, A, p)
129+
randsubseq!([rng=default_rng(),] S, A, p)
130130
131131
Like [`randsubseq`](@ref), but the results are stored in `S`
132132
(which is resized as needed).
@@ -154,7 +154,7 @@ randsubseq(r::AbstractRNG, A::AbstractArray{T}, p::Real) where {T} =
154154
randsubseq!(r, T[], A, p)
155155

156156
"""
157-
randsubseq([rng=GLOBAL_RNG,] A, p) -> Vector
157+
randsubseq([rng=default_rng(),] A, p) -> Vector
158158
159159
Return a vector consisting of a random subsequence of the given array `A`, where each
160160
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(
182182
## shuffle & shuffle!
183183

184184
"""
185-
shuffle!([rng=GLOBAL_RNG,] v::AbstractArray)
185+
shuffle!([rng=default_rng(),] v::AbstractArray)
186186
187187
In-place version of [`shuffle`](@ref): randomly permute `v` in-place,
188188
optionally supplying the random-number generator `rng`.
@@ -228,7 +228,7 @@ end
228228
shuffle!(a::AbstractArray) = shuffle!(default_rng(), a)
229229

230230
"""
231-
shuffle([rng=GLOBAL_RNG,] v::AbstractArray)
231+
shuffle([rng=default_rng(),] v::AbstractArray)
232232
233233
Return a randomly permuted copy of `v`. The optional `rng` argument specifies a random
234234
number generator (see [Random Numbers](@ref)).
@@ -260,7 +260,7 @@ shuffle(a::AbstractArray) = shuffle(default_rng(), a)
260260
## randperm & randperm!
261261

262262
"""
263-
randperm([rng=GLOBAL_RNG,] n::Integer)
263+
randperm([rng=default_rng(),] n::Integer)
264264
265265
Construct a random permutation of length `n`. The optional `rng`
266266
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
288288
randperm(n::Integer) = randperm(default_rng(), n)
289289

290290
"""
291-
randperm!([rng=GLOBAL_RNG,] A::Array{<:Integer})
291+
randperm!([rng=default_rng(),] A::Array{<:Integer})
292292
293293
Construct in `A` a random permutation of length `length(A)`. The
294294
optional `rng` argument specifies a random number generator (see
@@ -328,7 +328,7 @@ randperm!(a::Array{<:Integer}) = randperm!(default_rng(), a)
328328
## randcycle & randcycle!
329329

330330
"""
331-
randcycle([rng=GLOBAL_RNG,] n::Integer)
331+
randcycle([rng=default_rng(),] n::Integer)
332332
333333
Construct a random cyclic permutation of length `n`. The optional `rng`
334334
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
354354
randcycle(n::Integer) = randcycle(default_rng(), n)
355355

356356
"""
357-
randcycle!([rng=GLOBAL_RNG,] A::Array{<:Integer})
357+
randcycle!([rng=default_rng(),] A::Array{<:Integer})
358358
359359
Construct in `A` a random cyclic permutation of length `length(A)`.
360360
The optional `rng` argument specifies a random number generator, see

stdlib/Random/src/normal.jl

+4-4
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
## randn
1111

1212
"""
13-
randn([rng=GLOBAL_RNG], [T=Float64], [dims...])
13+
randn([rng=default_rng()], [T=Float64], [dims...])
1414
1515
Generate a normally-distributed random number of type `T`
1616
with mean 0 and standard deviation 1.
@@ -93,7 +93,7 @@ randn(rng::AbstractRNG, ::Type{Complex{T}}) where {T<:AbstractFloat} =
9393
## randexp
9494

9595
"""
96-
randexp([rng=GLOBAL_RNG], [T=Float64], [dims...])
96+
randexp([rng=default_rng()], [T=Float64], [dims...])
9797
9898
Generate a random number of type `T` according to the
9999
exponential distribution with scale 1.
@@ -141,7 +141,7 @@ end
141141
## arrays & other scalar methods
142142

143143
"""
144-
randn!([rng=GLOBAL_RNG], A::AbstractArray) -> A
144+
randn!([rng=default_rng()], A::AbstractArray) -> A
145145
146146
Fill the array `A` with normally-distributed (mean 0, standard deviation 1) random numbers.
147147
Also see the [`rand`](@ref) function.
@@ -162,7 +162,7 @@ julia> randn!(rng, zeros(5))
162162
function randn! end
163163

164164
"""
165-
randexp!([rng=GLOBAL_RNG], A::AbstractArray) -> A
165+
randexp!([rng=default_rng()], A::AbstractArray) -> A
166166
167167
Fill the array `A` with random numbers following the exponential distribution
168168
(with scale 1).

0 commit comments

Comments
 (0)