runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/minus.js

@@ -0,0 +1,244 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "minus",
+    "category": "math/elementwise",
+    "keywords": [
+        "minus",
+        "element-wise subtraction",
+        "-",
+        "gpu",
+        "implicit expansion"
+    ],
+    "summary": "Element-wise subtraction A - B with MATLAB-compatible implicit expansion, complex support, and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/minus.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider elem_sub for matching gpuArray shapes, scalar_sub for gpuArray - scalar, scalar_rsub for scalar - gpuArray, and gathers to host for implicit expansion or unsupported operand types."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::minus::tests::minus_scalar_numbers",
+        "integration": "builtins::math::elementwise::minus::tests::minus_row_column_broadcast",
+        "gpu": "builtins::math::elementwise::minus::tests::minus_gpu_pair_roundtrip",
+        "wgpu": "builtins::math::elementwise::minus::tests::minus_wgpu_matches_cpu_elementwise",
+        "like_gpu": "builtins::math::elementwise::minus::tests::minus_like_gpu_prototype_keeps_residency",
+        "like_host": "builtins::math::elementwise::minus::tests::minus_like_host_gathers_gpu_value",
+        "like_complex": "builtins::math::elementwise::minus::tests::minus_like_complex_prototype_yields_complex"
+    },
+    "description": "`minus(A, B)` (or the operator form `A - B`) subtracts corresponding elements of `B` from `A`, honouring MATLAB's implicit expansion rules so that scalars and singleton dimensions broadcast automatically.",
+    "behaviors": [
+        "Supports real, complex, logical, and character inputs; logical and character data are promoted to double precision before subtraction.",
+        "Implicit expansion works across any dimension, provided the non-singleton extents match. Size mismatches raise the standard MATLAB-compatible error message.",
+        "Complex operands follow MATLAB's analytic rule `(a + ib) - (c + id) = (a - c) + i(b - d)`.",
+        "Empty dimensions propagate naturally—if either operand has a zero-sized dimension after broadcasting, the result is empty with the broadcasted shape.",
+        "Integer inputs promote to double precision before subtraction, mirroring MATLAB behaviour and keeping numeric tower rules consistent with other RunMat arithmetic builtins.",
+        "The optional `'like'` prototype makes the output adopt the residency (host or GPU) and complexity characteristics of the prototype, which is particularly useful for keeping implicit-expansion expressions on the device."
+    ],
+    "examples": [
+        {
+            "description": "Subtracting two matrices element-wise",
+            "input": "A = [7 8 9; 4 5 6];\nB = [1 2 3; 1 2 3];\nD = minus(A, B)",
+            "output": "D =\n     6     6     6\n     3     3     3"
+        },
+        {
+            "description": "Subtracting a scalar from every matrix element",
+            "input": "A = magic(3);\nshifted = minus(A, 0.5)",
+            "output": "shifted =\n    7.5    0.5    5.5\n    2.5    4.5    6.5\n    3.5    8.5    1.5"
+        },
+        {
+            "description": "Broadcasting a column minus a row vector",
+            "input": "col = (1:3)';\nrow = [10 20 30];\nM = minus(col, row)",
+            "output": "M =\n    -9   -19   -29\n    -8   -18   -28\n    -7   -17   -27"
+        },
+        {
+            "description": "Subtracting complex numbers element-wise",
+            "input": "z1 = [1+2i, 3-4i];\nz2 = [2-1i, -1+1i];\ndiffz = minus(z1, z2)",
+            "output": "diffz =\n    -1 + 3i     4 - 5i"
+        },
+        {
+            "description": "Subtracting from character codes",
+            "input": "letters = 'DEF';\ncodes = minus(letters, 1)",
+            "output": "codes = [67 68 69]"
+        },
+        {
+            "description": "Keeping element-wise differences on the GPU with `'like'`",
+            "input": "proto = gpuArray.zeros(1, 1);\nG1 = gpuArray([10 20 30]);\nG2 = gpuArray([1 2 3]);\ndeviceDiff = minus(G1, G2, 'like', proto);\nresult = gather(deviceDiff)",
+            "output": "deviceDiff =\n  1x3 gpuArray\n     9    18    27\nresult =\n     9    18    27"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `minus` support MATLAB implicit expansion?",
+            "answer": "Yes. Any singleton dimensions expand automatically. If a dimension has incompatible non-singleton extents, `minus` raises the standard size-mismatch error."
+        },
+        {
+            "question": "What numeric type does `minus` return?",
+            "answer": "Results are double precision for real inputs and complex double when either operand is complex. Logical and character inputs are promoted to double before subtraction."
+        },
+        {
+            "question": "Can I subtract gpuArrays and host scalars?",
+            "answer": "Yes. RunMat keeps the computation on the GPU when the scalar is numeric. For other host operand types, the runtime gathers the gpuArray and computes on the CPU."
+        },
+        {
+            "question": "Does `minus` preserve gpuArray residency after a fallback?",
+            "answer": "When a fallback occurs (for example, implicit expansion that the provider does not implement), the resulting array stays on the host by default. Provide a `'like', gpuArray(...)` prototype if you need the runtime to re-upload the final result automatically."
+        },
+        {
+            "question": "How can I force the result to stay on the GPU?",
+            "answer": "Provide a `'like'` prototype: `minus(A, B, 'like', gpuArray.zeros(1, 1))` keeps the result on the device even if one of the inputs originated on the host."
+        },
+        {
+            "question": "How are empty arrays handled?",
+            "answer": "Empty dimensions propagate. If either operand has an extent of zero in the broadcasted shape, the result is empty with that broadcasted shape."
+        },
+        {
+            "question": "Are integer inputs supported?",
+            "answer": "Yes. Integers promote to double precision during the subtraction, matching other RunMat arithmetic builtins."
+        },
+        {
+            "question": "Can I mix complex and real operands?",
+            "answer": "Absolutely. The result is complex, with broadcasting rules identical to MATLAB."
+        },
+        {
+            "question": "What about string arrays?",
+            "answer": "String arrays are not numeric and therefore raise an error when passed to `minus`."
+        }
+    ],
+    "links": [
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/minus.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/minus.rs"
+    },
+    "gpu_residency": "RunMat's auto-offload planner keeps tensors on the GPU whenever fused expressions benefit from device execution. Explicit `gpuArray` / `gather` calls remain supported for MATLAB code that manages residency manually. When the active provider lacks the kernels needed for a particular call (for example, implicit expansion between gpuArrays of different shapes), RunMat gathers back to the host, computes the MATLAB-accurate result, and resumes execution seamlessly.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active:\n\n1. If both operands are gpuArrays with identical shapes, RunMat dispatches to the provider's `elem_sub` hook. 2. If the left operand is a gpuArray and the right operand is a scalar, RunMat calls `scalar_sub` to keep the computation on the device. 3. If the right operand is a gpuArray and the left operand is a scalar, RunMat calls `scalar_rsub` so the scalar subtraction also remains on the device. 4. Implicit-expansion workloads (e.g., mixing row and column vectors) or unsupported operand kinds gather transparently to host memory, compute the result with full MATLAB semantics, and return a host tensor unless a `'like'` GPU prototype is supplied—in which case the runtime re-uploads the output to honour the residency request."
+    ],
+    "key": "minus",
+    "slug": "minus",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=minus.js.map

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

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

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

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

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

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

package/dist/generated/builtins/mkdir.js

@@ -0,0 +1,220 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mkdir",
+    "category": "io/repl_fs",
+    "keywords": [
+        "mkdir",
+        "create directory",
+        "folder",
+        "filesystem",
+        "status",
+        "message",
+        "messageid"
+    ],
+    "summary": "Create folders with MATLAB-compatible status, message, and message ID outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/mkdir.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. When path inputs reside on the GPU, RunMat gathers them to host memory before creating directories."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::mkdir::tests",
+        "integration": "builtins::io::repl_fs::mkdir::tests::mkdir_captures_failure_status_and_message"
+    },
+    "description": "`mkdir` creates new folders on disk. It mirrors MATLAB by accepting either a single path string or a parent-folder plus child-name pair, and it returns diagnostic status information instead of throwing errors for most filesystem failures.",
+    "behaviors": [
+        "`status = mkdir(folder)` creates `folder`, returning `1` when the directory is created or already exists, and `0` on failure. Status outputs are `double` scalars for MATLAB compatibility.",
+        "`[status, message, messageID] = mkdir(parent, child)` creates the directory `fullfile(parent, child)`. When the directory is created during this call, the message outputs are empty. If the directory already exists, MATLAB populates them with `'Directory already exists.'` and `'RunMat:MKDIR:DirectoryExists'`. Failures return the system error text and message identifier.",
+        "The optional `message` and `messageID` outputs are character arrays (with size `1×0` when empty), matching MATLAB’s behaviour. Callers that prefer string scalars can wrap them with `string(message)`.",
+        "Passing a parent folder that does not exist leaves the filesystem unchanged and returns `status = 0`.",
+        "If the target path already exists as a file, `mkdir` fails gracefully with `status = 0` and a diagnostic message; it does not overwrite files.",
+        "Path arguments accept character vectors or string scalars. Other input types raise `mkdir: folder name must be a character vector or string scalar` (or the equivalent message for the parent argument).",
+        "The builtin expands `~` to the user’s home directory and honours relative paths with respect to the current working folder (`pwd`)."
+    ],
+    "examples": [
+        {
+            "description": "Create A New Folder In The Current Directory",
+            "input": "status = mkdir(\"results\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Create A Nested Folder Using Parent And Child Arguments",
+            "input": "mkdir(\"data\");\nstatus = mkdir(\"data\", \"archive/2024\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Detect When A Folder Already Exists",
+            "input": "mkdir(\"logs\");\n[status, message, messageID] = mkdir(\"logs\")",
+            "output": "status =\n     1\n\nmessage =\nDirectory already exists.\n\nmessageID =\nRunMat:MKDIR:DirectoryExists"
+        },
+        {
+            "description": "Handle Missing Parent Folder Gracefully",
+            "input": "[status, message, messageID] = mkdir(\"missing-parent\", \"child\")",
+            "output": "status =\n     0\nmessage =\nParent folder \"missing-parent\" does not exist.\nmessageID =\nRunMat:MKDIR:ParentDirectoryDoesNotExist"
+        },
+        {
+            "description": "Capture Detailed Status And Messages",
+            "input": "[status, message, messageID] = mkdir(\"reports\")",
+            "output": "status =\n     1\nmessage =\n\nmessageID ="
+        },
+        {
+            "description": "Create A Folder In Your Home Directory With Tilde Expansion",
+            "input": "status = mkdir(\"~\", \"RunMatProjects\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Use gpuArray Inputs For Paths",
+            "input": "status = mkdir(gpuArray(\"gpu-output\"))",
+            "output": "status =\n     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What status codes does `mkdir` return?",
+            "answer": "`1` indicates success (the directory exists afterwards), and `0` indicates failure. Status values are doubles to match MATLAB."
+        },
+        {
+            "question": "Does `mkdir` overwrite existing files?",
+            "answer": "No. If the target path already exists as a regular file, `mkdir` returns `status = 0` and reports that the path is not a directory."
+        },
+        {
+            "question": "Can I create multiple levels of folders at once?",
+            "answer": "Yes when you provide a single path, because RunMat mirrors MATLAB’s behaviour of creating intermediate directories. When using the two-argument form, the parent folder must already exist."
+        },
+        {
+            "question": "Does `mkdir` support string scalars and character vectors?",
+            "answer": "Yes. String arrays must contain exactly one element; other types raise an error."
+        },
+        {
+            "question": "How are error messages returned?",
+            "answer": "Failures return descriptive messages and MATLAB-style message IDs (for example, `RunMat:MKDIR:OSError`) in the second and third outputs. The builtin does not throw unless the inputs are invalid."
+        },
+        {
+            "question": "Are UNC paths and drive-letter paths supported on Windows?",
+            "answer": "Yes. Provide the path exactly as you would in MATLAB; RunMat forwards it to the operating system."
+        },
+        {
+            "question": "Can I run `mkdir` on the GPU?",
+            "answer": "No. The function operates on the host, but it automatically gathers GPU-resident inputs for convenience."
+        },
+        {
+            "question": "What happens if the folder already exists?",
+            "answer": "`mkdir` reports success (`status = 1`) and leaves the directory untouched, just like MATLAB."
+        },
+        {
+            "question": "Does tilde (`~`) expand to the home directory?",
+            "answer": "Yes. Both single-argument and two-argument forms expand `~` at the start of a path."
+        },
+        {
+            "question": "How do I handle errors programmatically?",
+            "answer": "Capture the optional outputs and test `status`. When it is `0`, inspect `message` and `messageID` for diagnostics."
+        }
+    ],
+    "links": [
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "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/mkdir.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/mkdir.rs"
+    },
+    "gpu_residency": "No. `mkdir` executes entirely on the host—GPU residency provides no benefit. However, if a script accidentally stores path strings on the GPU, RunMat automatically gathers them before accessing the filesystem so the call still succeeds.",
+    "gpu_behavior": [
+        "`mkdir` performs host-side filesystem operations. When callers supply GPU-resident scalars (for example, `gpuArray(\"logs\")`), RunMat gathers the value back to the CPU before resolving the path. Acceleration providers do not publish hooks for this builtin, so there is no device-side implementation to enable."
+    ],
+    "key": "mkdir",
+    "slug": "mkdir",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mkdir.js.map

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

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

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

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

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

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

