runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/inv.js

@@ -0,0 +1,164 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "inv",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "inv",
+        "matrix inverse",
+        "linear algebra",
+        "solve",
+        "gpu"
+    ],
+    "summary": "Compute the inverse of a square matrix with MATLAB-compatible pivoting and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/inv.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses the acceleration provider's `inv` hook when available; the default WGPU backend gathers to the host, computes the inverse, and re-uploads the result to preserve residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::inv::tests",
+        "gpu": "builtins::math::linalg::solve::inv::tests::inv_gpu_round_trip_matches_cpu",
+        "wgpu": "builtins::math::linalg::solve::inv::tests::inv_wgpu_matches_cpu"
+    },
+    "description": "`X = inv(A)` returns the matrix inverse of a square, full-rank matrix `A`. The result satisfies `A * X = eye(size(A))` within round-off. Scalars behave like `1 ./ A`, matching MATLAB semantics.",
+    "behaviors": [
+        "Inputs must be 2-D matrices (trailing singleton dimensions are accepted). Non-square matrices raise the MATLAB error `\"inv: input must be a square matrix.\"`",
+        "Singular or rank-deficient matrices raise `\"inv: matrix is singular to working precision.\"`",
+        "Logical and integer inputs are promoted to double precision before inversion.",
+        "Complex inputs are handled in full complex arithmetic.",
+        "Empty matrices return an empty matrix with the same dimensions (e.g., `inv([])` yields `[]`)."
+    ],
+    "examples": [
+        {
+            "description": "Inverting a 2x2 matrix for solving linear systems",
+            "input": "A = [4 -2; 1 3];\nX = inv(A)",
+            "output": "X =\n    0.3    0.2\n   -0.1    0.4"
+        },
+        {
+            "description": "Checking that `inv(A)` produces the identity matrix",
+            "input": "A = [2 1 0; 0 1 -1; 0 0 3];\nX = inv(A);\nproduct = A * X",
+            "output": "product =\n    1.0000         0         0\n         0    1.0000         0\n         0         0    1.0000"
+        },
+        {
+            "description": "Inverting a diagonal matrix with symbolic structure",
+            "input": "D = diag([2, 5, 10]);\nX = inv(D)",
+            "output": "X =\n    0.5000         0         0\n         0    0.2000         0\n         0         0    0.1000"
+        },
+        {
+            "description": "Computing the inverse of a complex matrix",
+            "input": "A = [1+2i  0; 3i  4-1i];\nX = inv(A)",
+            "output": "X =\n   0.2105 - 0.1053i  -0.0158 - 0.1579i\n  -0.1579 - 0.1184i   0.0526 + 0.2632i"
+        },
+        {
+            "description": "Using `inv` on a GPU-resident matrix",
+            "input": "G = gpuArray([3 1; 0 2]);\ninvG = inv(G);       % stays on the GPU when the provider implements inv\nresult = gather(invG)",
+            "output": "result =\n    0.3333   -0.1667\n         0    0.5000"
+        },
+        {
+            "description": "Handling singular matrices gracefully",
+            "input": "A = [1 2; 2 4];\nX = inv(A)",
+            "output": "Error using inv\ninv: matrix is singular to working precision."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Do I need to use `inv` to solve linear systems?",
+            "answer": "Prefer `mldivide` (`A \\\\ b`) or `linsolve` for numerical stability and performance. Use `inv` only when you explicitly need the inverse matrix."
+        },
+        {
+            "question": "What error do I get for singular matrices?",
+            "answer": "RunMat mirrors MATLAB and raises `\"inv: matrix is singular to working precision.\"` when LU factorisation detects a zero pivot."
+        },
+        {
+            "question": "Can I invert non-square matrices?",
+            "answer": "No. `inv` requires square matrices. Use `pinv` for pseudoinverses of rectangular matrices."
+        },
+        {
+            "question": "Does `inv` support complex numbers?",
+            "answer": "Yes. Complex matrices are inverted using full complex arithmetic."
+        },
+        {
+            "question": "What happens with empty matrices?",
+            "answer": "`inv([])` returns `[]` (an empty matrix) without error."
+        },
+        {
+            "question": "Does `inv` preserve GPU residency?",
+            "answer": "If the acceleration provider exposes an `inv` hook, the operation stays on the GPU. Otherwise, RunMat gathers, computes on the host, and re-uploads so the caller still receives a GPU tensor."
+        }
+    ],
+    "links": [
+        {
+            "label": "pinv",
+            "url": "./pinv"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cond",
+            "url": "./cond"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        },
+        {
+            "label": "rank",
+            "url": "./rank"
+        },
+        {
+            "label": "rcond",
+            "url": "./rcond"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/solve/inv.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/solve/inv.rs"
+    },
+    "gpu_residency": "You typically do not need to move data manually. If `A` already resides on the GPU and the provider implements `inv`, the computation stays on the device. Providers without a native kernel (including the current WGPU backend) download `A`, compute the inverse on the host, and re-upload the result, so subsequent GPU code continues to operate on device-resident data. `gpuArray` remains available for compatibility and for explicitly seeding GPU residency.",
+    "gpu_behavior": [
+        "When a GPU acceleration provider is active, RunMat forwards the operation to its `inv` hook. If the provider does not implement a native kernel, RunMat gathers the data to the host, uses the shared CPU implementation, and attempts to re-upload the result so downstream GPU work keeps its residency. The shipping WGPU backend currently follows this gather/compute/upload pattern."
+    ],
+    "key": "inv",
+    "slug": "inv",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=inv.js.map

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

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

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

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

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

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

@@ -0,0 +1,217 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ipermute",
+    "category": "array/shape",
+    "keywords": [
+        "ipermute",
+        "inverse permute",
+        "dimension reorder",
+        "gpu"
+    ],
+    "summary": "Reorder array dimensions using the inverse of a permutation vector.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64",
+            "i32",
+            "bool"
+        ],
+        "broadcasting": "none",
+        "notes": "Reuses the GPU permute hook; when unavailable the runtime gathers, applies the inverse permutation on the host, and re-uploads."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::shape::ipermute::tests",
+        "integration": "builtins::array::shape::ipermute::tests::ipermute_gpu_roundtrip"
+    },
+    "description": "`ipermute(A, order)` reverses the dimension reordering performed by `permute(A, order)`. It is equivalent to `permute(A, invOrder)`, where `invOrder(order(i)) = i`.",
+    "behaviors": [
+        "`order` must be a permutation of `1:n`, where `n = numel(order)`.",
+        "The length of `order` must be at least `ndims(A)`; missing axes are treated as trailing singleton dimensions.",
+        "Duplicate, zero, or negative indices raise an error.",
+        "Works with numeric tensors, logical masks, complex tensors, string arrays, character arrays, and gpuArray values.",
+        "Character arrays stay 2-D; only `[1 2]` (identity) and `[2 1]` (transpose) are valid orders.",
+        "If the active acceleration provider lacks a dedicated permute kernel, RunMat gathers the data, applies the inverse permutation on the host, and re-uploads so the result remains a gpuArray."
+    ],
+    "examples": [
+        {
+            "description": "Reversing a previous permute call",
+            "input": "A = reshape(1:24, [2 3 4]);\nB = permute(A, [2 1 3]);\nC = ipermute(B, [2 1 3]);\nisequal(A, C)",
+            "output": "ans = logical 1"
+        },
+        {
+            "description": "Restoring matrix orientation after swapping dimensions",
+            "input": "M = magic(3);\nP = permute(M, [2 1]);\nR = ipermute(P, [2 1]);\nsize(R)",
+            "output": "ans = [3 3]"
+        },
+        {
+            "description": "Undoing a permutation with extra singleton dimensions",
+            "input": "row = 1:5;\nP = permute(row, [2 1 3]);\nR = ipermute(P, [2 1 3]);\nsize(R)",
+            "output": "ans = [1 5 1]"
+        },
+        {
+            "description": "Recovering logical masks after reordering axes",
+            "input": "mask = false(2, 1, 3);\nmask(1, 1, 2) = true;\nrot = permute(mask, [3 1 2]);\norig = ipermute(rot, [3 1 2]);\norig(1,1,2)",
+            "output": "ans = logical 1"
+        },
+        {
+            "description": "Working with character arrays",
+            "input": "chars = ['r','u','n'; 'm','a','t'];\nT = permute(chars, [2 1]);\nR = ipermute(T, [2 1]);\nR",
+            "output": "R =\n    'run'\n    'mat'"
+        },
+        {
+            "description": "Restoring gpuArray tensors to host layout",
+            "input": "G = gpuArray(rand(4, 2, 3));\nH = permute(G, [3 1 2]);\nR = ipermute(H, [3 1 2]);\nisequal(gather(G), gather(R))",
+            "output": "ans = logical 1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Do I have to compute the inverse permutation myself?",
+            "answer": "No. Pass the same `order` vector you used with `permute`; `ipermute` computes the inverse for you."
+        },
+        {
+            "question": "What happens if I pass an invalid permutation?",
+            "answer": "RunMat raises an error when indices repeat, fall outside `1:n`, or when the order vector is not a row or column vector."
+        },
+        {
+            "question": "Can `ipermute` introduce new singleton dimensions?",
+            "answer": "Yes. If `order` is longer than `ndims(A)`, trailing singleton dimensions are added just like MATLAB."
+        },
+        {
+            "question": "Does `ipermute` modify the input array in-place?",
+            "answer": "No. It returns a new array with reordered metadata while leaving the original untouched."
+        },
+        {
+            "question": "How does `ipermute` behave for character arrays?",
+            "answer": "Character arrays remain 2-D. Only `[1 2]` and `[2 1]` orders are accepted; other permutations raise an error."
+        },
+        {
+            "question": "Is gpuArray behaviour identical to MATLAB?",
+            "answer": "Yes. Results remain gpuArray values. When providers lack a device kernel, RunMat gathers, permutes on the host, and uploads the result before returning."
+        },
+        {
+            "question": "Does `ipermute` preserve data ordering?",
+            "answer": "Yes. Column-major ordering is preserved. Applying `permute` followed by `ipermute` returns the original array exactly."
+        },
+        {
+            "question": "Can I use `ipermute` on scalar inputs?",
+            "answer": "Absolutely. Scalars are treated as 0-D/1-D tensors so the result is the same scalar."
+        },
+        {
+            "question": "What if the order vector is a gpuArray?",
+            "answer": "MATLAB requires host numeric vectors for order specifications. RunMat enforces the same rule and raises an error."
+        },
+        {
+            "question": "Is there a performance benefit on the GPU?",
+            "answer": "Yes when the provider implements the permute hook. Otherwise the fallback path behaves like MATLAB's gather/permut/gpuArray workflow."
+        }
+    ],
+    "links": [
+        {
+            "label": "`permute`",
+            "url": "./permute"
+        },
+        {
+            "label": "`reshape`",
+            "url": "./reshape"
+        },
+        {
+            "label": "`squeeze`",
+            "url": "./squeeze"
+        },
+        {
+            "label": "`size`",
+            "url": "./size"
+        },
+        {
+            "label": "`ndims`",
+            "url": "./ndims"
+        },
+        {
+            "label": "`gpuArray`",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "`gather`",
+            "url": "./gather"
+        },
+        {
+            "label": "cat",
+            "url": "./cat"
+        },
+        {
+            "label": "circshift",
+            "url": "./circshift"
+        },
+        {
+            "label": "diag",
+            "url": "./diag"
+        },
+        {
+            "label": "flip",
+            "url": "./flip"
+        },
+        {
+            "label": "fliplr",
+            "url": "./fliplr"
+        },
+        {
+            "label": "flipud",
+            "url": "./flipud"
+        },
+        {
+            "label": "horzcat",
+            "url": "./horzcat"
+        },
+        {
+            "label": "kron",
+            "url": "./kron"
+        },
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "rot90",
+            "url": "./rot90"
+        },
+        {
+            "label": "tril",
+            "url": "./tril"
+        },
+        {
+            "label": "triu",
+            "url": "./triu"
+        },
+        {
+            "label": "vertcat",
+            "url": "./vertcat"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/shape/ipermute.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/shape/ipermute.rs"
+    },
+    "gpu_behavior": [
+        "RunMat calls the provider's `permute` hook with the inverse order vector. Providers that support the hook perform the reorder entirely on the device. Otherwise RunMat gathers to the host, permutes, and uploads the result back to the GPU, matching MATLAB's gpuArray behaviour."
+    ],
+    "key": "ipermute",
+    "slug": "ipermute",
+    "categoryPath": [
+        "array",
+        "shape"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ipermute.js.map

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

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

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

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

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

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

package/dist/generated/builtins/isa.js

@@ -0,0 +1,176 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "isa",
+    "category": "introspection",
+    "keywords": [
+        "isa",
+        "type checking",
+        "class comparison",
+        "numeric category",
+        "gpuArray"
+    ],
+    "summary": "Test whether a value belongs to a specified MATLAB class or abstract category.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/isa.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Returns host logical scalars and inspects gpuArray metadata without launching kernels."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::introspection::isa::tests",
+        "integration": "builtins::introspection::isa::tests::isa_gpu_arrays_treat_metadata_correctly"
+    },
+    "description": "`isa(x, T)` returns logical `true` when the value `x` is a member of the MATLAB class or abstract category identified by `T`. Use it to branch on numeric vs integer data, handle objects, GPU arrays, function handles, and user-defined classes.",
+    "behaviors": [
+        "Exact class names (such as `\"double\"`, `\"cell\"`, `\"struct\"`, `\"event.listener\"`) match the value’s dynamic class. Comparisons are case-insensitive.",
+        "Abstract categories (`\"numeric\"`, `\"float\"`, `\"integer\"`, `\"handle\"`, `\"function_handle\"`, `\"gpuArray\"`, `\"listener\"`) mirror MATLAB’s grouping rules.",
+        "Logical scalars, logical arrays, and logical gpuArray masks satisfy `\"logical\"` and do not register as `\"numeric\"`. RunMat consults handle metadata rather than downloading device buffers.",
+        "Handle inheritance is respected: if a class derives from `handle`, `isa(obj, \"handle\")` returns `true` even when `class(obj)` reports a subclass name.",
+        "`isa` accepts either a string scalar or a character row vector as the class designator.",
+        "gpuArray inputs never need to be gathered; RunMat checks residency metadata to answer the query."
+    ],
+    "examples": [
+        {
+            "description": "Checking whether a scalar is double precision",
+            "input": "tf = isa(42, \"double\")",
+            "output": "tf = logical(1)"
+        },
+        {
+            "description": "Testing numeric arrays against the numeric category",
+            "input": "A = rand(3, 4);\nis_numeric = isa(A, \"numeric\");\nis_integer = isa(A, \"integer\")",
+            "output": "is_numeric = logical(1)\nis_integer = logical(0)"
+        },
+        {
+            "description": "Confirming that gpuArray data counts as numeric",
+            "input": "G = gpuArray(rand(1024, 1024));\ntf_numeric = isa(G, \"numeric\");\ntf_double = isa(G, \"double\");   % false — the class reports gpuArray",
+            "output": "tf_numeric = logical(1)\ntf_double = logical(0)"
+        },
+        {
+            "description": "Determining whether a GPU mask is logical",
+            "input": "G = gpuArray(rand(5) > 0.5);\nis_mask = isa(G, \"logical\");\nis_numeric = isa(G, \"numeric\")",
+            "output": "is_mask = logical(1)\nis_numeric = logical(0)"
+        },
+        {
+            "description": "Validating handle subclasses",
+            "input": "pt = pkg.TestHandle();          % derives from handle\ntf_handle = isa(pt, \"handle\");\ntf_exact = isa(pt, \"pkg.TestHandle\")",
+            "output": "tf_handle = logical(1)\ntf_exact = logical(1)"
+        },
+        {
+            "description": "Comparing string scalars and character vectors",
+            "input": "s = \"RunMat\";\nc = 'RunMat';\ntf_string = isa(s, \"string\");\ntf_char = isa(c, \"char\")",
+            "output": "tf_string = logical(1)\ntf_char = logical(1)"
+        },
+        {
+            "description": "Detecting function handles and listeners",
+            "input": "fh = @sin;\ntf_handle = isa(fh, \"function_handle\");\nlst = addlistener(TestSource, \"Changed\", @disp);\ntf_listener = isa(lst, \"listener\")",
+            "output": "tf_handle = logical(1)\ntf_listener = logical(1)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `isa` treat gpuArray values as numeric?",
+            "answer": "Yes for numeric device arrays. `isa(gpuArray(rand(4)), \"numeric\")` and `isa(..., \"float\")` return `true`, even though the concrete class is `\"gpuArray\"`. Logical gpuArray masks skip the numeric categories and only satisfy `\"logical\"`. Use `isa(..., \"double\")` when you specifically need host doubles."
+        },
+        {
+            "question": "How do I check for integer types?",
+            "answer": "Use the `\"integer\"` category. It matches MATLAB’s native integer classes (`int8`, `uint16`, and so on). For example `isa(int32(5), \"integer\")` returns `true` while `isa(5, \"integer\")` returns `false`."
+        },
+        {
+            "question": "Does `isa` understand handle inheritance?",
+            "answer": "Yes. If a class derives from `handle`, then the object passes the `\"handle\"` category check. The builtin walks parent classes registered with RunMat to mirror MATLAB semantics."
+        },
+        {
+            "question": "What kinds of strings can I pass as the type name?",
+            "answer": "Provide either a string scalar (double quotes) or a character row vector (single quotes). Multi-row character arrays and string arrays with more than one element throw a descriptive error."
+        },
+        {
+            "question": "How do I detect function handles or anonymous functions?",
+            "answer": "Both named function handles and closures pass `isa(value, \"function_handle\")`."
+        },
+        {
+            "question": "Will `isa` gather gpuArray inputs or launch kernels?",
+            "answer": "No. The builtin is metadata-only and returns a host logical scalar without copying device buffers."
+        },
+        {
+            "question": "How are listeners treated?",
+            "answer": "Event listeners pass both `isa(listener, \"event.listener\")` and the compatibility alias `isa(listener, \"listener\")`. They also satisfy the `\"handle\"` category."
+        },
+        {
+            "question": "Does `isa` differentiate between string and char arrays?",
+            "answer": "Yes. String scalars pass `\"string\"` while character arrays pass `\"char\"`. They are not interchangeable."
+        },
+        {
+            "question": "Can I use `isa` to test meta-class values?",
+            "answer": "Yes. Meta-class references created with `classref` return `true` for `\"meta.class\"`."
+        }
+    ],
+    "links": [
+        {
+            "label": "`class`",
+            "url": "./class"
+        },
+        {
+            "label": "`isnumeric`",
+            "url": "./isnumeric"
+        },
+        {
+            "label": "`islogical`",
+            "url": "./islogical"
+        },
+        {
+            "label": "`gpuArray`",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "`gather`",
+            "url": "./gather"
+        },
+        {
+            "label": "ischar",
+            "url": "./ischar"
+        },
+        {
+            "label": "isstring",
+            "url": "./isstring"
+        },
+        {
+            "label": "which",
+            "url": "./which"
+        },
+        {
+            "label": "who",
+            "url": "./who"
+        },
+        {
+            "label": "whos",
+            "url": "./whos"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/introspection/isa.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/introspection/isa.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the fusion planner keeps residency on GPU in branches of fused expressions. As such, when you call `isa` on a gpuArray result, the planner preserves the device buffer and `isa` answers the query using metadata only.\n\nTo preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call `gpuArray` explicitly to move data to the GPU if you want to be explicit about the residency.\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": [
+        "`isa` never launches GPU kernels. For gpuArray inputs RunMat inspects the `GpuTensorHandle` metadata to identify the device array and satisfy category checks such as `\"numeric\"` and `\"gpuArray\"`. Because the builtin only returns a host logical scalar it does not participate in fusion, and providers do not need to expose additional hooks."
+    ],
+    "key": "isa",
+    "slug": "isa",
+    "categoryPath": [
+        "introspection"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=isa.js.map

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

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

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

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

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

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