random.h 文件参考

伪随机数发生器与常用分布。 更多...

#include "lmmc/config.h"
#include "lmmc/status.h"
#include <stddef.h>
#include <stdint.h>

random.h 的引用(Include)关系图:

此图展示该文件被哪些文件直接或间接地引用了:

浏览该文件的源代码.

函数
lmmc_status_t	lmmc_rng_create (lmmc_rng_t **out_rng)
	创建随机数发生器实例。
lmmc_status_t	lmmc_rng_seed (lmmc_rng_t *rng, uint64_t seed)
	重新设定种子。
void	lmmc_rng_destroy (lmmc_rng_t *rng)
	销毁发生器，释放内部分配的所有内存。
lmmc_status_t	lmmc_rng_clone (const lmmc_rng_t *src, lmmc_rng_t **out_rng)
	深拷贝 RNG 状态。
lmmc_status_t	lmmc_rng_jump (lmmc_rng_t *rng)
	将 RNG 状态前进 2^128 步（xoshiro256** jump 多项式）。
lmmc_status_t	lmmc_rng_long_jump (lmmc_rng_t *rng)
	将 RNG 状态前进 2^192 步（xoshiro256** long_jump 多项式）。
uint64_t	lmmc_rng_next_u64 (lmmc_rng_t *rng)
	直接获取下一个 64 位均匀整数。
lmmc_status_t	lmmc_rng_uniform (lmmc_rng_t *rng, lmmc_real_t a, lmmc_real_t b, lmmc_real_t *out_value)
	实数分布参数的公共约束。
lmmc_status_t	lmmc_rng_normal (lmmc_rng_t *rng, lmmc_real_t mean, lmmc_real_t stddev, lmmc_real_t *out_value)
	生成正态分布 \(\mathcal{N}(\mu, \sigma^2)\) 样本。
lmmc_status_t	lmmc_rng_exponential (lmmc_rng_t *rng, lmmc_real_t rate, lmmc_real_t *out_value)
	生成参数为 rate 的指数分布样本。
lmmc_status_t	lmmc_rng_fill_uniform (lmmc_rng_t *rng, lmmc_real_t a, lmmc_real_t b, lmmc_real_t *array, size_t count)
	批量填充均匀分布样本到 array 。
lmmc_status_t	lmmc_rng_shuffle (lmmc_rng_t *rng, void *array, size_t count, size_t elem_size)
	Fisher-Yates 洗牌：就地随机重排 array 中的 count 个元素。 每次 Fisher-Yates 选择均使用无偏的拒绝采样。
lmmc_status_t	lmmc_rng_gamma (lmmc_rng_t *rng, lmmc_real_t shape, lmmc_real_t scale, lmmc_real_t *out)
	生成 Gamma 分布样本 \(\mathrm{Gamma}(\alpha, \beta)\) 。
lmmc_status_t	lmmc_rng_beta (lmmc_rng_t *rng, lmmc_real_t alpha, lmmc_real_t beta_param, lmmc_real_t *out)
	生成 Beta 分布样本 Beta(alpha, beta)。
lmmc_status_t	lmmc_rng_chi_squared (lmmc_rng_t *rng, lmmc_real_t df, lmmc_real_t *out)
	生成卡方分布样本 Chi-squared(df)。
lmmc_status_t	lmmc_rng_student_t (lmmc_rng_t *rng, lmmc_real_t df, lmmc_real_t *out)
	生成 Student-t 分布样本 t(df)。
lmmc_status_t	lmmc_rng_f (lmmc_rng_t *rng, lmmc_real_t df1, lmmc_real_t df2, lmmc_real_t *out)
	生成 F 分布样本 F(df1, df2)。
lmmc_status_t	lmmc_rng_poisson (lmmc_rng_t *rng, lmmc_real_t lambda, size_t *out)
	生成 Poisson 分布样本 \(\mathrm{Poisson}(\lambda)\) 。
lmmc_status_t	lmmc_rng_binomial (lmmc_rng_t *rng, size_t n, lmmc_real_t p, size_t *out)
	生成二项分布样本 Binomial(n, p)。
lmmc_status_t	lmmc_rng_int_uniform (lmmc_rng_t *rng, int64_t lo, int64_t hi, int64_t *out)
	在 [lo, hi] 闭区间内生成无偏均匀整数分布样本。

详细描述

伪随机数发生器与常用分布。

内部使用线程不安全的 PCG/xoshiro 类生成器（不透明实现）， 调用方应为每个线程独立创建 lmmc_rng_t 。

在文件 random.h 中定义.

函数说明

lmmc_rng_create()

lmmc_status_t lmmc_rng_create

(

lmmc_rng_t **

out_rng

)

创建随机数发生器实例。

分配并初始化一个 xoshiro256** 发生器。句柄由调用方拥有，默认 线程受限；跨线程传递或并发访问必须由调用方同步。并行工作负载应为 每个线程创建独立句柄，或使用 lmmc_rng_clone 和 ::lmmc_rng_jump。

参数

[out]

out_rng

输出新创建的 RNG 句柄。

返回

LMMC_STATUS_OK 成功； LMMC_STATUS_INVALID_ARGUMENT 若 out_rng 为 NULL； LMMC_STATUS_ALLOCATION_FAILED 若内存分配失败。

副作用

• 分配堆内存存储 RNG 内部状态，调用方必须调用 lmmc_rng_destroy 释放。

将平台熵混入默认种子,为各随机数发生器建立独立数据流.

在文件 random.c 第 76 行定义.

