RunMat
GitHub

View all functions

CategoryArray: Indexing
GPUYes

What does the sub2ind function do in MATLAB / RunMat?

sub2ind(sz, s1, s2, ...) converts row/column (or higher-dimensional) subscripts into MATLAB's column-major linear indexing form. The size vector sz defines the extents of the target array, and you must supply one subscript array per dimension.

How does the sub2ind function behave in MATLAB / RunMat?

  • Subscripts can be scalars or arrays. When arrays are provided, they must share the same size. Scalars broadcast to that common shape.
  • All subscripts must be positive integers within the corresponding dimension's range.
  • The size vector can be a row or column vector. Each element must be a positive integer.
  • Complex, NaN, or infinite values are rejected.
  • The result uses the same shape as the subscript arrays. Scalars produce a scalar double.
  • When any input is a GPU tensor, RunMat computes on the host (to reuse integer semantics) and uploads the resulting indices back to the GPU so fusion and downstream kernels keep operating on device.

sub2ind Function GPU Execution Behaviour

When a WGPU-backed provider is active, sub2ind executes entirely on the GPU. The shader mirrors MATLAB's validation rules: it rejects non-finite values, non-integer subscripts, and out-of-range indices, surfacing the same diagnostic messages as the CPU path. Providers that do not yet implement the hook fall back to the host implementation; after the indices are computed they are uploaded back to the active provider so downstream fused kernels continue operating on device data.

Examples of using the sub2ind function in MATLAB / RunMat

Converting a single matrix subscript to a linear index

idx = sub2ind([3 4], 2, 3);

Expected output:

idx = 8;

Mapping multiple subscripts into one-dimensional indices

rows = [1; 2; 3];
cols = [3; 3; 3];
idx = sub2ind([3 5], rows, cols);

Expected output:

idx =
     7
     8
     9

Handling higher-dimensional array subscripts

row = [1 1];
col = [2 3];
page = [1 2];
idx = sub2ind([2 3 4], row, col, page);

Expected output:

idx = [3 11];

Broadcasting scalar subscripts across array inputs

rows = [1 2 3];
idx = sub2ind([3 4], rows, 4);

Expected output:

idx = [10 11 12];

Retaining GPU residency for batched index conversions

rows = gpuArray((1:100)');
cols = gpuArray(ones(100, 1) * 4);
idx = sub2ind([100 4], rows, cols);

Expected behavior:

% idx remains a gpuArray containing the column-major indices.
disp(gather(idx(1:5)));
% Output:
%    301
%    302
%    303
%    304
%    305

Detecting invalid out-of-range subscripts

try
    idx = sub2ind([3 4], 4, 1);
catch ME
    disp(ME.message);
end

Expected output:

Index exceeds the number of rows in dimension 1.

GPU residency in RunMat (Do I need gpuArray?)

You typically do not need to call gpuArray yourself. When the active provider implements the sub2ind hook (WGPU today), the entire conversion runs on the GPU and returns a device tensor. If no provider is available, or the provider lacks the hook, RunMat falls back to the host implementation and uploads the resulting indices back to the GPU so residency is maintained automatically.

FAQ

What data types does sub2ind accept?

Numeric and logical inputs are accepted. Logical values are converted to doubles before validation. Complex, NaN, and infinite values are rejected with a descriptive error.

Can the size vector contain zeros?

No. Every dimension size must be a positive integer. This matches MATLAB's behavior for index conversion.

Do subscripts have to be the same size?

Yes. All non-scalar subscripts must share the same size (shape). Scalars broadcast to that common shape.

What happens when subscripts are out of range?

sub2ind throws an error explaining which dimension failed the bounds check. This mirrors MATLAB's run-time error.

Does the function support GPU arrays?

Yes. With the WGPU provider the conversion happens entirely on device, including validation. Other providers gather the data to the host, compute the indices, and upload them back to the device automatically.

Are fractional subscripts rounded?

No. Non-integer, NaN, or infinite subscripts raise an error.

How is the linear index computed?

The output uses MATLAB's column-major convention: 1 + sum((s_k - 1) * stride_k) where stride_k is the product of the preceding dimensions.

Can I call sub2ind with more subscripts than dimensions?

No. You must pass exactly one subscript per dimension listed in the size vector.

What about empty outputs?

If the subscript arrays are empty, sub2ind returns an empty double array with the same shape.

Does sub2ind change the orientation of row/column vectors?

No. The output preserves the orientation (shape) of the subscript arrays, so row vectors stay row vectors and column vectors stay column vectors.

See Also

ind2sub, find, size, gpuArray, gather

Source & Feedback