Random Numbers

Juliaでは、デフォルトでXoshiro256++アルゴリズムを使って乱数を生成し、状態はTaskごとに管理されます。AbstractRNG型を継承すれば、ほかのRNG型を組み込むこともでき、複数の乱数ストリームを生成できます。

RandomパッケージがエクスポートするPRNG(疑似乱数生成器)は次のとおりです。

  • TaskLocalRNG: 現在アクティブなタスクローカルのストリームを表すトークンです。親タスクから決定論的にシードされるか、プログラム開始時にRandomDevice(システム乱数を使用)によってシードされます。
  • Xoshiro: Xoshiro256++アルゴリズムを使い、小さな状態ベクトルと高い性能で、高品質な乱数ストリームを生成します。
  • RandomDevice: OSが提供するエントロピーを使います。暗号学的に安全な乱数(CS(P)RNG)に利用できます。
  • MersenneTwister: 以前のJuliaでデフォルトだった、もう一つの高品質なPRNGです。かなり高速ですが、状態ベクトルの保存と乱数列の生成に、より多くの領域を必要とします。

乱数生成に関係するほとんどの関数は、最初の引数として省略可能なAbstractRNGオブジェクトを受け取ります。また、乱数値の配列を生成するために、次元指定dims...(タプルで指定することもできます)を受け取る関数もあります。マルチスレッドプログラムでは、スレッドセーフにするため、通常はスレッドやタスクごとに異なるRNGオブジェクトを使ってください。ただし、Julia 1.3以降、デフォルトのRNGはスレッドセーフです(1.6まではスレッドごと、それ以降はタスクごとのRNGを使用します)。

用意されているRNGは、次の型の一様乱数を生成できます: Float16、Float32、Float64、BigFloat、Bool、Int8、UInt8、Int16、UInt16、Int32、UInt32、Int64、UInt64、Int128、UInt128、BigInt(またはこれらの型の複素数)。浮動小数点の乱数は$[0, 1)$上で一様に生成されます。BigIntは上限のない整数を表すため、区間を指定する必要があります(例: rand(big.(1:6)))。

さらに、一部のAbstractFloat型およびComplex型では、正規分布と指数分布が実装されています。詳しくはrandnおよびrandexpを参照してください。

ほかの分布から乱数を生成するには、Distributions.jlパッケージを参照してください。

Warning

乱数の生成方法の詳細は実装上の仕様とみなされるため、バージョン変更後には、バグ修正や高速化によって生成される乱数ストリームが変わることがあります。そのため、単体テストで特定のシードや生成された乱数ストリームに依存することは推奨されません。代わりに、対象のメソッドが満たすべき性質をテストしてください。

Random numbers module

Random generation functions

Base.rand — Function
rand([rng=default_rng()], [S], [dims...])

Sで指定された値の集合から、ランダムな要素を1つ、またはランダムな要素の配列を選びます。Sには、次のいずれかを指定できます。

  • インデックスでアクセスできるコレクション(例:1:9または('x', "y", :z))

  • AbstractDictまたはAbstractSetオブジェクト

  • 文字列(文字のコレクションとして扱われます)

  • 以下の型。指定した値の集合に対応します。

    • 具象整数型の場合、typemin(S):typemax(S)からサンプリングします(ただし、サポートされていないBigIntを除きます)。
    • 具象浮動小数点型の場合、[0, 1)からサンプリングします。
    • 具象複素数型Complex{T}の場合、Tがサンプリング可能な型であれば、実部と虚部をそれぞれTに対応する値の集合から独立に選びます。Tがサンプリング可能でない場合はサポートされません。
    • すべての<:AbstractChar型の場合、有効なUnicodeスカラー値の集合からサンプリングします。
    • ユーザー定義型と値の集合。実装方法についてはHooking into the Random APIを参照してください。
    • サイズが既知で、Sの各パラメーターがサンプリング可能な型であるタプル型。この場合、S型の値を返します。Tuple{Vararg{T}}(サイズ不明)やTuple{1:2}(値でパラメーター化されている)などのタプル型はサポートされません。
    • Pair型(例:Pair{X, Y})。Xに対してrandとYが定義されている場合、ランダムなペアが生成されます。

Sのデフォルト値はFloat64です。省略可能なrng以外に引数が1つだけ渡され、それがTupleの場合、その引数はdimsではなく、値のコレクション(S)として解釈されます。

正規分布に従う数値についてはrandnを、インプレースで操作する関数についてはrand!およびrandn!を参照してください。

Julia 1.1

タプルとしてのSのサポートには、Julia 1.1以降が必要です。

Julia 1.11

Tuple型としてのSのサポートには、Julia 1.11以降が必要です。

Examples

julia> rand(Int, 2)
2-element Vector{Int64}:
 1339893410598768192
 1575814717733606317

julia> using Random

julia> rand(Xoshiro(0), Dict(1=>2, 3=>4))
3 => 4

julia> rand((2, 3))
3

julia> rand(Float64, (2, 3))
2×3 Matrix{Float64}:
 0.999717  0.0143835  0.540787
 0.696556  0.783855   0.938235
Note

rand(rng, s::Union{AbstractDict,AbstractSet})の計算量は、sの長さに対して線形です。ただし、定数時間で実行できる最適化済みメソッドがある場合はこの限りではありません。該当するのはDict、Set、および密なBitSetです。呼び出しが数回を超える場合は、代わりにrand(rng, collect(s))を使用するか、用途に応じてrand(rng, Dict(s))またはrand(rng, Set(s))を使用してください。

source
Random.rand! — Function
rand!([rng=default_rng()], A, [S=eltype(A)])

配列 A にランダムな値を設定します。S が指定されている場合(S には型またはコレクションを指定できます。詳細は rand を参照)、値は S からランダムに選ばれます。これは、新しい配列を割り当てずに copyto!(A, rand(rng, S, size(A))) を実行するのと同等です。

Examples

julia> rand!(Xoshiro(123), zeros(5))
5-element Vector{Float64}:
 0.521213795535383
 0.5868067574533484
 0.8908786980927811
 0.19090669902576285
 0.5256623915420473
source
Random.bitrand — Function
bitrand([rng=default_rng()], [dims...])

ランダムな真偽値のBitArrayを生成します。

Examples

julia> bitrand(Xoshiro(123), 10)
10-element BitVector:
 0
 1
 0
 1
 0
 1
 0
 0
 1
 1
source
Base.randn — Function
randn([rng=default_rng()], [T=Float64], [dims...])

平均 0、標準偏差 1 の正規分布に従う T 型の乱数を生成します。省略可能な dims 引数を指定すると、サイズ dims の配列に、同じ分布に従う乱数を生成します。Julia の標準ライブラリでは、rand を実装する任意の浮動小数点型に対して randn をサポートしています。たとえば、Base 型の Float16、Float32(デフォルト)、Float64、BigFloat、およびそれらに対応する Complex が該当します。

(T が複素数の場合、分散 1 の円対称複素正規分布から値が生成されます。この分布では、実部と虚部は独立で、平均 0、分散 1/2 の正規分布に従います。)

インプレースで処理するには randn! も参照してください。

Examples

単一の乱数を生成する場合(デフォルトの Float64 型):

julia> randn()
-0.942481877315864

正規分布に従う乱数の行列を生成する場合(デフォルトの Float64 型):

julia> randn(2,3)
2×3 Matrix{Float64}:
  1.18786   -0.678616   1.49463
 -0.342792  -0.134299  -1.45005

再現可能な乱数を得るため、ユーザー定義のシードで乱数生成器 rng を初期化し、それを使って Float32 型の乱数、または ComplexF32 型の乱数行列を生成します。

julia> using Random

julia> rng = Xoshiro(123);

julia> randn(rng, Float32)
-0.6457307f0

julia> randn(rng, ComplexF32, (2, 3))
2×3 Matrix{ComplexF32}:
  -1.03467-1.14806im  0.693657+0.056538im   0.291442+0.419454im
 -0.153912+0.34807im    1.0954-0.948661im  -0.543347-0.0538589im
source
Random.randn! — Function
randn!([rng=default_rng()], A::AbstractArray) -> A

配列 A を、正規分布(平均 0、標準偏差 1)に従う乱数で埋めます。rand 関数も参照してください。

Examples

julia> randn!(Xoshiro(123), zeros(5))
5-element Vector{Float64}:
 -0.6457306721039767
 -1.4632513788889214
 -1.6236037455860806
 -0.21766510678354617
  0.4922456865251828
source
Random.randexp — Function
randexp([rng=default_rng()], [T=Float64], [dims...])

指数分布(スケール 1)に従う T 型の乱数を生成します。必要に応じて、そのような乱数の配列も生成できます。現在、Base モジュールは、Float16、Float32、および Float64(デフォルト)の各型に対する実装を提供しています。

Examples

julia> rng = Xoshiro(123);

julia> randexp(rng, Float32)
1.1757717f0

julia> randexp(rng, 3, 3)
3×3 Matrix{Float64}:
 1.37766  0.456653  0.236418
 3.40007  0.229917  0.0684921
 0.48096  0.577481  0.71835
source
Random.randexp! — Function
randexp!([rng=default_rng()], A::AbstractArray) -> A

