runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/imfilter.js

@@ -0,0 +1,143 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "imfilter",
+    "category": "image/filters",
+    "keywords": [
+        "imfilter",
+        "filter",
+        "image",
+        "convolution",
+        "correlation",
+        "padding"
+    ],
+    "summary": "Filter images or N-D arrays with correlation/convolution kernels and configurable padding.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Executes on the active acceleration provider when the 'imfilter' hook is implemented; otherwise RunMat gathers to the host automatically."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::image::filters::imfilter::tests",
+        "integration": "builtins::image::filters::imfilter::tests::gpu_fallback_uses_provider_upload"
+    },
+    "description": "`imfilter` applies N-D linear filters (correlation or convolution) to numeric or logical arrays. It provides MATLAB-compatible padding modes (`'replicate'`, `'symmetric'`, `'circular'`, `'fill'`), supports `'same'`, `'full'`, and `'valid'` output sizing, and can operate on GPU-resident tensors when RunMat Accelerate exposes the dedicated provider hook.",
+    "behaviors": [
+        "By default it performs correlation (`'corr'`) and returns an array the same size as the input (`'same'`) using zero padding.",
+        "Passing `'fill'` without an explicit value (or supplying a numeric scalar on its own) is equivalent to zero padding; the numeric argument can appear before or after the `'fill'` flag.",
+        "Convolution mode is available via the `'conv'` flag and matches `convn` semantics.",
+        "Padding modes control how out-of-bound indices are resolved: zero-fill (default `'fill'`/`'fill', 0` or a numeric pad value), `'replicate'`, `'symmetric'`, or `'circular'`.",
+        "Output sizing options determine whether RunMat crops (`'same'`), keeps the full convolution result (`'full'`), or returns only pixels covered completely by the kernel (`'valid'`).",
+        "Kernels may be generated by `fspecial` or authored manually; no automatic normalisation is applied.",
+        "Logical inputs are promoted to double precision (0.0/1.0) and all results are returned as double-precision tensors for MATLAB compatibility.",
+        "Multi-channel and higher-dimensional arrays are supported provided the filter dimensions are 1 along trailing axes that do not exist in the image."
+    ],
+    "examples": [
+        {
+            "description": "Smoothing an image with a 3x3 average filter",
+            "input": "I = [1 2; 3 4];\nH = ones(3) / 9;\nJ = imfilter(I, H);          % default zero padding, correlation",
+            "output": "J =\n    1.1111    1.1111\n    1.1111    1.1111"
+        },
+        {
+            "description": "Preserving borders with replicate padding",
+            "input": "I = magic(3);\nH = ones(3);\nJ = imfilter(I, H, 'replicate')",
+            "output": "J =\n    45    45    45\n    45    45    45\n    45    45    45"
+        },
+        {
+            "description": "Computing the full convolution result",
+            "input": "I = [1 2; 3 4];\nH = [1 2; 3 4];\nJ = imfilter(I, H, 'full')",
+            "output": "J =\n     0     0     0\n     0     4    11\n     0    14    30"
+        },
+        {
+            "description": "Switching to convolution mode",
+            "input": "I = reshape(1:6, [3 2]);\nH = [1 2; 3 4];\nJ = imfilter(I, H, 'conv');      % equivalent to convn(I, rot90(H,2), 'same')",
+            "output": "J =\n     1     6\n     5    25\n     9    35"
+        },
+        {
+            "description": "Wrapping edges with circular padding",
+            "input": "I = [1 2; 3 4];\nH = [0 1; 1 0];\nJ = imfilter(I, H, 'circular')",
+            "output": "J =\n     5     5\n     5     5"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which modes does `imfilter` support?",
+            "answer": "The builtin accepts `'corr'` (default) or `'conv'` to switch between correlation and convolution. Convolution is equivalent to correlating with the kernel rotated 180° in each dimension."
+        },
+        {
+            "question": "How do `'same'`, `'full'`, and `'valid'` differ?",
+            "answer": "`'same'` crops the result to the input size, `'full'` preserves every contribution from the convolution, and `'valid'` keeps only elements where the kernel lies fully within the original array (possibly returning empty slices)."
+        },
+        {
+            "question": "How does zero padding differ from `'fill'`?",
+            "answer": "Passing a numeric scalar (or the `'fill', padval` sequence) pads the image with that constant value. The default behaviour is equivalent to `'fill', 0`."
+        },
+        {
+            "question": "Can I filter RGB or higher-dimensional arrays?",
+            "answer": "Yes. The kernel must either match each image dimension or use size 1 along trailing axes (e.g., a 3×3×1 filter applied independently to each colour channel)."
+        },
+        {
+            "question": "Does `imfilter` normalise the kernel automatically?",
+            "answer": "No. The kernel is used exactly as supplied. Utilities such as `fspecial('average', ...)` or manual scaling should be used when normalisation is desired."
+        },
+        {
+            "question": "What happens when the kernel is larger than the image?",
+            "answer": "For `'same'` and `'full'`, the builtin applies the filter with the chosen padding, producing sensible output. `'valid'` returns an empty array for dimensions where the kernel exceeds the image size."
+        },
+        {
+            "question": "How does `imfilter` interact with the fusion planner?",
+            "answer": "The builtin registers a custom GPU spec rather than a fusion template. The planner treats it as a standalone op, enabling provider specialisation without attempting to fold it into generic fusion chains."
+        },
+        {
+            "question": "Is logical input supported?",
+            "answer": "Yes. Logical arrays are promoted to double precision (0.0/1.0) during filtering, mirroring MATLAB behaviour."
+        }
+    ],
+    "links": [
+        {
+            "label": "fspecial",
+            "url": "./fspecial"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "filter2",
+            "url": "./filter2"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/image/filters/imfilter.rs",
+        "url": "crates/runmat-runtime/src/builtins/image/filters/imfilter.rs"
+    },
+    "gpu_residency": "RunMat automatically keeps tensors on the GPU when the acceleration provider implements the `imfilter` hook, so explicit `gpuArray` calls are rarely necessary. For backwards compatibility and manual residency control, you may still wrap inputs in `gpuArray`; the builtin forwards handles directly to the provider. When the hook is absent, RunMat gathers arrays to the host transparently, ensuring functional parity with MATLAB even without a GPU implementation.",
+    "gpu_behavior": [
+        "When the active acceleration provider implements the custom `imfilter` hook, the builtin keeps the image and kernel on the device, honouring padding and size options without host round-trips. Mixed-residency inputs are handled automatically: device images cause host kernels to be uploaded on demand, and failures to upload or execute simply fall back to the reference path. Providers that do not yet expose this hook trigger a transparent fallback—RunMat gathers the operands to the host, executes the scalar reference implementation, and (when appropriate) returns a host tensor. This guarantees correctness while still allowing future GPU acceleration with no API surface changes."
+    ],
+    "key": "imfilter",
+    "slug": "imfilter",
+    "categoryPath": [
+        "image",
+        "filters"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=imfilter.js.map

package/dist/generated/builtins/imfilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imfilter.js","sourceRoot":"","sources":["../../../src/generated/builtins/imfilter.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/ind2sub.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=ind2sub.d.ts.map

package/dist/generated/builtins/ind2sub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ind2sub.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/ind2sub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAwJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/ind2sub.js

@@ -0,0 +1,157 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ind2sub",
+    "category": "array/indexing",
+    "keywords": [
+        "ind2sub",
+        "linear index",
+        "subscripts",
+        "column major",
+        "gpu",
+        "nd indexing"
+    ],
+    "summary": "Convert MATLAB column-major linear indices into per-dimension subscript arrays.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "When the active provider implements the `ind2sub` hook (WGPU today), conversions run entirely on the GPU. Other providers fall back to the host and re-upload the results."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::indexing::ind2sub::tests",
+        "integration": "builtins::array::indexing::ind2sub::tests::ind2sub_gpu_roundtrip"
+    },
+    "description": "`ind2sub(siz, idx)` converts MATLAB's 1-based column-major linear indices back into the individual subscripts for each dimension specified in `siz`.",
+    "behaviors": [
+        "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."
+    ],
+    "examples": [
+        {
+            "description": "Recovering row and column subscripts from a matrix index",
+            "input": "[row, col] = ind2sub([3 4], 8)",
+            "output": "row = 2;\ncol = 3"
+        },
+        {
+            "description": "Extracting multiple matrix indices at once",
+            "input": "idx = [7 8 9];\n[rows, cols] = ind2sub([3 5], idx)",
+            "output": "rows = [1 2 3];\ncols = [3 3 3]"
+        },
+        {
+            "description": "Converting indices for a 3-D volume",
+            "input": "idx = [3 11];\n[r, c, p] = ind2sub([2 3 4], idx)",
+            "output": "r = [1 1];\nc = [2 3];\np = [1 2]"
+        },
+        {
+            "description": "Keeping indices on the GPU",
+            "input": "rows = gpuArray([1; 2; 3]);\ncols = gpuArray([4; 4; 4]);\nlin = sub2ind([3 4], rows, cols);\nsubs = ind2sub([3 4], lin);  % subs{1} and subs{2} remain gpuArray values\nclass(subs{1})\nclass(subs{2})",
+            "output": "ans =\n    'gpuArray'\n\nans =\n    'gpuArray'"
+        },
+        {
+            "description": "Using a single output cell for flexible unpacking",
+            "input": "subs = ind2sub(size(magic(4)), 6:9);\n% Access with subs{1}, subs{2}, ...",
+            "output": "subs =\n  1×2 cell array\n    {1×4 double}    {1×4 double}"
+        },
+        {
+            "description": "Validating index ranges before reshaping",
+            "input": "A = magic(4);\nidx = 1:numel(A);\n[i, j] = ind2sub(size(A), idx)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What types does `ind2sub` accept for `idx`?",
+            "answer": "Numeric and logical inputs are accepted. Logical arrays are treated as double precision (with `true → 1`, `false → 0`); complex values are rejected."
+        },
+        {
+            "question": "Can `siz` contain zeros?",
+            "answer": "No. Each element of `siz` must be a positive integer, matching MATLAB behaviour."
+        },
+        {
+            "question": "How are errors reported for invalid indices?",
+            "answer": "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 …\")."
+        },
+        {
+            "question": "What shape do the output arrays have?",
+            "answer": "Each output array matches the shape of `idx`. Scalars produce scalar doubles; vectors remain vectors; higher-dimensional shapes are preserved."
+        },
+        {
+            "question": "Does `ind2sub` support GPU arrays?",
+            "answer": "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."
+        },
+        {
+            "question": "Can I request fewer outputs than dimensions?",
+            "answer": "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."
+        },
+        {
+            "question": "How does `ind2sub` relate to `sub2ind`?",
+            "answer": "They are inverse operations: `sub2ind` turns subscripts into linear indices, while `ind2sub` recovers subscripts from those linear indices."
+        },
+        {
+            "question": "Does `ind2sub` allocate full copies of the outputs?",
+            "answer": "Yes. Each subscript array is materialised as a dense double array matching the shape of `idx`, mirroring MATLAB semantics."
+        },
+        {
+            "question": "What happens with empty inputs?",
+            "answer": "Empty index arrays produce empty subscript arrays with the same shape."
+        },
+        {
+            "question": "Can I use `ind2sub` with more dimensions than two?",
+            "answer": "Definitely—`ind2sub` works for any number of dimensions represented in `siz`."
+        }
+    ],
+    "links": [
+        {
+            "label": "sub2ind",
+            "url": "./sub2ind"
+        },
+        {
+            "label": "size",
+            "url": "./size"
+        },
+        {
+            "label": "find",
+            "url": "./find"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/indexing/ind2sub.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/indexing/ind2sub.rs"
+    },
+    "gpu_residency": "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.",
+    "gpu_behavior": [
+        "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."
+    ],
+    "key": "ind2sub",
+    "slug": "ind2sub",
+    "categoryPath": [
+        "array",
+        "indexing"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ind2sub.js.map

package/dist/generated/builtins/ind2sub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ind2sub.js","sourceRoot":"","sources":["../../../src/generated/builtins/ind2sub.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/input.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=input.d.ts.map

package/dist/generated/builtins/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/input.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAiGjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/input.js

@@ -0,0 +1,102 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "input",
+    "category": "io",
+    "keywords": [
+        "input",
+        "prompt",
+        "stdin",
+        "interactive",
+        "pause",
+        "gather"
+    ],
+    "summary": "Prompt the user for input. Return either the typed text or a parsed numeric value.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/input.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Prompts are handled on the host. When `input` is called inside GPU-enabled workflows, only the textual arguments are gathered."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::input::tests",
+        "integration": null
+    },
+    "description": "`input(prompt)` displays `prompt`, waits for the user to type a line of text, and then returns the evaluated value. When you pass `'s'` as the second argument, `input` skips numeric parsing and returns the raw text as a character row vector. RunMat mirrors MATLAB’s single-line prompt/response flow so scripts that rely on interactive questions continue to work.",
+    "behaviors": [
+        "Prompts accept character row vectors and string scalars. When omitted, RunMat uses `\"Input: \"`.",
+        "The function always blocks until the host supplies a line of text (via the REPL, CLI pipe, or wasm bindings). `stdinRequested` events surface the outstanding prompt to JS hosts so they can resume later.",
+        "When `'s'` (or `\"s\"`) is provided, the return value is a character array containing exactly what the user typed (without the trailing newline).",
+        "Without `'s'`, RunMat forwards the response through the same numeric parser that backs `str2double`. This covers scalar numbers, MATLAB-style vector/matrix literals, `Inf`, `NaN`, and complex tokens. Arbitrary expressions (for example `1+rand()`) are not evaluated automatically—read the text with `'s'` and pass it to `eval` once that builtin lands.",
+        "Empty responses (just pressing Enter) return an empty `[]` double, consistent with MATLAB.",
+        "When the numeric parser rejects the text, RunMat raises `RunMat:input:InvalidNumericExpression` so callers can present a friendly retry loop."
+    ],
+    "examples": [
+        {
+            "description": "",
+            "input": "value = input(\"Enter a scalar: \")"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does RunMat evaluate arbitrary MATLAB expressions?",
+            "answer": "Not yet. The numeric branch reuses the `str2double` parser, which supports MATLAB numeric literals (scalars, vectors, matrices, `Inf`, `NaN`, complex pairs) but does not run arbitrary code. When you need to evaluate expressions such as `1+sin(pi/4)`, capture the text via `input(..., 's')` and pass it to `eval` in a follow-up release."
+        },
+        {
+            "question": "What happens if the user just presses Enter?",
+            "answer": "RunMat returns the empty double `[]`, matching MATLAB’s `input` behaviour."
+        },
+        {
+            "question": "Can I call `input` inside GPU workloads?",
+            "answer": "Yes. Prompts always flow through the host console/UI. GPU-resident prompt arguments are gathered once before display, and the response itself is always a host value."
+        },
+        {
+            "question": "What does input do in MATLAB?",
+            "answer": "`input(prompt)` displays the prompt string and waits for the user to type a response. The response is evaluated as a MATLAB expression. Use `input(prompt, 's')` to return the raw text as a string without evaluation."
+        },
+        {
+            "question": "How do I get string input from the user in MATLAB?",
+            "answer": "Use `str = input('Enter text: ', 's')`. The `'s'` flag tells MATLAB to return the typed text as a character vector instead of evaluating it as an expression."
+        },
+        {
+            "question": "What is the difference between input and keyboard in MATLAB?",
+            "answer": "`input` pauses for a single value from the user and returns it, while `keyboard` drops into an interactive debugging session. RunMat supports `input` for scripted user interaction."
+        },
+        {
+            "question": "Can I validate user input in MATLAB?",
+            "answer": "Use a `while` loop: keep calling `input` until the value passes your validation check. For example, `while x < 0; x = input('Enter positive number: '); end`."
+        },
+        {
+            "question": "Does input work in RunMat's browser sandbox?",
+            "answer": "Yes. `input` prompts the user within the RunMat sandbox. In non-interactive contexts, it returns the default empty value."
+        }
+    ],
+    "links": [
+        {
+            "label": "disp",
+            "url": "./disp"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/input.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/input.rs"
+    },
+    "key": "input",
+    "slug": "input",
+    "categoryPath": [
+        "io"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=input.js.map

package/dist/generated/builtins/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/generated/builtins/input.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE;QACV,OAAO;QACP,QAAQ;QACR,OAAO;QACP,aAAa;QACb,OAAO;QACP,QAAQ;KACT;IACD,SAAS,EAAE,oFAAoF;IAC/F,YAAY,EAAE;QACZ,sDAAsD;KACvD;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,gIAAgI;KAC1I;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,4BAA4B;QACpC,aAAa,EAAE,IAAI;KACpB;IACD,aAAa,EAAE,4WAA4W;IAC3X,WAAW,EAAE;QACX,mGAAmG;QACnG,4MAA4M;QAC5M,mJAAmJ;QACnJ,gWAAgW;QAChW,4FAA4F;QAC5F,+IAA+I;KAChJ;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,EAAE;YACjB,OAAO,EAAE,qCAAqC;SAC/C;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,oDAAoD;YAChE,QAAQ,EAAE,iVAAiV;SAC5V;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,4EAA4E;SACvF;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,uKAAuK;SAClL;QACD;YACE,UAAU,EAAE,+BAA+B;YAC3C,QAAQ,EAAE,yNAAyN;SACpO;QACD;YACE,UAAU,EAAE,oDAAoD;YAChE,QAAQ,EAAE,+JAA+J;SAC1K;QACD;YACE,UAAU,EAAE,8DAA8D;YAC1E,QAAQ,EAAE,sLAAsL;SACjM;QACD;YACE,UAAU,EAAE,sCAAsC;YAClD,QAAQ,EAAE,+JAA+J;SAC1K;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,2HAA2H;SACtI;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,kDAAkD;QAC3D,KAAK,EAAE,+FAA+F;KACvG;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,IAAI;KACL;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/intersect.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=intersect.d.ts.map

package/dist/generated/builtins/intersect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersect.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/intersect.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA8IjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/intersect.js

@@ -0,0 +1,147 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "intersect",
+    "category": "array/sorting_sets",
+    "keywords": [
+        "intersect",
+        "set",
+        "stable",
+        "rows",
+        "indices",
+        "gpu"
+    ],
+    "summary": "Return common elements or rows across arrays with MATLAB-compatible ordering and index outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/intersect.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "When providers lack a dedicated `intersect` hook, RunMat gathers GPU tensors and executes the CPU implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::sorting_sets::intersect::tests",
+        "integration": "builtins::array::sorting_sets::intersect::tests::intersect_gpu_roundtrip"
+    },
+    "description": "`intersect(A, B)` computes the set intersection of `A` and `B`. By default it returns the distinct common values sorted ascending, along with optional index outputs that map each result back to its originating position in the inputs.",
+    "behaviors": [
+        "`intersect(A, B)` flattens both inputs column-major, removes duplicates, and returns the sorted intersection.",
+        "`[C, IA, IB] = intersect(A, B)` also returns index vectors so that `C = A(IA)` and `C = B(IB)`.",
+        "`intersect(A, B, 'stable')` preserves the first appearance order from `A`.",
+        "`intersect(A, B, 'rows')` treats each row as an element. Inputs must share the same number of columns.",
+        "Character arrays, string arrays, logical arrays, complex values, and numerical types are fully supported. Mixed classes raise a descriptive error.",
+        "Legacy flags such as `'legacy'` or `'R2012a'` are not supported in RunMat."
+    ],
+    "examples": [
+        {
+            "description": "Finding common values in numeric vectors",
+            "input": "A = [5 7 5 1];\nB = [7 1 3];\n[C, IA, IB] = intersect(A, B)",
+            "output": "C =\n     1\n     7\nIA =\n     4\n     2\nIB =\n     2\n     1"
+        },
+        {
+            "description": "Preserving input order with `'stable'`",
+            "input": "A = [4 2 4 1 3];\nB = [3 4 5 1];\nC = intersect(A, B, 'stable')",
+            "output": "C =\n     4\n     1\n     3"
+        },
+        {
+            "description": "Intersecting matrix rows",
+            "input": "A = [1 2; 3 4; 1 2];\nB = [2 3; 1 2];\n[C, IA, IB] = intersect(A, B, 'rows')",
+            "output": "C =\n     1     2\nIA =\n     1\nIB =\n     2"
+        },
+        {
+            "description": "Working with strings and character arrays",
+            "input": "names1 = [\"apple\" \"orange\" \"pear\"];\nnames2 = [\"pear\" \"grape\" \"orange\"];\n[common, IA, IB] = intersect(names1, names2, 'stable')",
+            "output": "common =\n  1×2 string array\n    \"orange\"    \"pear\"\nIA =\n     2\n     3\nIB =\n     3\n     1"
+        },
+        {
+            "description": "Using `intersect` on GPU arrays",
+            "input": "G = gpuArray([10 4 6 4]);\nH = gpuArray([6 4 2]);\nresult = intersect(G, H)",
+            "output": "result =\n     4\n     6"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `intersect` keep duplicate values?",
+            "answer": "No. MATLAB and RunMat return each common value at most once. Use other logic (such as logical indexing) if you need multiset behavior."
+        },
+        {
+            "question": "What is the default ordering?",
+            "answer": "`intersect` sorts results ascending by default. Specify `'stable'` to preserve the input order from `A`."
+        },
+        {
+            "question": "Can I intersect rows that contain strings?",
+            "answer": "Yes. String arrays support both element and row intersections. When using `'rows'`, the inputs must have the same number of columns."
+        },
+        {
+            "question": "Are NaN values considered equal?",
+            "answer": "Yes. `NaN` values are treated as equal for the purposes of intersection, matching MATLAB."
+        },
+        {
+            "question": "Is the `'legacy'` flag supported?",
+            "answer": "No. RunMat only implements the modern MATLAB semantics. Passing `'legacy'` or `'R2012a'` raises an error."
+        }
+    ],
+    "links": [
+        {
+            "label": "union",
+            "url": "./union"
+        },
+        {
+            "label": "unique",
+            "url": "./unique"
+        },
+        {
+            "label": "sort",
+            "url": "./sort"
+        },
+        {
+            "label": "sortrows",
+            "url": "./sortrows"
+        },
+        {
+            "label": "argsort",
+            "url": "./argsort"
+        },
+        {
+            "label": "ismember",
+            "url": "./ismember"
+        },
+        {
+            "label": "issorted",
+            "url": "./issorted"
+        },
+        {
+            "label": "setdiff",
+            "url": "./setdiff"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/sorting_sets/intersect.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/sorting_sets/intersect.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` manually. RunMat's planner keeps tensors resident on the GPU when profitable. If a provider lacks an `intersect` kernel the runtime gathers automatically, so explicit residency management is rarely needed. Explicit calls to `gpuArray` remain available for compatibility with MathWorks MATLAB workflows.",
+    "gpu_behavior": [
+        "`intersect` registers as a residency sink. When the active acceleration provider offers a dedicated `intersect` hook, the set logic can execute directly on the device and return GPU-resident results. Until such a hook lands, RunMat automatically gathers GPU tensors to host memory, runs the CPU implementation, and materializes host-side outputs so behavior matches MathWorks MATLAB exactly."
+    ],
+    "key": "intersect",
+    "slug": "intersect",
+    "categoryPath": [
+        "array",
+        "sorting_sets"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=intersect.js.map

package/dist/generated/builtins/intersect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersect.js","sourceRoot":"","sources":["../../../src/generated/builtins/intersect.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/inv.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=inv.d.ts.map

package/dist/generated/builtins/inv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inv.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/inv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA+JjB,CAAC;AAEF,eAAe,UAAU,CAAC"}