> ## Documentation Index
> Fetch the complete documentation index at: https://numpyts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Random Module Overview

> Overview of the numpy-ts random number generation module, including legacy and modern APIs.

The `np.random` namespace provides NumPy-compatible random number generation with two APIs:

* **Legacy API** -- Global functions like `np.random.seed()`, `np.random.rand()`, `np.random.normal()`, etc. Uses **MT19937** (Mersenne Twister), matching NumPy's legacy random module.
* **Modern API** -- The `Generator` class created via `np.random.default_rng()`. Uses **PCG64** with SeedSequence, matching NumPy's recommended modern approach.

Both APIs produce statistically correct distributions and can be seeded for reproducibility.

## Seeding and State

### seed

Set the global seed for the legacy random number generator.

```typescript theme={null}
function seed(seedValue?: number | null): void
```

| Name | Type | Default | Description |
| - | - | - | - |
| `seedValue` | `number \| null` | `null` | Seed value (integer). If `null` or omitted, a time-based random seed is used. |

**Returns:** `void`

```typescript theme={null}
import * as np from 'numpy-ts';

np.random.seed(42);
console.log(np.random.random()); // Reproducible value
```

***

### get\_state

Get the internal state of the legacy MT19937 random number generator. The returned object can be passed to `set_state` to restore the RNG to this exact point.

```typescript theme={null}
function get_state(): { mt: number[]; mti: number; }
```

**Returns:** `{ mt: number[]; mti: number }` -- Object containing the MT19937 state array and index.

```typescript theme={null}
import * as np from 'numpy-ts';

np.random.seed(0);
const state = np.random.get_state();
const a = np.random.random();

np.random.set_state(state);
const b = np.random.random();
// a === b
```

***

### set\_state

Restore the internal state of the legacy random number generator from a previously saved state object.

```typescript theme={null}
function set_state(state: { mt: number[]; mti: number; }): void
```

| Name | Type | Default | Description |
| - | - | - | - |
| `state` | `{ mt: number[]; mti: number }` | -- | State object obtained from `get_state()`. |

**Returns:** `void`

***

### get\_bit\_generator

Get the current bit generator object. Returns an object with `name` and `state` properties.

```typescript theme={null}
function get_bit_generator(): BitGenerator
```

**Returns:** `BitGenerator` -- The current bit generator descriptor.

***

### set\_bit\_generator

Set the bit generator used by the legacy random functions.

```typescript theme={null}
function set_bit_generator(bitgen: BitGenerator): void
```

| Name | Type | Default | Description |
| - | - | - | - |
| `bitgen` | `BitGenerator` | -- | Bit generator descriptor. |

**Returns:** `void`

***

## Reproducibility

numpy-ts implements the same algorithms as NumPy for both the legacy and modern APIs:

| API | Bit Generator | Implementation | Initialization |
| - | - | - | - |
| Legacy (`np.random.seed`) | MT19937 | Zig/WASM | Direct seed init |
| Modern (`np.random.default_rng`) | PCG64 | Zig/WASM | SeedSequence expansion |

### NumPy Compatibility

| Category | Match Level | Notes |
| - | - | - |
| Uniform `[0, 1)` | Exact | Identical 53-bit float generation |
| Normal / Gaussian | Exact | Box-Muller transform, same pairing |
| Integer generation | Exact | Same range mapping |
| PCG64 (Generator) | Exact | Same SeedSequence, same state advance order |
| Gamma, Beta, Chi-square | Exact | Zig rewrite matches NumPy bit-for-bit |
| Poisson, Binomial | Exact | Zig rewrite matches NumPy bit-for-bit |
| Multivariate Normal | Exact | Cholesky-based, identical output |

> [!NOTE]
>
> As of v1.2.0, all distributions match NumPy exactly for the same seed, across both the legacy (`np.random.seed()`) and modern (`np.random.default_rng()`) APIs. The legacy API uses MT19937 implemented in Zig/WASM; the modern API uses PCG64 in Zig/WASM.

***

## default\_rng and Generator

The modern API uses `default_rng` to create a `Generator` instance backed by PCG64. See the [Generator API](https://numpyts.dev/v1.7.x/api/random/generator.md) page for full details.

```typescript theme={null}
import * as np from 'numpy-ts';

const rng = np.random.default_rng(12345);
const arr = rng.random([3, 3]);
const ints = rng.integers(0, 100, [5]);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.