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

How argsort runs 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

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.

Related functions to explore

These functions work well alongside argsort. Each page has runnable examples you can try in the browser.

sort, sortrows, randperm, max, min, intersect, ismember, issorted, setdiff, union, unique

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