RunMat
GitHub

View all functions

CategoryArray: Sorting Sets
GPUYes

What does the argsort function do in MATLAB / RunMat?

argsort(X) returns the permutation indices that order X the same way sort(X) would. It matches the indices produced by [~, I] = sort(X, ...) in MathWorks MATLAB and honours the same argument forms for dimensions, directions, and comparison methods.

How does the argsort function behave in MATLAB / RunMat?

  • Operates along the first non-singleton dimension by default. Pass a dimension argument to override.
  • Accepts the same direction keywords as sort: 'ascend' (default) or 'descend'.
  • Supports 'ComparisonMethod' values 'auto', 'real', and 'abs' for real and complex inputs.
  • Returns indices as double-precision tensors using MATLAB's one-based indexing.
  • Treats NaN values as missing: they appear at the end for ascending permutations and at the beginning for descending permutations.
  • Acts as a residency sink. GPU tensors are gathered when the active provider does not expose a specialised sort kernel.

GPU execution in RunMat

  • argsort shares the sort_dim provider hook with the sort builtin. When implemented, indices are computed without leaving the device.
  • If the provider lacks sort_dim, RunMat gathers tensors to host memory, evaluates the permutation, and returns host-resident indices.
  • Outputs are always host-resident double tensors because permutation indices are consumed immediately by host-side logic (e.g., indexing).

Examples of using argsort in MATLAB / RunMat

Getting indices that sort a vector

A = [4; 1; 3];
idx = argsort(A);

Expected output:

idx =
     2
     3
     1

Reordering data with the permutation indices

A = [3 9 1 5];
idx = argsort(A);
sorted = A(idx);

Expected output:

sorted =
     1     3     5     9

Sorting along a specific dimension

A = [1 6 4; 2 3 5];
idx = argsort(A, 2);

Expected output:

idx =
     1     3     2
     1     2     3

Descending order permutations

A = [10 4 7 9];
idx = argsort(A, 'descend');

Expected output:

idx =
     1     4     3     2

Using ComparisonMethod to sort by magnitude

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

Expected output:

idx =
     2     4     3     1

Handling NaN values during permutation

A = [NaN 4 1 2];
idx = argsort(A);

Expected output:

idx =
     3     4     2     1

Argsort on GPU tensors falls back gracefully

G = gpuArray(randn(5, 1));
idx = argsort(G);

RunMat gathers G to the host when no device sort kernel is available, ensuring the returned indices match MATLAB exactly.

FAQ

How is argsort different from sort?

argsort returns only the permutation indices. It behaves like calling [~, I] = sort(X, ...) without materialising the sorted values.

Are the indices one-based like MATLAB?

Yes. All indices follow MATLAB's one-based convention so they can be used directly with subsequent indexing operations.

Does argsort support the same arguments as sort?

Yes. Dimension arguments, direction keywords, and 'ComparisonMethod' behave exactly like they do for sort.

How are NaN values ordered?

NaNs are treated as missing. They appear at the end for ascending permutations and at the beginning for descending permutations, matching MATLAB.

Can I call argsort on GPU arrays?

Yes. When the active provider implements the sort_dim hook, permutations stay on the device. Otherwise tensors are gathered automatically and sorted on the host.

Is the permutation stable?

Yes. Equal elements keep their relative order so that argsort remains consistent with MATLAB's stable sorting semantics.

What type is returned?

A double-precision tensor (or scalar) with the same shape as the input, containing permutation indices.

Does argsort mutate its input?

No. It only returns indices. Combine the result with indexing (A(idx)) to obtain reordered values when needed.

See also

sort, sortrows, randperm, max, min

Source & Feedback