引用了 lmmc_memory_alloc(), lmmc_rng_create(), lmmc_rng_seed(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT , 以及 LMMC_STATUS_OK.

被这些函数引用 lmmc_rng_create().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_seed()

lmmc_status_t lmmc_rng_seed	(	lmmc_rng_t *	rng,
		uint64_t	seed )

重新设定种子。

在文件 random.c 第 96 行定义.

引用了 lmmc_rng_seed(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_create(), lmmc_rng_default_get(), lmmc_rng_seed() , 以及 lmmc_std_random_seed().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_destroy()

void lmmc_rng_destroy

(

lmmc_rng_t *

rng

)

销毁发生器，释放内部分配的所有内存。

在文件 random.c 第 112 行定义.

引用了 lmmc_memory_free(), lmmc_rng_destroy() , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_destroy().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_clone()

lmmc_status_t lmmc_rng_clone	(	const lmmc_rng_t *	src,
		lmmc_rng_t **	out_rng )

深拷贝 RNG 状态。

调用方可对副本调用 lmmc_rng_jump 以获得独立的并行流。

参数

[in]	src	源 RNG（不可为 NULL）。
[out]	out_rng	输出新分配的 RNG 副本。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 src 或 out_rng 为 NULL。

副作用

• 分配堆内存存储副本状态，调用方必须调用 lmmc_rng_destroy 释放。

在文件 random.c 第 120 行定义.

引用了 lmmc_memory_alloc(), lmmc_rng_clone(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_clone().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_jump()

lmmc_status_t lmmc_rng_jump

(

lmmc_rng_t *

rng

)

将 RNG 状态前进 2^128 步（xoshiro256** jump 多项式）。

用于将一个 RNG 流拆分为多个不重叠的子流。

参数

[in,out]

rng

已初始化的 RNG（不可为 NULL）。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 rng 为 NULL。

副作用

• 就地修改 rng 的内部状态。

在文件 random.c 第 190 行定义.

引用了 lmmc_rng_jump(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_jump().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_long_jump()

lmmc_status_t lmmc_rng_long_jump

(

lmmc_rng_t *

rng

)

将 RNG 状态前进 2^192 步（xoshiro256** long_jump 多项式）。

用于在更大尺度上拆分并行流。

参数

[in,out]

rng

已初始化的 RNG（不可为 NULL）。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 rng 为 NULL。

副作用

• 就地修改 rng 的内部状态。

在文件 random.c 第 200 行定义.

引用了 lmmc_rng_long_jump(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_long_jump().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_next_u64()

uint64_t lmmc_rng_next_u64

(

lmmc_rng_t *

rng

)

直接获取下一个 64 位均匀整数。

在文件 random.c 第 210 行定义.

引用了 lmmc_rng_next_u64() , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_next_u64().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_uniform()

lmmc_status_t lmmc_rng_uniform	(	lmmc_rng_t *	rng,
		lmmc_real_t	a,
		lmmc_real_t	b,
		lmmc_real_t *	out_value )

实数分布参数的公共约束。

所有实数参数必须有限；尺度、形状、速率和自由度参数还必须为正数。 违反约束时返回 LMMC_STATUS_INVALID_ARGUMENT，且不会进入拒绝采样循环。

在 \([a,b)\) 区间内生成均匀分布样本。

使用防溢出的仿射插值；有限端点即使跨越完整 double 范围也不会因 计算 b-a 而产生无穷值。

在文件 random.c 第 220 行定义.

引用了 lmmc_rng_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_uniform() , 以及 lmmc_std_random_rand().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_normal()

lmmc_status_t lmmc_rng_normal	(	lmmc_rng_t *	rng,
		lmmc_real_t	mean,
		lmmc_real_t	stddev,
		lmmc_real_t *	out_value )

生成正态分布 \(\mathcal{N}(\mu, \sigma^2)\) 样本。

使用 Box-Muller 或 Ziggurat 方法生成标准正态样本后进行仿射变换。

参数

[in]	rng	已初始化的 RNG。
[in]	mean	均值 \(\mu\) 。
[in]	stddev	标准差 \(\sigma\) ，必须 > 0。
[out]	out_value	输出样本值。

返回

LMMC_STATUS_OK 成功； LMMC_STATUS_INVALID_ARGUMENT 若参数非有限、stddev <= 0 或指针为 NULL。

副作用

• 就地修改 rng 的内部状态（消耗随机数）。
• 不分配堆内存。

在文件 random_normal.c 第 93 行定义.

引用了 lmmc_rng_normal(), lmmc_rng_standard_normal(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_normal() , 以及 lmmc_std_random_normal().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_exponential()

lmmc_status_t lmmc_rng_exponential	(	lmmc_rng_t *	rng,
		lmmc_real_t	rate,
		lmmc_real_t *	out_value )

生成参数为 rate 的指数分布样本。

在文件 random.c 第 240 行定义.

引用了 lmmc_rng_exponential(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_exponential().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_fill_uniform()

lmmc_status_t lmmc_rng_fill_uniform	(	lmmc_rng_t *	rng,
		lmmc_real_t	a,
		lmmc_real_t	b,
		lmmc_real_t *	array,
		size_t	count )

批量填充均匀分布样本到 array 。

在文件 random.c 第 263 行定义.

引用了 lmmc_rng_fill_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_fill_uniform().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_shuffle()

lmmc_status_t lmmc_rng_shuffle	(	lmmc_rng_t *	rng,
		void *	array,
		size_t	count,
		size_t	elem_size )

Fisher-Yates 洗牌：就地随机重排 array 中的 count 个元素。 每次 Fisher-Yates 选择均使用无偏的拒绝采样。

参数

[in]	rng	已初始化的 RNG。
[in,out]	array	待洗牌的数组，就地重排。
[in]	count	元素个数。
[in]	elem_size	每个元素的字节大小。

副作用

• 就地修改 array 中元素的顺序。
• 就地修改 rng 的内部状态。

在文件 random.c 第 288 行定义.

引用了 lmmc_memory_alloc(), lmmc_memory_free(), lmmc_rng_shuffle(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_shuffle().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_gamma()

lmmc_status_t lmmc_rng_gamma	(	lmmc_rng_t *	rng,
		lmmc_real_t	shape,
		lmmc_real_t	scale,
		lmmc_real_t *	out )

生成 Gamma 分布样本 \(\mathrm{Gamma}(\alpha, \beta)\) 。

使用 Marsaglia-Tsang 方法（shape >= 1），shape < 1 时使用 \(X = Y \cdot U^{1/\alpha}\) 变换法（Y ~ Gamma(1+α, β)）。

参数

[in]	rng	已初始化的 RNG。
[in]	shape	形状参数 \(\alpha\) （> 0）。
[in]	scale	尺度参数 \(\beta\) （> 0）。
[out]	out	输出样本值。

返回

LMMC_STATUS_OK 成功； LMMC_STATUS_INVALID_ARGUMENT 若参数非有限、shape <= 0、 scale <= 0 或指针为 NULL。

副作用

• 就地修改 rng 的内部状态（消耗多个随机数，次数不确定）。
• 不分配堆内存。

shape < 1 时采用采样恒等式 Gamma(shape) = Gamma(shape+1) * U^(1/shape)。

shape >= 1 时使用 Marsaglia-Tsang 法。

以挤压界快速判定接受。

按完整接受条件判定候选值。

在文件 random_continuous.c 第 4 行定义.

引用了 lmmc_rng_gamma(), lmmc_rng_standard_normal(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_chi_squared() , 以及 lmmc_rng_gamma().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_beta()

lmmc_status_t lmmc_rng_beta	(	lmmc_rng_t *	rng,
		lmmc_real_t	alpha,
		lmmc_real_t	beta_param,
		lmmc_real_t *	out )

生成 Beta 分布样本 Beta(alpha, beta)。

参数

[in]	rng	已初始化的 RNG。
[in]	alpha	参数 alpha（> 0）。
[in]	beta_param	参数 beta（> 0）。
[out]	out	[0,1] 内的有限样本，仅成功时写入。 对数 Gamma 比例支持极小形状参数；舍入或下溢可产生端点 0/1。

返回

LMMC_STATUS_OK 表示成功；LMMC_STATUS_INVALID_ARGUMENT 表示空指针 或非有限、非正形状参数，此时 RNG 保持原状态； LMMC_STATUS_NUMERICAL_FAILURE 表示中间数值无效； LMMC_STATUS_CONVERGENCE_FAILED 表示排除均匀随机数零端点的尝试次数耗尽。

注解

采样失败时 RNG 状态可能已推进。

在文件 random_continuous.c 第 117 行定义.

引用了 lmmc_rng_beta(), LMMC_STATUS_INVALID_ARGUMENT , 以及 LMMC_STATUS_OK.

被这些函数引用 lmmc_rng_beta().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_chi_squared()

lmmc_status_t lmmc_rng_chi_squared	(	lmmc_rng_t *	rng,
		lmmc_real_t	df,
		lmmc_real_t *	out )

生成卡方分布样本 Chi-squared(df)。

参数

[in]	rng	已初始化的 RNG。
[in]	df	自由度（> 0）。
[out]	out	有限且非负的样本，仅成功时写入；极小正自由度可舍入为零。

返回

LMMC_STATUS_OK 成功；无效参数返回 LMMC_STATUS_INVALID_ARGUMENT； 其余采样失败返回相应数值状态。

在文件 random_continuous.c 第 147 行定义.

引用了 lmmc_rng_chi_squared(), lmmc_rng_gamma(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_chi_squared(), lmmc_rng_f() , 以及 lmmc_rng_student_t().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_student_t()

lmmc_status_t lmmc_rng_student_t	(	lmmc_rng_t *	rng,
		lmmc_real_t	df,
		lmmc_real_t *	out )

生成 Student-t 分布样本 t(df)。

参数

[in]	rng	已初始化的 RNG。
[in]	df	自由度（> 0）。
[out]	out	有限样本，仅成功时写入。

返回

LMMC_STATUS_OK 成功；无效参数返回 LMMC_STATUS_INVALID_ARGUMENT； 样本分母下溢或结果不可表示时返回 LMMC_STATUS_NUMERICAL_FAILURE。

在文件 random_continuous.c 第 177 行定义.

引用了 lmmc_rng_chi_squared(), lmmc_rng_standard_normal(), lmmc_rng_student_t(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_NUMERICAL_FAILURE, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_student_t().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_f()

lmmc_status_t lmmc_rng_f	(	lmmc_rng_t *	rng,
		lmmc_real_t	df1,
		lmmc_real_t	df2,
		lmmc_real_t *	out )

生成 F 分布样本 F(df1, df2)。

参数

[in]	rng	已初始化的 RNG。
[in]	df1	分子自由度（> 0）。
[in]	df2	分母自由度（> 0）。
[out]	out	有限且非负的样本，仅成功时写入。

返回

LMMC_STATUS_OK 成功；无效参数返回 LMMC_STATUS_INVALID_ARGUMENT； 样本分母下溢或结果不可表示时返回 LMMC_STATUS_NUMERICAL_FAILURE。

在文件 random_continuous.c 第 211 行定义.

引用了 lmmc_rng_chi_squared(), lmmc_rng_f(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_NUMERICAL_FAILURE , 以及 LMMC_STATUS_OK.

被这些函数引用 lmmc_rng_f().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_poisson()

lmmc_status_t lmmc_rng_poisson	(	lmmc_rng_t *	rng,
		lmmc_real_t	lambda,
		size_t *	out )

生成 Poisson 分布样本 \(\mathrm{Poisson}(\lambda)\) 。

lambda >= 10 使用 PTRD（Hörmann）算法（接受-拒绝）， lambda < 10 使用逆变换法（Knuth 方法）。

参数

[in]	rng	已初始化的 RNG。
[in]	lambda	期望值（> 0）。
[out]	out	输出样本值（非负整数）。

返回

LMMC_STATUS_OK 成功； LMMC_STATUS_INVALID_ARGUMENT 若 lambda 非有限、<= 0 或指针为 NULL； LMMC_STATUS_NUMERICAL_FAILURE 若样本超出 size_t 范围或中间量非有限。

注解

不分配堆内存；接受-拒绝过程消耗的随机数次数不固定。 out 仅成功时写入，失败时 RNG 状态可能已推进。

在文件 random_discrete.c 第 94 行定义.

引用了 lmmc_rng_poisson(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_poisson().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_binomial()

lmmc_status_t lmmc_rng_binomial	(	lmmc_rng_t *	rng,
		size_t	n,
		lmmc_real_t	p,
		size_t *	out )

生成二项分布样本 Binomial(n, p)。

小均值参数使用精确逆 CDF，其余参数使用 BTPE 接受-拒绝算法； 超过 IEEE-754 精确整数范围的 n 会拆分为独立精确子问题。

参数

[in]	rng	已初始化的 RNG。
[in]	n	试验次数。
[in]	p	有限成功概率（0 <= p <= 1）。
[out]	out	输出样本值；参数无效时保持不变。

返回

LMMC_STATUS_OK 成功；参数或指针无效时返回 LMMC_STATUS_INVALID_ARGUMENT。

在文件 random_discrete.c 第 275 行定义.

引用了 lmmc_rng_binomial(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_binomial().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_int_uniform()

lmmc_status_t lmmc_rng_int_uniform	(	lmmc_rng_t *	rng,
		int64_t	lo,
		int64_t	hi,
		int64_t *	out )

在 [lo, hi] 闭区间内生成无偏均匀整数分布样本。

支持完整的 int64_t 定义域且不执行有符号溢出；lo == hi 时不消耗 RNG 状态。

参数

[in]	rng	已初始化的 RNG。
[in]	lo	下界（含）。
[in]	hi	上界（含）。
[out]	out	输出样本值。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 lo > hi。

在文件 random.c 第 329 行定义.

引用了 lmmc_rng_int_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_int_uniform(), lmmc_std_random_choice() , 以及 lmmc_std_random_randint().

函数调用图:

这是这个函数的调用关系图: