runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/not.js

@@ -0,0 +1,136 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "not",
+    "category": "logical/bit",
+    "keywords": [
+        "logical not",
+        "boolean negation",
+        "gpuArray not",
+        "MATLAB not",
+        "logical invert"
+    ],
+    "summary": "Element-wise logical negation for scalars, arrays, and gpuArray values.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Executes on the GPU when the provider implements `logical_not`; otherwise inputs gather to the host transparently."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::logical::bit::not::tests",
+        "integration": "builtins::logical::bit::not::tests::not_gpu_roundtrip",
+        "gpu": "builtins::logical::bit::not::tests::not_wgpu_matches_host_path"
+    },
+    "description": "`not(X)` inverts the logical interpretation of every element in `X`. Values that evaluate to `true` become `false`, and vice versa. MATLAB treats any non-zero (or non-empty) numeric or complex value as `true`, including `NaN`.",
+    "behaviors": [
+        "Works on scalars, vectors, matrices, and N-D tensors with MATLAB broadcasting semantics.",
+        "Accepts logical, numeric, complex, and character arrays. Character code points equal to zero become `true`, all others become `false`.",
+        "Returns a logical scalar when the input has exactly one element; otherwise the result is a logical array matching the input shape.",
+        "Honors gpuArray residency. If the active acceleration provider exposes `logical_not`, the entire operation runs on the GPU; otherwise RunMat falls back to the CPU path automatically.",
+        "`NaN` evaluates to `true`, so `not(NaN)` produces `false`, consistent with MATLAB."
+    ],
+    "examples": [
+        {
+            "description": "Checking if a scalar value is zero",
+            "input": "result = not(5)",
+            "output": "result =\n     0"
+        },
+        {
+            "description": "Negating a logical mask to find the complement",
+            "input": "mask = [true false true];\ninverseMask = not(mask)",
+            "output": "inverseMask =\n  1×3 logical array\n     0     1     0"
+        },
+        {
+            "description": "Turning nonzero numeric entries into false values",
+            "input": "A = [0 1 2 0];\nB = not(A)",
+            "output": "B =\n  1×4 logical array\n     1     0     0     1"
+        },
+        {
+            "description": "Flipping zero and nonzero character codes",
+            "input": "chars = ['A' 0 'C'];\nflags = not(chars)",
+            "output": "flags =\n  1×3 logical array\n     0     1     0"
+        },
+        {
+            "description": "Performing logical NOT directly on the GPU",
+            "input": "G = gpuArray([0 4 0 9]);\ndeviceResult = not(G);\nhostResult = gather(deviceResult)",
+            "output": "deviceResult =\n  1×4 gpuArray logical array\n     1     0     1     0\nhostResult =\n  1×4 logical array\n     1     0     1     0"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `not` return logical values?",
+            "answer": "Yes. Scalar inputs yield logical scalars (`true`/`false`). Array inputs produce logical arrays where each element is either `0` or `1`."
+        },
+        {
+            "question": "How does `not` treat `NaN` or complex numbers?",
+            "answer": "`NaN` and complex numbers with any non-zero component evaluate as `true`, so `not(NaN)` and `not(1+2i)` return `false`."
+        },
+        {
+            "question": "Can I pass a `gpuArray` to `not`?",
+            "answer": "Absolutely. If the provider implements `logical_not`, the negation runs entirely on the GPU. Otherwise the runtime gathers to the host, performs the operation, and returns a logical array."
+        },
+        {
+            "question": "What happens with empty arrays?",
+            "answer": "Empty inputs produce empty logical outputs with matching shape, preserving MATLAB's empty propagation semantics."
+        },
+        {
+            "question": "Is there a difference between `not(X)` and `~X`?",
+            "answer": "No. They share the same element-wise semantics. The functional form is convenient for higher-order APIs or when passing the operator as a handle."
+        },
+        {
+            "question": "Does `not` modify the input in place?",
+            "answer": "No. It returns a new logical value. When operating on gpuArrays, the provider writes into a fresh buffer so the original data remains unchanged."
+        }
+    ],
+    "links": [
+        {
+            "label": "and",
+            "url": "./and"
+        },
+        {
+            "label": "or",
+            "url": "./or"
+        },
+        {
+            "label": "xor",
+            "url": "./xor"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/logical/bit/not.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/logical/bit/not.rs"
+    },
+    "gpu_residency": "You usually do **not** have to call `gpuArray` manually. RunMat's auto-offload planner moves data to the GPU when a fused expression benefits from device execution. The `not` builtin preserves existing residency; results remain on the GPU until you gather them or another operation requires host access. Use `gpuArray` when porting MATLAB code that already does so explicitly or when you want to pin tensors to the GPU ahead of time.",
+    "gpu_behavior": [
+        "When RunMat Accelerate is active, `not` dispatches to the provider hook `logical_not`. Providers write `0` or `1` into a device buffer, keeping the result resident on the GPU. If the provider does not implement the hook, RunMat gathers the input to host memory, executes the CPU implementation, and (if the caller passed a `gpuArray`) returns a logical array on the host so the call never fails."
+    ],
+    "key": "not",
+    "slug": "not",
+    "categoryPath": [
+        "logical",
+        "bit"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=not.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"not.js","sourceRoot":"","sources":["../../../src/generated/builtins/not.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,aAAa;IACzB,UAAU,EAAE;QACV,aAAa;QACb,kBAAkB;QAClB,cAAc;QACd,YAAY;QACZ,gBAAgB;KACjB;IACD,SAAS,EAAE,yEAAyE;IACpF,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,oHAAoH;KAC9H;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,oCAAoC;QAC5C,aAAa,EAAE,uDAAuD;QACtE,KAAK,EAAE,gEAAgE;KACxE;IACD,aAAa,EAAE,oOAAoO;IACnP,WAAW,EAAE;QACX,0FAA0F;QAC1F,wIAAwI;QACxI,oIAAoI;QACpI,wLAAwL;QACxL,oFAAoF;KACrF;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,iBAAiB;YAC1B,QAAQ,EAAE,kBAAkB;SAC7B;QACD;YACE,aAAa,EAAE,gDAAgD;YAC/D,OAAO,EAAE,oDAAoD;YAC7D,QAAQ,EAAE,wDAAwD;SACnE;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,4BAA4B;YACrC,QAAQ,EAAE,oDAAoD;SAC/D;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,0CAA0C;YACnD,QAAQ,EAAE,kDAAkD;SAC7D;QACD;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,qFAAqF;YAC9F,QAAQ,EAAE,qIAAqI;SAChJ;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,mCAAmC;YAC/C,QAAQ,EAAE,yIAAyI;SACpJ;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,yHAAyH;SACpI;QACD;YACE,UAAU,EAAE,mCAAmC;YAC/C,QAAQ,EAAE,8LAA8L;SACzM;QACD;YACE,UAAU,EAAE,iCAAiC;YAC7C,QAAQ,EAAE,kHAAkH;SAC7H;QACD;YACE,UAAU,EAAE,kDAAkD;YAC9D,QAAQ,EAAE,mJAAmJ;SAC9J;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,kJAAkJ;SAC7J;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,yDAAyD;QAClE,KAAK,EAAE,sGAAsG;KAC9G;IACD,eAAe,EAAE,mbAAmb;IACpc,cAAc,EAAE;QACd,6YAA6Y;KAC9Y;IACD,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,cAAc,EAAE;QACd,SAAS;QACT,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/num2str.js

@@ -0,0 +1,168 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "num2str",
+    "category": "strings/core",
+    "keywords": [
+        "num2str",
+        "number to string",
+        "format",
+        "precision",
+        "gpu"
+    ],
+    "summary": "Convert numeric scalars, vectors, and matrices into MATLAB-style character arrays using general or custom formats.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/num2str.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Always formats on the CPU. GPU tensors are gathered to host memory before conversion."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::strings::core::num2str::tests",
+        "integration": "builtins::strings::core::num2str::tests::num2str_gpu_tensor_roundtrip"
+    },
+    "description": "`num2str(x)` converts numeric scalars, vectors, and matrices into a character array where each row of `x` becomes a row of text. Values use MATLAB's short-`g` formatting by default, and you can provide a precision or an explicit format specifier to control the output. Complex inputs produce `a ± bi` strings, and logical data is converted to `0` or `1`.",
+    "behaviors": [
+        "Default formatting uses up to 15 significant digits with MATLAB-style `g` behaviour (switching to scientific notation when needed).",
+        "`num2str(x, p)` formats using `p` significant digits (`0 ≤ p ≤ 52`).",
+        "`num2str(x, fmt)` accepts a single-number `printf`-style format such as `'%0.3f'`, `'%10.4e'`, or `'%.5g'`. Width, `+`, `-`, and `0` flags are supported.",
+        "A trailing `'local'` argument switches the decimal separator to the one inferred from the active locale (or the `RUNMAT_DECIMAL_SEPARATOR` environment variable).",
+        "Vector inputs return single-row character arrays; matrices return one textual row per numeric row.",
+        "Empty matrices return empty character arrays that match MATLAB's dimension rules.",
+        "Non-numeric types raise MATLAB-compatible errors."
+    ],
+    "examples": [
+        {
+            "description": "Converting A Scalar With Default Precision",
+            "input": "label = num2str(pi)",
+            "output": "label =\n    '3.14159265358979'"
+        },
+        {
+            "description": "Formatting With A Specific Number Of Significant Digits",
+            "input": "digits = num2str(pi, 4)",
+            "output": "digits =\n    '3.142'"
+        },
+        {
+            "description": "Using A Custom Format String",
+            "input": "row = num2str([1.234 5.678], '%.2f')",
+            "output": "row =\n    '1.23  5.68'"
+        },
+        {
+            "description": "Displaying A Matrix With Column Alignment",
+            "input": "block = num2str([1 23 456; 78 9 10])",
+            "output": "block =\n    ' 1  23  456'\n    '78   9   10'"
+        },
+        {
+            "description": "Formatting Complex Numbers",
+            "input": "z = num2str([3+4i 5-6i])",
+            "output": "z =\n    '3 + 4i  5 - 6i'"
+        },
+        {
+            "description": "Respecting Locale-Specific Decimal Separators",
+            "input": "text = num2str(0.125, 'local')"
+        },
+        {
+            "description": "Converting GPU-Resident Data",
+            "input": "G = gpuArray([10.5 20.5]);\ntxt = num2str(G, '%.1f')",
+            "output": "txt =\n    '10.5  20.5'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Can I request more than 15 digits?",
+            "answer": "Yes. Pass a precision between 0 and 52 to control the number of significant digits, e.g. `num2str(x, 20)`."
+        },
+        {
+            "question": "What format strings are supported?",
+            "answer": "RunMat supports single-value `printf` conversions using `%f`, `%e`, `%E`, `%g`, and `%G`, including optional width, `+`, `-`, and `0` flags. Unsupported flags raise descriptive errors."
+        },
+        {
+            "question": "Does `num2str` alter the size of my array?",
+            "answer": "No. The textual result has the same number of rows as the input and aligns each column with spaces."
+        },
+        {
+            "question": "How are complex numbers rendered?",
+            "answer": "Real and imaginary components are formatted separately using the selected precision. The result is `a + bi` or `a - bi`, with zero real parts simplifying to `bi`."
+        },
+        {
+            "question": "How does the `'local'` flag work?",
+            "answer": "`num2str(..., 'local')` replaces the decimal point with the separator inferred from the active locale. You can override the detected character with `RUNMAT_DECIMAL_SEPARATOR`, e.g. `RUNMAT_DECIMAL_SEPARATOR=,`."
+        },
+        {
+            "question": "What happens with non-numeric inputs?",
+            "answer": "Passing structs, objects, handles, or text raises a MATLAB-compatible error. Convert the data to numeric form first or use `string` for rich text conversions."
+        }
+    ],
+    "links": [
+        {
+            "label": "sprintf",
+            "url": "./sprintf"
+        },
+        {
+            "label": "string",
+            "url": "./string"
+        },
+        {
+            "label": "str2double",
+            "url": "./str2double"
+        },
+        {
+            "label": "char",
+            "url": "./char"
+        },
+        {
+            "label": "compose",
+            "url": "./compose"
+        },
+        {
+            "label": "strcmp",
+            "url": "./strcmp"
+        },
+        {
+            "label": "strcmpi",
+            "url": "./strcmpi"
+        },
+        {
+            "label": "string.empty",
+            "url": "./string.empty"
+        },
+        {
+            "label": "strings",
+            "url": "./strings"
+        },
+        {
+            "label": "strlength",
+            "url": "./strlength"
+        },
+        {
+            "label": "strncmp",
+            "url": "./strncmp"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/strings/core/num2str.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/core/num2str.rs"
+    },
+    "gpu_behavior": [
+        "When the input resides on the GPU, RunMat gathers the data back to host memory using the active RunMat Accelerate provider before applying the formatting logic. The formatted character array always lives on the CPU, so providers do not need to implement specialised kernels."
+    ],
+    "key": "num2str",
+    "slug": "num2str",
+    "categoryPath": [
+        "strings",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=num2str.js.map

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

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

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

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

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

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

@@ -0,0 +1,164 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "numel",
+    "category": "array/introspection",
+    "keywords": [
+        "numel",
+        "number of elements",
+        "array length",
+        "gpu metadata",
+        "dimensions"
+    ],
+    "summary": "Count the number of elements in scalars, vectors, matrices, and N-D arrays.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Reads tensor metadata from handles; falls back to host inspection when provider metadata is incomplete."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::introspection::numel::tests",
+        "integration": "builtins::array::introspection::numel::tests::numel_gpu_tensor_uses_shape"
+    },
+    "description": "`numel(A)` returns the number of elements contained in `A`, matching MATLAB semantics for dense arrays, logical arrays, cell arrays, structs, strings, and character arrays. The result is always a double-precision scalar.",
+    "behaviors": [
+        "`numel(A)` counts every stored element; for matrices this is `prod(size(A))`.",
+        "`numel(A, dim1, dim2, ...)` multiplies the extents of the requested dimensions. Each dimension argument must be a positive integer. Dimensions beyond the array rank contribute a factor of `1`.",
+        "Passing a numeric vector of dimensions (for example `numel(A, [1 3])`) is equivalent to listing them separately.",
+        "Scalars return `1`, character arrays report `rows × cols`, and cell arrays count the number of cells.",
+        "Empty arrays return `0` when any dimension is zero.",
+        "GPU-resident arrays use metadata stored on the device handle; when unavailable, RunMat gathers the data to maintain correctness."
+    ],
+    "examples": [
+        {
+            "description": "Counting elements in a matrix",
+            "input": "A = [1 2 3; 4 5 6];\nn = numel(A)",
+            "output": "n = 6"
+        },
+        {
+            "description": "Checking the number of elements in a cell array",
+            "input": "C = {1, 2, 3; 4, 5, 6};\ncells = numel(C)",
+            "output": "cells = 6"
+        },
+        {
+            "description": "Getting the number of elements along selected dimensions",
+            "input": "T = rand(4, 3, 2);\nplane = numel(T, 1, 2);   % product of the first two dimensions",
+            "output": "plane = 12"
+        },
+        {
+            "description": "Using `numel` with gpuArray data",
+            "input": "G = gpuArray(ones(256, 4));\ncount = numel(G)",
+            "output": "count = 1024"
+        },
+        {
+            "description": "Confirming the number of characters in a char array",
+            "input": "name = ['R' 'u' 'n' 'M' 'a' 't'];\nchars = numel(name)",
+            "output": "chars = 6"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `numel` different from `length`?",
+            "answer": "`numel(A)` counts every element in `A`, whereas `length(A)` returns the size of the largest single dimension."
+        },
+        {
+            "question": "What happens when I specify dimensions?",
+            "answer": "`numel(A, dim1, dim2, ...)` multiplies the lengths of the listed dimensions. Missing dimensions (for example, requesting the fourth dimension of a matrix) contribute a factor of `1`, matching MATLAB."
+        },
+        {
+            "question": "Does `numel` gather GPU data?",
+            "answer": "Usually no. The runtime reads shape metadata from the GPU tensor handle. It gathers only when the provider fails to populate that metadata."
+        },
+        {
+            "question": "What does `numel` return for empty arrays?",
+            "answer": "If any dimension is zero, `numel` returns `0`. This behaviour matches MATLAB for empty matrices, cell arrays, and logical arrays."
+        },
+        {
+            "question": "Can I use `numel` on strings and character arrays?",
+            "answer": "Yes. Character arrays return the total number of characters (`rows × cols`). String arrays are treated as ordinary arrays with MATLAB-compatible dimensions."
+        },
+        {
+            "question": "Is `numel` safe inside fused GPU expressions?",
+            "answer": "Yes. The builtin returns a host double scalar and does not allocate device buffers, so fusion plans remain intact."
+        },
+        {
+            "question": "Does `numel` accept non-integer dimensions?",
+            "answer": "No. Dimension arguments must be positive integers. Fractional, negative, or non-numeric values raise an error that mirrors MATLAB."
+        },
+        {
+            "question": "What does numel do in MATLAB?",
+            "answer": "`numel(A)` returns the total number of elements in array `A`. It is equivalent to `prod(size(A))`. In RunMat, `numel` works identically and supports GPU arrays."
+        },
+        {
+            "question": "Is numel the same as length in MATLAB?",
+            "answer": "No. `numel` returns the total element count across all dimensions, while `length` returns the size of the largest dimension. For a 3×4 matrix, `numel` returns 12 but `length` returns 4."
+        },
+        {
+            "question": "Can I use numel with cell arrays and structs?",
+            "answer": "Yes. `numel` counts the number of cells in a cell array or the number of elements in a struct array. It does not recurse into cell contents or struct fields."
+        }
+    ],
+    "links": [
+        {
+            "label": "size",
+            "url": "./size"
+        },
+        {
+            "label": "length",
+            "url": "./length"
+        },
+        {
+            "label": "numel",
+            "url": "./numel"
+        },
+        {
+            "label": "size",
+            "url": "./size"
+        },
+        {
+            "label": "isempty",
+            "url": "./isempty"
+        },
+        {
+            "label": "ismatrix",
+            "url": "./ismatrix"
+        },
+        {
+            "label": "isscalar",
+            "url": "./isscalar"
+        },
+        {
+            "label": "isvector",
+            "url": "./isvector"
+        },
+        {
+            "label": "ndims",
+            "url": "./ndims"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/introspection/numel.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/introspection/numel.rs"
+    },
+    "gpu_behavior": [
+        "`numel` does not launch GPU kernels or register provider hooks. When the input is a GPU tensor, the runtime consults the shape metadata stored in the handle to compute the count. If the active provider omits this metadata, RunMat downloads the tensor once to recover the correct answer. The builtin always returns a host double scalar and never allocates device memory, so it can safely be used inside fused GPU expressions without breaking residency."
+    ],
+    "key": "numel",
+    "slug": "numel",
+    "categoryPath": [
+        "array",
+        "introspection"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=numel.js.map

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

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

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

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

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

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