permute

Permute array dimensions

Syntax

B = permute(A,dimorder)

Description

B = permute(A,dimorder) rearranges the dimensions of an array in the order specified by the vector dimorder. For example, permute(A,[2 1]) switches the row and column dimensions of a matrix A. In general, the ith dimension of the output array is the dimension dimorder(i) from the input array.

example

Examples

collapse all

3-D Array

Open Live Script

Create a 3-by-4-by-2 array and permute it so that the first and third dimensions are switched, resulting in a 2-by-4-by-3 array.

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

A = 
A(:,:,1) =

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


A(:,:,2) =

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

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

B = 
B(:,:,1) =

    0.8147    0.9134    0.2785    0.9649
    0.9572    0.1419    0.7922    0.0357


B(:,:,2) =

    0.9058    0.6324    0.5469    0.1576
    0.4854    0.4218    0.9595    0.8491


B(:,:,3) =

    0.1270    0.0975    0.9575    0.9706
    0.8003    0.9157    0.6557    0.9340

szB = size(B)

szB = 1×3

     2     4     3

Input Arguments

collapse all

`A` — 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 that represent 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:

Dimension order must be compile-time constant for heterogeneous cell array inputs. For more information, see Code Generation for Cell Arrays (MATLAB Coder).
See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This 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 permute 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™.

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

Version History

Introduced before R2006a

expand all

R2019b: Noninteger or complex dimension order arguments produce error

Starting in R2019b, the syntax permute(A,dimorder) produces an error when dimorder is a noninteger or complex value. Instead, specify real, positive integer values for dimorder.

permute

Syntax

Description

Examples

3-D Array

Input Arguments

A — Input array vector | matrix | multidimensional array

dimorder — Dimension order row vector

Extended Capabilities

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

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

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

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