runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/det.js

@@ -0,0 +1,175 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "det",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "det",
+        "determinant",
+        "linear algebra",
+        "matrix",
+        "gpu"
+    ],
+    "summary": "Compute the determinant of a square matrix with MATLAB-compatible pivoting and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/det.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider LU factorization when available; real matrices re-upload a scalar result, while complex inputs gather to the host."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::det::tests",
+        "gpu": "builtins::math::linalg::solve::det::tests::det_gpu_roundtrip_matches_cpu",
+        "wgpu": "builtins::math::linalg::solve::det::tests::det_wgpu_matches_cpu"
+    },
+    "description": "`det(A)` returns the determinant of a real or complex square matrix `A`. Scalars behave like `det(1x1) = A(1,1)`, and the empty matrix (`[]`) has determinant `1`, matching MATLAB's convention.",
+    "behaviors": [
+        "Inputs must be 2-D square matrices. RunMat rejects non-square or higher-rank inputs with the MATLAB error `\"det: input must be a square matrix.\"`",
+        "Determinants are computed from an LU factorization with partial pivoting, ensuring numerical behavior that mirrors MATLAB. Singular matrices return `0` (within floating-point round-off).",
+        "Logical and integer inputs are promoted to double precision before evaluation.",
+        "Complex inputs are handled with full complex arithmetic. The result has complex type whenever the input is complex.",
+        "The determinant of the empty matrix (`[]`) is `1`."
+    ],
+    "examples": [
+        {
+            "description": "Determinant Of A 2x2 Matrix",
+            "input": "A = [4 -2; 1 3];\nd = det(A)",
+            "output": "d = 14"
+        },
+        {
+            "description": "Checking Zero Determinant For Singular Matrix",
+            "input": "B = [1 2; 2 4];\nd = det(B)",
+            "output": "d = 0"
+        },
+        {
+            "description": "Determinant Of A Complex Matrix",
+            "input": "C = [1+2i 0; 3i 4-1i];\nd = det(C)",
+            "output": "d = 6 + 7i"
+        },
+        {
+            "description": "Determinant Equals Product Of Diagonal For Triangular Matrix",
+            "input": "U = [3 2 1; 0 5 -1; 0 0 2];\nd = det(U)",
+            "output": "d = 30"
+        },
+        {
+            "description": "Determinant Of An Empty Matrix",
+            "input": "d = det([])",
+            "output": "d = 1"
+        },
+        {
+            "description": "Using `det` With `gpuArray` Data",
+            "input": "G = gpuArray([2 0 0; 0 3 0; 1 0 4]);\nd_gpu = det(G);     % stays on the GPU when a provider is active\nd = gather(d_gpu)",
+            "output": "d = 24"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why does `det` require square matrices?",
+            "answer": "The determinant is only defined for square matrices. RunMat mirrors MATLAB by rejecting non-square inputs with `\"det: input must be a square matrix.\"`"
+        },
+        {
+            "question": "What is `det([])`?",
+            "answer": "The determinant of the empty matrix (`[]`) is `1`, matching MATLAB's convention for the product of an empty diagonal."
+        },
+        {
+            "question": "Does `det` warn for nearly singular matrices?",
+            "answer": "No. RunMat returns the floating-point result of the LU-based determinant. Very small magnitudes indicate near singularity, just as in MATLAB."
+        },
+        {
+            "question": "How does `det` handle complex matrices?",
+            "answer": "Complex matrices are factorized in complex arithmetic. The result is complex; if the imaginary part happens to be zero, it is still reported through the complex number interface."
+        },
+        {
+            "question": "Will the result stay on the GPU?",
+            "answer": "Yes, when a GPU provider is active RunMat re-uploads the scalar determinant so that subsequent GPU code continues to operate on device-resident data. Providers without LU support fall back to the CPU path and return a host scalar."
+        },
+        {
+            "question": "Can `det` overflow or underflow?",
+            "answer": "Large determinants can overflow or underflow double precision just as in MATLAB. RunMat does not rescale the matrix; if you require scaling, consider `log(det(A))` via `lu` or `chol`."
+        },
+        {
+            "question": "Do logical inputs work?",
+            "answer": "Yes. Logical arrays are promoted to doubles before computing the determinant."
+        },
+        {
+            "question": "Is the determinant computed exactly?",
+            "answer": "No. The LU factorization works in floating-point, so the result is subject to round-off. The behavior matches MATLAB's `det`."
+        }
+    ],
+    "links": [
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "pinv",
+            "url": "./pinv"
+        },
+        {
+            "label": "lu",
+            "url": "./lu"
+        },
+        {
+            "label": "trace",
+            "url": "./trace"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cond",
+            "url": "./cond"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        },
+        {
+            "label": "rank",
+            "url": "./rank"
+        },
+        {
+            "label": "rcond",
+            "url": "./rcond"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/solve/det.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/solve/det.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB). The fusion planner keeps producers on the GPU, `det` invokes the provider's `lu` hook when available, and real determinants are re-uploaded as device scalars so subsequent kernels keep their residency. When the provider lacks `lu`, RunMat transparently gathers the matrix, computes the determinant with the host fallback, and re-uploads the scalar for real inputs. Complex determinants currently return host scalars until device complex scalars land. `gpuArray` and `gather` remain available for explicit residency control and MATLAB compatibility.",
+    "gpu_behavior": [
+        "When a GPU acceleration provider is active, RunMat first asks the provider for an LU factorization via the `lu` hook. Providers that implement it keep the factors on device, multiply the diagonal of `U`, and re-upload the scalar determinant for real inputs so downstream kernels keep running on the GPU. Complex matrices currently gather to the host for the final scalar. Providers that do not expose `lu` (including the current fallback backends) automatically route to the shared CPU implementation with no user intervention required."
+    ],
+    "key": "det",
+    "slug": "det",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=det.js.map

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

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

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

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

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

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

