RunMat
GitHub

View all functions

CategoryArray: Indexing
GPUYes

What does the find function do in MATLAB / RunMat?

find(X) returns the indices of nonzero elements of X. With a single output it produces MATLAB's 1-based linear indices. With multiple outputs it returns row/column (and optionally value) vectors describing each nonzero element.

How does the find function behave in MATLAB / RunMat?

  • find(X) scans in column-major order and returns a column vector of linear indices.
  • find(X, K) limits the result to the first K matches; K = 0 yields an empty result.
  • find(X, K, 'first') (default) scans from the start, while 'last' scans from the end.
  • find(X, 'last') is equivalent to find(X, 1, 'last') and returns the final nonzero index.
  • [row, col] = find(X) returns per-element row and column subscripts for 2-D or N-D inputs (higher dimensions are flattened into the column index, matching MATLAB semantics).
  • [row, col, val] = find(X) also returns the corresponding values; complex inputs preserve their complex values.
  • Logical, char, integer, and double inputs are all supported. Empty inputs return empty outputs with MATLAB-compatible shapes.

find Function GPU Execution Behaviour

When the input already resides on the GPU (i.e., a gpuArray), RunMat gathers it if the active provider does not implement a dedicated find kernel, performs the computation on the host, and then uploads the results back to the provider. This preserves residency so downstream fused kernels can continue on the device without an explicit gather. Providers may implement a custom hook in the future to run find entirely on the GPU; until then, the automatic gather/upload path maintains correctness with a small one-off cost.

Examples of using the find function in MATLAB / RunMat

Finding linear indices of nonzero elements

A = [0 4 0; 7 0 9];
k = find(A);

Expected output:

k =
     2
     4
     6

Limiting the number of matches

A = [0 3 5 0 8];
first_two = find(A, 2);

Expected output:

first_two =
     2
     3

Locating the last nonzero element

A = [1 0 0 6 0 2];
last_index = find(A, 'last');

Expected output:

last_index =
     6

Retrieving row and column subscripts

A = [0 4 0; 7 0 9];
[rows, cols] = find(A);

Expected outputs:

rows =
     2
     1
     2

cols =
     1
     2
     3

Capturing values alongside indices (including complex inputs)

Z = [0 1+2i; 0 0; 3-4i 0];
[r, c, v] = find(Z);

Expected outputs:

r =
     1
     3

c =
     1
     1

v =
   1.0000 + 2.0000i
   3.0000 - 4.0000i

GPU residency in RunMat (Do I need gpuArray?)

Usually you do not need to move data with gpuArray manually. If a provider backs find directly, the entire operation stays on the GPU. Otherwise, RunMat gathers once, computes on the host, and then uploads results back to the active provider so subsequent kernels remain device-resident. This means GPU pipelines continue seamlessly without additional gather/gpuArray calls from user code.

FAQ

What elements does find consider nonzero?

Any element whose real or imaginary component is nonzero. For logical inputs, true maps to 1 and is considered nonzero; false is ignored.

How are higher-dimensional arrays handled when requesting row/column outputs?

find treats the first dimension as rows and flattens the remaining dimensions into the column index, matching MATLAB's column-major storage.

What happens when I request more matches than exist?

find returns all available nonzero elements—no error is raised. For example, find(A, 10) simply returns every nonzero in A if it has fewer than 10.

Does find support char arrays and integers?

Yes. Characters are converted to their numeric code points during the test for nonzero values; integers are promoted to double precision for the result vectors.

Can I run find entirely on the GPU today?

Not yet. The runtime gathers GPU inputs, computes on the host, and re-uploads results. Providers can implement the optional find hook to make the entire path GPU-native in the future.

What shapes do empty results take?

When no element matches, the returned arrays are 0×1 column vectors, just like MATLAB.

How does find interact with fusion or auto-offload?

find is a control-flow style operation, so it does not participate in fusion. Auto-offload still keeps data resident on the GPU where possible by uploading results after the host computation.

Does find preserve complex values in the third output?

Yes. When you request the value output, complex inputs return a complex column vector that matches MATLAB's behaviour.

Can I combine find with gpuArray explicitly?

Absolutely. If you call find(gpuArray(X)), the runtime ensures outputs stay on the GPU so later GPU-aware builtins can consume them without additional transfers.

Is there a way to obtain subscripts for every dimension?

Use find to get linear indices and then call ind2sub(size(X), ...) if you need explicit per-dimension subscripts for N-D arrays.

See Also

ind2sub, sub2ind, logical, gpuArray

Source & Feedback