argsort — Return the permutation indices that would sort tensors along a dimension.

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 argsort works

• 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.

How RunMat runs argsort on the GPU

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

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)

FAQ

Related Array functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how argsort works, line by line, in Rust.

• View argsort.rs on GitHub
• Learn how the runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing