randperm

→Tensor

randperm(n: int, generator: _C_engine.Generator | None = None, dtype: DTypeLike = int64, device: DeviceLike = None, requires_grad: bool = False)

source edit

Return a uniformly random permutation of the integers $0, 1, \ldots, n-1$ .

Produces a rank-1 tensor containing a uniformly random element of $S_n$ , the symmetric group of permutations on $n$ symbols. Every one of the $n!$ orderings is equally likely:

P(\sigma) = \frac{1}{n!} \quad \forall\; \sigma \in S_n

Parameters

nint

Number of elements. Must be

\geq 0

. Returns an empty tensor when n = 0.

generatorlucid._C.engine.Generator= None

Explicit generator. Defaults to the global default.

dtypelucid.dtype= int64

Integer data type of the output. Defaults to lucid.int64.

devicestr or lucid.device= None

Target device — "cpu" or "metal".

requires_gradbool= False

Enable autograd tracking. Default: False.

Returns

Tensor

1-D integer tensor of shape (n,) containing a permutation of $\{0, 1, \ldots, n-1\}$ .

Notes

The implementation uses the lottery-ticket argsort trick: assign each integer $k$ a uniform random key $u_k \sim U[0,1)$ and return the argsort of those keys:

\pi = \operatorname{argsort}(u), \quad u_k \sim U[0,1)^n

This is equivalent to the Fisher–Yates shuffle in expectation and is more cache-friendly on SIMD hardware because the sort can be vectorised without branch-dependent swaps.

randperm is the standard building block for:

Dataset shuffling — dataset[lucid.randperm(len(dataset))]
k-fold cross-validation — split a shuffled index tensor
Contrastive learning — negative-sample mining via permuted indices

Examples

>>> import lucid
>>> lucid.manual_seed(0)
>>> lucid.randperm(5).tolist()
[2, 4, 3, 1, 0]
Shuffle a dataset of 1024 examples in one line:
>>> idx = lucid.randperm(1024)
>>> shuffled = data[idx]
Edge cases:
>>> lucid.randperm(0).shape
(0,)
>>> lucid.randperm(1).tolist()
[0]

>>> import lucid >>> lucid.manual_seed(0) >>> lucid.randperm(5).tolist() [2, 4, 3, 1, 0] Shuffle a dataset of 1024 examples in one line: >>> idx = lucid.randperm(1024) >>> shuffled = data[idx] Edge cases: >>> lucid.randperm(0).shape (0,) >>> lucid.randperm(1).tolist() [0]