ipermute — Reorder array dimensions using the inverse of a permutation vector.

ipermute(A, order) reverses the dimension reordering performed by permute(A, order). It is equivalent to permute(A, invOrder), where invOrder(order(i)) = i.

How ipermute works in RunMat

• 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 stay 2-D; only [1 2] (identity) and [2 1] (transpose) are valid orders.
• If the active acceleration provider lacks a dedicated permute kernel, RunMat gathers the data, applies the inverse permutation on the host, and re-uploads so the result remains a gpuArray.

How ipermute runs on the GPU

RunMat calls the provider's permute hook with the inverse order vector. Providers that support the hook perform the reorder entirely on the device. Otherwise RunMat gathers to the host, permutes, and uploads the result back to the GPU, matching MATLAB's gpuArray behaviour.

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 1

Restoring 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 1]

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 1

Working with character arrays

chars = ['r','u','n'; 'm','a','t'];
T = permute(chars, [2 1]);
R = ipermute(T, [2 1]);
R

Expected 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 1

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 remain 2-D. Only [1 2] and [2 1] orders are accepted; other permutations raise an error.

Is gpuArray behaviour identical to MATLAB?

Yes. Results remain gpuArray values. When providers lack a device kernel, RunMat gathers, permutes on the host, and uploads the result before returning.

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?

Absolutely. Scalars are treated as 0-D/1-D tensors so the result is the same scalar.

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 functions to explore

These functions work well alongside ipermute. Each page has runnable examples you can try in the browser.

permute, reshape, squeeze, size, ndims, gpuArray, gather, cat, circshift, diag, flip, fliplr, flipud, horzcat, kron, repmat, rot90, tril, triu, vertcat

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how ipermute works, line by line, in Rust.

• View ipermute.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing