# gaussian-random

**Repository Path**: nodets/gaussian-random

## Basic Information

- **Project Name**: gaussian-random
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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

```bash
# npm
npm install gaussian-random

# yarn
yarn add gaussian-random

# pnpm
pnpm add gaussian-random
```

### 浏览器直接引入（IIFE）

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

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

```

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


## 使用方法

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

```javascript
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）

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

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

### 浏览器全局环境（IIFE）

```html
<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`。


## 示例

```javascript
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