gaussian-random

一个高效生成符合正态分布（均值为0，标准差可通过scale参数自定义）随机数及数组的工具库，支持ESM、CJS、IIFE多种模块格式，适用于浏览器和Node.js环境。

特性

• 基于Box-Muller变换生成正态分布随机数，数学严谨，可通过scale参数控制标准差（默认生成标准正态分布N(0,1)）
• 内置随机数缓存机制，减少50%计算量，性能更优
• 支持生成普通数组、32位浮点数数组（Float32Array）、64位浮点数数组（Float64Array）
• 完整的参数校验（非负整数长度、非负标准差），提升使用健壮性
• 支持多种模块格式：ESM、CJS、IIFE（浏览器全局变量）

安装

使用npm/yarn/pnpm

# npm
npm install gaussian-random

# yarn
yarn add gaussian-random

# pnpm
pnpm add gaussian-random

浏览器直接引入（IIFE）

通过CDN引入（支持unpkg、jsDelivr等）：

<!-- unpkg -->
<script src="https://unpkg.com/gaussian-random@latest/dist/index.global.js"></script>

引入后可通过全局变量 gaussianRandom 使用（如 gaussianRandom.random(2)）。

使用方法

ESM 环境（如现代浏览器、Vite、Webpack等）

import { random, randomArr, random32, random64 } from 'gaussian-random';

// 生成单个标准正态分布（scale=1，N(0,1)）随机数
const num1 = random();

// 生成单个标准差为2的正态分布（N(0,4)）随机数
const num2 = random(2);

// 生成包含5个元素、标准差为0.5的普通数组（N(0,0.25)）
const arr = randomArr(5, 0.5);

// 生成包含10个元素、标准差为3的32位浮点数数组（N(0,9)）
const float32Arr = random32(10, 3);

// 生成包含8个元素、默认标准差的64位浮点数数组（N(0,1)）
const float64Arr = random64(8);

CJS 环境（如Node.js）

const { random, randomArr, random32, random64 } = require('gaussian-random');

// 用法同上
const num = random(1.5); // 生成N(0, 2.25)分布的随机数

浏览器全局环境（IIFE）

<script src="https://unpkg.com/gaussian-random@latest/dist/index.global.js"></script>
<script>
  // 通过全局变量gaussianRandom调用
  const num = gaussianRandom.random(2); // N(0,4)
  const arr = gaussianRandom.randomArr(3, 0.8); // 3个元素，N(0,0.64)
</script>

API 文档

random(scale?: number): number

生成一个符合正态分布（均值=0，标准差=scale）的随机数。

参数：

• scale：可选，标准差，控制分布的离散程度，必须为非负数（≥0），默认值为1。
  • 当scale=1时，生成标准正态分布N(0,1)
  • 当scale=σ时，生成N(0, σ²)分布

返回值：符合N(0, scale²)分布的随机数（number）。

抛出错误：若scale为负数或非数字，将抛出Error。

原理：基于Box-Muller变换实现，通过缓存变换过程中生成的第二个随机数，减少50%的计算量（平均每次调用仅需执行一次变换的1/2计算）。

randomArr(n: number, scale?: number): number[]

生成包含n个符合正态分布（均值=0，标准差=scale）随机数的普通数组。

参数：

• n：数组长度，必须为非负整数（≥0且为整数）。
• scale：可选，标准差，非负数，默认值为1。

返回值：元素为N(0, scale²)分布随机数的number[]数组。

抛出错误：若n为负数/非整数，或scale为负数/非数字，将抛出Error。

random32(n: number, scale?: number): Float32Array

生成包含n个符合正态分布（均值=0，标准差=scale）随机数的32位浮点数数组（节省内存，适用于精度要求不高的场景）。

参数：

• n：数组长度，必须为非负整数（≥0且为整数）。
• scale：可选，标准差，非负数，默认值为1。

返回值：元素为N(0, scale²)分布随机数的Float32Array。

抛出错误：若n为负数/非整数，或scale为负数/非数字，将抛出Error。

random64(n: number, scale?: number): Float64Array

生成包含n个符合正态分布（均值=0，标准差=scale）随机数的64位浮点数数组（高精度，适用于对精度要求较高的场景）。

参数：

• n：数组长度，必须为非负整数（≥0且为整数）。
• scale：可选，标准差，非负数，默认值为1。

返回值：元素为N(0, scale²)分布随机数的Float64Array。

抛出错误：若n为负数/非整数，或scale为负数/非数字，将抛出Error。

示例

import { random, randomArr, random32, random64 } from 'gaussian-random';

// 生成单个标准正态分布随机数（scale=1）
console.log(random()); // 示例输出：0.3421（服从N(0,1)）

// 生成单个标准差为2的随机数（N(0,4)）
console.log(random(2)); // 示例输出：2.684（约95%概率落在[-4,4]）

// 生成包含3个元素、标准差0.5的普通数组（N(0,0.25)）
console.log(randomArr(3, 0.5)); // 示例输出：[-0.32, 0.15, -0.47]

// 生成10个元素的32位浮点数数组（scale=3，N(0,9)）
const float32 = random32(10, 3);
console.log(float32.byteLength); // 输出：40（10 * 4字节）
console.log(float32[0]); // 示例输出：4.12（约99.7%概率落在[-9,9]）

// 生成5个元素的64位浮点数数组（默认scale=1）
const float64 = random64(5);
console.log(float64.byteLength); // 输出：40（5 * 8字节）

注意事项

1. 参数校验：所有函数对n（非负整数）和scale（非负数）有严格校验，无效值会抛出Error。
2. 随机性依赖：随机数基于JavaScript原生Math.random()生成，其随机性依赖于运行环境的实现。
3. 正态分布特性：对于给定scale=σ，约68%的数值落在[-σ, σ]，约95%落在[-2σ, 2σ]，约99.7%落在[-3σ, 3σ]。
4. 性能优化：random函数通过缓存Box-Muller变换的结果，平均减少50%计算量，scale参数不影响这一优化。

许可证

MIT