RunMat
GitHub

View all functions

CategoryArray: Sorting Sets
GPUYes

What does the sort function do in MATLAB / RunMat?

sort orders the elements of its input along a chosen dimension. By default, it sorts ascending along the first non-singleton dimension and can also return the permutation indices that achieve the ordering.

How does the sort function behave in MATLAB / RunMat?

  • Scalars remain unchanged; vectors are reordered into ascending or descending order.
  • For matrices and higher-dimensional tensors, the sort operates along a specified dimension (default: first non-singleton). All other dimensions remain untouched.
  • [B, I] = sort(A, ...) returns both the sorted values B and the permutation indices I, using MATLAB's one-based indexing.
  • Direction arguments accept 'ascend' (default) or 'descend'.
  • Name-value pairs support 'ComparisonMethod' with values 'auto', 'real', or 'abs'. The 'abs' option sorts by absolute value while breaking ties using the signed value.
  • For complex inputs, the default 'ComparisonMethod'='auto' behaves like 'abs' (magnitude ordering) and 'real' compares the real component first with the imaginary component used for tie-breaking.
  • NaN values are treated as missing: they appear at the end for ascending sorts and at the beginning for descending sorts (matching MATLAB's 'MissingPlacement','auto' behaviour for doubles).
  • Dimensions greater than ndims(A) are treated as singleton dimensions (size 1) and therefore leave A unchanged while returning index values of 1.

GPU execution in RunMat

  • sort is registered as a sink builtin. When tensors reside on a GPU without a specialised sort kernel, RunMat gathers them to host memory, performs the sort, and returns host-resident outputs.
  • Providers may implement a future sort_dim hook to keep data on the GPU. Until then, all providers fall back to the host path automatically.
  • The returned index tensor is always host-resident double precision.

Examples of using sort in MATLAB / RunMat

Sorting a column vector in ascending order

A = [3; 1; 2];
B = sort(A);

Expected output:

B =
     1
     2
     3

Sorting rows by specifying the dimension

A = [1 4 2; 3 2 5];
B = sort(A, 2);

Expected output:

B =
     1     2     4
     2     3     5

Sorting values in descending order

A = [10 4 7 9];
B = sort(A, 'descend');

Expected output:

B =
    10     9     7     4

Retrieving permutation indices alongside the sorted values

A = [4 1 9 2];
[B, I] = sort(A);

Expected output:

B =
     1     2     4     9
I =
     2     4     1     3

Sorting by absolute value using ComparisonMethod

A = [-8 -1 3 -2];
B = sort(A, 'ComparisonMethod', 'abs');

Expected output:

B =
    -1    -2     3    -8

Sorting tensors containing NaN values

A = [NaN 4 1 2];
[B, I] = sort(A);

Expected output:

B =
     1     2     4   NaN
I =
     3     4     2     1

Sorting GPU tensors with automatic host fallback

G = gpuArray(randn(5, 1));
[B, I] = sort(G, 'descend');

The runtime gathers G, performs the sort on the host, and returns host-resident results. The ordering matches MATLAB's semantics exactly.

FAQ

Can sort return both values and indices?

Yes. Use [B, I] = sort(A, ...) to receive the permutation indices alongside the sorted values.

How are NaN values handled?

NaN values are considered missing. They appear last for ascending sorts and first for descending sorts, matching MATLAB's 'MissingPlacement','auto' default for doubles.

What happens when I sort along a dimension that does not exist?

sort(A, dim) treats dimensions beyond ndims(A) as singleton dimensions (size 1). The data remains unchanged and the index output is filled with ones.

Does sort support name-value arguments?

Yes. 'ComparisonMethod' accepts 'auto', 'real', or 'abs'. Other name-value pairs such as 'MissingPlacement' are currently not supported and raise an error.

Are GPU tensors sorted in-place?

Not yet. sort is a sink builtin that gathers GPU tensors to host memory when no GPU sort kernel is available. Providers can implement specialised hooks in the future.

Does sort preserve the shape of the input?

Yes. The output is the same size as the input tensor. Only values along the selected dimension are reordered.

What numeric type do the index outputs use?

Permutation indices are returned as double-precision tensors (or scalars) using MATLAB's one-based indexing.

Is the sorting stable?

Yes. Equal elements (including ties when sorting by absolute value) preserve their original order.

How does ComparisonMethod behave with real inputs?

'auto' and 'real' behave identically. 'abs' sorts by absolute value and uses the signed value to break ties so that results match MATLAB.

How does ComparisonMethod behave with complex inputs?

'auto' (the default) and 'abs' order values by magnitude. 'real' compares the real component first and falls back to the imaginary component to break ties while preserving stability.

Do logical or scalar inputs work?

Yes. Logical inputs are promoted to double precision automatically. Scalars are returned unchanged with an index output of 1 when requested.

See also

sortrows, unique, max, min, permute

Source & Feedback