permute — Reorder array dimensions in MATLAB and RunMat.
permute(A, order) rearranges dimensions of A according to integer vector order. Permutation validation and size-one trailing-dimension behavior follow MATLAB semantics.
Syntax
B = permute(A, order)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input array/value. |
order | NumericArray | Yes | — | Row/column vector containing a permutation of 1:ndims(A). |
Returns
| Name | Type | Description |
|---|---|---|
B | Any | Input array with dimensions reordered by order. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:permute:InvalidOrder | order is non-numeric, non-vector, empty, non-integer, out of range, or duplicated. | permute: invalid order vector |
RunMat:permute:RankMismatch | order length is less than ndims(A). | permute: order length must be at least ndims(A) |
RunMat:permute:UnsupportedInput | A has unsupported type for permute. | permute: unsupported input type |
How permute works
ordermust be a permutation of1:n, wheren = numel(order). Each dimension index appears exactly once.- The length of
ordermust be at leastndims(A). You can specify additional trailing dimensions; RunMat pads missing axes with size one. - Duplicate or zero dimension indices throw an error.
- Works on empty arrays and arrays with zero-sized dimensions. The result preserves MATLAB's column-major ordering.
- Logical, complex, and string arrays keep their types. Character arrays support 2-D permutations (transpose or identity).
- gpuArray inputs stay on the GPU. If the provider lacks a native permute kernel, RunMat gathers once, permutes on the host, and uploads the result back to the device.
Does RunMat run permute on the GPU?
The runtime first asks the active acceleration provider for the permute hook. When implemented (e.g., a fused copy kernel), the permutation occurs entirely on the device. Otherwise RunMat falls back to a gather/permute/upload path. Either way, the result is returned as a gpuArray to match MATLAB behaviour.
Examples
Swapping the first two dimensions of a 3-D tensor
A = reshape(1:24, [2 3 4]);
B = permute(A, [2 1 3]);
size(B)Expected output:
ans = [3 2 4]Moving the last dimension to the front
A = rand(4, 2, 5);
C = permute(A, [3 1 2]);
size(C)Expected output:
ans = [5 4 2]Adding an explicit trailing singleton dimension
row = 1:5;
T = permute(row, [2 1 3]);
size(T)Expected output:
ans = [5 1 1]Permuting logical masks without losing type information
mask = false(2, 1, 3);
mask(1, 1, 2) = true;
rotated = permute(mask, [3 1 2]);
class(rotated)Expected output:
ans = 'logical'Transposing character arrays
C = ['r','u','n'; 'm','a','t'];
Ct = permute(C, [2 1])Expected output:
Ct =
'rm'
'ua'
'nt'Permuting gpuArray data while staying on the device
G = gpuArray(rand(4, 2, 3));
H = permute(G, [3 1 2]);
isgpuarray(H)Expected output:
ans = logical 1Using permute with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how permute changes the result.
Run a small permute example, explain the result, then change one input and compare the output.
FAQ
Does order have to contain every dimension exactly once?⌄
Yes. order must be a true permutation of 1:n. RunMat raises an error when dimensions repeat or are missing.
Can I introduce new singleton dimensions?⌄
Yes. Set order to include additional trailing indices (e.g., [1 2 3 4] for a matrix) and RunMat will append size-one axes.
What happens with empty arrays or zero-sized dimensions?⌄
They are preserved. The permutation still follows column-major ordering even when some dimensions are zero.
Can I use permute on character arrays?⌄
Yes, but only for 2-D permutations (identity or transpose) because MATLAB character arrays are stored as 2-D matrices.
How does permute interact with gpuArray values?⌄
RunMat keeps the result on the GPU. Providers that lack a native kernel trigger a gather-and-reupload fallback, which is documented above.
Is the operation in-place?⌄
No. permute returns a new array; the original input remains unchanged.
How do I invert a permutation?⌄
Use ipermute with the same order vector.
Does permute change data layout or ordering?⌄
Only the dimension metadata changes. Column-major linearisation is preserved, so reshaping back with the inverse order recovers the original array.
Can cell arrays be permuted?⌄
Cell arrays above two dimensions are not yet supported in RunMat; the builtin will report an error.
What if I pass a gpuArray as the order argument?⌄
MATLAB requires numeric vectors on the host. RunMat mirrors this and reports an error if the order vector is gpu-resident.
Related Array functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how permute is executed, line by line, in Rust.
- View the source for permute 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.