runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/ls.js

@@ -0,0 +1,226 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ls",
+    "category": "io/repl_fs",
+    "keywords": [
+        "ls",
+        "list files",
+        "folder contents",
+        "wildcard listing",
+        "dir"
+    ],
+    "summary": "List files and folders in the current directory or matching a wildcard pattern.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/ls.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Executes entirely on the host CPU. When the input argument resides on the GPU, RunMat gathers it to the host before expanding any patterns."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::ls::tests",
+        "integration": "builtins::io::repl_fs::ls::tests::ls_handles_wildcard_patterns"
+    },
+    "description": "`ls` lists the contents of a directory. Without inputs, it shows the files and folders in the current working directory. With an argument, it lists the items that match a path or wildcard pattern. The return value is a character array whose rows contain the matching names padded with spaces, mirroring MATLAB behaviour.",
+    "behaviors": [
+        "`ls` without outputs displays the directory listing in the REPL. When you assign the result to a variable, you receive a character array with one row per item, padded with spaces to a fixed width.",
+        "`ls(name)` accepts character vectors or string scalars. The argument may be an absolute path, a relative path, or a wildcard such as `*.m` or `build/*`.",
+        "Paths beginning with `~` or `~/` expand to the current user's home directory, matching MATLAB desktop behaviour on every supported platform.",
+        "Wildcards follow MATLAB rules: `*` matches any sequence of characters and `?` matches exactly one character. The pattern is evaluated relative to the current folder unless it contains a leading path.",
+        "Directory results include the platform-specific file separator (`/` on Unix, `\\` on Windows) so you can quickly distinguish folders from files, and duplicate matches are removed automatically.",
+        "Empty matches return a `0×0` character array rather than raising an error, enabling idioms such as `isempty(ls(\"*.tmp\"))`.",
+        "Only scalar inputs are supported. Multi-row character arrays, multi-element string arrays, numeric values, or logical arguments raise `ls: name must be a character vector or string scalar`, mirroring MATLAB's diagnostics."
+    ],
+    "examples": [
+        {
+            "description": "List Files In The Current Folder",
+            "input": "fid = fopen(\"README.md\", \"w\"); fclose(fid);\nmkdir(\"src\");\nmkdir(\"tests\");\nls",
+            "output": "README.md\nsrc/\ntests/"
+        },
+        {
+            "description": "List Only MATLAB Files Using Wildcards",
+            "input": "fid = fopen(\"script.m\", \"w\"); fclose(fid);\nfid = fopen(\"solver.m\", \"w\"); fclose(fid);\nfid = fopen(\"test_helper.m\", \"w\"); fclose(fid);\nls(\"*.m\")",
+            "output": "script.m\nsolver.m\ntest_helper.m"
+        },
+        {
+            "description": "Capture A Directory Listing In A Variable",
+            "input": "fid = fopen(\"README.md\", \"w\"); fclose(fid);\nlisting = ls;\ndisp(listing(1, :));  % Display the first entry",
+            "output": "README.md"
+        },
+        {
+            "description": "List The Contents Of A Specific Folder",
+            "input": "mkdir(\"tmp\");\nfid = fopen(fullfile(\"tmp\", \"tmpfile.txt\"), \"w\"); fclose(fid);\nmkdir(fullfile(\"tmp\", \"subdir\"));\ntempDir = fullfile(pwd, \"tmp\");\nls(tempDir)",
+            "output": "tmpfile.txt\nsubdir/"
+        },
+        {
+            "description": "Use Wildcards With Nested Paths",
+            "input": "mkdir(fullfile(\"src\", \"utils\"));\nfid = fopen(fullfile(\"src\", \"main.rs\"), \"w\"); fclose(fid);\nfid = fopen(fullfile(\"src\", \"utils\", \"helpers.rs\"), \"w\"); fclose(fid);\nls(\"src/**/*.rs\")",
+            "output": "src/main.rs\nsrc/utils/helpers.rs"
+        },
+        {
+            "description": "Handle Missing Matches Gracefully",
+            "input": "if isempty(ls(\"*.tmp\"))\n    disp(\"No temporary files found.\");\nend",
+            "output": "No temporary files found."
+        },
+        {
+            "description": "Combine `ls` With `cd` For Temporary Directory Changes",
+            "input": "mkdir(\"examples\");\nfid = fopen(fullfile(\"examples\", \"animation.m\"), \"w\"); fclose(fid);\nfid = fopen(fullfile(\"examples\", \"plot_surface.m\"), \"w\"); fclose(fid);\nstart = cd(\"examples\");\ncleanup = onCleanup(@() cd(start));\nfiles = ls(\"*.m\")",
+            "output": "animation.m\nplot_surface.m"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What types can I pass to `ls`?",
+            "answer": "Use character vectors or string scalars. Other types – including numeric values, logical arrays, or string arrays with multiple elements – produce an error."
+        },
+        {
+            "question": "Does `ls` support wildcard patterns?",
+            "answer": "Yes. Use `*` to match any sequence and `?` for a single character. Patterns are resolved relative to the current folder unless you provide an absolute path."
+        },
+        {
+            "question": "How are directories indicated in the output?",
+            "answer": "Directory entries end with the platform-specific file separator (`/` or `\\`) so you can distinguish them from files."
+        },
+        {
+            "question": "What happens if there are no matches?",
+            "answer": "The function returns a `0×0` character array. You can test for this with `isempty` or by checking `size`."
+        },
+        {
+            "question": "Can I list the contents of another drive or mounted volume?",
+            "answer": "Yes. Provide the absolute path, e.g., `ls(\"D:\\Projects\")` on Windows or `ls(\"/Volumes/Data\")` on macOS."
+        },
+        {
+            "question": "Does `ls` follow symbolic links?",
+            "answer": "The function reports the link itself; if the link points to a directory, it receives the directory suffix but the listing does not recursively expand the target."
+        },
+        {
+            "question": "Will `ls` respect the current working directory set by `cd`?",
+            "answer": "Absolutely. `ls` always evaluates relative paths against whatever `pwd` reports."
+        },
+        {
+            "question": "Is the output sorted?",
+            "answer": "Yes. RunMat sorts case-insensitively on Windows and case-sensitively on Unix-like systems to match MATLAB conventions."
+        },
+        {
+            "question": "How do I list hidden files?",
+            "answer": "Hidden files are included when they match the pattern you specify. On Unix-like systems, prepend a dot: `ls(\".*\")`."
+        },
+        {
+            "question": "Can I send the output directly to another builtin?",
+            "answer": "Yes. Because the result is a character array, you can convert it to a string array with `string(ls)` or operate on individual rows using indexing."
+        }
+    ],
+    "links": [
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "savepath",
+            "url": "./savepath"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        },
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/ls.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/ls.rs"
+    },
+    "gpu_residency": "No. Directory listings are always computed on the CPU. Passing `gpuArray(\"*.m\")` offers no benefit: RunMat will gather the value automatically before enumerating files, and results are materialised as host-resident character arrays.",
+    "gpu_behavior": [
+        "`ls` is an I/O-centric builtin with no GPU execution path. When the argument is a GPU-resident scalar (for example, the output of `gather` that remained on the device), RunMat gathers it to the host before expanding wildcards. No device kernels run, and acceleration providers do not need to implement hooks for this builtin."
+    ],
+    "key": "ls",
+    "slug": "ls",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ls.js.map

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

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

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

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

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

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

