randperm — Generate random permutations in MATLAB and RunMat.
randperm(n) returns a random permutation of integers 1:n. randperm(n, k) returns k unique values without replacement, with MATLAB-compatible result shapes. Ordinary output uses the CPU stream; resident output uses the separate GPU child stream.
Syntax
p = randperm(n)
p = randperm(n, k)
p = randperm(n, "double")
p = randperm(n, k, "double")
p = randperm(n, "like", prototype)
p = randperm(n, k, "like", prototype)Inputs
n- Type
SizeArg- Required
- Yes
- Description
- Population size.
k- Type
SizeArg- Required
- No
- Description
- Number of selected elements.
typename- Type
StringScalar- Required
- No
- Default
"double"- Description
- Class override ('double').
like_kw- Type
StringScalar- Required
- Yes
- Default
"like"- Description
- Like keyword.
prototype- Type
LikePrototype- Required
- Yes
- Description
- Prototype array used for class/device.
Returns
p- Type
NumericArray- Description
- Row vector containing permutation values.
Errors
- When
- No N argument is provided.
- Message
randperm: requires at least one input argument
- When
- N or K is not a supported non-negative integer scalar.
- Message
randperm: N/K must be non-negative integers
- When
- K is larger than N.
- Message
randperm: K must satisfy 0 <= K <= N
Behavior
randperm(n) produces a row vector whose length is n and whose entries are a random ordering of 1:n.
randperm(n, k) returns the first k entries of the permutation without replacement (0 ≤ k ≤ n). The result is a 1 × k row vector.
Both n and k accept all eight documented integer classes and are decoded exactly as structural counts; ordinary output remains double.
In runmat compatibility mode, the RunMat-only randperm(n, ___, 'like', A) selector preserves GPU residency when A is resident while output remains double.
In runmat compatibility mode, the RunMat-only explicit 'double' selector keeps the default double-precision output.
randperm errors when n or k are non-integers, negative, or exceed the IEEE double integer precision limit (2^53).
Empty permutations (e.g., randperm(0) or randperm(n, 0)) return a 1×0 tensor.
Execution and residency
Ordinary randperm construction does not become GPU-resident solely because a provider is active. In runmat compatibility mode, a resident RunMat-only 'like' prototype explicitly requests a result on that owner; host generation followed by a typed upload preserves admitted residency.
Ordinary output consumes the CPU stream controlled by rng. The RunMat-only resident 'like' form consumes the independent GPU child stream controlled by gpurng; the currently admitted route computes its O(k) unbiased reservoir and shuffle on the host from that stream, then restores Double output through the exact provider owner. Legacy provider-global permutation hooks are not a source of session stream authority.
Examples
Getting a random permutation of integers 1 through N
rng(0);
p = randperm(6)Selecting K unique indices without replacement
rng(0);
idx = randperm(10, 3)Generating a reproducible permutation after seeding RNG
rng(42);
p1 = randperm(8);
rng(42);
p2 = randperm(8)Creating a resident random permutation
gpurng(0);
G = gpuArray.zeros(4, 4);
p = randperm(12, 4, 'like', G);
peek = gather(p)Working with empty permutations
p = randperm(0);
q = randperm(5, 0)Using randperm with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how randperm changes the result.
Run a small randperm example, explain the result, then change one input and compare the output.
FAQ
What ranges does randperm draw from?⌄
randperm(n) always returns integers in the inclusive range 1:n. The optional second argument k picks the first k elements of that permutation.
Can k be zero?⌄
Yes. randperm(n, 0) returns a 1×0 empty row vector without consuming any additional random numbers.
Does randperm support 'single' or integer output types?⌄
The result is always double. Supplying 'single' or integer class names raises a descriptive error; the explicit 'double' and 'like' selectors are available only in runmat compatibility mode.
How does randperm interact with rng?⌄
Ordinary randperm consumes the CPU stream controlled by rng. Resident output uses the independent GPU stream controlled by gpurng; seed or restore the relevant stream for reproducibility.
Why is there a 2^53 limit?⌄
All outputs are stored in IEEE double. Values beyond 2^53 cannot be represented exactly, so RunMat rejects inputs larger than 2^53 to avoid duplicate entries.
Does the GPU path stay device-resident?⌄
A resident 'like' prototype in RunMat mode requests a device-resident Double result from its exact owner. This form consumes gpurng state, not the CPU rng stream; current generation is host-mediated before an admitted typed upload.
Related Array functions
Creation
colon · createArray · empty · eye · false · full · inf · int16.empty · int32.empty · int64.empty · int8.empty · linspace · logspace · magic · meshgrid · nan · ndgrid · nonzeros · ones · peaks · rand · randi · randn · range · sparse · spdiags · speye · spones · sprand · true · uint16.empty · uint32.empty · uint64.empty · uint8.empty · zeros
Accumulation
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · shiftdim · squeeze · toeplitz · tril · triu · vertcat
Combinatorics
Binning
Grouping
Source you can read
Every RunMat function's source is public. Read exactly how randperm is executed, line by line, in Rust.
- View the source for randperm in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.