RunMat
GitHub

View all functions

CategoryArray: Indexing
GPUYes

What does the ind2sub function do in MATLAB / RunMat?

ind2sub(siz, idx) converts MATLAB's 1-based column-major linear indices back into the individual subscripts for each dimension specified in siz.

How does the ind2sub function behave in MATLAB / RunMat?

  • The size vector siz supplies one extent per dimension. Each entry must be a positive integer.
  • idx can be a scalar or an array of any shape; every element must be a positive integer within prod(siz).
  • The result is always a 1×N cell array (N is numel(siz)). Each cell contains a double array that matches the shape of idx.
  • Non-integer, complex, NaN, Inf, or out-of-range indices raise MATLAB-compatible errors.
  • Empty inputs produce empty outputs with matching shapes.
  • When called with multiple outputs ([i,j,k] = ind2sub(...)) RunMat unpacks the cell array automatically, mirroring MATLAB semantics.

ind2sub Function GPU Execution Behaviour

When a WGPU-backed provider is active, ind2sub executes entirely on the GPU. The shader mirrors MATLAB's validation rules, rejecting non-integer, non-positive, or out-of-range indices with the same diagnostic messages as the CPU path. Providers that do not yet implement the hook fall back to the host implementation; after computing the subscripts RunMat uploads the results back to the active provider so downstream fused kernels continue operating on device-resident data.

Examples of using the ind2sub function in MATLAB / RunMat

Recovering row and column subscripts from a matrix index

[row, col] = ind2sub([3 4], 8);

Expected output:

row = 2;
col = 3;

Extracting multiple matrix indices at once

idx = [7 8 9];
[rows, cols] = ind2sub([3 5], idx);

Expected output:

rows = [1 2 3];
cols = [3 3 3];

Converting indices for a 3-D volume

idx = [3 11];
[r, c, p] = ind2sub([2 3 4], idx);

Expected output:

r = [1 1];
c = [2 3];
p = [1 2];

Keeping indices on the GPU

rows = gpuArray([1; 2; 3]);
cols = gpuArray([4; 4; 4]);
lin = sub2ind([3 4], rows, cols);
subs = ind2sub([3 4], lin);  % subs{1} and subs{2} remain gpuArray values
class(subs{1})
class(subs{2})

Expected output:

ans =
    'gpuArray'

ans =
    'gpuArray'

Using a single output cell for flexible unpacking

subs = ind2sub(size(magic(4)), 6:9);
% Access with subs{1}, subs{2}, ...

Expected output:

subs =
  1×2 cell array
    {1×4 double}    {1×4 double}

Validating index ranges before reshaping

idx = 1:numel(A);
[i, j] = ind2sub(size(A), idx);
B = accumarray([i(:) j(:)], A(:));

GPU residency in RunMat (Do I need gpuArray?)

You typically do not need to convert tensors manually. When the active provider implements the ind2sub hook (WGPU today), the entire conversion stays on the GPU. Otherwise RunMat gathers the inputs, performs validation on the host, and uploads the resulting subscript arrays back to the device so downstream kernels or fusion plans can continue using them without additional gather calls.

FAQ

What types does ind2sub accept for idx?

Numeric and logical inputs are accepted. Logical arrays are treated as double precision (with true → 1, false → 0); complex values are rejected.

Can siz contain zeros?

No. Each element of siz must be a positive integer, matching MATLAB behaviour.

How are errors reported for invalid indices?

Indices that are non-integer, non-positive, or exceed prod(siz) raise errors matching MATLAB's wording (e.g., "Index exceeds number of array elements. Index must not exceed …").

What shape do the output arrays have?

Each output array matches the shape of idx. Scalars produce scalar doubles; vectors remain vectors; higher-dimensional shapes are preserved.

Does ind2sub support GPU arrays?

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

Can I request fewer outputs than dimensions?

Yes. In a multi-output context RunMat provides as many outputs as requested in order, just like MATLAB. Any additional dimensions are still available inside the single-output cell if you need them.

How does ind2sub relate to sub2ind?

They are inverse operations: sub2ind turns subscripts into linear indices, while ind2sub recovers subscripts from those linear indices.

Does ind2sub allocate full copies of the outputs?

Yes. Each subscript array is materialised as a dense double array matching the shape of idx, mirroring MATLAB semantics.

What happens with empty inputs?

Empty index arrays produce empty subscript arrays with the same shape.

Can I use ind2sub with more dimensions than two?

Definitely—ind2sub works for any number of dimensions represented in siz.

See Also

sub2ind, size, find, gpuArray, gather

Source & Feedback