runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/filter2.js

@@ -0,0 +1,136 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "filter2",
+    "category": "image/filters",
+    "keywords": [
+        "filter2",
+        "correlation",
+        "convolution",
+        "image filtering",
+        "gpu"
+    ],
+    "summary": "Apply 2-D correlation or convolution using MATLAB-compatible semantics.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Reuses the imfilter acceleration hook when available; otherwise RunMat gathers tensors to the host automatically."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::image::filters::filter2::tests",
+        "integration": "builtins::image::filters::filter2::tests::filter2_gpu_matches_cpu"
+    },
+    "description": "`filter2(H, X)` performs a 2-D correlation of the image (or matrix) `X` with the kernel `H`. By default the operation returns an array the same size as `X`, mirroring MATLAB’s behaviour and matching the identity `filter2(H, X) == conv2(X, rot90(H, 2), 'same')`.",
+    "behaviors": [
+        "The first argument is the kernel and the second is the image or matrix being filtered.",
+        "The default configuration performs correlation with zero padding and `'same'` output sizing.",
+        "Passing `'full'` or `'valid'` as the third argument switches the output size to the full convolution result or the strictly valid interior, respectively.",
+        "Supplying `'conv'` rotates the kernel by 180° so the operation matches MATLAB convolution. Use `'corr'` for an explicit correlation request; it is the default.",
+        "Inputs may be numeric or logical. Logical arrays are promoted to double precision prior to filtering.",
+        "Both arguments may be gpuArray handles; RunMat keeps them on the device whenever the active acceleration provider exposes the `imfilter` hook."
+    ],
+    "examples": [
+        {
+            "description": "Averaging a matrix with a 3x3 kernel",
+            "input": "H = ones(3) / 9;\nX = [1 2 3; 4 5 6; 7 8 9];\nY = filter2(H, X)",
+            "output": "Y =\n    1.3333    2.3333    1.7778\n    3.0000    5.0000    3.6667\n    2.6667    4.3333    3.1111"
+        },
+        {
+            "description": "Requesting the full correlation result",
+            "input": "H = [1 2; 3 4];\nX = [4 1; 2 0];\nY = filter2(H, X, 'full')",
+            "output": "Y =\n    16    16     3\n    16    12     1\n     4     2     0"
+        },
+        {
+            "description": "Restricting the result to the valid interior",
+            "input": "H = ones(3);\nX = magic(5);\nY = filter2(H, X, 'valid')",
+            "output": "Y =\n   100    98   116\n    99   117   135\n   118   136   134"
+        },
+        {
+            "description": "Switching to convolution mode",
+            "input": "H = [1 2; 3 4];\nX = [1 2 3; 4 5 6; 7 8 9];\nY = filter2(H, X, 'conv')",
+            "output": "Y =\n     1     4     7\n     7    23    33\n    19    53    63"
+        },
+        {
+            "description": "Filtering data already on the GPU",
+            "input": "H = gpuArray([1 0 -1; 1 0 -1; 1 0 -1]);\nX = gpuArray([1 2 3; 4 5 6; 7 8 9]);\nY = filter2(H, X);\nresult = gather(Y)",
+            "output": "result =\n    -7    -4     7\n   -15    -6    15\n   -13    -4    13"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Can I pass string padding modes like `imfilter`?",
+            "answer": "No. `filter2` mirrors MATLAB and only accepts `'same'`, `'full'`, `'valid'`, `'corr'`, and `'conv'`. For advanced padding control use `imfilter`."
+        },
+        {
+            "question": "Does the builtin normalise the kernel?",
+            "answer": "No. The kernel is used exactly as supplied. Use helpers such as `fspecial` or manual scaling when you need a normalised filter."
+        },
+        {
+            "question": "What happens when the kernel is larger than the image?",
+            "answer": "`'same'` still returns an output the same size as the input, padded with zeros where the kernel extends beyond the image. `'valid'` returns an empty array whenever the kernel does not fully fit within the image."
+        },
+        {
+            "question": "Can I combine `filter2` with gpuArray inputs?",
+            "answer": "Yes. If either argument is a gpuArray, RunMat forwards the computation to the active acceleration provider and only gathers the data when the provider hook is unavailable."
+        },
+        {
+            "question": "Does `filter2` support higher-dimensional arrays?",
+            "answer": "MathWorks MATLAB defines `filter2` for 2-D filtering. Use `imfilter` when you need explicit padding control or want to extend the operation to higher-dimensional arrays."
+        },
+        {
+            "question": "Does `filter2` preserve logical inputs?",
+            "answer": "Logical arrays are promoted to double precision before filtering, matching MATLAB behaviour."
+        },
+        {
+            "question": "How do I perform separable filtering efficiently?",
+            "answer": "Apply successive 1-D `filter2` calls with thin kernels or use `imfilter` for more control over padding and dimensionality."
+        }
+    ],
+    "links": [
+        {
+            "label": "imfilter",
+            "url": "./imfilter"
+        },
+        {
+            "label": "fspecial",
+            "url": "./fspecial"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/image/filters/filter2.rs",
+        "url": "crates/runmat-runtime/src/builtins/image/filters/filter2.rs"
+    },
+    "gpu_residency": "Usually not. When the acceleration provider exposes the `imfilter` hook, `filter2` keeps the operands on the GPU and returns a GPU tensor. Host fallbacks are automatic; the builtin gathers data only when the required hook is missing or reports an error. Explicit `gpuArray` calls remain useful for deterministic residency or backwards compatibility with MATLAB scripts.",
+    "gpu_behavior": [
+        "The builtin delegates to the same acceleration hook that powers `imfilter`. When the provider implements `imfilter`, `filter2` uploads host-resident kernels on demand, keeps GPU-resident images on the device, and only downloads results when absolutely necessary. Providers that skip the hook trigger a transparent fallback: RunMat gathers the operands to the host and executes the shared reference implementation, guaranteeing MATLAB-compatible results without extra configuration."
+    ],
+    "key": "filter2",
+    "slug": "filter2",
+    "categoryPath": [
+        "image",
+        "filters"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=filter2.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter2.js","sourceRoot":"","sources":["../../../src/generated/builtins/filter2.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE;QACV,SAAS;QACT,aAAa;QACb,aAAa;QACb,iBAAiB;QACjB,KAAK;KACN;IACD,SAAS,EAAE,yEAAyE;IACpF,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,mHAAmH;KAC7H;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,0CAA0C;QAClD,aAAa,EAAE,mEAAmE;KACnF;IACD,aAAa,EAAE,uQAAuQ;IACtR,WAAW,EAAE;QACX,wFAAwF;QACxF,8FAA8F;QAC9F,2JAA2J;QAC3J,iKAAiK;QACjK,uGAAuG;QACvG,gJAAgJ;KACjJ;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,sCAAsC;YACrD,OAAO,EAAE,iEAAiE;YAC1E,QAAQ,EAAE,qGAAqG;SAChH;QACD;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,6DAA6D;YACtE,QAAQ,EAAE,iEAAiE;SAC5E;QACD;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,yDAAyD;YAClE,QAAQ,EAAE,iEAAiE;SAC5E;QACD;YACE,aAAa,EAAE,+BAA+B;YAC9C,OAAO,EAAE,wEAAwE;YACjF,QAAQ,EAAE,iEAAiE;SAC5E;QACD;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,uHAAuH;YAChI,QAAQ,EAAE,sEAAsE;SACjF;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,kDAAkD;YAC9D,QAAQ,EAAE,mJAAmJ;SAC9J;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,iIAAiI;SAC5I;QACD;YACE,UAAU,EAAE,wDAAwD;YACpE,QAAQ,EAAE,qNAAqN;SAChO;QACD;YACE,UAAU,EAAE,+CAA+C;YAC3D,QAAQ,EAAE,6KAA6K;SACxL;QACD;YACE,UAAU,EAAE,mDAAmD;YAC/D,QAAQ,EAAE,2KAA2K;SACtL;QACD;YACE,UAAU,EAAE,yCAAyC;YACrD,QAAQ,EAAE,8FAA8F;SACzG;QACD;YACE,UAAU,EAAE,mDAAmD;YAC/D,QAAQ,EAAE,4HAA4H;SACvI;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,6DAA6D;QACtE,KAAK,EAAE,6DAA6D;KACrE;IACD,eAAe,EAAE,mXAAmX;IACpY,cAAc,EAAE;QACd,meAAme;KACpe;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,OAAO;QACP,SAAS;KACV;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/find.js

@@ -0,0 +1,150 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "find",
+    "category": "array/indexing",
+    "keywords": [
+        "find",
+        "nonzero",
+        "indices",
+        "row",
+        "column",
+        "gpu"
+    ],
+    "summary": "Locate indices and values of nonzero elements in scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "WGPU provider executes find directly on the device; other providers fall back to the host and re-upload results to preserve residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::indexing::find::tests",
+        "integration": "builtins::array::indexing::find::tests::find_gpu_roundtrip"
+    },
+    "description": "`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.",
+    "behaviors": [
+        "`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."
+    ],
+    "examples": [
+        {
+            "description": "Finding linear indices of nonzero elements",
+            "input": "A = [0 4 0; 7 0 9];\nk = find(A)",
+            "output": "k =\n     2\n     4\n     6"
+        },
+        {
+            "description": "Limiting the number of matches",
+            "input": "A = [0 3 5 0 8];\nfirst_two = find(A, 2)",
+            "output": "first_two =\n     2\n     3"
+        },
+        {
+            "description": "Locating the last nonzero element",
+            "input": "A = [1 0 0 6 0 2];\nlast_index = find(A, 'last')",
+            "output": "last_index =\n     6"
+        },
+        {
+            "description": "Retrieving row and column subscripts",
+            "input": "A = [0 4 0; 7 0 9];\n[rows, cols] = find(A)",
+            "output": "rows =\n     2\n     1\n     2\n\ncols =\n     1\n     2\n     3"
+        },
+        {
+            "description": "Capturing values alongside indices (including complex inputs)",
+            "input": "Z = [0 1+2i; 0 0; 3-4i 0];\n[r, c, v] = find(Z)",
+            "output": "r =\n     1\n     3\n\nc =\n     1\n     1\n\nv =\n   1.0000 + 2.0000i\n   3.0000 - 4.0000i"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What elements does `find` consider nonzero?",
+            "answer": "Any element whose real or imaginary component is nonzero. For logical inputs, `true` maps to 1 and is considered nonzero; `false` is ignored."
+        },
+        {
+            "question": "How are higher-dimensional arrays handled when requesting row/column outputs?",
+            "answer": "`find` treats the first dimension as rows and flattens the remaining dimensions into the column index, matching MATLAB's column-major storage."
+        },
+        {
+            "question": "What happens when I request more matches than exist?",
+            "answer": "`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."
+        },
+        {
+            "question": "Does `find` support char arrays and integers?",
+            "answer": "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."
+        },
+        {
+            "question": "Can I run `find` entirely on the GPU today?",
+            "answer": "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."
+        },
+        {
+            "question": "What shapes do empty results take?",
+            "answer": "When no element matches, the returned arrays are `0×1` column vectors, just like MATLAB."
+        },
+        {
+            "question": "How does `find` interact with fusion or auto-offload?",
+            "answer": "`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."
+        },
+        {
+            "question": "Does `find` preserve complex values in the third output?",
+            "answer": "Yes. When you request the value output, complex inputs return a complex column vector that matches MATLAB's behaviour."
+        },
+        {
+            "question": "Can I combine `find` with `gpuArray` explicitly?",
+            "answer": "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."
+        },
+        {
+            "question": "Is there a way to obtain subscripts for every dimension?",
+            "answer": "Use `find` to get linear indices and then call `ind2sub(size(X), ...)` if you need explicit per-dimension subscripts for N-D arrays."
+        }
+    ],
+    "links": [
+        {
+            "label": "ind2sub",
+            "url": "./ind2sub"
+        },
+        {
+            "label": "sub2ind",
+            "url": "./sub2ind"
+        },
+        {
+            "label": "logical",
+            "url": "./logical"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/indexing/find.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/indexing/find.rs"
+    },
+    "gpu_residency": "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.",
+    "gpu_behavior": [
+        "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."
+    ],
+    "key": "find",
+    "slug": "find",
+    "categoryPath": [
+        "array",
+        "indexing"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=find.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fix.js

@@ -0,0 +1,140 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fix",
+    "category": "math/rounding",
+    "keywords": [
+        "fix",
+        "truncate",
+        "rounding",
+        "toward zero",
+        "gpu"
+    ],
+    "summary": "Round scalars, vectors, matrices, or N-D tensors toward zero.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host implementation when the active provider lacks unary_fix."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::rounding::fix::tests",
+        "integration": "builtins::math::rounding::fix::tests::fix_gpu_provider_roundtrip"
+    },
+    "description": "`fix(X)` removes the fractional part of each element in `X` by rounding toward zero. Positive numbers behave like `floor`, negatives behave like `ceil`, and zeros stay zero. The operation works element-wise on scalars, vectors, matrices, N-D tensors, and complex values.",
+    "behaviors": [
+        "`fix` rounds positive inputs down toward zero and negative inputs up toward zero.",
+        "Integer-valued elements are returned unchanged. Logical inputs are promoted to double before rounding.",
+        "Complex numbers are rounded component-wise (`fix(a + bi) = fix(a) + i·fix(b)`), matching MATLAB.",
+        "`NaN`, `Inf`, and `-Inf` propagate unchanged.",
+        "Character arrays are treated as their numeric code points and return dense double tensors.",
+        "Empty arrays return empty arrays with identical shape."
+    ],
+    "examples": [
+        {
+            "description": "Truncating positive and negative values toward zero",
+            "input": "values = [-3.7 -2.4 -0.6 0 0.6 2.4 3.7];\ntruncated = fix(values)",
+            "output": "truncated = [-3 -2 0 0 0 2 3]"
+        },
+        {
+            "description": "Removing fractional parts from a matrix",
+            "input": "A = [1.9  4.1; -2.8  0.5];\nB = fix(A)",
+            "output": "B = [1 4; -2 0]"
+        },
+        {
+            "description": "Keeping GPU residency when kernels are available",
+            "input": "G = gpuArray(linspace(-2.4, 2.4, 6));\ntruncGpu = fix(G);\nhostValues = gather(truncGpu)",
+            "output": "hostValues = [-2 -1 0 0 1 2]"
+        },
+        {
+            "description": "Dropping fractional parts of complex numbers",
+            "input": "z = [1.9 + 2.6i, -3.4 - 0.2i];\nfixed = fix(z)",
+            "output": "fixed = [1 + 2i, -3 + 0i]"
+        },
+        {
+            "description": "Converting character arrays to truncated numeric codes",
+            "input": "letters = ['A' 'B' 'C'];\ncodes = fix(letters)",
+            "output": "codes = [65 66 67]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `fix` different from `floor` and `ceil`?",
+            "answer": "`fix` always rounds toward zero. Positive numbers behave like `floor`, negatives behave like `ceil`. Use `floor` or `ceil` when you specifically want to round toward negative or positive infinity."
+        },
+        {
+            "question": "What happens to existing integers?",
+            "answer": "Integer-valued inputs (including logical values) are returned unchanged; the output is still reported as a double tensor, matching MATLAB's default numeric type."
+        },
+        {
+            "question": "Does `fix` change NaN or Inf values?",
+            "answer": "No. `NaN`, `Inf`, and `-Inf` propagate unchanged."
+        },
+        {
+            "question": "How are complex numbers handled?",
+            "answer": "`fix` rounds the real and imaginary components independently, exactly like MATLAB."
+        },
+        {
+            "question": "Will `fix` stay on the GPU?",
+            "answer": "Yes, when the active provider implements `unary_fix`. Otherwise, RunMat gathers to the host and applies the CPU implementation, guaranteeing MATLAB-compatible behaviour."
+        }
+    ],
+    "links": [
+        {
+            "label": "floor",
+            "url": "./floor"
+        },
+        {
+            "label": "ceil",
+            "url": "./ceil"
+        },
+        {
+            "label": "round",
+            "url": "./round"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "mod",
+            "url": "./mod"
+        },
+        {
+            "label": "rem",
+            "url": "./rem"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/rounding/fix.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/rounding/fix.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nG = gpuArray(linspace(-2.4, 2.4, 6));\ntruncGpu = fix(G);\nhostValues = gather(truncGpu);\n```\n\nExpected output:\n\n```matlab\nhostValues = [-2 -1 0 0 1 2];\n```",
+    "gpu_behavior": [
+        "When a tensor already resides on the GPU, RunMat Accelerate checks whether the active provider implements the optional `unary_fix` hook. If available, the truncation is executed directly on the device and the result stays on the GPU. If the hook is missing, RunMat gathers the values to the host, applies the CPU implementation, and returns a host-resident result—ensuring MATLAB-compatible semantics everywhere."
+    ],
+    "key": "fix",
+    "slug": "fix",
+    "categoryPath": [
+        "math",
+        "rounding"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fix.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fix.js","sourceRoot":"","sources":["../../../src/generated/builtins/fix.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,eAAe;IAC3B,UAAU,EAAE;QACV,KAAK;QACL,UAAU;QACV,UAAU;QACV,aAAa;QACb,KAAK;KACN;IACD,SAAS,EAAE,+DAA+D;IAC1E,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,iFAAiF;KAC3F;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,sCAAsC;QAC9C,aAAa,EAAE,kEAAkE;KAClF;IACD,aAAa,EAAE,gRAAgR;IAC/R,WAAW,EAAE;QACX,mFAAmF;QACnF,wGAAwG;QACxG,kGAAkG;QAClG,+CAA+C;QAC/C,4FAA4F;QAC5F,wDAAwD;KACzD;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,qDAAqD;YACpE,OAAO,EAAE,mEAAmE;YAC5E,QAAQ,EAAE,+BAA+B;SAC1C;QACD;YACE,aAAa,EAAE,yCAAyC;YACxD,OAAO,EAAE,wCAAwC;YACjD,QAAQ,EAAE,iBAAiB;SAC5B;QACD;YACE,aAAa,EAAE,kDAAkD;YACjE,OAAO,EAAE,0FAA0F;YACnG,QAAQ,EAAE,8BAA8B;SACzC;QACD;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,gDAAgD;YACzD,QAAQ,EAAE,2BAA2B;SACtC;QACD;YACE,aAAa,EAAE,wDAAwD;YACvE,OAAO,EAAE,gDAAgD;YACzD,QAAQ,EAAE,oBAAoB;SAC/B;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,iDAAiD;YAC7D,QAAQ,EAAE,sMAAsM;SACjN;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,mKAAmK;SAC9K;QACD;YACE,UAAU,EAAE,sCAAsC;YAClD,QAAQ,EAAE,mDAAmD;SAC9D;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,oFAAoF;SAC/F;QACD;YACE,UAAU,EAAE,6BAA6B;YACzC,QAAQ,EAAE,2KAA2K;SACtL;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,2DAA2D;QACpE,KAAK,EAAE,wGAAwG;KAChH;IACD,eAAe,EAAE,yLAAyL;IAC1M,cAAc,EAAE;QACd,8ZAA8Z;KAC/Z;IACD,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,cAAc,EAAE;QACd,MAAM;QACN,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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