ipermute — Reorder array dimensions with inverse permutation in MATLAB and RunMat.
ipermute(A, order) reverses dimension reordering performed by permute(A, order). Inverse-order handling and shape behavior follow MATLAB semantics.
Syntax
A = ipermute(B, order)Inputs
B- Type
Any- Required
- Yes
- Description
- Permuted input array/value.
order- Type
NumericArray- Required
- Yes
- Description
- Permutation vector previously used with permute.
Returns
A- Type
Any- Description
- Array with inverse permutation applied.
Errors
RunMat:ipermute:InvalidOrder- When
- order is non-numeric, non-vector, empty, non-integer, out of range, or duplicated.
- Message
ipermute: invalid order vector
RunMat:ipermute:RankMismatch- When
- order length is less than ndims(B).
- Message
ipermute: order length must be at least ndims(B)
RunMat:ipermute:UnsupportedInput- When
- B has unsupported type for ipermute.
- Message
ipermute: unsupported input type
Behavior
order must be a permutation of 1:n, where n = numel(order).
The length of order must be at least ndims(A); missing axes are treated as trailing singleton dimensions.
Duplicate, zero, or negative indices raise an error.
Works with numeric tensors, logical masks, complex tensors, string arrays, character arrays, and gpuArray values.
Character arrays use the N-D inverse structural permutation of their stored shape; identity and transpose are the two-dimensional cases.
An admitted provider permutation keeps the result on the device. A host fallback applies the inverse order to exact-class values and attempts restoration through the input's owning provider.
Execution and residency
Reuses the owning provider's permute hook with the inverse order vector; fallback transfers use that same owner and preserve 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
Reversing a previous permute call
A = reshape(1:24, [2 3 4]);
B = permute(A, [2 1 3]);
C = ipermute(B, [2 1 3]);
isequal(A, C)Expected output:
ans = logical 1Restoring matrix orientation after swapping dimensions
M = magic(3);
P = permute(M, [2 1]);
R = ipermute(P, [2 1]);
size(R)Expected output:
ans = [3 3]Undoing a permutation with extra singleton dimensions
row = 1:5;
P = permute(row, [2 1 3]);
R = ipermute(P, [2 1 3]);
size(R)Expected output:
ans = [1 5]Recovering logical masks after reordering axes
mask = false(2, 1, 3);
mask(1, 1, 2) = true;
rot = permute(mask, [3 1 2]);
orig = ipermute(rot, [3 1 2]);
orig(1,1,2)Expected output:
ans = logical 1Working with character arrays
chars = ['r','u','n'; 'm','a','t'];
T = permute(chars, [2 1]);
R = ipermute(T, [2 1]);
RExpected output:
R =
'run'
'mat'Restoring gpuArray tensors to host layout
G = gpuArray(rand(4, 2, 3));
H = permute(G, [3 1 2]);
R = ipermute(H, [3 1 2]);
isequal(gather(G), gather(R))Expected output:
ans = logical 1Using ipermute with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ipermute changes the result.
Run a small ipermute example, explain the result, then change one input and compare the output.
FAQ
Do I have to compute the inverse permutation myself?⌄
No. Pass the same order vector you used with permute; ipermute computes the inverse for you.
What happens if I pass an invalid permutation?⌄
RunMat raises an error when indices repeat, fall outside 1:n, or when the order vector is not a row or column vector.
Can ipermute introduce new singleton dimensions?⌄
Yes. If order is longer than ndims(A), trailing singleton dimensions are added just like MATLAB.
Does ipermute modify the input array in-place?⌄
No. It returns a new array with reordered metadata while leaving the original untouched.
How does ipermute behave for character arrays?⌄
Character arrays use the same N-D structural permutation machinery as their stored shape; identity and transpose are the two-dimensional cases.
Is gpuArray behaviour identical to MATLAB?⌄
RunMat preserves explicit gpuArray intent: a host fallback must restore through the owning provider or report an error. Automatically placed floating-point values may remain on the host when restoration upload is unsupported.
Does ipermute preserve data ordering?⌄
Yes. Column-major ordering is preserved. Applying permute followed by ipermute returns the original array exactly.
Can I use ipermute on scalar inputs?⌄
Numeric and logical scalar inputs use the existing numeric tensor adaptation and require an order covering the two-dimensional scalar shape. Complex scalar and scalar string inputs are unsupported.
What if the order vector is a gpuArray?⌄
MATLAB requires host numeric vectors for order specifications. RunMat enforces the same rule and raises an error.
Is there a performance benefit on the GPU?⌄
Yes when the provider implements the permute hook. Otherwise the fallback path behaves like MATLAB's gather/permut/gpuArray workflow.
Related Array functions
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · kron · permute · 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 ipermute is executed, line by line, in Rust.
- View the source for ipermute 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.