std.random

乱数生成の機能を実装しています。旧形式の関数 rand_seed と rand は、グローバル状態を使っていてスレッド安全性など様々な問題を引き起こすため、すぐに非推奨となる予定です。

新形式の乱数生成器はそれぞれ自身の状態を保持したオブジェクトとなっているため、スレッドの問題とは無縁です。乱数生成器は、よく知られた様々な乱数生成方式によって実装されています。全体的に高速で信頼性の高い乱数生成法は "周期 2^19937 の Mersenne Twister " から名前をとった Mt19937 です。メモリの制約のきつい状況では、線形合同法による生成器 MinstdRand0 や MinstdRand が有用でしょう。標準ライブラリでは、alias Random を、ターゲット環境にもっとも合っていると思われる生成器の別名として提供しています。

Example:

// 範囲 [0, 14] に一様に分布する整数を生成
auto i = uniform(0, 15);
// 範囲 [0, 100) に一様に分布する実数を
// 指定の乱数ジェネレータを使って生成
Random gen;
auto r = uniform(0.0L, 100.0L, gen);

乱数生成器に加え、このモジュールでは、生成器の出力をさまざまな統計分布にしたがって変換する "分布（distribution）" オブジェクトを提供します。現在のところ、整数と実数の一様分布が実装されています。

Source:
std/random.d

License:
Boost License 1.0.

Authors:
Andrei Alexandrescu

Credits:
乱数ライブラリ全体の構成は、 Jens Maurer の提案であり Fermi laborartory の研究者の貢献からなる、素晴らしい C++0X の乱数機能を元にしています。

struct LinearCongruentialEngine(UIntType,UIntType a,UIntType c,UIntType m);

線形合同法による生成器

bool hasFixedRange;: この生成器の値域は固定か？ (固定ならば true)
UIntType min;: 生成されうる最小の値 (c == 0 ならば 1 で、それ以外ならば 0)
UIntType max;: 生成されうる最大の値 (modulus - 1).
UIntType multiplier; UIntType increment; UIntType modulus;: この分布のパラメタ。乱数は x = (x * multipler + increment) % modulus
this(UIntType x0);: LinearCongruentialEngine 生成器をシード x0 で構築
void seed(UIntType x0 = 1);: 生成器のシードを(再)設定。
void popFront();: 乱数列を一つ進めます。
UIntType front();: 現在の乱数値を返します。
typeof(this) save();
bool empty;: 常に false (乱数生成器は無限レンジです)
const bool opEquals(ref const LinearCongruentialEngine rhs);: rhs との等しさを判定します。

alias MinstdRand0; alias MinstdRand;

LinearCongruentialEngine を"良い"パラメタに設定した生成器です。 MinstdRand0 は Park と Miller の "minimal standard" generator を使用しており、multiplier として 16807 を採用します。MinstdRand は、multiplier として 48271 を採用することでわずかにベターなスペクトル検定結果を実現した変種です。どちらも非常に簡単すぎる乱数生成器です。

Example:

// 定数でシードを与える
auto rnd0 = MinstdRand0(1);
auto n = rnd0.front; // 実行によらず同じ値
// 予測不能値にシードを設定
rnd0.seed(unpredictableSeed);
n = rnd0.front; // 実行するたびに違う値

struct MersenneTwisterEngine(UIntType,size_t w,size_t n,size_t m,size_t r,UIntType a,size_t u,size_t s,UIntType b,size_t t,UIntType c,size_t l);

Mersenne Twister 生成器

size_t wordSize;: 生成器のパラメタ
UIntType min;: 生成されうる最小の値 (0)。
UIntType max;: 生成されうる最大の値。
UIntType defaultSeed;: デフォルトのシード
this(UIntType value);: MersenneTwisterEngine オブジェクトを構築します。
void seed(UIntType value = defaultSeed);: MersenneTwisterEngine オブジェクトにシードを設定します。
void popFront();: 乱数列を一つ進めます。
UIntType front();: 現在の乱数値を返します。
typeof(this) save();
bool empty;: 常に false.

alias Mt19937;

MersenneTwisterEngine を、オリジナルの実装 MT19937 と同じパラメタでインスタンス化したもの。一様分布した32bitの数値を、2の19937乗の周期で生成します。メモリが著しく制限されている場合でない限り（その場合は LinearCongruentialEngine を選択すべきでしょう）、お勧めの乱数生成エンジンです。

Example:

// 定数でシードを与える
Mt19937 gen;
auto n = gen.front; // 実行によらず同じ値
// 予測不能値にシードを設定
gen.seed(unpredictableSeed);
n = gen.front; // 実行するたびに違う値

uint unpredictableSeed();

乱数エンジンを初期化するための "良い" シードです。 unpredictableSeed でエンジンを初期化すると、実行のたびに違う乱数列を出力するようになります。

Example:

auto rnd = Random(unpredictableSeed);
auto n = rnd.front;
...

