find — Locate nonzero indices and values with exact integer and GPU-aware semantics.
find(X) returns the 1-based indices of nonzero elements in column-major order. The documented input classes are single, double, all eight integer classes, logical, and char, including complex numeric arrays. With three outputs, v preserves the selected value class and authoritative integer values.
Syntax
idx = find(X)
idx = find(X, K)
idx = find(X, K, direction)
[row, col] = find(X)
[row, col] = find(X, K, direction)
[row, col, v] = find(X)
[row, col, v] = find(X, K, direction)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input array to search. |
K | NumericScalar | Yes | — | Maximum number of indices to return. |
direction | StringScalar | Yes | "first" | Direction selector: `"first"` or `"last"`. |
Returns
| Name | Type | Description |
|---|---|---|
idx | NumericArray | Linear indices of non-zero elements. |
row | NumericArray | Row subscripts of non-zero elements. |
col | NumericArray | Column subscripts of non-zero elements. |
v | Any | Values at the reported row/column locations. |
Returned values from find depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:find:InvalidInput | Input type or option arguments are not valid for find. | find: invalid input arguments |
RunMat:find:ProviderOutput | GPU provider does not return expected output buffers for requested nargout. | find: provider output buffer mismatch |
RunMat:find:InternalError | Internal tensor conversion/materialization fails while building outputs. | find: internal error |
How find works
- For one output, a row-vector input produces a row vector of indices; every other nonspecial input produces a column vector.
find([])andfind(0)use MATLAB's empty-matrix convention and return[]; other empty or all-zero row vectors return1×0, and other empty results return0×1.find(X,K)requires a positive integer scalar K. Typed K values are converted exactly and zero, negative, fractional, nonfinite, or out-of-platform-range values reject before X is traversed.find(X,K,'first')scans from the start.find(X,K,'last')selects the last K matches but returns them in ascending linear-index order.[row,col,v] = find(X)returns column vectors. For N-D X, col linearizes the trailing dimensions.- Integer and complex-integer inputs use authoritative storage for zero testing and preserve exact v values above flintmax. Logical v remains logical and single v remains single.
- Typed-integer sparse storage is a gated RunMat extension because MATLAB sparse value storage is single, double, or logical.
find(X,direction)without K is a gated RunMat convenience extension; the documented MATLAB form isfind(X,K,direction).
Does RunMat run find on the GPU?
Provider execution is limited to cases where the owning provider can produce exact double indices. Other resident integer inputs gather exactly through their owning provider, compute on the host, and restore outputs through that same provider even when another provider is active.
GPU memory and residency
F64 real inputs use the owning provider's hook when available. F32, logical, and integer resident inputs take a correctness-first host fallback because index outputs must be exact doubles and v must preserve its input class; fallback outputs are re-uploaded through that same owner so they remain resident on the input device.
Examples
Find linear indices
A = [0 4 0; 7 0 9];
k = find(A)Expected output:
k =
2
4
6Find the final two matches
A = [1 0 2 3 0];
k = find(A,2,'last')Expected output:
k =
3
4Preserve integer values
A = uint64([0 9007199254740993]);
[r,c,v] = find(A)Expected output:
r = 1
c = 2
v = uint64(9007199254740993)Using find with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how find changes the result.
Run a small find example, explain the result, then change one input and compare the output.
FAQ
What counts as nonzero?⌄
A real value is nonzero when it is not exact zero. A complex value is nonzero when either component is nonzero. NaN and infinities are nonzero.
Are index outputs integers?⌄
No. MATLAB-compatible k, row, and col outputs are double. RunMat rejects an index that cannot be represented exactly as binary64 instead of silently rounding it.
What happens on an f32 GPU provider?⌄
RunMat gathers and computes the result on the host so double indices remain exact, then re-uploads the outputs through the input handle's owning provider to preserve gpuArray residency and device ownership. An f64 provider can execute the operation natively.
Does the third output preserve integer values?⌄
Yes. v preserves all eight integer classes exactly, including int64 and uint64 values above flintmax.
Why can strict compatibility reject find(X,'last')?⌄
MATLAB documents direction only after K. Enable RunMat extensions to use the direction-only convenience form, or write find(X,1,'last').
Related Array functions
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how find is executed, line by line, in Rust.
- View the source for find in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.