runmat 0.3.6 → 0.4.1

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

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

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

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

package/dist/generated/builtins/cd.js

@@ -0,0 +1,200 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cd",
+    "category": "io/repl_fs",
+    "keywords": [
+        "cd",
+        "change directory",
+        "current folder",
+        "working directory",
+        "pwd"
+    ],
+    "summary": "Change the current working folder or query the folder that RunMat is executing in.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/cd.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. When the folder argument resides on the GPU, RunMat gathers it to the host before resolving the new path."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::cd::tests",
+        "integration": "builtins::io::repl_fs::cd::tests::cd_changes_directory_and_returns_previous"
+    },
+    "description": "`cd` displays the current working folder or switches RunMat to a different folder. It mirrors MATLAB so scripts and interactive sessions can rely on the same workspace layout when loading files, saving artifacts, or invoking other builtins that reference relative paths.",
+    "behaviors": [
+        "`cd` with no input returns the absolute path of the current folder as a character row vector (`1×N`).",
+        "`cd(newFolder)` changes the working folder and returns the previous folder, enabling the classic MATLAB pattern `old = cd(new); ...; cd(old);`.",
+        "Accepts character vectors and string scalars. String arrays must contain exactly one element. Other types raise `cd: folder name must be a character vector or string scalar`.",
+        "Supports relative paths (for example `cd('..')`), absolute paths, and the shell-style `~` expansion to jump to the user home folder.",
+        "Emits descriptive errors when the folder does not exist or cannot be accessed.",
+        "Does not modify GPU residency; path values always live on the host."
+    ],
+    "examples": [
+        {
+            "description": "Display The Current Working Folder In RunMat",
+            "input": "current = cd",
+            "output": "% current is the absolute path to the folder where RunMat is executing"
+        },
+        {
+            "description": "Change Directory To A Project Subfolder",
+            "input": "projectRoot = pwd;\nmkdir(\"data/logs\");\nold = cd(\"data/logs\");\n% ... work inside the logs folder ...\ncd(old)",
+            "output": "% old contains the previous folder so you can restore it later, and the final cd(old)\n% call brings you back to projectRoot"
+        },
+        {
+            "description": "Navigate Up One Level From The Current Folder",
+            "input": "old = cd(\"..\")",
+            "output": "% RunMat moves to the parent folder and old captures the prior location"
+        },
+        {
+            "description": "Switch To Your Home Folder With cd ~",
+            "input": "old = cd(\"~\")",
+            "output": "% Changes to the user home directory; old stores the previous folder"
+        },
+        {
+            "description": "Capture The Previous Folder And Restore Later",
+            "input": "old = cd(\"results\");\n% ... run code that writes outputs into results ...\ncd(old)",
+            "output": "% The working folder is restored to its original location at the end"
+        },
+        {
+            "description": "Handle Missing Folders With A try/catch Block",
+            "input": "try\n    cd(\"missing-folder\");\ncatch err\n    disp(err.message);\nend",
+            "output": "% Displays a descriptive error such as:\n% \"cd: unable to change directory to 'missing-folder' (No such file or directory)\""
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `cd` return the new folder or the old folder?",
+            "answer": "When you pass an input, `cd` returns the previous folder so that you can restore it later. Calling `cd` with no input returns the current folder."
+        },
+        {
+            "question": "Can I pass GPU-resident strings to `cd`?",
+            "answer": "Yes. RunMat gathers any GPU scalar arguments automatically before resolving the path."
+        },
+        {
+            "question": "Is tilde (`~`) expansion supported?",
+            "answer": "Yes. `cd('~')` and `cd('~/subdir')` jump to the user home folder. Other leading `~` patterns are treated literally so existing MATLAB scripts continue to work on platforms that support them."
+        },
+        {
+            "question": "How are relative paths resolved?",
+            "answer": "Relative folders are interpreted with respect to whatever `cd` reports as the current folder, exactly like MATLAB."
+        },
+        {
+            "question": "What happens if the target folder does not exist?",
+            "answer": "`cd` throws an error that includes both the requested folder and the underlying operating system message."
+        },
+        {
+            "question": "Can I change to folders whose names include spaces?",
+            "answer": "Yes. Provide them as strings or character vectors—RunMat preserves whitespace exactly."
+        }
+    ],
+    "links": [
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "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": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "savepath",
+            "url": "./savepath"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        },
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/cd.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/cd.rs"
+    },
+    "gpu_residency": "`cd` operates entirely on the CPU, so there is no performance benefit to moving folder arguments onto the GPU. If a path value is already wrapped in `gpuArray`, RunMat transparently gathers it before resolving the change directory request. Scripts can keep using plain character vectors or string scalars without worrying about residency.",
+    "gpu_behavior": [
+        "`cd` performs host-side path manipulation and process-level directory changes. When callers supply the folder argument from GPU memory, RunMat gathers the value before resolving the new path. Providers are not expected to implement hooks for this builtin, and no GPU kernels run as part of `cd`."
+    ],
+    "key": "cd",
+    "slug": "cd",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cd.js.map

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

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

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

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

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

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

