randperm — Random permutations of the integers 1:n with MATLAB-compatible semantics.

randperm(n) returns a uniformly random permutation of the integers 1:n. randperm(n, k) selects k unique integers from 1:n without replacement. RunMat mirrors MATLAB's behaviour, including RNG seeding through rng, GPU-aware 'like' prototypes, and deterministic results during testing.

How randperm works in RunMat

• 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.

How randperm runs 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

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?

Not yet. The builtin currently emits double-precision arrays. Supplying 'single' or integer class names raises a descriptive error.

How does randperm interact with rng?

randperm consumes the shared RunMat RNG stream. Use the MATLAB-compatible rng builtin to seed or restore the generator for reproducible permutations.

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?

Yes—when a provider is active RunMat uploads the host permutation after it is generated. Providers that later add a dedicated permutation kernel can replace the fallback without changing user code.

Related functions to explore

These functions work well alongside randperm. Each page has runnable examples you can try in the browser.

rand, randi, rng, gpuArray, gather, colon, eye, false, fill, linspace, logspace, magic, meshgrid, ones, randn, range, true, zeros

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how randperm works, line by line, in Rust.

• View randperm.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing