runmat 0.3.5 → 0.4.0

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

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

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

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

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

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

package/dist/generated/builtins/mod.js

@@ -0,0 +1,155 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mod",
+    "category": "math/rounding",
+    "keywords": [
+        "mod",
+        "modulus",
+        "remainder",
+        "rounding",
+        "gpu"
+    ],
+    "summary": "Compute the MATLAB-style modulus a - b .* floor(./b) for scalars, matrices, N-D tensors, and complex values.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/mod.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Composed from elem_div → unary_floor → elem_mul → elem_sub when all GPU operands share a shape; otherwise RunMat gathers to the host."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::rounding::mod::tests",
+        "integration": "builtins::math::rounding::mod::tests::mod_gpu_pair_roundtrip"
+    },
+    "description": "`C = mod(A, B)` returns the modulus after division such that `C` has the same sign as `B` and satisfies `A = B.*Q + C` with `Q = floor(./B)`. The definition holds for scalars, vectors, matrices, higher-dimensional tensors, and complex numbers.",
+    "behaviors": [
+        "Works with MATLAB-style implicit expansion (broadcasting) between `A` and `B`.",
+        "Returns `NaN` for elements where `B` is zero or both arguments are non-finite in incompatible ways (`Inf` modulo finite, `NaN` inputs, etc.).",
+        "Logical and integer inputs are promoted to double precision; character arrays operate on their Unicode code points.",
+        "Complex inputs use the MATLAB definition `mod(a, b) = a - b.*floor(a./b)` with complex division and component-wise `floor`.",
+        "Empty arrays propagate emptiness while retaining their shapes."
+    ],
+    "examples": [
+        {
+            "description": "Computing the modulus of positive integers",
+            "input": "r = mod(17, 5)",
+            "output": "r = 2"
+        },
+        {
+            "description": "Modulus with negative divisors keeps the divisor's sign",
+            "input": "values = [-7 -3 4 9];\nmods   = mod(values, -4)",
+            "output": "mods = [-3 -3 0 -3]"
+        },
+        {
+            "description": "Broadcasting a scalar divisor across a matrix",
+            "input": "A = [4.5  7.1; -2.3  0.4];\nresult = mod(A, 2)",
+            "output": "result =\n    [0.5  1.1;\n     1.7  0.4]"
+        },
+        {
+            "description": "MATLAB-compatible modulus for complex numbers",
+            "input": "z = [3 + 4i, -2 + 5i];\ndiv = 2 + 1i;\nres = mod(z, div)",
+            "output": "res =\n    [0.0 + 0.0i, 0.0 + 1.0i]"
+        },
+        {
+            "description": "Handling zeros in the divisor",
+            "input": "warn = mod([2, 0, -2], [0, 0, 0])",
+            "output": "warn = [NaN NaN NaN]"
+        },
+        {
+            "description": "Using `mod` with character arrays",
+            "input": "letters = mod('ABC', 5)",
+            "output": "letters = [0 1 2]"
+        },
+        {
+            "description": "Staying on the GPU when hooks are available",
+            "input": "G = gpuArray(-5:5);\nH = mod(G, 4);\ncpuCopy = gather(H)",
+            "output": "cpuCopy = [3 0 1 2 3 0 1 2 3 0 1]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `mod` different from `rem`?",
+            "answer": "`mod` uses `floor` and keeps the sign of the divisor. `rem` uses `fix` and keeps the sign of the dividend."
+        },
+        {
+            "question": "What happens when the divisor is zero?",
+            "answer": "The result is `NaN` (or `NaN + NaNi` for complex inputs), matching MATLAB semantics."
+        },
+        {
+            "question": "Does `mod` support complex numbers?",
+            "answer": "Yes. Both operands can be complex; the runtime applies MATLAB's definition with complex division and component-wise `floor`."
+        },
+        {
+            "question": "Do GPU sources need identical shapes?",
+            "answer": "Yes. The device fast path currently requires both operands to share the same shape. Other cases fall back to the CPU implementation automatically."
+        },
+        {
+            "question": "Are empty arrays preserved?",
+            "answer": "Yes. Empty inputs return empty outputs with the same shape."
+        },
+        {
+            "question": "Will `mod` ever change integer classes?",
+            "answer": "Inputs promote to double precision internally; results are reported as double scalars or tensors, mirroring MATLAB's default numeric type."
+        }
+    ],
+    "links": [
+        {
+            "label": "rem",
+            "url": "./rem"
+        },
+        {
+            "label": "floor",
+            "url": "./floor"
+        },
+        {
+            "label": "fix",
+            "url": "./fix"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ceil",
+            "url": "./ceil"
+        },
+        {
+            "label": "round",
+            "url": "./round"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/rounding/mod.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/rounding/mod.rs"
+    },
+    "gpu_residency": "Usually not. When the provider exposes the elementwise hooks noted above, `mod` executes entirely on the GPU. Otherwise RunMat gathers transparently, ensuring MATLAB-compatible behaviour without manual intervention. Explicit `gpuArray` / `gather` calls remain available for scripts that mirror MathWorks MATLAB workflows.",
+    "gpu_behavior": [
+        "When both operands are GPU tensors with the same shape, RunMat composes `mod` from the provider hooks `elem_div`, `unary_floor`, `elem_mul`, and `elem_sub`. This keeps the computation on the device when those hooks are implemented (the shipped WGPU backend and in-process provider expose them). For mixed residency, shape-mismatched operands, or providers that lack any of these hooks, RunMat gathers to the host, applies the CPU implementation, and returns a host-resident result."
+    ],
+    "key": "mod",
+    "slug": "mod",
+    "categoryPath": [
+        "math",
+        "rounding"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mod.js.map

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

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

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

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

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

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

package/dist/generated/builtins/movefile.js

@@ -0,0 +1,217 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "movefile",
+    "category": "io/repl_fs",
+    "keywords": [
+        "movefile",
+        "rename",
+        "move file",
+        "filesystem",
+        "status",
+        "message",
+        "messageid",
+        "force",
+        "overwrite"
+    ],
+    "summary": "Move or rename files and folders with MATLAB-compatible status, message, and message ID outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/movefile.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. When path inputs or flags reside on the GPU, RunMat gathers them to host memory before moving files."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::movefile::tests",
+        "integration": "builtins::io::repl_fs::movefile::tests::movefile_force_overwrites_existing_file"
+    },
+    "description": "`movefile` renames files and folders or moves them to a new location. It mirrors MATLAB by returning status information instead of throwing errors for filesystem failures and by accepting the optional `'f'` flag to overwrite destinations.",
+    "behaviors": [
+        "`status = movefile(source, destination)` moves or renames `source`. `status` is a double scalar that is `1` on success and `0` on failure.",
+        "`[status, message, messageID] = movefile(...)` also returns MATLAB-style diagnostic text. Successful operations populate both strings with empty character arrays (`1×0`).",
+        "`movefile(source, destination, 'f')` forces the move, overwriting an existing destination file or folder. Without the flag, `movefile` refuses to overwrite existing targets.",
+        "Wildcards in `source` (such as `*.m`) expand to matching filesystem entries. When the pattern resolves to multiple items, `destination` must be an existing folder and `movefile` moves each match into that folder.",
+        "Inputs accept character vectors or string scalars. Other types raise MATLAB-style errors before any filesystem work occurs.",
+        "Paths are resolved relative to the current working directory (`pwd`) and expand a leading `~` into the user's home directory.",
+        "Filesystem failures—including missing files, permission errors, or read-only destinations—return `status = 0` plus descriptive diagnostics; only invalid inputs raise immediate errors."
+    ],
+    "examples": [
+        {
+            "description": "Rename a file in the same folder",
+            "input": "fid = fopen(\"results.txt\", \"w\"); fclose(fid);\nstatus = movefile(\"results.txt\", \"archive.txt\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Move a file into an existing folder",
+            "input": "mkdir(\"reports\");\nfid = fopen(\"summary.txt\", \"w\"); fclose(fid);\nstatus = movefile(\"summary.txt\", \"reports\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Force overwrite an existing destination",
+            "input": "fid = fopen(\"draft.txt\", \"w\"); fclose(fid);\nfid = fopen(\"final.txt\", \"w\"); fclose(fid);\n[status, message, messageID] = movefile(\"draft.txt\", \"final.txt\", \"f\")",
+            "output": "status =\n     1\nmessage =\n\nmessageID ="
+        },
+        {
+            "description": "Move multiple files with a wildcard",
+            "input": "mkdir(\"data\");\nfid = fopen(\"a.log\", \"w\"); fclose(fid);\nfid = fopen(\"b.log\", \"w\"); fclose(fid);\nstatus = movefile(\"*.log\", \"data\")",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Handle missing sources gracefully",
+            "input": "[status, message, messageID] = movefile(\"missing.txt\", \"dest.txt\")",
+            "output": "status =\n     0\nmessage =\nSource \"missing.txt\" does not exist.\nmessageID =\nRunMat:MOVEFILE:FileDoesNotExist"
+        },
+        {
+            "description": "Use gpuArray inputs for paths",
+            "input": "fid = fopen(\"draft.txt\", \"w\"); fclose(fid);\nstatus = movefile(gpuArray(\"draft.txt\"), gpuArray(\"final.txt\"))",
+            "output": "status =\n     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What status codes does `movefile` return?",
+            "answer": "`1` indicates every requested move succeeded; `0` indicates that nothing was moved. Status values are doubles so existing MATLAB scripts continue to work."
+        },
+        {
+            "question": "Does `movefile` throw exceptions?",
+            "answer": "Only invalid inputs raise errors. Filesystem failures surface through the status, message, and message ID outputs."
+        },
+        {
+            "question": "How do I overwrite an existing file?",
+            "answer": "Pass the `'f'` flag as the third argument. Without it, `movefile` refuses to overwrite existing files or folders."
+        },
+        {
+            "question": "Can I move multiple files at once?",
+            "answer": "Yes. Include wildcards such as `*.txt` in `source`. The destination must be an existing folder in that case."
+        },
+        {
+            "question": "Does `movefile` work with folders?",
+            "answer": "Yes. It can move or rename entire folders. When moving into another folder and the target name already exists, pass `'f'` to overwrite it."
+        },
+        {
+            "question": "How are paths resolved?",
+            "answer": "Paths are resolved relative to `pwd`, and a leading `~` expands to the user's home directory."
+        },
+        {
+            "question": "Will GPU acceleration speed up `movefile`?",
+            "answer": "No. The builtin executes on the host CPU. GPU-resident strings are gathered automatically before performing the move."
+        },
+        {
+            "question": "What happens if no files match a wildcard?",
+            "answer": "The function returns `status = 0`, sets `message` to `\"Source \\\"pattern\\\" does not exist.\"`, and leaves the filesystem unchanged."
+        },
+        {
+            "question": "Does the function preserve timestamps or permissions?",
+            "answer": "Yes. `movefile` forwards the operation to the operating system, which preserves attributes when possible."
+        },
+        {
+            "question": "Can I move directories across volumes?",
+            "answer": "When the underlying operating system reports an error (for example, moving across volumes without rename support), `movefile` returns `status = 0` along with the system error text so you can handle it programmatically."
+        }
+    ],
+    "links": [
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "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/movefile.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/movefile.rs"
+    },
+    "gpu_residency": "No. `movefile` always runs on the host CPU, so storing paths on the GPU offers no benefit. If a string argument is already GPU-resident, RunMat gathers it automatically before touching the filesystem so existing scripts continue to work unchanged.",
+    "gpu_behavior": [
+        "`movefile` performs host-side filesystem operations. When acceleration providers are active, RunMat first gathers any GPU-resident arguments (for example, `gpuArray(\"logs\")`), executes the move on the CPU, and returns host-resident outputs. Providers do not expose special hooks for this builtin, so GPU execution is not applicable."
+    ],
+    "key": "movefile",
+    "slug": "movefile",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=movefile.js.map

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

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

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

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

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

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

package/dist/generated/builtins/mpower.js

@@ -0,0 +1,161 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mpower",
+    "category": "math/linalg/ops",
+    "keywords": [
+        "mpower",
+        "matrix power",
+        "linear algebra",
+        "gpu"
+    ],
+    "summary": "Raise scalars or square matrices to a scalar power (A^B) following MATLAB's matrix power semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/mpower.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Repeatedly invokes the provider matmul hook with binary exponentiation; falls back to the host when matmul or eye-like allocation is unavailable."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::ops::mpower::tests::matrix_square_power",
+        "gpu": "builtins::math::linalg::ops::mpower::tests::gpu_matrix_power_roundtrip"
+    },
+    "description": "`C = mpower(A, B)` evaluates the matrix power `A^B`. For scalars it behaves like ordinary exponentiation, while square matrices use repeated matrix multiplication with MATLAB-compatible rules for identity, errors, and complex promotion.",
+    "behaviors": [
+        "`A` must be square when it is a matrix. If `A` is `m × n` with `m != n`, RunMat throws `Matrix must be square for matrix power: m×n`.",
+        "The exponent `B` must be a scalar numeric value. Integer-valued doubles are accepted (`2.0` is treated as `2`); non-integer exponents raise `Matrix power requires integer exponent`.",
+        "`A^0` returns the identity matrix of the same size as `A`. Scalar inputs follow the expected rule `x^0 = 1`.",
+        "Positive integers are evaluated with binary exponentiation (`A^5` → `A * A * A * A * A`). Negative exponents are currently unsupported and produce the MATLAB-style message `Negative matrix powers not supported yet`.",
+        "Complex scalars are handled exactly; complex matrices are supported so long as the exponent is an integer."
+    ],
+    "examples": [
+        {
+            "description": "Raising a matrix to an integer power",
+            "input": "A = [1 3; 2 4];\nC = mpower(A, 2)",
+            "output": "C =\n     7    15\n    10    22"
+        },
+        {
+            "description": "Returning the identity matrix when exponent is zero",
+            "input": "A = [5 2; 7 1];\nI = mpower(A, 0)",
+            "output": "I =\n     1     0\n     0     1"
+        },
+        {
+            "description": "Scalar bases behave like ordinary exponentiation",
+            "input": "result = mpower(4, 0.5)",
+            "output": "result = 2"
+        },
+        {
+            "description": "Non-integer exponents raise an error for matrices",
+            "input": "A = [1 2; 3 4];\nC = mpower(A, 1.5)",
+            "output": "Error using  mpower\nMatrix power requires integer exponent."
+        },
+        {
+            "description": "Computing matrix powers on the GPU",
+            "input": "G = gpuArray([2 0; 0 2]);\nH = mpower(G, 3);\ngather(H)",
+            "output": "ans =\n     8     0\n     0     8"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `mpower` support non-square matrices?",
+            "answer": "No. `mpower` requires `A` to be square. Use `A.^B` for element-wise powers on non-square arrays."
+        },
+        {
+            "question": "Can I raise a matrix to a non-integer exponent?",
+            "answer": "Not yet. RunMat matches MATLAB by requiring the exponent to be an integer-valued scalar for matrix powers. Non-integer exponents raise `Matrix power requires integer exponent`."
+        },
+        {
+            "question": "Are negative exponents supported?",
+            "answer": "Negative matrix exponents will return with `Negative matrix powers not supported yet`. Use `inv(A)` manually for now."
+        },
+        {
+            "question": "How does `mpower` differ from the element-wise power operator?",
+            "answer": "`mpower` performs matrix multiplication repeatedly. Element-wise power (`.^`) raises each entry independently and supports arbitrary array shapes."
+        },
+        {
+            "question": "Will results stay on the GPU?",
+            "answer": "Yes—provided the acceleration provider implements `matmul`. When it does not, RunMat computes on the host but attempts to re-upload the result so GPU pipelines continue smoothly."
+        },
+        {
+            "question": "Is there a limit on the exponent magnitude?",
+            "answer": "Integers up to ±(2³¹−1) are supported. Exponents outside this range trigger a descriptive error."
+        }
+    ],
+    "links": [
+        {
+            "label": "mtimes",
+            "url": "./mtimes"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ctranspose",
+            "url": "./ctranspose"
+        },
+        {
+            "label": "dot",
+            "url": "./dot"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "mrdivide",
+            "url": "./mrdivide"
+        },
+        {
+            "label": "trace",
+            "url": "./trace"
+        },
+        {
+            "label": "transpose",
+            "url": "./transpose"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/ops/mpower.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/ops/mpower.rs"
+    },
+    "gpu_residency": "When a provider with matrix multiplication is active, RunMat keeps inputs and results on the GPU automatically—`gpuArray(A)^3` never leaves device memory. If the provider cannot service the request, the runtime gathers to the host, computes the reference result, and (when the outcome is real) uploads it back so the calling code still sees a `gpuArray`.",
+    "gpu_behavior": [
+        "1. When either operand already resides on the GPU, RunMat asks the active acceleration provider for repeated matrix multiplications using the provider’s `matmul` hook. 2. Identity results (`A^0`) are generated with `eye_like` when the provider exposes it; otherwise the runtime fabricates the identity on the host and uploads it. 3. If the provider declines any step (missing `matmul`, unsupported precision, unimplemented identity), RunMat gathers operands to the host, evaluates the CPU reference implementation, and uploads the result back to the device when possible so downstream code can stay on the GPU."
+    ],
+    "key": "mpower",
+    "slug": "mpower",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "ops"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mpower.js.map

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

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

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

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

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

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