package/dist/generated/builtins/diag.js

@@ -0,0 +1,242 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "diag",
+    "category": "array/shape",
+    "keywords": [
+        "diag",
+        "diagonal",
+        "matrix",
+        "extraction",
+        "gpu"
+    ],
+    "summary": "Create diagonal matrices from vectors or extract diagonals from matrices.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Keeps results on the GPU when providers implement custom diag hooks; otherwise gathers to the host, materialises the result once, and uploads it back to the device."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::shape::diag::tests",
+        "integration": "builtins::array::shape::diag::tests::diag_gpu_roundtrip"
+    },
+    "description": "`diag` either constructs a diagonal matrix from a vector (placing the vector on a specified diagonal) or extracts a diagonal from a matrix. The behaviour matches MATLAB, including support for offsets, logical inputs, complex values, and character arrays.",
+    "behaviors": [
+        "`diag(v)` with a vector `v` returns a square matrix whose main diagonal is `v`.",
+        "`diag(v, k)` places `v` on the `k`-th diagonal: super-diagonals for `k > 0`, sub-diagonals for `k < 0`. The output size grows by `abs(k)`.",
+        "`diag(A)` with a matrix `A` returns a column vector containing the main diagonal of `A`.",
+        "`diag(A, k)` extracts the `k`-th diagonal. When the requested diagonal does not exist, an empty column vector is returned.",
+        "`diag(v, 'vector')` always returns a column vector copy of `v`, even when `v` is already a vector.",
+        "`diag(v, [m n])` creates an explicit rectangular size. You can combine it with offsets (e.g. `diag(v, k, [m n])`) when you need a wider diagonal band.",
+        "`diag(___, 'logical')` converts the result to a logical array. `diag(___, 'double')` forces a double-precision result when inputs are logical.",
+        "`diag(___, 'like', prototype)` matches the numeric flavour and residency of `prototype` (including GPU handles).",
+        "Logical inputs stay logical; complex inputs stay complex; character arrays preserve padding with spaces off the diagonal.",
+        "Higher-dimensional inputs are accepted when trailing dimensions are singleton—only the leading 2-D slice participates in the diagonal operation."
+    ],
+    "examples": [
+        {
+            "description": "Creating a diagonal matrix from a vector",
+            "input": "v = [4 5 6];\nD = diag(v)",
+            "output": "D =\n     4     0     0\n     0     5     0\n     0     0     6"
+        },
+        {
+            "description": "Placing a vector on an upper diagonal",
+            "input": "v = [1 2 3];\nU = diag(v, 1)",
+            "output": "U =\n     0     1     0     0\n     0     0     2     0\n     0     0     0     3\n     0     0     0     0"
+        },
+        {
+            "description": "Extracting a subdiagonal as a column vector",
+            "input": "A = [1 2 3; 4 5 6; 7 8 9];\nd = diag(A, -1)",
+            "output": "d =\n     4\n     8"
+        },
+        {
+            "description": "Building a diagonal matrix from a logical mask",
+            "input": "mask = logical([1 0 1 0]);\nM = diag(mask)",
+            "output": "M =\n     1     0     0     0\n     0     0     0     0\n     0     0     1     0\n     0     0     0     0"
+        },
+        {
+            "description": "Keeping diagonal results on the GPU",
+            "input": "G = gpuArray([2; 4; 8]);\nD = diag(G);\nfirstTwo = gather(D(1:2, 1:2))",
+            "output": "firstTwo =\n     2     0\n     0     4"
+        },
+        {
+            "description": "Returning a vector without creating a matrix",
+            "input": "v = [10 20 30];\nd = diag(v, 'vector')",
+            "output": "d =\n    10\n    20\n    30"
+        },
+        {
+            "description": "Creating a rectangular diagonal matrix with `sz`",
+            "input": "v = [1 2];\nR = diag(v, [2 4])",
+            "output": "R =\n     1     0     0     0\n     0     2     0     0"
+        },
+        {
+            "description": "Matching residency and type with `'like'`",
+            "input": "G = gpuArray([1 3 5]');\nD = diag([1 2 3], 'like', G)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `diag` always return a square matrix?",
+            "answer": "Only when the input is a vector and you do not request otherwise. Use `'vector'` to keep the result as a column vector, or pass a size vector (e.g. `diag(v, [m n])`) to create rectangular matrices."
+        },
+        {
+            "question": "What happens if I request a diagonal outside the matrix bounds?",
+            "answer": "You receive an empty column vector (size `0 × 0`), matching MATLAB's behaviour."
+        },
+        {
+            "question": "Can I use `diag` with logical or character arrays?",
+            "answer": "Yes. Logical inputs produce logical outputs, and character inputs produce padded character arrays with spaces away from the diagonal."
+        },
+        {
+            "question": "Does `diag` support complex numbers?",
+            "answer": "Complex inputs are supported. The output keeps the real and imaginary parts intact."
+        },
+        {
+            "question": "How do offsets work with vectors?",
+            "answer": "`diag(v, k)` grows the matrix by `abs(k)` and shifts the diagonal up (`k > 0`) or down (`k < 0`)."
+        },
+        {
+            "question": "Can I place a diagonal inside a non-square matrix?",
+            "answer": "Yes. Pass an explicit size vector such as `diag(v, [m n])`, and optionally combine it with an offset via `diag(v, k, [m n])`."
+        },
+        {
+            "question": "What if the vector is empty?",
+            "answer": "`diag([])` returns a `0 × 0` matrix. `diag([], k)` returns a square matrix of size `abs(k)` filled with zeros."
+        },
+        {
+            "question": "Do GPU results stay on the device?",
+            "answer": "Yes—providers with diag hooks operate entirely on the GPU. Providers without hooks perform a single host gather and upload, so downstream fused expressions still see a GPU handle. When you request `'like'` with a GPU prototype, the result is uploaded back to the device even if a host fallback was required."
+        },
+        {
+            "question": "Is the offset argument required to be an integer?",
+            "answer": "Yes. Non-integer or non-finite offsets raise an error."
+        },
+        {
+            "question": "Does `diag` modify the original input?",
+            "answer": "No. It always returns a new array, leaving the input unchanged."
+        },
+        {
+            "question": "How do I match another array's type or residency?",
+            "answer": "Use the `'like'` syntax: `diag(v, 'like', prototype)`. Logical, complex, and GPU prototypes are respected even when the computation falls back to the CPU path."
+        },
+        {
+            "question": "Is single precision supported?",
+            "answer": "Not yet. Requesting `'single'` currently raises an error. Use `'like'` with an appropriate prototype once single-precision support lands."
+        }
+    ],
+    "links": [
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        },
+        {
+            "label": "ones",
+            "url": "./ones"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cat",
+            "url": "./cat"
+        },
+        {
+            "label": "circshift",
+            "url": "./circshift"
+        },
+        {
+            "label": "flip",
+            "url": "./flip"
+        },
+        {
+            "label": "fliplr",
+            "url": "./fliplr"
+        },
+        {
+            "label": "flipud",
+            "url": "./flipud"
+        },
+        {
+            "label": "horzcat",
+            "url": "./horzcat"
+        },
+        {
+            "label": "ipermute",
+            "url": "./ipermute"
+        },
+        {
+            "label": "kron",
+            "url": "./kron"
+        },
+        {
+            "label": "permute",
+            "url": "./permute"
+        },
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "reshape",
+            "url": "./reshape"
+        },
+        {
+            "label": "rot90",
+            "url": "./rot90"
+        },
+        {
+            "label": "squeeze",
+            "url": "./squeeze"
+        },
+        {
+            "label": "tril",
+            "url": "./tril"
+        },
+        {
+            "label": "triu",
+            "url": "./triu"
+        },
+        {
+            "label": "vertcat",
+            "url": "./vertcat"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/shape/diag.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/shape/diag.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the auto-offload planner keeps residency on the GPU when expressions make use of GPU providers. Even when the provider lacks `diag_from_vector` / `diag_extract`, the builtin gathers once on the host, performs the diagonal operation, and re-uploads the result so later GPU-friendly ops can continue without intervention.\n\nTo preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call `gpuArray` to move data to the GPU. That mirrors MATLAB's behaviour while still allowing RunMat's planner to decide whether the GPU offers an advantage for the surrounding computation.\n\nSince MathWorks MATLAB does not have a fusion planner, and they kept their parallel execution toolbox separate from the core language, as their toolbox is a separate commercial product, MathWorks MATLAB users need to call `gpuArray` to move data to the GPU manually whereas RunMat users can rely on the fusion planner to keep data on the GPU automatically.",
+    "gpu_behavior": [
+        "When the input lives on the GPU, RunMat calls the acceleration provider's `diag_from_vector` or `diag_extract` hook (see the GPU spec). Providers that do not expose these hooks fall back to a host round-trip: the input is gathered once, the diagonal computation runs on the CPU, and the result is uploaded back to the device. Size overrides or the `'vector'` option also trigger the host path because they are not yet exposed through provider hooks. `'like'` requests are honoured regardless of the path: GPU prototypes stay on the device, while logical or complex prototypes adjust the element type accordingly."
+    ],
+    "key": "diag",
+    "slug": "diag",
+    "categoryPath": [
+        "array",
+        "shape"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=diag.js.map

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

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

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

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

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

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

package/dist/generated/builtins/diff.js

@@ -0,0 +1,208 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "diff",
+    "category": "math/reduction",
+    "keywords": [
+        "diff",
+        "difference",
+        "finite difference",
+        "nth difference",
+        "gpu"
+    ],
+    "summary": "Forward finite differences of scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Calls the provider's `diff_dim` hook; falls back to host when that hook is unavailable."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::reduction::diff::tests",
+        "integration": "builtins::math::reduction::diff::tests::diff_gpu_provider_roundtrip"
+    },
+    "description": "`diff(X)` computes forward finite differences along the first dimension of `X` whose size exceeds 1. For vectors, this is simply the difference between adjacent elements. Higher-order differences are obtained by repeating this process.",
+    "behaviors": [
+        "`diff(X)` walks along the first non-singleton dimension. Column vectors therefore differentiate down the rows, while row vectors operate across columns.",
+        "`diff(X, N)` computes the Nth forward difference. `N = 0` returns `X` unchanged. Each order reduces the length of the working dimension by one, so the output length becomes `max(len - N, 0)`.",
+        "`diff(X, N, dim)` lets you choose the dimension explicitly. Passing `[]` for `N` or `dim` keeps the defaults, and dimensions larger than `ndims(X)` behave like length-1 axes (so any positive order yields an empty result).",
+        "Real, logical, and character inputs promote to double precision tensors before differencing. Complex inputs retain their complex type, with forward differences applied to both the real and imaginary parts independently.",
+        "Empty slices propagate: if the selected dimension has length 0 or 1, the corresponding axis in the output has length 0."
+    ],
+    "examples": [
+        {
+            "description": "Computing first differences of a vector",
+            "input": "v = [3 4 9 15];\nd1 = diff(v)",
+            "output": "d1 = [1 5 6]"
+        },
+        {
+            "description": "Taking second-order differences",
+            "input": "v = [1 4 9 16 25];\nd2 = diff(v, 2)",
+            "output": "d2 = [2 2 2]"
+        },
+        {
+            "description": "Selecting the working dimension explicitly",
+            "input": "A = [1 2 3; 4 5 6];\nrowDiff = diff(A, 1, 2)",
+            "output": "rowDiff =\n     1     1\n     1     1"
+        },
+        {
+            "description": "Running `diff` on GPU arrays",
+            "input": "G = gpuArray([1 4 9 16]);\ngDiff = diff(G);\nresult = gather(gDiff)",
+            "output": "result = [3 5 7]"
+        },
+        {
+            "description": "N exceeding the dimension length returns an empty array",
+            "input": "v = (1:3)';\nemptyResult = diff(v, 5)",
+            "output": "emptyResult =\n  0×1 empty double column vector"
+        },
+        {
+            "description": "Applying `diff` to character data",
+            "input": "codes = diff('ACEG')",
+            "output": "codes = [2 2 2]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `diff` change the size of the input?",
+            "answer": "`diff` reduces the length along the working dimension by `N`. All other dimensions are preserved. If the working dimension is shorter than `N`, the result is empty. With the WGPU backend the empty result remains GPU-resident."
+        },
+        {
+            "question": "How are higher-order differences computed?",
+            "answer": "RunMat applies the first-order forward difference repeatedly. This mirrors MATLAB’s definition and produces the same numerical results."
+        },
+        {
+            "question": "Can I pass `[]` for the order or dimension arguments?",
+            "answer": "Yes. An empty array keeps the default value (`N = 1`, first non-singleton dimension)."
+        },
+        {
+            "question": "Does `diff` support complex numbers?",
+            "answer": "Yes. Differences are taken on the real and imaginary parts independently, and the result remains complex unless it becomes empty."
+        },
+        {
+            "question": "What happens for character or logical inputs?",
+            "answer": "Characters and logical values are promoted to double precision differences, matching MATLAB."
+        },
+        {
+            "question": "Will the GPU path produce the same results as the CPU path?",
+            "answer": "Yes. When a provider lacks a finite-difference kernel, RunMat gathers the data and computes on the CPU to preserve MATLAB semantics exactly. Otherwise, the WGPU backend produces identical results on the GPU."
+        },
+        {
+            "question": "What does diff do in MATLAB?",
+            "answer": "`diff(X)` computes differences between adjacent elements. For a vector, it returns `X(2:end) - X(1:end-1)`, producing an output one element shorter than the input."
+        },
+        {
+            "question": "How do I compute second differences with diff?",
+            "answer": "Use `diff(X, 2)` to compute the second-order difference, equivalent to `diff(diff(X))`. The output is two elements shorter than the input."
+        },
+        {
+            "question": "How do I compute differences along columns vs rows?",
+            "answer": "Use `diff(X, 1, 1)` for differences along columns (default for matrices) and `diff(X, 1, 2)` for differences along rows. The third argument specifies the dimension."
+        },
+        {
+            "question": "Can I use diff to compute numerical derivatives?",
+            "answer": "Yes. For evenly spaced data with step `h`, the numerical derivative is approximately `diff(y) / h`. For non-uniform spacing, use `diff(y) ./ diff(x)`."
+        },
+        {
+            "question": "Does diff support GPU acceleration in RunMat?",
+            "answer": "Yes. `diff` runs on GPU arrays in RunMat. The GPU path produces the same results as the CPU path for both real and complex inputs."
+        }
+    ],
+    "links": [
+        {
+            "label": "cumsum",
+            "url": "./cumsum"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "cumprod",
+            "url": "./cumprod"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "all",
+            "url": "./all"
+        },
+        {
+            "label": "any",
+            "url": "./any"
+        },
+        {
+            "label": "cummax",
+            "url": "./cummax"
+        },
+        {
+            "label": "cummin",
+            "url": "./cummin"
+        },
+        {
+            "label": "max",
+            "url": "./max"
+        },
+        {
+            "label": "mean",
+            "url": "./mean"
+        },
+        {
+            "label": "median",
+            "url": "./median"
+        },
+        {
+            "label": "min",
+            "url": "./min"
+        },
+        {
+            "label": "nnz",
+            "url": "./nnz"
+        },
+        {
+            "label": "prod",
+            "url": "./prod"
+        },
+        {
+            "label": "std",
+            "url": "./std"
+        },
+        {
+            "label": "var",
+            "url": "./var"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/reduction/diff.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/reduction/diff.rs"
+    },
+    "gpu_residency": "Manual `gpuArray` promotion is optional. RunMat keeps tensors on the GPU when providers implement the relevant hooks and the planner predicts a benefit. With the WGPU backend registered, `diff` executes fully on the GPU and returns a device-resident tensor. When the hook is missing, RunMat gathers transparently, computes on the CPU, and keeps residency metadata consistent so fused expressions can re-promote values when profitable.",
+    "gpu_behavior": [
+        "When the operand already resides on the GPU, RunMat asks the active acceleration provider for a finite-difference kernel via `diff_dim`. The WGPU backend implements this hook, so forward differences execute entirely on the device and the result stays resident on the GPU. Providers that have not wired `diff_dim` yet transparently gather the data, run the CPU implementation, and hand the result back to the planner so subsequent kernels can re-promote it when beneficial."
+    ],
+    "key": "diff",
+    "slug": "diff",
+    "categoryPath": [
+        "math",
+        "reduction"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=diff.js.map