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
A- Type
Any- Required
- Yes
- Description
- Input array/value.
order- Type
NumericArray- Required
- Yes
- Description
- Row/column vector containing a permutation of 1:ndims(A).
Returns
B- Type
Any- Description
- Input array with dimensions reordered by order.
Errors
RunMat:permute:InvalidOrder- When
- order is non-numeric, non-vector, empty, non-integer, out of range, or duplicated.
- Message
permute: invalid order vector
RunMat:permute:RankMismatch- When
- order length is less than ndims(A).
- Message
permute: order length must be at least ndims(A)
RunMat:permute:UnsupportedInput- When
- A has unsupported type for permute.
- Message
permute: unsupported input type
Behavior
order must be a permutation of 1:n, where n = numel(order). Each dimension index appears exactly once.
The length of order must be at least ndims(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, string, character, structure, and all eight native integer array classes retain their values. Host scalar logical input follows the existing numeric-scalar adaptation; cell inputs are unsupported.
Dimension order accepts every integer class and is decoded exactly as a one-based structural permutation.
An admitted provider permutation keeps the result on the device. A host fallback permutes exact-class values and attempts restoration through the input's owning provider.
Execution and residency
The runtime uses the input's owning provider for device permutation and any fallback transfers, preserving the numerical class.
Explicit gpuArray input cannot silently produce a host result. For automatically placed floating-point data, unsupported upload during class-preserving restoration can leave the result on the host; subsequent placement uses that actual residency.
Structural data retains its admitted single, double, logical, or native signed/unsigned integer storage, including supported complex arrays. This does not upgrade preceding numerical accuracy or authorize an unsupported carrier.
The first argument is the data operand; remaining arguments, where present, are dimension or order controls. No scalar broadcasting, elementwise/reduction fusion template, or standalone fusion constant ABI is declared.
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]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. Character arrays use the same N-D structural permutation as their stored shape, including identity and transpose.
How does permute interact with gpuArray values?⌄
Device implementations preserve residency. An admitted host fallback attempts exact-owner restoration; explicit gpuArray intent forbids silent host publication, while automatically placed floating-point values may remain on the host when upload is unsupported.
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?⌄
Permutation reorders linear data to match the requested axes while preserving column-major indexing. Applying the inverse permutation recovers the original array.
Can cell arrays be permuted?⌄
No. The current permute runtime rejects cell arrays, including two-dimensional cells.
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
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · repelem · repmat · reshape · rot90 · shiftdim · squeeze · toeplitz · tril · triu · vertcat
Accumulation
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Creation
colon · createArray · empty · eye · false · full · inf · int16.empty · int32.empty · int64.empty · int8.empty · linspace · logspace · magic · meshgrid · nan · ndgrid · nonzeros · ones · peaks · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · uint16.empty · uint32.empty · uint64.empty · uint8.empty · zeros
Combinatorics
Binning
Grouping
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.