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 RNG and shape behavior following MATLAB semantics.

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

Returns

Errors

How randperm works

• 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.
• randperm(n, ___, 'like', A) matches the numeric class and residency of A when possible (e.g., GPU tensors).
• randperm(n, ___, 'double') 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.

Does RunMat run randperm on the GPU?

When the 'like' prototype lives on the GPU, RunMat asks the active acceleration provider for a device-side permutation via the dedicated random_permutation_like hook. The bundled WGPU provider executes the entire selection and shuffle in a compute kernel, keeping the data resident on the device. Providers that do not advertise this hook fall back to the host implementation and upload the result once, preserving correctness while highlighting the extra transfer cost.

GPU memory and residency

You usually do NOT need to call gpuArray yourself in RunMat (unlike MATLAB).

In RunMat, the fusion planner and acceleration layer keep residency on the GPU whenever downstream computation benefits from it. When you request a permutation 'like' a GPU tensor, RunMat asks the active acceleration provider to generate and shuffle the permutation directly on the device. If the provider does not implement the permutation hook, RunMat falls back to host generation and performs a single upload so later GPU work still sees a device-resident array.

To preserve backwards compatibility with MathWorks MATLAB—and for situations where you want to be explicit—you can always wrap inputs in gpuArray.

Examples

Getting a random permutation of integers 1 through N

rng(0);
p = randperm(6)

Expected output:

p = [1 6 2 4 3 5]

Selecting K unique indices without replacement

rng(0);
idx = randperm(10, 3)

Expected output:

idx = [1 10 9]

Generating a reproducible permutation after seeding RNG

rng(42);
p1 = randperm(8);
rng(42);
p2 = randperm(8)

Expected output:

isequal(p1, p2)
ans = logical
     1

Creating a GPU-resident random permutation

G = gpuArray.zeros(4, 4);
p = randperm(12, 4, 'like', G);
peek = gather(p)

Expected output:

isa(p, 'gpuArray')
ans = logical
     1

Working with empty permutations

p = randperm(0);
q = randperm(5, 0)

Expected output:

size(p)
ans =
     1     0

size(q)
ans =
     1     0

Using randperm with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how randperm changes the result.

FAQ

Related Array functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. 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 an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.

Getting started · Benchmarks · Pricing