package/dist/generated/builtins/mldivide.js

@@ -0,0 +1,156 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mldivide",
+    "category": "math/linalg/ops",
+    "keywords": [
+        "mldivide",
+        "matrix left division",
+        "linear systems",
+        "least squares",
+        "gpu"
+    ],
+    "summary": "Solve A * X = B using MATLAB's left-division operator (`\\`).",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/double.mldivide.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Prefers the accel provider's mldivide hook; providers without a native solve gather to host, run the shared SVD solver, then re-upload the result to preserve GPU residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::ops::mldivide::tests",
+        "gpu": "builtins::math::linalg::ops::mldivide::tests::gpu_round_trip_matches_cpu",
+        "wgpu": "builtins::math::linalg::ops::mldivide::tests::wgpu_round_trip_matches_cpu"
+    },
+    "description": "`X = A \\ B` (or `mldivide(A, B)`) solves the left-sided linear system `A * X = B`. When `A` is square and nonsingular the solution matches `inv(A) * B`. Rectangular or rank-deficient matrices are handled via a minimum-norm least-squares solve, mirroring MATLAB's SVD-based semantics.",
+    "behaviors": [
+        "Scalars divide exactly: `s \\ B` scales `B` by `1/s`, while `A \\ s` requires `A` to be scalar.",
+        "Logical and integer inputs are promoted to double precision before solving.",
+        "Purely real operands return real outputs; any complex operand promotes the computation (and result) to complex arithmetic.",
+        "Inputs must behave like 2-D matrices; trailing singleton dimensions are allowed.",
+        "The number of rows must agree (`size(A, 1) == size(B, 1)`), otherwise RunMat raises the MATLAB error `\"Matrix dimensions must agree.\"`",
+        "Underdetermined and overdetermined systems return the minimum-norm least-squares solution."
+    ],
+    "examples": [
+        {
+            "description": "Solving a square linear system with backslash",
+            "input": "A = [1 2; 3 4];\nb = [5; 6];\nx = A \\ b",
+            "output": "x =\n    -4.0000\n     4.5000"
+        },
+        {
+            "description": "Computing a least-squares solution with backslash",
+            "input": "A = [1 2; 3 4; 5 6];\nb = [7; 8; 9];\nx = A \\ b",
+            "output": "x =\n    -6.0000\n     6.5000"
+        },
+        {
+            "description": "Scaling by a scalar using backslash",
+            "input": "s = 2;\nB = [2 4 6];\nscaled = s \\ B",
+            "output": "scaled = [1 2 3]"
+        },
+        {
+            "description": "Solving multiple right-hand sides at once",
+            "input": "A = [4 1; 2 3];\nB = [1 0; 0 1];\nX = A \\ B",
+            "output": "X =\n     0.3   -0.1\n    -0.2    0.4"
+        },
+        {
+            "description": "Left division with complex matrices",
+            "input": "A = [2+i 1; -1 3-2i];\nB = [1; 4+i];\nX = A \\ B",
+            "output": "X =\n   -0.0732 - 0.3415i\n    0.8049 + 0.7561i"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why must `A` and `B` share the number of rows?",
+            "answer": "Left division solves `A * X = B`, which requires `size(A, 1) == size(B, 1)` for matrix multiplication to be defined."
+        },
+        {
+            "question": "What happens if `A` is singular or rectangular?",
+            "answer": "RunMat mirrors MATLAB by computing the minimum-norm least-squares solution using singular-value decomposition—no explicit pseudoinverse is necessary."
+        },
+        {
+            "question": "Does `mldivide` work with higher-dimensional arrays?",
+            "answer": "Inputs must behave like matrices. Trailing singleton dimensions are allowed, but higher-rank arrays should be reshaped before calling `mldivide`."
+        },
+        {
+            "question": "How are logical or integer arrays treated?",
+            "answer": "They are promoted to double precision (`true → 1`, `false → 0`) before solving, matching MATLAB semantics."
+        },
+        {
+            "question": "How does RunMat handle NaN or Inf values?",
+            "answer": "NaNs and Infs propagate through the least-squares solver exactly as MATLAB does—any slice containing NaNs will typically produce NaNs in the corresponding output entries."
+        }
+    ],
+    "links": [
+        {
+            "label": "mrdivide",
+            "url": "./mrdivide"
+        },
+        {
+            "label": "mtimes",
+            "url": "./mtimes"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ctranspose",
+            "url": "./ctranspose"
+        },
+        {
+            "label": "dot",
+            "url": "./dot"
+        },
+        {
+            "label": "mpower",
+            "url": "./mpower"
+        },
+        {
+            "label": "trace",
+            "url": "./trace"
+        },
+        {
+            "label": "transpose",
+            "url": "./transpose"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/ops/mldivide.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/ops/mldivide.rs"
+    },
+    "gpu_residency": "No manual residency management is required. If both operands already live on the GPU and the active provider implements `mldivide`, the solve stays on the device. When the provider falls back to the host (as the current WGPU backend does), RunMat gathers data, executes the same SVD solver used by the CPU implementation, and re-uploads the result so subsequent GPU work continues seamlessly.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active, RunMat first offers the solve to its `mldivide` hook. The current WGPU provider downloads the operands to the host, executes the shared SVD-based solver, then uploads the result back to the device so downstream GPU pipelines keep their residency. If no provider is available—or a provider declines the request—RunMat gathers gpuArray inputs to the host, performs the solve there, and returns a host tensor."
+    ],
+    "key": "mldivide",
+    "slug": "mldivide",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "ops"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mldivide.js.map