package/dist/generated/builtins/ceil.js

@@ -0,0 +1,175 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ceil",
+    "category": "math/rounding",
+    "keywords": [
+        "ceil",
+        "rounding",
+        "digits",
+        "significant digits",
+        "gpu",
+        "like"
+    ],
+    "summary": "Round scalars, vectors, matrices, or N-D tensors toward positive infinity or to specified digits.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host implementation when the active provider lacks unary_ceil."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::rounding::ceil::tests",
+        "integration": "builtins::math::rounding::ceil::tests::ceil_gpu_provider_roundtrip"
+    },
+    "description": "`ceil(X)` rounds each element of `X` toward positive infinity, returning the smallest integer greater than or equal to the input. Optional arguments match MATLAB's extended syntax for rounding to fixed decimal places, significant digits, and prototype-based residency.",
+    "behaviors": [
+        "Works on scalars, vectors, matrices, and higher-dimensional tensors with MATLAB broadcasting semantics.",
+        "`ceil(X, N)` rounds toward positive infinity with `N` decimal digits (positive `N`) or powers of ten (negative `N`).",
+        "`ceil(X, N, 'significant')` rounds to `N` significant digits; `N` must be a positive integer.",
+        "Logical inputs are promoted to doubles (`false → 0`, `true → 1`) before applying the ceiling operation.",
+        "Character arrays are interpreted numerically (their Unicode code points) and return dense double tensors.",
+        "Complex inputs are rounded component-wise: `ceil(a + bi) = ceil(a) + i·ceil(b)`.",
+        "Non-finite values (`NaN`, `Inf`, `-Inf`) propagate unchanged.",
+        "Empty arrays return empty arrays of the appropriate shape.",
+        "Appending `'like', prototype` forces the result to match the residency of `prototype` (CPU or GPU). Prototypes must currently be numeric."
+    ],
+    "examples": [
+        {
+            "description": "Rounding values up to the next integer",
+            "input": "x = [-2.7, -0.3, 0, 0.8, 3.2];\ny = ceil(x)",
+            "output": "y = [-2, 0, 0, 1, 4]"
+        },
+        {
+            "description": "Rounding a matrix up element-wise",
+            "input": "A = [1.2 4.7; -3.4 5.0];\nB = ceil(A)",
+            "output": "B = [2 5; -3 5]"
+        },
+        {
+            "description": "Rounding fractions upward in a tensor",
+            "input": "t = reshape([-1.8, -0.2, 0.4, 1.1, 2.1, 3.6], [3, 2]);\nup = ceil(t)",
+            "output": "up =\n    [-1  2;\n      0  3;\n      1  4]"
+        },
+        {
+            "description": "Rounding up to two decimal places",
+            "input": "temps = [21.452 19.991 22.501];\nrounded = ceil(temps, 2)",
+            "output": "rounded = [21.46 20 22.51]"
+        },
+        {
+            "description": "Rounding to significant digits",
+            "input": "measurements = [0.001234 12.3456 98765];\nsig2 = ceil(measurements, 2, 'significant')",
+            "output": "sig2 = [0.0013 13.0 99000]"
+        },
+        {
+            "description": "Rounding complex numbers toward positive infinity",
+            "input": "z = [1.2 + 2.1i, -0.2 - 3.9i];\nresult = ceil(z)",
+            "output": "result = [2 + 3i, 0 - 3i]"
+        },
+        {
+            "description": "Keeping GPU results on-device with `unary_ceil`",
+            "input": "G = gpuArray([1.8 -0.2 0.0; -1.1 2.5 -3.4]);\nup = ceil(G);\ngather(up)",
+            "output": "ans =\n    [ 2  0  0;\n     -1  3 -3]"
+        },
+        {
+            "description": "Forcing GPU residency with a `'like'` prototype",
+            "input": "A = [1.8 -0.2; 2.7 3.4];\nproto = gpuArray(0);\nG = ceil(A, 'like', proto);   % Result remains on the GPU\nresult = gather(G)",
+            "output": "result =\n    [ 2  0;\n      3  4]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `ceil` always round toward positive infinity?",
+            "answer": "Yes—positive values round up away from zero, while negative values round toward zero (e.g., `ceil(-0.1) = 0`)."
+        },
+        {
+            "question": "How are complex numbers handled?",
+            "answer": "The real and imaginary parts are ceiled independently, matching MATLAB's component-wise definition."
+        },
+        {
+            "question": "Can I round to decimal digits or significant digits?",
+            "answer": "Yes. Use `ceil(X, N)` for decimal digits or `ceil(X, N, 'significant')` for significant digits. Negative `N` values round to powers of ten."
+        },
+        {
+            "question": "What happens with logical arrays?",
+            "answer": "Logical values promote to doubles (`0` or `1`) before rounding, so the outputs remain 0 or 1."
+        },
+        {
+            "question": "Can I pass character arrays to `ceil`?",
+            "answer": "Yes. Character data is treated as its numeric code points, producing a double tensor of the same size."
+        },
+        {
+            "question": "Do `NaN` and `Inf` values change?",
+            "answer": "No. Non-finite inputs propagate unchanged."
+        },
+        {
+            "question": "Will GPU execution change floating-point results?",
+            "answer": "No. Providers implement IEEE-compliant ceiling; when a provider lacks `unary_ceil`, RunMat falls back to the CPU to preserve MATLAB-compatible behaviour."
+        },
+        {
+            "question": "Does `'like'` work with `ceil`?",
+            "answer": "Yes. Append `'like', prototype` to request output that matches the prototype's residency. Currently prototypes must be numeric (scalars or dense tensors, host or GPU)."
+        },
+        {
+            "question": "Can fusion keep `ceil` on the GPU?",
+            "answer": "Yes. `ceil` participates in elementwise fusion, so fused graphs can stay resident on the device when supported."
+        }
+    ],
+    "links": [
+        {
+            "label": "floor",
+            "url": "./floor"
+        },
+        {
+            "label": "round",
+            "url": "./round"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "fix",
+            "url": "./fix"
+        },
+        {
+            "label": "mod",
+            "url": "./mod"
+        },
+        {
+            "label": "rem",
+            "url": "./rem"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/rounding/ceil.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/rounding/ceil.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nA = [1.8 -0.2; 2.7 3.4];\nproto = gpuArray(0);\nG = ceil(A, 'like', proto);   % Result remains on the GPU\nresult = gather(G);\n```\n\nExpected output:\n\n```matlab\nresult =\n    [ 2  0;\n      3  4]\n```",
+    "gpu_behavior": [
+        "When tensors already reside on the GPU, RunMat consults the active acceleration provider. If the provider implements the `unary_ceil` hook, `ceil(X)` executes entirely on the device and keeps tensors resident. When decimal or significant-digit rounding is requested—or when the provider lacks `unary_ceil`—RunMat gathers the tensor to host memory, applies the CPU implementation, and honours any `'like'` GPU prototype by uploading the result back to the device. This maintains MATLAB-compatible behaviour while exposing GPU acceleration whenever it is available."
+    ],
+    "key": "ceil",
+    "slug": "ceil",
+    "categoryPath": [
+        "math",
+        "rounding"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ceil.js.map

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

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

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

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

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

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

package/dist/generated/builtins/cell.js

@@ -0,0 +1,152 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cell",
+    "category": "cells/core",
+    "keywords": [
+        "cell",
+        "cell array",
+        "containers",
+        "empty",
+        "like",
+        "gpu fallback"
+    ],
+    "summary": "Create MATLAB cell arrays, including `'like'` prototypes, with RunMat's modern builtin pipeline.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Cell arrays are allocated on the host. Size inputs that reside on the GPU are gathered, and `'like'` prototypes backed by gpuArray currently fall back to host storage until device-side cells are implemented."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::cells::core::cell::tests",
+        "integration": "builtins::cells::core::cell::tests::cell_like_gpu_prototype_falls_back_to_host"
+    },
+    "description": "`cell` constructs cell arrays—containers that can hold heterogeneous values in each element. Every cell starts out containing an empty value: by default the empty double array `[]`, or an empty value that matches a `'like'` prototype when the prototype lives on the host. GPU-backed prototypes currently fall back to empty double arrays on the host. RunMat mirrors MATLAB's behaviour for scalar and arbitrary size forms (`cell`, `cell(n)`, `cell(m, n, p, ...)`, `cell([m n p ...])`, `cell(size(A))`, and `cell(___, 'like', prototype)`).",
+    "behaviors": [
+        "`cell` (with no arguments) returns a `0×0` empty cell array.",
+        "`cell(n)` returns an `n×n` cell array whose elements default to the empty value.",
+        "`cell(m, n, p, ...)` accepts any number of size scalars and returns an N-D cell array whose dimensions match the arguments.",
+        "`cell(sz)` or `cell(size(A))` accepts a numeric size vector of any length. A single-element vector produces an `m×1` cell array; longer vectors create higher-dimensional cell arrays matching the provided extents.",
+        "`cell(___, 'like', prototype)` copies the prototype's size when no explicit dimensions are supplied and fills each element with the empty value that matches the prototype's class (for example logical empty arrays, complex empties, or empty strings). When the prototype is a `gpuArray`, RunMat keeps the host-empty double fallback until GPU-resident cell storage ships.",
+        "Size arguments must be finite, non-negative integers that are representable in double precision."
+    ],
+    "examples": [
+        {
+            "description": "Creating a square cell array of empty placeholders",
+            "input": "C = cell(3);\nsize(C)",
+            "output": "ans =\n     3     3"
+        },
+        {
+            "description": "Creating a rectangular 2-by-4 cell array",
+            "input": "C = cell(2, 4);\nclass(C)",
+            "output": "ans =\n    'cell'"
+        },
+        {
+            "description": "Creating a 3-D cell array",
+            "input": "C = cell(2, 3, 4);\nsize(C)",
+            "output": "ans =\n     2     3     4"
+        },
+        {
+            "description": "Matching the size of an existing matrix",
+            "input": "A = ones(5, 2);\nC = cell(size(A));\nsize(C)",
+            "output": "ans =\n     5     2"
+        },
+        {
+            "description": "Creating a cell array using a `'like'` prototype",
+            "input": "proto = logical.empty(0, 0);\nC = cell(2, 3, 'like', proto);\ncellfun(@isempty, C)",
+            "output": "ans =\n     1     1     1\n     1     1     1"
+        },
+        {
+            "description": "Using a column size vector",
+            "input": "sz = [4; 1];\nC = cell(sz);\nsize(C)",
+            "output": "ans =\n     4     1"
+        },
+        {
+            "description": "Verifying that every cell starts with `[]`",
+            "input": "C = cell(2, 2);\nisequal(C{1,1}, [], C{2,2}, [])",
+            "output": "ans = logical\n     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What values do new cells contain?",
+            "answer": "Each cell starts with an empty value. By default that is the empty double array `[]`. When you supply a `'like'` prototype, RunMat chooses the matching empty logical, complex, string, character, or cell value instead. GPU-backed prototypes currently fall back to empty double arrays on the host until device-resident cell elements are supported."
+        },
+        {
+            "question": "Are negative or fractional sizes allowed?",
+            "answer": "No. Every size argument must be a finite, non-negative integer that can be represented exactly in double precision."
+        },
+        {
+            "question": "Can I create zero-sized cell arrays?",
+            "answer": "Yes. You can use `cell(0)`, `cell(0, n)`, or supply a size vector containing zeros. RunMat returns an empty cell array with the requested shape."
+        },
+        {
+            "question": "Do GPU prototypes change how `cell` behaves?",
+            "answer": "A `'like'` prototype that resides on the GPU is gathered automatically. Shape inference follows the prototype, and each cell receives an empty double array on the host while GPU cell storage is still under development."
+        },
+        {
+            "question": "What about N-dimensional cell arrays?",
+            "answer": "RunMat supports N-dimensional cell arrays. Supply as many scalar dimensions or size-vector entries as you need and the builtin constructs a cell array with that exact shape. Trailing singleton dimensions are preserved so downstream code can introspect the full size vector."
+        },
+        {
+            "question": "Does `cell` copy data from existing containers?",
+            "answer": "No. The builtin only allocates empty cells. Populate the elements afterwards with assignments such as `C{1,2} = magic(3);`."
+        }
+    ],
+    "links": [
+        {
+            "label": "cellfun",
+            "url": "./cellfun"
+        },
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cell2mat",
+            "url": "./cell2mat"
+        },
+        {
+            "label": "cellstr",
+            "url": "./cellstr"
+        },
+        {
+            "label": "mat2cell",
+            "url": "./mat2cell"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/cells/core/cell.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/cells/core/cell.rs"
+    },
+    "gpu_residency": "No. Cell arrays are created on the host regardless of the residency of the size arguments. If the inputs happen to live on the GPU (for example, a `gpuArray` size vector), RunMat gathers those values before allocating the cell array. The result is always a host cell array; downstream code can still place tensors or gpuArrays inside individual cells as needed.",
+    "gpu_behavior": [
+        "Cell arrays live on the CPU heap because each element can contain arbitrarily typed values that may require garbage-collected storage. When `cell` is invoked inside a fused GPU expression RunMat terminates the fusion group, gathers any GPU-resident size inputs, and creates the cell array on the host. `'Like'` prototypes that refer to gpuArray inputs are honoured for shape inference. Each cell currently receives an empty double array even if the prototype itself is a `gpuArray`; this fallback will disappear once device-side cell residency lands. Once the acceleration layer adds true GPU cells, providers can register hooks without changing user code."
+    ],
+    "key": "cell",
+    "slug": "cell",
+    "categoryPath": [
+        "cells",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cell.js.map

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

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

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

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

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

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