RunMat
GitHub

View all functions

CategoryArray: Shape
GPUYes

permute — Reorder the dimensions of arrays, tensors, logical masks, and gpuArray values.

permute(A, order) rearranges the dimensions of A to match the order specified by the integer vector order. It works for numeric arrays, logical masks, complex arrays, string arrays, and gpuArray values. Dimensions not explicitly mentioned in the original array become size-one axes.

How does the permute function behave in MATLAB / RunMat?

  • 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, 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.

GPU behavior

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 of using permute in MATLAB / RunMat

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 1

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.

See also

ipermute, reshape, squeeze, size, ndims, gpuArray, gather

Source & Feedback