alias Random;

実行環境における "デフォルトの", "好ましい", "お勧めの" 乱数生成器です。上で定義された生成器のどれか１つのtypedefとなっています。 (1) なにかしら良い乱数生成器が必要で、しかも (2) 細かい実装方式は特に気にしない、という場合はこの型を使うと良いでしょう。

Random rndGen();

このモジュールの様々な関数で乱数ジェネレータを指定しなかった場合に使われる、デフォルトのグローバル乱数ジェネレータです。スレッド毎に別々に割り当てられ、各スレッドで別々の予測不能値で初期化されます。

CommonType!(T1,T2) uniform(string boundaries = "[)", T1, T2, UniformRandomNumberGenerator

aburng

外部の生成器を使って、区間内に一様分布する数値を生成します。引数 boundaries によって、区間の形式（両側が開区間か閉区間か）を制御します。boundaries に指定可能な値は "[]", "(]", "[)", "()" で、デフォルトは [a, b) です。

Example:

Random gen(unpredictableSeed);
// 区間 [0, 1023] 内の整数を生成
auto a = uniform(0, 1024, gen);
// 区間 [0, 1) 内のfloatを生成
auto a = uniform(0.0f, 1.0f, gen);

CommonType!(T1,T2) uniform(string boundaries = "[)", T1, T2

(T1 a, T2 b); )

上と同様ですが、rndGen をジェネレータとして使います

F[] uniformDistribution(F = double)(size_t n, F[] useThis = null);

サイズ n の、確率の一様分布を生成します。つまり、サイズ n で F の配列で、和が 1 となるようなものを生成します。 useThis が指定されていれば、そこにデータを書き込みます。

void randomShuffle(Range, RandomGen = Random)(Range r, ref RandomGen gen = rndGen);

r の要素を、gen からの乱数を使ってシャッフルします。r はlengthを持つランダムアクセスレンジである必要があります。

size_t dice(R, Num)(ref R rnd, Num[] proportions...);
size_t dice(R, Range)(ref R rnd, Range proportions);
size_t dice(Num)(Num[] proportions...);
size_t dice(Range)(Range proportions);

proportions に指定された確率で目がでるサイコロを振った結果を返します。返値は、配列 proportions のインデックスから選択されます。

Example:

auto x = dice(0.5, 0.5);   // x は等確率で 0 か 1
auto y = dice(50, 50);     // y は等確率で 0 か 1
auto z = dice(70, 20, 10); // z は 7 割の確率で 0、2割の確率で 1、
                           // 1割の確率で 2

struct RandomCover(Range,Random);
RandomCover!(Range,Random) randomCover(Range, Random)(Range r, Random rnd);

渡されたレンジ r をランダムにカバーするレンジです。つまり、r の要素全てをちょうど一度ずつ、ランダムに返すレンジになります。r にはlengthのとれるランダムアクセスレンジを指定して使用します。

Example:

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
auto rnd = Random(unpredictableSeed);
foreach (e; randomCover(a, rnd))
{
    writeln(e);
}

struct RandomSample(R);
RandomSample!(R) randomSample(R)(R r, size_t n, size_t total);
RandomSample!(R) randomSample(R)(R r, size_t n);

レンジ r から、ちょうど n 要素をランダムに取り出します。取り出す順番はオリジナルのレンジと同じです。 r の長さは事前にわかっている必要があります。total が渡された場合は長さは total であると見なし、そうでない場合は RandomSample では r.length を使います。

要素数がちょうど total ではなかった場合、RandomSample は例外を投げます。これは、 total が、レンジから要素を取得する確率を計算するのに本質的であるためです。

Example:

int[] a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ];
// rか5つランダムに取り出し
foreach (e; randomSample(n, 5))
{
    writeln(e);
}

this(R input, size_t howMany); this(R input, size_t howMany, size_t total);: コンストラクタ
const bool empty(); void popFront(); typeof(this) save(); size_t length();: レンジの基本関数
size_t index();: 返したエントリのインデックスを返します

void rand_seed(uint seed, uint index);

乱数生成ルーチンは、プログラムのスタート時にランダムな値で seedが与えられます。これにより、確実に、プログラムの起動毎に違う乱数列が生成されます。再現性のある乱数列を生成するには、 rand_seed() を呼んで乱数列の計算を始めて下さい。 seed と開始 index から始めて、一回乱数を得るごとに index が１増えていきます。これは、n 番目の乱数値は rand_seed() へ直接 index + n を渡せば得られることを意味します。

Note:
この関数は、Cのrand()よりもランダム性が高く、かわりに遅い関数です。 C の rand() を使うには、std.c.stdlib を import します。

BUGS:
単一のグローバル状態を共有しており、マルチスレッド非対応です。廃止予定です

deprecated uint rand();

乱数列中の次の乱数を得ます。

BUGS:
単一のグローバル状態を共有しており、マルチスレッド非対応です。廃止予定です