> ## 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.
</Note>

***

## default\_rng and Generator

The modern API uses `default_rng` to create a `Generator` instance backed by PCG64. See the [Generator API](./generator) 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]);
```