配列 A を、尺度パラメーターが 1 の指数分布に従う乱数で埋めます。

Examples

julia> randexp!(Xoshiro(123), zeros(5))
5-element Vector{Float64}:
 1.1757716836348473
 1.758884569451514
 1.0083623637301151
 0.3510644315565272
 0.6348266443720407
source
Random.randstring — Function
randstring([rng=default_rng()], [chars], [len=8])

len の長さで、chars の文字からなるランダムな文字列を生成します。デフォルトでは、大文字と小文字のアルファベットおよび数字 0~9 が使われます。省略可能な引数 rng では乱数生成器を指定します。詳しくは Random Numbers を参照してください。

Examples

julia> Random.seed!(3); randstring()
"Lxz5hUwn"

julia> randstring(Xoshiro(3), 'a':'z', 6)
"iyzcsm"

julia> randstring("ACGT")
"TGCTCCTC"
Note

chars には、rand がそこから文字をランダムに選べるものであれば、Char 型または UInt8 型(より効率的)の任意の文字コレクションを指定できます。

source

Subsequences, permutations and shuffling

Random.randsubseq — Function
randsubseq([rng=default_rng(),] A, p) -> Vector

与えられた配列 A のランダムな部分列を返します。A の各要素は、独立に確率 p で(順序を保って)含まれます。(計算量は p*length(A) に対して線形なので、p が小さく、A が大きい場合でも効率的です。)厳密には、この処理は A の「ベルヌーイサンプリング」と呼ばれます。

Examples

julia> randsubseq(Xoshiro(123), 1:8, 0.3)
2-element Vector{Int64}:
 4
 7
source
Random.randsubseq! — Function
randsubseq!([rng=default_rng(),] S, A, p)

randsubseqと同様ですが、結果は必要に応じてサイズが変更されるSに格納されます。

Examples

julia> S = Int64[];

julia> randsubseq!(Xoshiro(123), S, 1:8, 0.3)
2-element Vector{Int64}:
 4
 7

julia> S
2-element Vector{Int64}:
 4
 7
source
Random.randperm — Function
randperm([rng=default_rng(),] n::Integer)

長さがnのランダムな順列を生成します。省略可能なrng引数では、乱数生成器を指定します(Random Numbersを参照)。結果の要素型はnの型と同じです。

任意のベクトルをランダムに並べ替えるには、shuffleまたはshuffle!を参照してください。

Julia 1.1

Julia 1.1では、randpermはeltype(v) == typeof(n)を持つベクトルvを返しますが、Julia 1.0ではeltype(v) == Intです。

Examples

julia> randperm(Xoshiro(0), 6)
6-element Vector{Int64}:
 5
 1
 2
 6
 3
 4
source
Random.randperm! — Function
randperm!([rng=default_rng(),] A::AbstractArray{<:Integer})

Aで、長さlength(A)のランダムな順列を生成します。省略可能なrng引数では、乱数生成器を指定します(Random Numbersを参照)。任意のベクトルをランダムに並べ替える方法については、shuffleまたはshuffle!を参照してください。

Julia 1.13

Julia v1.13より前では、A isa Arrayが必須でした。

Examples

julia> randperm!(Xoshiro(0), Vector{Int}(undef, 6))
6-element Vector{Int64}:
 5
 1
 2
 6
 3
 4
source
Random.randcycle — Function
randcycle([rng=default_rng(),] n::Integer)

長さ n のランダムな巡回置換を構築します。省略可能な引数 rng には乱数生成器を指定します。詳細は Random Numbers を参照してください。戻り値の要素型は n の型と同じです。

ここで「巡回置換」とは、すべての要素が単一の巡回に含まれる置換を指します。n > 0 の場合、巡回置換は $(n-1)!$ 通りあり、いずれも一様に抽出されます。n == 0 の場合、randcycle は空のベクトルを返します。

randcycle! は、この関数のインプレース版です。

Julia 1.1

Julia 1.1 以降では、randcycle は eltype(v) == typeof(n) を持つベクトル v を返しますが、Julia 1.0 では eltype(v) == Int です。

Examples

julia> randcycle(Xoshiro(0), 6)
6-element Vector{Int64}:
 5
 1
 4
 6
 3
 2
source
Random.randcycle! — Function
randcycle!([rng=default_rng(),] A::AbstractArray{<:Integer})

A 内に、長さ n = length(A) のランダムな巡回置換を構成します。省略可能な rng 引数には乱数生成器を指定します。詳細は Random Numbers を参照してください。

