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

# Basic Random Functions

> Legacy random sampling functions for uniform, normal, and integer distributions.

All functions on this page are accessed via the `np.random` namespace and use the global MT19937 generator. Seed with `np.random.seed()` for reproducible results.

<Note>
  As of v1.2.0, random functions on this page (`rand`, `randn`, `random`, `randint`, `uniform`, `normal`, `choice`, `shuffle`, `permutation`, `bytes`) are now implemented as Zig-compiled WASM kernels. With `np.random.seed(n)`, outputs match NumPy exactly for the same seed across every function listed here.
</Note>

### random

Generate random floats in the half-open interval `[0.0, 1.0)`.

```typescript theme={null}
function random(size?: number | number[]): NDArray | number
```

| Name   | Type                 | Default     | Description                                       |
| ------ | -------------------- | ----------- | ------------------------------------------------- |
| `size` | `number \| number[]` | `undefined` | Output shape. If omitted, returns a single float. |

**Returns:** `NDArray | number` -- Random values in `[0, 1)`.

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

np.random.seed(42);

// Single value
const x = np.random.random();

// 1-D array
const a = np.random.random(5);
// array([...])  shape [5]

// 2-D array
const b = np.random.random([3, 4]);
// array([...])  shape [3, 4]
```

***

### rand

Random values in a given shape. Variadic form of `random` -- pass dimensions as separate arguments.

```typescript theme={null}
function rand(...shape: number[]): NDArray | number
```

| Name       | Type       | Default | Description                                                                |
| ---------- | ---------- | ------- | -------------------------------------------------------------------------- |
| `...shape` | `number[]` | --      | Dimensions of the returned array. If no arguments, returns a single float. |

**Returns:** `NDArray | number` -- Random values in `[0, 1)`.

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

const a = np.random.rand(2, 3);
// array([...])  shape [2, 3]
```

***

### randn

Return samples from the standard normal distribution (mean=0, std=1). Variadic shape, like `rand`.

```typescript theme={null}
function randn(...shape: number[]): NDArray | number
```

| Name       | Type       | Default | Description                                                                |
| ---------- | ---------- | ------- | -------------------------------------------------------------------------- |
| `...shape` | `number[]` | --      | Dimensions of the returned array. If no arguments, returns a single float. |

**Returns:** `NDArray | number` -- Samples from the standard normal distribution.

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

const a = np.random.randn(1000);
// 1000 standard-normal samples
```

***

### randint

Return random integers from `low` (inclusive) to `high` (exclusive).

```typescript theme={null}
function randint(
  low: number,
  high?: number | null,
  size?: number | number[],
  dtype?: DType
): NDArray | number
```

| Name    | Type                 | Default     | Description                                                                                                   |
| ------- | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `low`   | `number`             | --          | Lowest integer (inclusive). If `high` is omitted, this is treated as the upper bound and `low` defaults to 0. |
| `high`  | `number \| null`     | `null`      | One above the highest integer (exclusive).                                                                    |
| `size`  | `number \| number[]` | `undefined` | Output shape. If omitted, returns a single integer.                                                           |
| `dtype` | `DType`              | `'int64'`   | Desired output dtype.                                                                                         |

**Returns:** `NDArray | number` -- Random integers in `[low, high)`.

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

// 0 to 9
const a = np.random.randint(10);

// 5 to 14, shape [2, 3]
const b = np.random.randint(5, 15, [2, 3]);
```

***

### random\_sample

Alias for `random()`. Return random floats in `[0.0, 1.0)`.

```typescript theme={null}
function random_sample(size?: number | number[]): NDArray | number
```

| Name   | Type                 | Default     | Description   |
| ------ | -------------------- | ----------- | ------------- |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Random values in `[0, 1)`.

***

### ranf

Alias for `random()`. Return random floats in `[0.0, 1.0)`.

```typescript theme={null}
function ranf(size?: number | number[]): NDArray | number
```

| Name   | Type                 | Default     | Description   |
| ------ | -------------------- | ----------- | ------------- |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Random values in `[0, 1)`.

***

### sample

Alias for `random()`. Return random floats in `[0.0, 1.0)`.

```typescript theme={null}
function sample(size?: number | number[]): NDArray | number
```

| Name   | Type                 | Default     | Description   |
| ------ | -------------------- | ----------- | ------------- |
| `size` | `number \| number[]` | `undefined` | Output shape. |

**Returns:** `NDArray | number` -- Random values in `[0, 1)`.

***

### random\_integers

<Warning>
  **Deprecated.** Use `randint` instead.
</Warning>

Return random integers between `low` and `high`, inclusive on both ends.

```typescript theme={null}
function random_integers(
  low: number,
  high?: number,
  size?: number | number[]
): NDArray | number
```

| Name   | Type                 | Default     | Description                                                |
| ------ | -------------------- | ----------- | ---------------------------------------------------------- |
| `low`  | `number`             | --          | Lowest integer. If `high` is omitted, range is `[1, low]`. |
| `high` | `number`             | `undefined` | Highest integer (inclusive).                               |
| `size` | `number \| number[]` | `undefined` | Output shape.                                              |

**Returns:** `NDArray | number` -- Random integers in `[low, high]`.

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

// Random integers from 1 to 6 (inclusive), like a die roll
const die = np.random.random_integers(1, 6, [10]);
```

***

### bytes

Return random bytes as a `Uint8Array`.

```typescript theme={null}
function bytes(length: number): Uint8Array
```

| Name     | Type     | Default | Description                         |
| -------- | -------- | ------- | ----------------------------------- |
| `length` | `number` | --      | Number of random bytes to generate. |

**Returns:** `Uint8Array` -- Array of random bytes.

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

const b = np.random.bytes(16);
// Uint8Array of 16 random bytes
```

***

### choice

Generate a random sample from a given 1-D array or from `range(a)` when `a` is an integer.

```typescript theme={null}
function choice(
  a: number | ArrayLike,
  size?: number | number[],
  replace?: boolean,
  p?: ArrayLike
): NDArray | number
```

| Name      | Type                  | Default     | Description                                                                   |
| --------- | --------------------- | ----------- | ----------------------------------------------------------------------------- |
| `a`       | `number \| ArrayLike` | --          | If `number`, sample from `0..a-1`; otherwise sample from the provided values. |
| `size`    | `number \| number[]`  | `undefined` | Output shape.                                                                 |
| `replace` | `boolean`             | `true`      | Whether sampling is with replacement.                                         |
| `p`       | `ArrayLike`           | `undefined` | Optional probabilities for each entry in `a`.                                 |

***

### permutation

Randomly permute a sequence or return a permuted range.

```typescript theme={null}
function permutation(x: number | ArrayLike): NDArray
```

| Name | Type                  | Default | Description                                                        |
| ---- | --------------------- | ------- | ------------------------------------------------------------------ |
| `x`  | `number \| ArrayLike` | --      | If `number`, permute `0..x-1`; otherwise permute the input values. |

***

### shuffle

Shuffle an array in place along the first axis.

```typescript theme={null}
function shuffle(x: ArrayLike): void
```

| Name | Type        | Default | Description                |
| ---- | ----------- | ------- | -------------------------- |
| `x`  | `ArrayLike` | --      | Array to shuffle in place. |