Random number generation in Julia uses the Mersenne Twister library via MersenneTwister
objects. Julia has a global RNG, which is used by default. Other RNG types can be plugged in by inheriting the AbstractRNG
type; they can then be used to have multiple streams of random numbers. Besides MersenneTwister
, Julia also provides the RandomDevice
RNG type, which is a wrapper over the OS provided entropy.
Most functions related to random generation accept an optional AbstractRNG
object as first argument, which defaults to the global one if not provided. Moreover, some of them accept optionally dimension specifications dims...
(which can be given as a tuple) to generate arrays of random values.
A MersenneTwister
or RandomDevice
RNG can generate uniformly random numbers of the following types: Float16
, Float32
, Float64
, BigFloat
, Bool
, Int8
, UInt8
, Int16
, UInt16
, Int32
, UInt32
, Int64
, UInt64
, Int128
, UInt128
, BigInt
(or complex numbers of those types). Random floating point numbers are generated uniformly in $[0, 1)$. As BigInt
represents unbounded integers, the interval must be specified (e.g. rand(big.(1:6))
).
Additionally, normal and exponential distributions are implemented for some AbstractFloat
and Complex
types, see randn
and randexp
for details.
Random.Random
Module
Random
Support for generating random numbers. Provides rand
, randn
, AbstractRNG
, MersenneTwister
, and RandomDevice
.
Base.rand
Function
rand([rng=GLOBAL_RNG], [S], [dims...])
Pick a random element or array of random elements from the set of values specified by S
; S
can be
1:9
or ('x', "y", :z)
),AbstractDict
or AbstractSet
object,typemin(S):typemax(S)
for integers (this is not applicable to BigInt
), and to $[0, 1)$ for floating point numbers;S
defaults to Float64
.
Support for S
as a tuple requires at least Julia 1.1.
Examples
julia> rand(Int, 2) 2-element Array{Int64,1}: 1339893410598768192 1575814717733606317 julia> using Random julia> rand(MersenneTwister(0), Dict(1=>2, 3=>4)) 1=>2
The complexity of rand(rng, s::Union{AbstractDict,AbstractSet})
is linear in the length of s
, unless an optimized method with constant complexity is available, which is the case for Dict
, Set
and BitSet
. For more than a few calls, use rand(rng, collect(s))
instead, or either rand(rng, Dict(s))
or rand(rng, Set(s))
as appropriate.
Random.rand!
Function
rand!([rng=GLOBAL_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
for details), the values are picked randomly from S
. This is equivalent to copyto!(A, rand(rng, S, size(A)))
but without allocating a new array.
Examples
julia> rng = MersenneTwister(1234); julia> rand!(rng, zeros(5)) 5-element Array{Float64,1}: 0.5908446386657102 0.7667970365022592 0.5662374165061859 0.4600853424625171 0.7940257103317943source
Random.bitrand
Function
bitrand([rng=GLOBAL_RNG], [dims...])
Generate a BitArray
of random boolean values.
Examples
julia> rng = MersenneTwister(1234); julia> bitrand(rng, 10) 10-element BitArray{1}: 0 1 1 1 1 0 1 0 0 1source
Base.randn
Function
randn([rng=GLOBAL_RNG], [T=Float64], [dims...])
Generate a normally-distributed random number of type T
with mean 0 and standard deviation 1. Optionally generate an array of normally-distributed random numbers. The Base
module currently provides an implementation for the types Float16
, Float32
, and Float64
(the default), and their Complex
counterparts. When the type argument is complex, the values are drawn from the circularly symmetric complex normal distribution.
Examples
julia> using Random julia> rng = MersenneTwister(1234); julia> randn(rng, ComplexF64) 0.6133070881429037 - 0.6376291670853887im julia> randn(rng, ComplexF32, (2, 3)) 2×3 Array{Complex{Float32},2}: -0.349649-0.638457im 0.376756-0.192146im -0.396334-0.0136413im 0.611224+1.56403im 0.355204-0.365563im 0.0905552+1.31012imsource
Random.randn!
Function
randn!([rng=GLOBAL_RNG], A::AbstractArray) -> A
Fill the array A
with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand
function.
Examples
julia> rng = MersenneTwister(1234); julia> randn!(rng, zeros(5)) 5-element Array{Float64,1}: 0.8673472019512456 -0.9017438158568171 -0.4944787535042339 -0.9029142938652416 0.8644013132535154source
Random.randexp
Function
randexp([rng=GLOBAL_RNG], [T=Float64], [dims...])
Generate a random number of type T
according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. The Base
module currently provides an implementation for the types Float16
, Float32
, and Float64
(the default).
Examples
julia> rng = MersenneTwister(1234); julia> randexp(rng, Float32) 2.4835055f0 julia> randexp(rng, 3, 3) 3×3 Array{Float64,2}: 1.5167 1.30652 0.344435 0.604436 2.78029 0.418516 0.695867 0.693292 0.643644source
Random.randexp!
Function
randexp!([rng=GLOBAL_RNG], A::AbstractArray) -> A
Fill the array A
with random numbers following the exponential distribution (with scale 1).
Examples
julia> rng = MersenneTwister(1234); julia> randexp!(rng, zeros(5)) 5-element Array{Float64,1}: 2.4835053723904896 1.516703605376473 0.6044364871025417 0.6958665886385867 1.3065196315496677source
Random.randstring
Function
randstring([rng=GLOBAL_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 and the digits 0-9. The optional rng
argument specifies a random number generator, see Random Numbers.
Examples
julia> Random.seed!(0); randstring() "0IPrGg0J" julia> randstring(MersenneTwister(0), 'a':'z', 6) "aszvqk" julia> randstring("ACGT") "TATCGGTC"
chars
can be any collection of characters, of type Char
or UInt8
(more efficient), provided rand
can randomly pick characters from it.
Random.randsubseq
Function
randsubseq([rng=GLOBAL_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 linear in p*length(A)
, so this function is efficient even if p
is small and A
is large.) Technically, this process is known as "Bernoulli sampling" of A
.
Examples
julia> rng = MersenneTwister(1234); julia> randsubseq(rng, collect(1:8), 0.3) 2-element Array{Int64,1}: 7 8source
Random.randsubseq!
Function
randsubseq!([rng=GLOBAL_RNG,] S, A, p)
Like randsubseq
, but the results are stored in S
(which is resized as needed).
Examples
julia> rng = MersenneTwister(1234); julia> S = Int64[]; julia> randsubseq!(rng, S, collect(1:8), 0.3); julia> S 2-element Array{Int64,1}: 7 8source
Random.randperm
Function
randperm([rng=GLOBAL_RNG,] n::Integer)
Construct a random permutation of length n
. The optional rng
argument specifies a random number generator (see Random Numbers). The element type of the result is the same as the type of n
.
To randomly permute an arbitrary vector, see shuffle
or shuffle!
.
In Julia 1.1 randperm
returns a vector v
with eltype(v) == typeof(n)
while in Julia 1.0 eltype(v) == Int
.
Examples
julia> randperm(MersenneTwister(1234), 4) 4-element Array{Int64,1}: 2 1 4 3source
Random.randperm!
Function
randperm!([rng=GLOBAL_RNG,] A::Array{<:Integer})
Construct in A
a random permutation of length length(A)
. The optional rng
argument specifies a random number generator (see Random Numbers). To randomly permute an arbitrary vector, see shuffle
or shuffle!
.
Examples
julia> randperm!(MersenneTwister(1234), Vector{Int}(undef, 4)) 4-element Array{Int64,1}: 2 1 4 3source
Random.randcycle
Function
randcycle([rng=GLOBAL_RNG,] n::Integer)
Construct a random cyclic permutation of length n
. The optional rng
argument specifies a random number generator, see Random Numbers. The element type of the result is the same as the type of n
.
In Julia 1.1 randcycle
returns a vector v
with eltype(v) == typeof(n)
while in Julia 1.0 eltype(v) == Int
.
Examples
julia> randcycle(MersenneTwister(1234), 6) 6-element Array{Int64,1}: 3 5 4 6 1 2source
Random.randcycle!
Function
randcycle!([rng=GLOBAL_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 Random Numbers.
Examples
julia> randcycle!(MersenneTwister(1234), Vector{Int}(undef, 6)) 6-element Array{Int64,1}: 3 5 4 6 1 2source
Random.shuffle
Function
shuffle([rng=GLOBAL_RNG,] v::AbstractArray)
Return a randomly permuted copy of v
. The optional rng
argument specifies a random number generator (see Random Numbers). To permute v
in-place, see shuffle!
. To obtain randomly permuted indices, see randperm
.
Examples
julia> rng = MersenneTwister(1234); julia> shuffle(rng, Vector(1:10)) 10-element Array{Int64,1}: 6 1 10 2 3 9 5 7 4 8source
Random.shuffle!
Function
shuffle!([rng=GLOBAL_RNG,] v::AbstractArray)
In-place version of shuffle
: randomly permute v
in-place, optionally supplying the random-number generator rng
.
Examples
julia> rng = MersenneTwister(1234); julia> shuffle!(rng, Vector(1:16)) 16-element Array{Int64,1}: 2 15 5 14 1 9 10 6 11 3 16 7 4 12 8 13source
Random.seed!
Function
seed!([rng=GLOBAL_RNG], seed) -> rng seed!([rng=GLOBAL_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 don't accept a seed, like RandomDevice
. After the call to seed!
, rng
is equivalent to a newly created object initialized with the same seed.
Examples
julia> Random.seed!(1234); julia> x1 = rand(2) 2-element Array{Float64,1}: 0.590845 0.766797 julia> Random.seed!(1234); julia> x2 = rand(2) 2-element Array{Float64,1}: 0.590845 0.766797 julia> x1 == x2 true julia> rng = MersenneTwister(1234); rand(rng, 2) == x1 true julia> MersenneTwister(1) == Random.seed!(rng, 1) true julia> rand(Random.seed!(rng), Bool) # not reproducible true julia> rand(Random.seed!(rng), Bool) false julia> rand(MersenneTwister(), Bool) # not reproducible either truesource
Random.AbstractRNG
Type
AbstractRNG
Supertype for random number generators such as MersenneTwister
and RandomDevice
.
Random.MersenneTwister
Type
MersenneTwister(seed) MersenneTwister()
Create a MersenneTwister
RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. The seed
may be a non-negative integer or a vector of UInt32
integers. If no seed is provided, a randomly generated one is created (using entropy from the system). See the seed!
function for reseeding an already existing MersenneTwister
object.
Examples
julia> rng = MersenneTwister(1234); julia> x1 = rand(rng, 2) 2-element Array{Float64,1}: 0.5908446386657102 0.7667970365022592 julia> rng = MersenneTwister(1234); julia> x2 = rand(rng, 2) 2-element Array{Float64,1}: 0.5908446386657102 0.7667970365022592 julia> x1 == x2 truesource
Random.RandomDevice
Type
RandomDevice()
Create a RandomDevice
RNG object. Two such objects will always generate different streams of random numbers. The entropy is obtained from the operating system.
Random
APIThere are two mostly orthogonal ways to extend Random
functionalities:
The API for 1) is quite functional, but is relatively recent so it may still have to evolve in subsequent releases of the Random
module. For example, it's typically sufficient to implement one rand
method in order to have all other usual methods work automatically.
The API for 2) is still rudimentary, and may require more work than strictly necessary from the implementor, in order to support usual types of generated values.
There are two categories: generating values from a type (e.g. rand(Int)
), or from a collection (e.g. rand(1:3)
). The simple cases are explained first, and more advanced usage is presented later. We assume here that the choice of algorithm is independent of the RNG, so we use AbstractRNG
in our signatures.
Given a type T
, it's currently assumed that if rand(T)
is defined, an object of type T
will be produced. In order to define random generation of values of type T
, the following method can be defined: rand(rng::AbstractRNG, ::Random.SamplerType{T})
(this should return what rand(rng, T)
is expected to return).
Let's take the following example: we implement a Die
type, with a variable number n
of sides, numbered from 1
to n
. We want rand(Die)
to produce a die with a random number of up to 20 sides (and at least 4):
struct Die nsides::Int # number of sides end Random.rand(rng::AbstractRNG, ::Random.SamplerType{Die}) = Die(rand(rng, 4:20)) # output
Scalar and array methods for Die
now work as expected:
julia> rand(Die) Die(18) julia> rand(MersenneTwister(0), Die) Die(4) julia> rand(Die, 3) 3-element Array{Die,1}: Die(6) Die(11) Die(5) julia> a = Vector{Die}(undef, 3); rand!(a) 3-element Array{Die,1}: Die(18) Die(6) Die(8)
Given a collection type S
, it's currently assumed that if rand(::S)
is defined, an object of type eltype(S)
will be produced. In order to define random generation out of objects of type S
, the following method can be defined: rand(rng::AbstractRNG, sp::Random.SamplerTrivial{S})
. Here, sp
simply wraps an object of type S
, which can be accessed via sp[]
. Continuing the Die
example, we want now to define rand(d::Die)
to produce an Int
corresponding to one of d
's sides:
julia> Random.rand(rng::AbstractRNG, d::Random.SamplerTrivial{Die}) = rand(rng, 1:d[].nsides); julia> rand(Die(4)) 3 julia> rand(Die(4), 3) 3-element Array{Any,1}: 3 4 2
In the last example, a Vector{Any}
is produced; the reason is that eltype(Die) == Any
. The remedy is to define Base.eltype(::Type{Die}) = Int
.
AbstractFloat
typeAbstractFloat
types are special-cased, because by default random values are not produced in the whole type domain, but rather in [0,1)
. The following method should be implemented for T <: AbstractFloat
: Random.rand(::AbstractRNG, ::Random.SamplerTrivial{Random.CloseOpen01{T}})
When repeatedly generating random values (with the same rand
parameters), it happens for some types that the result of a computation is used for each call. In this case, the computation can be decoupled from actually generating the values. This is the case for example with the default implementation for AbstractArray
. Assume that rand(rng, 1:20)
has to be called repeatedly in a loop: the way to take advantage of this decoupling is as follows:
rng = MersenneTwister() sp = Random.Sampler(rng, 1:20) # or Random.Sampler(MersenneTwister,1:20) for x in X n = rand(rng, sp) # similar to n = rand(rng, 1:20) # use n end
This mechanism is of course used by the default implementation of random array generation (like in rand(1:20, 10)
). In order to implement this decoupling for a custom type, a helper type can be used. Going back to our Die
example: rand(::Die)
uses random generation from a range, so there is an opportunity for this optimization:
import Random: Sampler, rand struct SamplerDie <: Sampler{Int} # generates values of type Int die::Die sp::Sampler{Int} # this is an abstract type, so this could be improved end Sampler(RNG::Type{<:AbstractRNG}, die::Die, r::Random.Repetition) = SamplerDie(die, Sampler(RNG, 1:die.nsides, r)) # the `r` parameter will be explained later on rand(rng::AbstractRNG, sp::SamplerDie) = rand(rng, sp.sp)
It's now possible to get a sampler with sp = Sampler(rng, die)
, and use sp
instead of die
in any rand
call involving rng
. In the simplistic example above, die
doesn't need to be stored in SamplerDie
but this is often the case in practice.
This pattern is so frequent that a helper type named Random.SamplerSimple
is available, saving us the definition of SamplerDie
: we could have implemented our decoupling with:
Sampler(RNG::Type{<:AbstractRNG}, die::Die, r::Random.Repetition) = SamplerSimple(die, Sampler(RNG, 1:die.nsides, r)) rand(rng::AbstractRNG, sp::SamplerSimple{Die}) = rand(rng, sp.data)
Here, sp.data
refers to the second parameter in the call to the SamplerSimple
constructor (in this case equal to Sampler(rng, 1:die.nsides, r)
), while the Die
object can be accessed via sp[]
.
Another helper type is currently available for other cases, Random.SamplerTag
, but is considered as internal API, and can break at any time without proper deprecations.
In some cases, whether one wants to generate only a handful of values or a large number of values will have an impact on the choice of algorithm. This is handled with the third parameter of the Sampler
constructor. Let's assume we defined two helper types for Die
, say SamplerDie1
which should be used to generate only few random values, and SamplerDieMany
for many values. We can use those types as follows:
Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{1}) = SamplerDie1(...) Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{Inf}) = SamplerDieMany(...)
Of course, rand
must also be defined on those types (i.e. rand(::AbstractRNG, ::SamplerDie1)
and rand(::AbstractRNG, ::SamplerDieMany)
).
Note: Sampler(rng, x)
is simply a shorthand for Sampler(rng, x, Val(Inf))
, and Random.Repetition
is an alias for Union{Val{1}, Val{Inf}}
.
The API is not clearly defined yet, but as a rule of thumb:
rand
method producing "basic" types (isbitstype
integer and floating types in Base
) should be defined for this specific RNG, if they are needed;rand
methods accepting an AbstractRNG
should work out of the box, (provided the methods from 1) what are relied on are implemented), but can of course be specialized for this RNG if there is room for optimization.Concerning 1), a rand
method may happen to work automatically, but it's not officially supported and may break without warnings in a subsequent release.
To define a new rand
method for an hypothetical MyRNG
generator, and a value specification s
(e.g. s == Int
, or s == 1:10
) of type S==typeof(s)
or S==Type{s}
if s
is a type, the same two methods as we saw before must be defined:
Sampler(::Type{MyRNG}, ::S, ::Repetition)
, which returns an object of type say SamplerS
rand(rng::MyRNG, sp::SamplerS)
It can happen that Sampler(rng::AbstractRNG, ::S, ::Repetition)
is already defined in the Random
module. It would then be possible to skip step 1) in practice (if one wants to specialize generation for this particular RNG type), but the corresponding SamplerS
type is considered as internal detail, and may be changed without warning.
In some cases, for a given RNG type, generating an array of random values can be more efficient with a specialized method than by merely using the decoupling technique explained before. This is for example the case for MersenneTwister
, which natively writes random values in an array.
To implement this specialization for MyRNG
and for a specification s
, producing elements of type S
, the following method can be defined: rand!(rng::MyRNG, a::AbstractArray{S}, ::SamplerS)
, where SamplerS
is the type of the sampler returned by Sampler(MyRNG, s, Val(Inf))
. Instead of AbstractArray
, it's possible to implement the functionality only for a subtype, e.g. Array{S}
. The non-mutating array method of rand
will automatically call this specialization internally.
© 2009–2019 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/v1.2.0/stdlib/Random/