RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

What does the ipermute function do in MATLAB / RunMat?

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 does the ipermute function behave in MATLAB / 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.

ipermute Function GPU Execution Behaviour

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 of using the ipermute function in MATLAB / RunMat

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

  1. 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.
  2. 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.
  3. Can ipermute introduce new singleton dimensions?
    Yes. If order is longer than ndims(A), trailing singleton dimensions are added just like MATLAB.
  4. Does ipermute modify the input array in-place?
    No. It returns a new array with reordered metadata while leaving the original untouched.
  5. 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.
  6. 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.
  7. Does ipermute preserve data ordering?
    Yes. Column-major ordering is preserved. Applying permute followed by ipermute returns the original array exactly.
  8. Can I use ipermute on scalar inputs?
    Absolutely. Scalars are treated as 0-D/1-D tensors so the result is the same scalar.
  9. 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.
  10. 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/permute/gpuArray workflow.

See Also

Source & Feedback