perms — Return all permutations of a vector as rows.
P = perms(v) returns every permutation of the elements in vector v, one permutation per row. RunMat follows MATLAB's reverse lexicographic row order and preserves supported vector container classes.
Syntax
P = perms(v)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
v | Any | Yes | — | Input vector to permute. |
Returns
| Name | Type | Description |
|---|---|---|
P | Any | Matrix whose rows contain every permutation of the input vector. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:perms:InvalidInput | The input is missing, not a vector, or has an unsupported type. | perms: input must be a vector |
RunMat:perms:TooLarge | The factorial-size output would exceed RunMat's supported materialisation limit. | perms: output is too large |
RunMat:perms:Internal | Output allocation, GPU gather, or container construction failed. | perms: internal error |
How perms works
perms(v)accepts row vectors, column vectors, scalars, and empty vectors.- The output has
factorial(numel(v))rows andnumel(v)columns. - Rows are emitted in MATLAB-compatible reverse lexicographic permutation order relative to the original element positions.
- Duplicate input values are permuted by position and are not deduplicated.
- Dense numeric tensors preserve their native class and exact values, including all eight integer classes and wide 64-bit values; logical, character, string-array, and cell-array vectors return matching container types.
- Scalar numeric, logical, and string inputs return the scalar value unchanged.
- Complex numeric vectors are permuted positionally and preserve their complex values.
- Inputs that are not vectors, unsupported object-like values, sparse tensors, and outputs beyond RunMat's materialization limit raise stable errors.
Examples
Permute a numeric vector
P = perms([1 2 3])Expected output:
P =
3 2 1
3 1 2
2 3 1
2 1 3
1 3 2
1 2 3Permute characters
P = perms('abc')Expected output:
P =
'cba'
'cab'
'bca'
'bac'
'acb'
'abc'Duplicate values are retained
P = perms([1 1 2])Expected output:
% P has six rows; duplicate rows are preserved.Work with an empty vector
P = perms([])Expected output:
% P is a 1-by-0 empty double array.Using perms with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how perms changes the result.
Run a small perms example, explain the result, then change one input and compare the output.
FAQ
Why can perms error for long vectors?⌄
perms materializes factorial(numel(v)) * numel(v) elements. RunMat rejects outputs beyond its configured materialization limit instead of exhausting memory.
Does perms remove duplicate rows?⌄
No. Like MATLAB, values are permuted by position. Repeated input values can therefore produce repeated rows.
Can perms run on gpuArray inputs?⌄
RunMat gathers through the owning provider, constructs the result on the host, and restores the same-class result to that provider. Explicit gpuArray input fails if the provider cannot preserve residency.
Related Array functions
Creation
colon · createArray · empty · eye · false · full · inf · linspace · logspace · magic · meshgrid · nan · nchoosek · ndgrid · nonzeros · ones · peaks · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · zeros
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how perms is executed, line by line, in Rust.
- View the source for perms 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.