RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

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 does the randperm function behave in MATLAB / 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.

GPU behavior

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 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 of using randperm in MATLAB / RunMat

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.

See also

rand, randi, rng, gpuArray, gather

Source & Feedback