随机数

    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: , Float32, , BigFloat, , Int8, , Int16, , Int32, , Int64, , Int128, , 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 and randexp for details.

    — Function.

    Pick a random element or array of random elements from the set of values specified by S; S can be

    • an indexable collection (for example 1:n or ['x','y','z']),
    • an AbstractDict or AbstractSet object,
    • a string (considered as a collection of characters), or
    • a type: the set of values to pick from is then equivalent to typemin(S):typemax(S) for integers (this is not applicable to BigInt), and to $[0, 1)$ for floating point numbers;S defaults to (except when dims is a tuple of integers, in which case S must be specified).

    Examples

    1. julia> rand(Int, 2)
    2. 2-element Array{Int64,1}:
    3.  1339893410598768192
    4.  1575814717733606317
    6. julia> rand(MersenneTwister(0), Dict(1=>2, 3=>4))
    7. 1=>2

    Note

    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.

    1. 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. 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

    1. julia> rng = MersenneTwister(1234);
    3. julia> rand!(rng, zeros(5))
    4. 5-element Array{Float64,1}:
    5.  0.5908446386657102
    6.  0.7667970365022592
    7.  0.5662374165061859
    8.  0.4600853424625171
    9.  0.7940257103317943

    Random.bitrand — Function.

    1. bitrand([rng=GLOBAL_RNG], [dims...])

    Generate a BitArray of random boolean values.

    Examples

    1. julia> rng = MersenneTwister(1234);
    3. julia> bitrand(rng, 10)
    4. 10-element BitArray{1}:
    5.  false
    6.   true
    7.   true
    8.   true
    9.   true
    10.  false
    11.   true
    12.  false
    13.  false
    14.   true

    — Function.

    1. 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, , and Float64 (the default), and their counterparts. When the type argument is complex, the values are drawn from the circularly symmetric complex normal distribution.

    Examples

    1. julia> rng = MersenneTwister(1234);
    3. julia> randn(rng, ComplexF64)
    4. 0.6133070881429037 - 0.6376291670853887im
    6. julia> randn(rng, ComplexF32, (2, 3))
    7. 2×3 Array{Complex{Float32},2}:
    8.  -0.349649-0.638457im  0.376756-0.192146im  -0.396334-0.0136413im
    9.   0.611224+1.56403im   0.355204-0.365563im  0.0905552+1.31012im

    Random.randn! — Function.

    1. randn!([rng=GLOBAL_RNG], A::AbstractArray) -> A

    Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the function.

    Examples

    1. julia> rng = MersenneTwister(1234);
    3. julia> randn!(rng, zeros(5))
    4. 5-element Array{Float64,1}:
    5.   0.8673472019512456
    6.  -0.9017438158568171
    7.  -0.4944787535042339
    8.  -0.9029142938652416
    9.   0.8644013132535154

    Random.randexp — Function.

    1. 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 , Float32, and (the default).

    Examples

    1. julia> rng = MersenneTwister(1234);
    3. julia> randexp(rng, Float32)
    4. 2.4835055f0
    6. julia> randexp(rng, 3, 3)
    7. 3×3 Array{Float64,2}:
    8.  1.5167    1.30652   0.344435
    9.  0.604436  2.78029   0.418516
    10.  0.695867  0.693292  0.643644

    Random.randexp! — Function.

    1. randexp!([rng=GLOBAL_RNG], A::AbstractArray) -> A

    Fill the array A with random numbers following the exponential distribution (with scale 1).

    Examples

    1. julia> rng = MersenneTwister(1234);
    3. julia> randexp!(rng, zeros(5))
    4. 5-element Array{Float64,1}:
    5.  2.4835053723904896
    6.  1.516703605376473
    7.  0.6044364871025417
    8.  0.6958665886385867
    9.  1.3065196315496677

    — Function.

    Examples

    1. julia> Random.seed!(0); randstring()
    2. "0IPrGg0J"
    4. julia> randstring(MersenneTwister(0), 'a':'z', 6)
    5. "aszvqk"
    7. julia> randstring("ACGT")
    8. "TATCGGTC"

    Note

    chars can be any collection of characters, of type Char or UInt8 (more efficient), provided rand can randomly pick characters from it.

    — Function.

      Return a vector consisting of a random subsequence of the given array A, where each element of 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

      1. julia> rng = MersenneTwister(1234);
      3. julia> randsubseq(rng, collect(1:8), 0.3)
      4. 2-element Array{Int64,1}:
      5.  7
      6.  8

      Random.randsubseq! — Function.

      1. randsubseq!([rng=GLOBAL_RNG,] S, A, p)

      Like , but the results are stored in S (which is resized as needed).

      Examples

      1. julia> rng = MersenneTwister(1234);
      3. julia> S = Int64[];
      5. julia> randsubseq!(rng, S, collect(1:8), 0.3);
      7. julia> S
      8. 2-element Array{Int64,1}:
      9.  7
      10.  8

      Random.randperm — Function.

      1. randperm([rng=GLOBAL_RNG,] n::Integer)

      Construct a random permutation of length n. The optional rng argument specifies a random number generator (see ). To randomly permute an arbitrary vector, see shuffle or .

      Examples

      1. julia> randperm(MersenneTwister(1234), 4)
      2. 4-element Array{Int64,1}:
      3.  2
      4.  1
      5.  4
      6.  3

      Random.randperm! — Function.

      1. 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 ). To randomly permute an arbitrary vector, see shuffle or .

      Examples

      1. julia> randperm!(MersenneTwister(1234), Vector{Int}(undef, 4))
      2. 4-element Array{Int64,1}:
      3.  2
      4.  1
      5.  4
      6.  3

      Random.randcycle — Function.

      1. randcycle([rng=GLOBAL_RNG,] n::Integer)

      Construct a random cyclic permutation of length n. The optional rng argument specifies a random number generator, see .

      Examples

      1. julia> randcycle(MersenneTwister(1234), 6)
      2. 6-element Array{Int64,1}:
      3.  3
      4.  5
      5.  4
      6.  6
      7.  1
      8.  2

      Random.randcycle! — Function.

      1. 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 .

      Examples

      1. julia> randcycle!(MersenneTwister(1234), Vector{Int}(undef, 6))
      2. 6-element Array{Int64,1}:
      3.  3
      4.  5
      5.  4
      6.  6
      7.  1
      8.  2

      Random.shuffle — Function.

      Return a randomly permuted copy of v. The optional rng argument specifies a random number generator (see ). To permute v in-place, see shuffle!. To obtain randomly permuted indices, see .

      Examples

      1. julia> rng = MersenneTwister(1234);
      3. julia> shuffle(rng, Vector(1:10))
      4. 10-element Array{Int64,1}:
      5.   6
      6.   1
      7.  10
      8.   2
      9.   3
      10.   9
      11.   5
      12.   7
      13.   4
      14.   8

      Random.shuffle! — Function.

      1. shuffle!([rng=GLOBAL_RNG,] v::AbstractArray)

      In-place version of : randomly permute v in-place, optionally supplying the random-number generator rng.

      Examples

      1. julia> rng = MersenneTwister(1234);
      3. julia> shuffle!(rng, Vector(1:16))
      4. 16-element Array{Int64,1}:
      5.   2
      6.  15
      7.   5
      8.  14
      9.   1
      10.   9
      11.  10
      12.   6
      13.  11
      14.   3
      15.  16
      16.   7
      17.   4
      18.  12
      19.   8
      20.  13
      1. seed!([rng=GLOBAL_RNG], seed) -> rng
      2. 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

      1. julia> Random.seed!(1234);
      3. julia> x1 = rand(2)
      4. 2-element Array{Float64,1}:
      5.  0.590845
      6.  0.766797
      8. julia> Random.seed!(1234);
      10. julia> x2 = rand(2)
      11. 2-element Array{Float64,1}:
      12.  0.766797
      14. julia> x1 == x2
      15. true
      17. julia> rng = MersenneTwister(1234); rand(rng, 2) == x1
      18. true
      20. julia> MersenneTwister(1) == Random.seed!(rng, 1)
      21. true
      23. julia> rand(Random.seed!(rng), Bool) # not reproducible
      24. true
      26. julia> rand(Random.seed!(rng), Bool)
      27. false
      29. julia> rand(MersenneTwister(), Bool) # not reproducible either
      30. true

      Random.MersenneTwister — Type.

      1. MersenneTwister(seed)
      2. 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 function for reseeding an already existing MersenneTwister object.

      Examples

      1. julia> rng = MersenneTwister(1234);
      4. 2-element Array{Float64,1}:
      5.  0.5908446386657102
      6.  0.7667970365022592
      8. julia> rng = MersenneTwister(1234);
      10. julia> x2 = rand(rng, 2)
      11. 2-element Array{Float64,1}:
      12.  0.5908446386657102
      13.  0.7667970365022592
      15. julia> x1 == x2
      16. true

      Random.RandomDevice — Type.

      1. 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.

      There are two mostly orthogonal ways to extend Random functionalities:

      • generating random values of custom types
      • creating new generatorsThe 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.

      Generating values from a type

      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):

      1. struct Die
      2.     nsides::Int # number of sides
      3. end
      5. Random.rand(rng::AbstractRNG, ::Random.SamplerType{Die}) = Die(rand(rng, 4:20))
      7. # output

      Die 的标量和数组方法现在可以正常工作了：

      1. julia> rand(Die)
      2. Die(18)
      4. julia> rand(MersenneTwister(0), Die)
      5. Die(4)
      7. julia> rand(Die, 3)
      8. 3-element Array{Die,1}:
      9.  Die(6)
      10.  Die(11)
      11.  Die(5)
      13. julia> a = Vector{Die}(undef, 3); rand!(a)
      14. 3-element Array{Die,1}:
      15.  Die(18)
      16.  Die(6)
      17.  Die(8)

      Generating values from a collection

      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:

      1. julia> Random.rand(rng::AbstractRNG, d::Random.SamplerTrivial{Die}) = rand(rng, 1:d[].nsides);
      3. julia> rand(Die(4))
      4. 3
      6. julia> rand(Die(4), 3)
      7. 3-element Array{Any,1}:
      8.  3
      9.  4
      10.  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.

      Generating values for an AbstractFloat type

      AbstractFloat 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}})

      Optimizing generation with cached computation between calls

      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:

      1. rng = MersenneTwister()
      2. sp = Random.Sampler(rng, 1:20) # or Random.Sampler(MersenneTwister,1:20)
      3. for x in X
      4.     n = rand(rng, sp) # similar to n = rand(rng, 1:20)
      5.     # use n
      6. 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:

      1. import Random: Sampler, rand
      3. struct SamplerDie <: Sampler{Int} # generates values of type Int
      4.     die::Die
      5.     sp::Sampler{Int} # this is an abstract type, so this could be improved
      6. end
      8. Sampler(RNG::Type{<:AbstractRNG}, die::Die, r::Random.Repetition) =
      9.     SamplerDie(die, Sampler(RNG, 1:die.nsides, r))
      10. # the `r` parameter will be explained later on
      12. 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:

      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.

      Using distinct algorithms for scalar or array generation

      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:

      1. Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{1}) = SamplerDie1(...)
      2. 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}}.

      Creating new generators

      The API is not clearly defined yet, but as a rule of thumb:

      • any rand method producing "basic" types (isbitstype integer and floating types in Base) should be defined for this specific RNG, if they are needed;
      • other documented 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

      Specializing array generation

      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.