ここで「巡回置換」とは、すべての要素が単一の巡回に含まれる置換を指します。A が空でない場合(n > 0)、可能な巡回置換は $(n-1)!$ 通りあり、その中から一様にサンプリングされます。A が空の場合、randcycle! は変更を加えません。

randcycle は、この関数の新しいベクトルを割り当てるバリアントです。

Julia 1.13

Julia v1.13 より前は A isa Array が必要でした。

Examples

julia> randcycle!(Xoshiro(0), Vector{Int}(undef, 6))
6-element Vector{Int64}:
 5
 1
 4
 6
 3
 2
source
Random.shuffle — Function
shuffle([rng=default_rng(),] v::Union{NTuple,AbstractArray})

v の要素をランダムに並べ替えたコピーを返します。省略可能な rng 引数では、乱数生成器を指定します(Random Numbers を参照)。v をインプレースで並べ替える方法については、shuffle! を参照してください。ランダムに並べ替えたインデックスを取得する方法については、randperm を参照してください。

Julia 1.13

NTuple の値をシャッフルするには、Julia v1.13 以降が必要です。

Examples

julia> shuffle(Xoshiro(0), 1:6)
6-element Vector{Int64}:
 5
 1
 2
 6
 3
 4
source
Random.shuffle! — Function
shuffle!([rng=default_rng(),] v::AbstractArray)

shuffleのインプレース版です。vをランダムに並べ替えます。必要に応じて、乱数生成器rngを指定できます。

Examples

julia> shuffle!(Xoshiro(0), Vector(1:6))
6-element Vector{Int64}:
 5
 1
 2
 6
 3
 4
source

Generators (creation and seeding)

Random.default_rng — Function
Random.default_rng() -> rng

明示的な RNG が指定されていない場合に、rand 関連の関数で使用される、デフォルトのグローバル乱数生成器(RNG)を返します。

Random モジュールが読み込まれると、デフォルトの RNG は Random.seed!() を介してランダムにシードされます。つまり、seed!(seed) が先に呼び出されない限り、新しい Julia セッションを開始するたびに、rand() の最初の呼び出しで異なる結果が生成されます。

スレッドセーフです。異なるスレッドから、default_rng() に対して rand 関連の関数を同時に安全に呼び出せます(例:rand(default_rng()))。

Note

デフォルト RNG の型は実装の詳細です。Julia のバージョンが異なる場合、デフォルト RNG の型が常に同じであることや、同じシードに対して同じ乱数列が生成されることは期待できません。

Julia 1.3

この関数は Julia 1.3 で導入されました。

source
Random.seed! — Function
seed!([rng=default_rng()], seed) -> rng
seed!([rng=default_rng()]) -> rng

乱数生成器を再シードします。rngは、seedが指定されている場合に限り、再現可能な数列を生成します。RandomDeviceのように、シードを受け付けないRNGもあります。seed!を呼び出した後のrngは、同じシードで初期化した新しいオブジェクトと同等です。

受け付けるシードの型はrngの型によって異なりますが、一般に整数のシードを使用できます。シードにnothingを指定した場合、シードを指定しない場合と同等です。

rngを指定しない場合、共有タスクローカルジェネレーターの状態をシードする設定が既定で使用されます。

Examples

julia> Random.seed!(1234);

julia> x1 = rand(2)
2-element Vector{Float64}:
 0.32597672886359486
 0.5490511363155669

julia> Random.seed!(1234);

julia> x2 = rand(2)
2-element Vector{Float64}:
 0.32597672886359486
 0.5490511363155669

julia> x1 == x2
true

julia> rng = Xoshiro(1234); rand(rng, 2) == x1
true

julia> Xoshiro(1) == Random.seed!(rng, 1)
true

julia> rand(Random.seed!(rng), Bool) # not reproducible
true

julia> rand(Random.seed!(rng), Bool) # not reproducible either
false

julia> rand(Xoshiro(), Bool) # not reproducible either
true
source
Random.TaskLocalRNG — Type
TaskLocalRNG

TaskLocalRNGの状態はスレッドではなくタスクに属します。タスクの作成時に親タスクの状態を引き継いで初期化されますが、親タスクのRNGの状態は進みません。

利点として、TaskLocalRNGは非常に高速で、(競合状態がない限り)スケジューラの判断に左右されず、再現可能なマルチスレッドシミュレーションを実行できます。タスクの作成時にスレッド数を判断材料として使わなければ、シミュレーション結果は利用可能なスレッド数やCPU数にも左右されません。エンディアンや、場合によってはワードサイズを除き、乱数ストリームはハードウェアの仕様に依存しないはずです。

TaskLocalRNG()をseed!でシードする場合、渡すシードは(指定するなら)任意の整数にできます。

Julia 1.11

TaskLocalRNG()に負の整数シードを指定するには、Julia 1.11以降が必要です。

Julia 1.10

Julia 1.10以降では、タスクの作成によって親タスクのRNGの状態が進むことはありません。

source
Random.Xoshiro — Type
Xoshiro(seed::Union{Integer, AbstractString})
Xoshiro()

Xoshiro256++ は、David Blackman と Sebastiano Vigna による論文「Scrambled Linear Pseudorandom Number Generators」(ACM Trans. Math. Softw., 2021)で解説されている高速な擬似乱数生成器です。参照実装は https://prng.di.unimi.it で入手できます。

Xoshiro は高速であるだけでなく、メモリ使用量も少ないため、多数の異なる乱数生成状態を長期間保持する必要がある用途に適しています。

Julia の Xoshiro 実装には一括生成モードがあります。このモードでは、親の PRNG から新たな仮想 PRNG のシードを生成し、SIMD を使って並列に乱数を生成します(つまり、一括生成されるストリームは、複数の xoshiro インスタンスの出力を交互に組み合わせたものです)。仮想 PRNG は一括生成の要求を処理し終えると破棄されます(また、ヒープ割り当ては発生しないはずです)。

シードを指定しない場合は、システムから得たエントロピーを使ってランダムなシードを生成します。既存の Xoshiro オブジェクトにシードを再設定する方法については、seed! 関数を参照してください。

Julia 1.11

負の整数をシードとして渡すには、Julia 1.11 以降が必要です。

Examples

julia> using Random

julia> rng = Xoshiro(1234);

julia> x1 = rand(rng, 2)
2-element Vector{Float64}:
 0.32597672886359486
 0.5490511363155669

julia> rng = Xoshiro(1234);

julia> x2 = rand(rng, 2)
2-element Vector{Float64}:
 0.32597672886359486
 0.5490511363155669

julia> x1 == x2
true
source
Random.MersenneTwister — Type
MersenneTwister(seed)
MersenneTwister()

MersenneTwister オブジェクトを作成します。RNG オブジェクトごとに異なるシードを設定できるため、異なる乱数列を生成する場合に便利です。seed には、整数、文字列、または UInt32 整数のベクトルを指定できます。シードを指定しない場合は、システムのエントロピーを使ってランダムに生成されます。既存の MersenneTwister オブジェクトにシードを設定し直す方法については、seed! 関数を参照してください。

Julia 1.11

負の整数シードを渡すには、Julia 1.11 以降が必要です。

Examples

julia> rng = MersenneTwister(123);

julia> x1 = rand(rng, 2)
2-element Vector{Float64}:
 0.37453777969575874
 0.8735343642013971

julia> x2 = rand(MersenneTwister(123), 2)
2-element Vector{Float64}:
 0.37453777969575874
 0.8735343642013971

julia> x1 == x2
true
source
Random.RandomDevice — Type
RandomDevice()

RandomDevice RNG オブジェクトを作成します。このようなオブジェクトを2つ作成すると、必ず異なる乱数列が生成されます。エントロピーはオペレーティングシステムから取得されます。

source

Hooking into the Random API

Randomの機能を拡張する方法は、大きく分けて次の2つあります。

  1. 独自の型の乱数値を生成する
  2. 新しい生成器を作成する

1)のAPIはかなり実用的ですが、比較的新しいため、今後のRandomモジュールのリリースで変更される可能性があります。たとえば、通常使われるほかのメソッドを自動的に動作させるには、通常randメソッドを1つ実装するだけで十分です。

2)のAPIはまだ初歩的で、一般的な型の値を生成できるようにするには、実装者が必要以上の作業を求められる場合があります。

Generating random values of custom types

分布から乱数値を生成する際には、さまざまなトレードオフが生じることがあります。離散分布のalias tableや、1変量分布の“squeezing” functionsのように、値を事前計算しておくと、サンプリングを大幅に高速化できます。どの程度の情報を事前計算するかは、その分布から生成する値の個数によって変わります。また、乱数生成器によっては、アルゴリズムが利用できる特性を備えている場合もあります。

Randomモジュールは、こうした問題に対応するため、カスタマイズ可能な乱数値取得の仕組みを定義しています。randを呼び出すたびにサンプラーが生成されます。このサンプラーは、上記のトレードオフを考慮してカスタマイズできます。具体的には、Samplerにメソッドを追加します。このメソッドは、乱数生成器、分布を特徴づけるオブジェクト、繰り返し回数の目安に応じてディスパッチされます。現在、繰り返し回数の目安には、1回のサンプルを表すVal{1}と、任意の回数を表すVal{Inf}が使われます。Random.Repetitionはその両方の別名です。