package/dist/generated/builtins/lt.js

@@ -0,0 +1,153 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "lt",
+    "category": "logical/rel",
+    "keywords": [
+        "lt",
+        "<",
+        "less than",
+        "logical comparison",
+        "gpuArray less-than"
+    ],
+    "summary": "Element-wise less-than comparison for scalars, arrays, strings, and gpuArray inputs.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider elem_lt kernels when available; otherwise inputs gather back to host memory transparently."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::logical::rel::lt::tests",
+        "integration": "builtins::logical::rel::lt::tests::lt_gpu_provider_roundtrip",
+        "gpu": "builtins::logical::rel::lt::tests::lt_wgpu_matches_host"
+    },
+    "description": "`lt(A, B)` (or the infix `A < B`) performs an element-wise less-than comparison. The result is a logical scalar when the broadcasted shape contains one element, or a logical array otherwise.",
+    "behaviors": [
+        "Numeric, logical, and character inputs compare element-wise using MATLAB's implicit expansion rules.",
+        "Character arrays compare by Unicode code point; mixing them with numeric arrays behaves like comparing numeric codes (`'A' < 66`).",
+        "String scalars and string arrays compare lexically; implicit expansion works across string dimensions.",
+        "Complex inputs are not supported, matching MATLAB's behaviour.",
+        "Mixed numeric/string inputs raise MATLAB-compatible type errors."
+    ],
+    "examples": [
+        {
+            "description": "Determine Whether One Scalar Is Less Than Another",
+            "input": "flag = lt(17, 42)",
+            "output": "flag =\n     1"
+        },
+        {
+            "description": "Filter Matrix Elements Below A Threshold",
+            "input": "M = [1 2 3; 4 5 6];\nmask = lt(M, 3)",
+            "output": "mask =\n  2×3 logical array\n     1     1     0\n     0     0     0"
+        },
+        {
+            "description": "Apply Less-Than With Implicit Expansion",
+            "input": "v = [1 3 5 7];\nmask = lt(v, [2 6])",
+            "output": "mask =\n  1×4 logical array\n     1     0     0     0"
+        },
+        {
+            "description": "Compare Character Data To Numeric Codes",
+            "input": "letters = ['A' 'B' 'C'];\nisBeforeC = lt(letters, 67)",
+            "output": "isBeforeC =\n  1×3 logical array\n     1     1     0"
+        },
+        {
+            "description": "Compare String Arrays Lexicographically",
+            "input": "names = [\"alice\" \"charlie\" \"bob\"];\nearlier = lt(names, \"bob\")",
+            "output": "earlier =\n  1×3 logical array\n     1     0     0"
+        },
+        {
+            "description": "Run `lt` Directly On `gpuArray` Inputs",
+            "input": "G1 = gpuArray([1 4 7]);\nG2 = gpuArray([2 4 8]);\ndeviceResult = lt(G1, G2);\nhostResult = gather(deviceResult)",
+            "output": "deviceResult =\n  1×3 gpuArray logical array\n     1     0     1\nhostResult =\n  1×3 logical array\n     1     0     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `lt` return logical values?",
+            "answer": "Yes. Scalars return `true` or `false`. Arrays return logical arrays, and `gpuArray` inputs return `gpuArray` logical outputs."
+        },
+        {
+            "question": "How are NaN values treated?",
+            "answer": "Any comparison involving `NaN` returns `false`, matching MATLAB behaviour."
+        },
+        {
+            "question": "Can I compare complex numbers with `lt`?",
+            "answer": "No. MATLAB does not define relational ordering for complex numbers, so RunMat raises a MATLAB-compatible error when complex inputs are supplied."
+        },
+        {
+            "question": "How are strings compared?",
+            "answer": "String scalars and arrays compare lexicographically using Unicode code points, with full support for implicit expansion against scalar strings."
+        },
+        {
+            "question": "Are character vectors treated as numbers or text?",
+            "answer": "Character arrays participate as numeric code points when compared to numeric inputs, and they are converted to strings when compared against string scalars or arrays."
+        },
+        {
+            "question": "Do I need to gather results manually after a GPU comparison?",
+            "answer": "No. When both inputs are `gpuArray` values and the provider supports `elem_lt`, the result stays on the GPU. Otherwise, RunMat gathers inputs transparently and returns a host logical array."
+        },
+        {
+            "question": "Does implicit expansion apply to string arrays?",
+            "answer": "Yes. String arrays support MATLAB-style implicit expansion, so you can compare against scalar strings without manual replication."
+        },
+        {
+            "question": "Can I fuse `lt` inside GPU expressions?",
+            "answer": "Yes. The builtin registers element-wise fusion metadata so the planner can fuse comparisons with surrounding GPU-friendly operations."
+        }
+    ],
+    "links": [
+        {
+            "label": "gt",
+            "url": "./gt"
+        },
+        {
+            "label": "ge",
+            "url": "./ge"
+        },
+        {
+            "label": "eq",
+            "url": "./eq"
+        },
+        {
+            "label": "ne",
+            "url": "./ne"
+        },
+        {
+            "label": "isequal",
+            "url": "./isequal"
+        },
+        {
+            "label": "le",
+            "url": "./le"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/logical/rel/lt.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/logical/rel/lt.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's native auto-offload planner keeps intermediate results on the GPU when fused expressions benefit from device execution. Explicit `gpuArray` and `gather` calls remain available for compatibility with MATLAB code that manages residency manually.",
+    "gpu_behavior": [
+        "When both operands are `gpuArray` values and the active acceleration provider implements the `elem_lt` hook, RunMat executes the comparison entirely on the device and returns a `gpuArray` logical result. If the provider does not expose this hook, the runtime gathers the inputs to host memory automatically and performs the CPU comparison instead of failing."
+    ],
+    "key": "lt",
+    "slug": "lt",
+    "categoryPath": [
+        "logical",
+        "rel"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=lt.js.map

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

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

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

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

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

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

package/dist/generated/builtins/lu.js

@@ -0,0 +1,164 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "lu",
+    "category": "math/linalg/factor",
+    "keywords": [
+        "lu",
+        "factorization",
+        "decomposition",
+        "lower-upper",
+        "permutation"
+    ],
+    "summary": "LU decomposition with partial pivoting, matching MATLAB semantics.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses the provider `lu` hook when available; otherwise gathers to the host fallback implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::factor::lu::tests",
+        "integration": "builtins::math::linalg::factor::lu::tests::lu_three_outputs_matches_factorization"
+    },
+    "description": "`lu(A)` computes the LU factorization of a real or complex matrix `A` using partial pivoting. It exposes the same calling forms as MATLAB:\n\n- Single output: `lu(A)` returns a single matrix whose strictly lower-triangular entries encode `L` (with an implicit unit diagonal) and whose upper-triangular part encodes `U`. - Two outputs: `[L, U] = lu(A)` returns the explicit unit-lower-triangular factor `L` and the upper-triangular factor `U`. - Three outputs: `[L, U, P] = lu(A)` additionally returns a permutation so that `P * A = L * U`. Use the option `'vector'` to receive the permutation as a pivot vector instead of a matrix.\n\nThe implementation follows MATLAB’s dense behaviour for full matrices and supports rectangular inputs.",
+    "behaviors": [
+        "Partial pivoting is applied to improve numerical stability. The permutation is encoded either as a dense matrix (`'matrix'`, default) or as a pivot vector (`'vector'`).",
+        "Rectangular inputs are supported. `L` is always `m × m` (unit lower-triangular), and `U` is `m × n`, where `m` and `n` are the row and column counts of `A`.",
+        "Singular matrices are permitted. Zero pivots propagate into the `U` factor just as in MATLAB; MATLAB-compatible warnings are not yet emitted.",
+        "Only the first three outputs are implemented today. Column permutations (`Q`) and scaling (`R`) for the five-output sparse form are not yet available."
+    ],
+    "examples": [
+        {
+            "description": "Factorizing a square matrix with `lu`",
+            "input": "A = [2 1 1; 4 -6 0; -2 7 2];\n[L, U, P] = lu(A)",
+            "output": "L =\n     1     0     0\n    -1     1     0\n     0    -1     1\n\nU =\n     4    -6     0\n     0     1     1\n     0     0     3\n\nP =\n     0     1     0\n     1     0     0\n     0     0     1"
+        },
+        {
+            "description": "Obtaining only the combined LU factor",
+            "input": "LU = lu([1 3 5; 2 4 7; 1 1 0])",
+            "output": "LU =\n     2     4     7\n   0.5     1   -1.5\n   0.5   -0.5    2"
+        },
+        {
+            "description": "Requesting the permutation vector with the `'vector'` option",
+            "input": "[L, U, p] = lu([4 3; 6 3], 'vector')",
+            "output": "p =\n     2\n     1"
+        },
+        {
+            "description": "LU factorization of a rectangular matrix",
+            "input": "A = [3 1 2; 6 3 4];\n[L, U, P] = lu(A)",
+            "output": "L =\n     1     0\n     0.5   1\n\nU =\n     6     3     4\n     0    -0.5    0\n\nP =\n     0     1\n     1     0"
+        },
+        {
+            "description": "Using LU factors to solve a linear system",
+            "input": "A = [3 1 2; 6 3 4];\nb = [1; 2];\n[L, U, P] = lu(A);\ny = L \\ (P * b);\nx = U \\ y",
+            "output": "x =\n    0.0\n    0.5\n   -0.0"
+        },
+        {
+            "description": "Running `lu` on a `gpuArray`",
+            "input": "G = gpuArray([10 7; 3 2]);\n[L, U, P] = lu(G);\nclass(L)\nclass(U)\nclass(P)",
+            "output": "ans =\n    'gpuArray'\n\nans =\n    'gpuArray'\n\nans =\n    'gpuArray'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why does RunMat currently stop at three outputs?",
+            "answer": "Column pivoting (`Q`) and scaling (`R`) from MATLAB’s five-output sparse form are planned but not yet implemented. The dense three-output contract mirrors MATLAB’s default dense behaviour."
+        },
+        {
+            "question": "Does the permutation vector use MATLAB’s 1-based indexing?",
+            "answer": "Yes. When you request `'vector'`, the returned pivot vector contains 1-based row indices so that `A(p, :) = L * U`."
+        },
+        {
+            "question": "How are singular matrices handled?",
+            "answer": "Partial pivoting proceeds exactly as in MATLAB. If a pivot column is entirely zero, the corresponding diagonal entries in `U` become zero. No warning is emitted yet."
+        },
+        {
+            "question": "Are complex matrices supported?",
+            "answer": "Yes. Complex inputs produce complex `L`, `U`, and `LU`. The permutation remains real because it only contains zeros and ones."
+        },
+        {
+            "question": "Will the factors stay on the GPU when I pass a `gpuArray`?",
+            "answer": "Yes. When the active acceleration provider exposes the `lu` hook (WGPU today), the combined factor, `L`, `U`, and the permutation outputs remain `gpuArray` values—the provider currently performs the decomposition on the host once and reuploads the results to preserve residency. Without provider support, RunMat gathers to host memory before returning the factors."
+        },
+        {
+            "question": "Can I call `lu` on logical arrays?",
+            "answer": "Yes. Logical inputs are promoted to double precision before factorization, matching MATLAB semantics."
+        },
+        {
+            "question": "Is pivoting deterministic?",
+            "answer": "Yes. Partial pivoting always chooses the first maximal entry in each column, mirroring MATLAB’s behaviour for dense matrices."
+        },
+        {
+            "question": "How accurate is the factorization?",
+            "answer": "The implementation uses standard double-precision arithmetic (or complex double when needed). Numerical properties therefore match MATLAB’s dense fallback (without iterative refinement)."
+        },
+        {
+            "question": "What happens if I pass more than one option argument?",
+            "answer": "RunMat currently supports at most one option string (`'matrix'` or `'vector'`). Passing additional options raises an error."
+        },
+        {
+            "question": "Can I reuse the combined LU factor to solve systems?",
+            "answer": "Yes. The combined matrix returned by `lu(A)` stores `L` in the strictly lower-triangular part (with an implicit unit diagonal) and `U` in the upper-triangular part, just like MATLAB. You can use forward/back substitution routines that understand this layout."
+        }
+    ],
+    "links": [
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "chol",
+            "url": "./chol"
+        },
+        {
+            "label": "qr",
+            "url": "./qr"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "eig",
+            "url": "./eig"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/math/linalg/factor/lu.rs",
+        "url": "crates/runmat-runtime/src/builtins/math/linalg/factor/lu.rs"
+    },
+    "gpu_behavior": [
+        "When an acceleration provider implements the `lu` hook (the WGPU provider does), the factorization executes through that provider and the combined LU factor, `L`, `U`, and permutation outputs all remain on the device. The current WGPU backend performs the decomposition on the host once and immediately reuploads the factors so residency is preserved until dedicated kernels land.",
+        "The `'vector'` option likewise returns a GPU-resident pivot vector when a provider hook is active.",
+        "If no provider hook is available, RunMat automatically gathers the input to host memory and falls back to the CPU implementation so behaviour stays MATLAB-compatible."
+    ],
+    "key": "lu",
+    "slug": "lu",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "factor"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=lu.js.map

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

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

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

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

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

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