gpucoder.sort

Optimized GPU implementation of the MATLAB sort function

Syntax

B = gpucoder.sort(A)

B = gpucoder.sort(A,dim)

B = gpucoder.sort(A,direction)

[B,I] = gpucoder.sort(A,...)

Description

B = gpucoder.sort(A) sorts the elements of an array A, and the generated CUDA^® code from gpucoder.sort performs the sort operation on the GPU. The function sorts A along the first non-singleton dimension. For example:

• If A is a vector, gpucoder.sort(A) sorts the elements of A,

• If A is a matrix, gpucoder.sort(A) sorts the elements of each column of A.

The sorted output in B has the same type and size as A.

B = gpucoder.sort(A,dim) has the optional argument dim that specifies the dimension along which the sort operation is performed.

B = gpucoder.sort(A,direction) has the optional argument direction that specifies the sort direction. direction can take one of two values:

• 'ascend' - Sorts in the ascending order. This is the default option.

• 'descend' - Sorts in the descending order.

[B,I] = gpucoder.sort(A,...) returns a sort index I which specifies how the elements of A were rearranged to obtain the sorted output B.

• If A is a vector, then B = A(I).

• If A is an m-by-n matrix and dim = 1, then

  for j = 1:n
    B(:,j) = A(I(:,j),j);
  end

The sort ordering is stable. Namely, when more than one element has the same value, the order of the equal elements is preserved in the sorted output B and the indices I relating to equal elements are ascending.

When gpucoder.sort is called from MATLAB^®, it uses the built-in sort function.

Examples

Sort a Matrix

This example generates CUDA code to sort the columns of a matrix in descending order.

In one file, write an entry-point function mySort that accepts a matrix inputs A. Use the gpucoder.sort function to sort the columns of A in descending order.

function B = mySort(A)
     B = gpucoder.sort(A, 1, 'descend');
end

Use the codegen function to generate CUDA MEX function.

codegen -config coder.gpuConfig('mex') -args {ones(1024,1024,'double')} -report mySort

Input Arguments

A — Input array

vector | matrix | multidimensional array

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

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char

dim — Dimension to operate along

positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If no value is specified, then the default is the first array dimension whose size does not equal 1.

sort returns A if dim is greater than ndims(A). dim is not supported when A is a cell array, that is, sort only operates along the first array dimension whose size does not equal 1.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

direction — Sorting direction

'ascend' (default) | 'descend'

Sorting direction, specified as 'ascend' or 'descend'. direction is not supported when A is a cell array, that is, sort only sorts in ascending order.

Output Arguments

B — Sorted array

vector | matrix | multidimensional array

Sorted array, returned as a vector, matrix, or multidimensional array. B is the same size and type as A. The order of the elements in B preserves the order of equal elements in A.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char

I — Sort index

vector | matrix | multidimensional array

Sort index, returned as a vector, matrix, or multidimensional array. I is the same size as A. The index vectors are oriented along the same dimension that sort operates on. For example, if A is a 2-by-3 matrix, then [B,I] = sort(A,2) sorts the elements in each row of A. The output I is a collection of 1-by-3 row index vectors describing the rearrangement of each row of A.

Limitations

• gpucoder.sort does not support complex numbers.

• gpucoder.sort does not support 'MissingPlacement' and 'ComparisonMethod' name-value pairs supported by the MATLAB sort function.

Version History

Introduced in R2018b

R2025a: Improved GPU code generation when using GPU Memory Manager

If you enable the GPU Memory Manager and use CUDA Toolkit version 11.6 or newer, generated CUDA code from the gpucoder.sort function has improved performance. The GPU Memory Manager allocates, frees, and manages GPU memory. For more information about the GPU Memory Manager, see How Shared GPU Memory Manager Improves Performance of Generated MEX.