Samplerが返すオブジェクトを使って、乱数値を生成します。サンプリング可能な値Xの乱数生成インターフェースを実装する場合は、次のメソッドを定義してください。

rand(rng, sampler)

これは、Sampler(rng, X, repetition)が返す特定のsamplerに対して定義します。

サンプラーには、rand(rng, sampler)を実装する任意の値を使えますが、多くの用途では、次の定義済みサンプラーで十分です。

  1. SamplerType{T}()は、型T(例: rand(Int))から値を取り出すサンプラーの実装に使えます。これは、型に対してSamplerが返すデフォルト値です。
  2. SamplerTrivial(self)は、selfを単純にラップするものです。[]でアクセスできます。事前計算が不要な場合(例: rand(1:3))に推奨されるサンプラーであり、値に対してSamplerが返すデフォルト値です。
  3. SamplerSimple(self, data)には、追加のフィールドdataもあります。このフィールドには任意の事前計算値を格納でき、その値はSamplerのカスタムメソッドで計算します。

それぞれの例を示します。ここでは、アルゴリズムの選択はRNGに依存しないものとし、シグネチャにはAbstractRNGを使います。

Random.Sampler — Type
Sampler(rng, x, repetition = Val(Inf))

rngからxを生成するために使用できるサンプラーオブジェクトを返します。

sp = Sampler(rng, x, repetition)の場合、ランダム値の生成にはrand(rng, sp)が使用されるため、それに応じて定義する必要があります。

repetitionにはVal(1)またはVal(Inf)を指定できます。該当する場合は、事前計算の量を決める際の目安として使用してください。

Random.SamplerTypeとRandom.SamplerTrivialは、それぞれ型と値のデフォルトのフォールバックです。Random.SamplerSimpleを使えば、この目的だけのために追加の型を定義せずに、事前計算した値を格納できます。

source
Random.SamplerType — Type
SamplerType{T}()

型を対象とするサンプラーで、ほかの情報は含みません。型を指定して呼び出した場合のSamplerのデフォルトのフォールバックです。

source
Random.SamplerTrivial — Type
SamplerTrivial(x)

与えられた値 x をそのままラップするサンプラーを作成します。これは値に対するデフォルトのフォールバックです。このサンプラーの eltype は eltype(x) と等しくなります。

推奨される用途は、事前計算されたデータがない値からサンプリングすることです。

source
Random.SamplerSimple — Type
SamplerSimple(x, data)

指定した値 x と data をラップするサンプラーを作成します。このサンプラーの eltype は eltype(x) と等しくなります。

事前計算済みのデータを持つ値からサンプリングする場合に、この方法を使うことを推奨します。

source

事前計算と実際の値の生成を分離することはAPIの一部であり、ユーザーも利用できます。たとえば、ループ内でrand(rng, 1:20)を繰り返し呼び出す場合、この分離を活用するには次のようにします。

rng = Xoshiro()
sp = Random.Sampler(rng, 1:20) # or Random.Sampler(Xoshiro, 1:20)
for x in X
    n = rand(rng, sp) # similar to n = rand(rng, 1:20)
    # use n
end

これは標準ライブラリでも使われている仕組みです。たとえば、乱数配列生成のデフォルト実装(rand(1:20, 10)など)で利用されています。

Generating values from a type

型Tについては、rand(T)が定義されていれば、型Tのオブジェクトが生成されるものと、現在は想定されています。SamplerTypeは型に対するデフォルトのサンプラーです。型Tの値を生成するには、rand(rng::AbstractRNG, ::Random.SamplerType{T})メソッドを定義し、rand(rng, T)が返すことを期待される値を返すようにします。

例として、面の数nが可変で、1からnまでの番号が付いたDie型を実装します。rand(Die)で、面が4つ以上20個以下のDieをランダムに生成したいとします。

struct Die
    nsides::Int # number of sides
end

Random.rand(rng::AbstractRNG, ::Random.SamplerType{Die}) = Die(rand(rng, 4:20))

# output

これで、Dieのスカラー用および配列用メソッドが期待どおりに動作します。

julia> rand(Die)
Die(5)

julia> rand(Xoshiro(0), Die)
Die(10)

julia> rand(Die, 3)
3-element Vector{Die}:
 Die(9)
 Die(15)
 Die(14)

julia> a = Vector{Die}(undef, 3); rand!(a)
3-element Vector{Die}:
 Die(19)
 Die(7)
 Die(17)

A simple sampler without pre-computed data

ここでは、コレクション用のサンプラーを定義します。事前計算データが不要なら、SamplerTrivialサンプラーで実装できます。これは実際には、値に対するデフォルトのフォールバックです。

