ipermute

Inverse permute array dimensions

Syntax

A = ipermute(B,dimorder)

Description

A = ipermute(B,dimorder) rearranges the dimensions of an array B in the order specified by the vector dimorder such that B = permute(A,dimorder). In other words, the ith dimension of the input array becomes the dimension dimorder(i) in the output array.

Examples

Inverse Permutation of 2-D Matrix

Create a 4-by-3 matrix. Permute this matrix to switch the row and column dimensions.

A = [1 2 3; 4 5 6; 7 8 9; 10 11 12]

A = 4×3

     1     2     3
     4     5     6
     7     8     9
    10    11    12

B = permute(A,[2 1])

B = 3×4

     1     4     7    10
     2     5     8    11
     3     6     9    12

Perform an inverse permutation on this resulting matrix. The result is equal to the original matrix A.

C = ipermute(B,[2 1])

C = 4×3

     1     2     3
     4     5     6
     7     8     9
    10    11    12

Inverse Permutation of 3-D Array

Create a 4-by-3-by-2 array B. Compute its inverse permutation according to the dimension order [3 1 2].

rng default
B = rand(4,3,2)

B = 
B(:,:,1) =

    0.8147    0.6324    0.9575
    0.9058    0.0975    0.9649
    0.1270    0.2785    0.1576
    0.9134    0.5469    0.9706


B(:,:,2) =

    0.9572    0.4218    0.6557
    0.4854    0.9157    0.0357
    0.8003    0.7922    0.8491
    0.1419    0.9595    0.9340

A = ipermute(B,[3 1 2])

A = 
A(:,:,1) =

    0.8147    0.9572
    0.6324    0.4218
    0.9575    0.6557


A(:,:,2) =

    0.9058    0.4854
    0.0975    0.9157
    0.9649    0.0357


A(:,:,3) =

    0.1270    0.8003
    0.2785    0.7922
    0.1576    0.8491


A(:,:,4) =

    0.9134    0.1419
    0.5469    0.9595
    0.9706    0.9340

The inverse permutation A is the array such that, when you permute it using the same dimension order, the result is equal to the original array B.

C = permute(A,[3 1 2])

C = 
C(:,:,1) =

    0.8147    0.6324    0.9575
    0.9058    0.0975    0.9649
    0.1270    0.2785    0.1576
    0.9134    0.5469    0.9706


C(:,:,2) =

    0.9572    0.4218    0.6557
    0.4854    0.9157    0.0357
    0.8003    0.7922    0.8491
    0.1419    0.9595    0.9340

Input Arguments

B — Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array.

dimorder — Dimension order

row vector

Dimension order, specified as a row vector with unique, positive integer elements representing the dimensions of the input array.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function supports tall arrays with the limitation:

Permuting the tall dimension (dimension one) is not supported.

For more information, see Tall Arrays for Out-of-Memory Data.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• dimorder must be a fixed-size row vector.

• If B is a heterogeneous cell array, dimorder must be a constant. To learn more about heterogeneous cell arrays, see Code Generation for Cell Arrays (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The ipermute function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The ipermute function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

The ipermute function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a