型Sのオブジェクトから乱数を生成するには、次のメソッドを定義します: rand(rng::AbstractRNG, sp::Random.SamplerTrivial{S})。ここでspは、型Sのオブジェクトを単純にラップしており、sp[]からアクセスできます。先ほどのDieの例を続けて、今度はrand(d::Die)が、Intを生成するようにします。これはdの面のいずれかに対応します。

julia> Random.rand(rng::AbstractRNG, d::Random.SamplerTrivial{Die}) = rand(rng, 1:d[].nsides);

julia> rand(Die(4))
1

julia> rand(Die(4), 3)
3-element Vector{Any}:
 2
 3
 3

コレクション型Sについては、rand(::S)が定義されていれば、型eltype(S)のオブジェクトが生成されるものと、現在は想定されています。直前の例ではVector{Any}が生成されます。これはeltype(Die) == Anyが理由です。これを解決するには、Base.eltype(::Type{Die}) = Intを定義します。

Generating values for an AbstractFloat type

AbstractFloat型は特別扱いされます。デフォルトでは、型の値域全体ではなく、[0,1)から乱数値が生成されるためです。T <: AbstractFloatに対して、次のメソッドを実装してください: Random.rand(::AbstractRNG, ::Random.SamplerTrivial{Random.CloseOpen01{T}})

An optimized sampler with pre-computed data

離散分布を考えます。数値1:nが、合計が1になる所定の確率で選ばれます。この分布から多数の値を得る場合、最速の方法はalias tableを使うことです。ここでは、そのテーブルを構築するアルゴリズムは示しませんが、代わりにmake_alias_table(probabilities)で利用できるものとし、draw_number(rng, alias_table)でそこから乱数を取り出せるとします。

分布が次のように記述されるとします。

struct DiscreteDistribution{V <: AbstractVector}
    probabilities::V
end

また、必要な値の個数にかかわらず、常にエイリアステーブルを構築したいとします(この後、カスタマイズ方法を説明します)。次のメソッドを定義して、

Random.eltype(::Type{<:DiscreteDistribution}) = Int

function Random.Sampler(::Type{<:AbstractRNG}, distribution::DiscreteDistribution, ::Repetition)
    SamplerSimple(distribution, make_alias_table(distribution.probabilities))
end

事前計算データを持つサンプラーを返すようにします。その後、

function rand(rng::AbstractRNG, sp::SamplerSimple{<:DiscreteDistribution})
    draw_number(rng, sp.data)
end

を使って値を取り出します。

Custom sampler types

事前計算データを扱う用途のほとんどでは、SamplerSimple型で十分です。ただし、独自のサンプラー型の使い方を示すため、ここではSamplerSimpleに似たものを実装します。

先ほどのDieの例に戻ります。rand(::Die)は範囲から乱数を生成するため、この最適化を適用できます。独自のサンプラーをSamplerDieと名付けます。

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)

これで、sp = Sampler(rng, die)を使ってサンプラーを取得し、rngを含む任意のrand呼び出しで、dieの代わりにspを使えます。上の単純な例では、dieをSamplerDieに格納する必要はありませんが、実際にはそうすることがよくあります。

もちろん、このパターンは非常によく使われるため、上で使ったヘルパー型Random.SamplerSimpleが用意されています。これを使えば、SamplerDieを定義する必要はありません。次のようにして、事前計算と生成を分離できます。

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)

ここでsp.dataは、SamplerSimpleコンストラクターの呼び出しにおける2番目のパラメーター(この場合はSampler(rng, 1:die.nsides, r))を指します。Dieオブジェクトには、sp[]からアクセスできます。

SamplerDieと同様に、独自のサンプラーはすべてSampler{T}のサブタイプでなければなりません。ここでTは生成される値の型です。SamplerSimple(x, data) isa Sampler{eltype(x)}であるため、SamplerSimpleの第1引数に指定できる型には制約があります(Dieの例のように、SamplerSimpleを使うことを推奨します。この例では、xをそのまま転送しながらSamplerメソッドを定義しています)。同様に、SamplerTrivial(x) isa Sampler{eltype(x)}です。

ほかのケース向けには、Random.SamplerTagというヘルパー型も用意されています。ただし、これは内部APIとみなされており、適切な非推奨化の手続きを経ずにいつでも変更される可能性があります。

Using distinct algorithms for scalar or array generation

生成する値が少数か多数かによって、アルゴリズムの選択が変わる場合があります。これはSamplerコンストラクターの第3パラメーターで扱います。Die用に、少数の乱数値の生成に使うSamplerDie1と、多数の値の生成に使うSamplerDieManyという2つのヘルパー型を定義したとします。これらの型は次のように使えます。

Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{1}) = SamplerDie1(...)
Sampler(RNG::Type{<:AbstractRNG}, die::Die, ::Val{Inf}) = SamplerDieMany(...)

もちろん、これらの型に対してもrandを定義する必要があります(つまり、rand(::AbstractRNG, ::SamplerDie1)とrand(::AbstractRNG, ::SamplerDieMany)です)。通常どおり、独自の型が不要ならSamplerTrivialとSamplerSimpleを使えます。

注: Sampler(rng, x)はSampler(rng, x, Val(Inf))の略記であり、Random.RepetitionはUnion{Val{1}, Val{Inf}}の別名です。

Creating new generators

APIはまだ明確に定義されていませんが、目安として次の点に従ってください。

  1. 「基本」型(Baseにおけるisbitstype整数型および浮動小数点型)を生成するrandメソッドは、必要に応じて、このRNG専用に定義してください。
  2. AbstractRNGを受け取る、ドキュメント化されたほかのrandメソッドは、1)で依存するメソッドが実装されていれば、そのまま動作するはずです。ただし、最適化の余地があれば、このRNG向けに特化してもかまいません。
  3. 疑似RNGに対するcopyは、呼び出し時点から元のRNGとまったく同じ乱数列を、同じ方法で生成する独立したコピーを返す必要があります。これが実現できない場合(ハードウェアベースのRNGなど)は、copyを実装してはいけません。

1)については、randメソッドが偶然そのまま動作する場合もありますが、公式にはサポートされていません。今後のリリースで警告なく動作しなくなる可能性があります。

仮想的なMyRNG生成器に対する新しいrandメソッドと、値指定s(例: s == Intまたはs == 1:10)を定義するには、sが型の場合、型S==typeof(s)またはS==Type{s}に対して、先ほどと同じ2つのメソッドを定義する必要があります。

  1. Sampler(::Type{MyRNG}, ::S, ::Repetition)。たとえば、型SamplerSのオブジェクトを返します。
  2. rand(rng::MyRNG, sp::SamplerS)

Sampler(rng::AbstractRNG, ::S, ::Repetition)が、すでにRandomモジュールで定義されている場合もあります。その場合、実際には手順1)を省略して(この特定のRNG型向けに生成を特化したい場合)、対応するSamplerS型を使うこともできます。ただし、この型は内部実装の詳細とみなされており、予告なく変更される可能性があります。

Specializing array generation

RNG型によっては、事前計算と生成の分離を使うより、専用メソッドで乱数配列を生成するほうが効率的な場合があります。たとえばMersenneTwisterは、配列に乱数値を直接書き込みます。

MyRNGと指定sに対してこの特化を実装し、型Sの要素を生成するには、次のメソッドを定義できます: rand!(rng::MyRNG, a::AbstractArray{S}, ::SamplerS)。ここでSamplerSは、Sampler(MyRNG, s, Val(Inf))が返すサンプラーの型です。AbstractArrayではなく、そのサブタイプ(例: Array{S})に対してのみ機能を実装することもできます。randの非変更配列メソッドは、内部でこの特化メソッドを自動的に呼び出します。

Reproducibility

指定したシードで初期化したRNGを使えば、プログラムを複数回実行しても同じ疑似乱数列を再現できます。ただし、Juliaのマイナーリリース(例: 1.3から1.4)によって、特定のシードから生成される疑似乱数列が変わることがあります。(randのような低レベル関数が生成する列に変更がなくても、アルゴリズムの更新によって、randsubseqのような高レベル関数の出力が変わる場合があります。)その理由は、疑似乱数ストリームが決して変わらないことを保証すると、アルゴリズムの改善が大きく制限されるためです。

乱数データの完全な再現性を保証する必要がある場合は、データをそのまま保存することをお勧めします(例: 科学論文の補足資料として添付する)。もちろん、ビット単位の再現性が必要なら、特定のJuliaバージョンとパッケージマニフェストを指定する方法もあります。

特定の「乱数」データに依存するソフトウェアテストでは、通常、データを保存するか、テストコードに埋め込むか、StableRNGs.jlのようなサードパーティパッケージを使ってください。一方、ほとんどの乱数データで成功すべきテスト(例: ランダム行列A = randn(n,n)に対するA \ (A*x) ≈ xのテスト)では、固定シードのRNGを使うと、テストを何度も実行した際に、極めて起こりにくいデータ(たとえば、非常に悪条件な行列)が原因で失敗するのを防げます。

乱数サンプルが従う統計的な分布は、Juliaのどのマイナーリリース間でも同じであることが保証されています。