runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/rmfield.js

@@ -0,0 +1,136 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rmfield",
+    "category": "structs/core",
+    "keywords": [
+        "rmfield",
+        "remove field",
+        "struct",
+        "struct array",
+        "metadata"
+    ],
+    "summary": "Remove one or more fields from scalar structs or struct arrays.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host; values that already live on the GPU remain device-resident."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::structs::core::rmfield::tests",
+        "integration": "builtins::structs::core::rmfield::tests::rmfield_struct_array_roundtrip"
+    },
+    "description": "`S2 = rmfield(S, name)` returns a copy of `S` with the field `name` removed. The builtin accepts additional field names, string arrays, or cell arrays of names to delete several fields in one call.",
+    "behaviors": [
+        "Works with scalar structs and struct arrays created by `struct`, `load`, or other builtins.",
+        "Accepts character vectors, string scalars, string arrays, and cell arrays containing those types to identify the fields that should be removed.",
+        "Every listed field must already exist. Attempting to remove a missing field raises the standard MATLAB-style error `Reference to non-existent field '<name>'`.",
+        "Removing multiple fields applies to every element in a struct array; the operation fails if any element is missing one of the requested fields.",
+        "The input `S` is not mutated in place. `rmfield` returns a new struct (or struct array) while the original remains unchanged."
+    ],
+    "examples": [
+        {
+            "description": "Removing a single field from a scalar struct",
+            "input": "s = struct(\"name\", \"Ada\", \"score\", 42);\nt = rmfield(s, \"score\");\nisfield(t, \"score\")",
+            "output": "ans =\n  logical\n   0"
+        },
+        {
+            "description": "Removing several fields with a cell array of names",
+            "input": "cfg = struct(\"mode\", \"fast\", \"rate\", 60, \"debug\", true);\ncfg = rmfield(cfg, {\"rate\", \"debug\"});\nfieldnames(cfg)",
+            "output": "ans =\n  1×1 cell array\n    {'mode'}"
+        },
+        {
+            "description": "Removing a field from every element of a struct array",
+            "input": "people = struct(\"name\", {\"Ada\", \"Grace\"}, \"id\", {101, 102}, \"email\", {\"ada@example.com\", \"grace@example.com\"});\ntrimmed = rmfield(people, \"email\");\nfieldnames(trimmed)",
+            "output": "ans =\n  2×1 cell array\n    {'id'}\n    {'name'}"
+        },
+        {
+            "description": "Supplying a string array of field names to delete",
+            "input": "stats = struct(\"mean\", 10, \"median\", 9, \"stdev\", 2);\nnames = [\"mean\", \"median\"];\nreduced = rmfield(stats, names);\nfieldnames(reduced)",
+            "output": "ans =\n  1×1 cell array\n    {'stdev'}"
+        },
+        {
+            "description": "Conditionally removing optional fields",
+            "input": "record = struct(\"id\", 7, \"notes\", \"draft\");\nif isfield(record, \"notes\")\n    record = rmfield(record, \"notes\");\nend\nfieldnames(record)",
+            "output": "ans =\n  1×1 cell array\n    {'id'}"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `rmfield` modify the input in place?",
+            "answer": "No. The function returns a new struct (or struct array) with the specified fields removed. The input value remains unchanged, mirroring MATLAB's copy-on-write semantics."
+        },
+        {
+            "question": "What argument types can I use for the field names?",
+            "answer": "You can pass character vectors, string scalars, string arrays, or cell arrays whose elements are strings or character vectors. Mixing these forms in a single call is supported—`rmfield` concatenates all supplied names into one list."
+        },
+        {
+            "question": "What happens if a field is missing?",
+            "answer": "RunMat raises the MATLAB-compatible error `Reference to non-existent field '<name>'.` and leaves the struct unchanged."
+        },
+        {
+            "question": "Can I remove nested fields with `rmfield`?",
+            "answer": "No. `rmfield` only removes top-level fields. Use `setfield` with nested assignments or restructure your data if you need to manipulate nested content."
+        },
+        {
+            "question": "Does `rmfield` work with MATLAB-style objects or handle classes?",
+            "answer": "No. The builtin is restricted to structs and struct arrays. Use class-specific helpers (such as `rmprop`) for objects."
+        },
+        {
+            "question": "Does removing a field move GPU tensors back to the CPU?",
+            "answer": "No. The builtin merely rewrites metadata. Any GPU-resident values stored in remaining fields stay on the device until another operation decides otherwise."
+        }
+    ],
+    "links": [
+        {
+            "label": "fieldnames",
+            "url": "./fieldnames"
+        },
+        {
+            "label": "isfield",
+            "url": "./isfield"
+        },
+        {
+            "label": "setfield",
+            "url": "./setfield"
+        },
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "orderfields",
+            "url": "./orderfields"
+        },
+        {
+            "label": "getfield",
+            "url": "./getfield"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/structs/core/rmfield.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/structs/core/rmfield.rs"
+    },
+    "gpu_residency": "No additional residency management is required. `rmfield` leaves existing GPU tensors untouched and never gathers or uploads buffers. Subsequent GPU-aware builtins decide whether to keep values on the device.",
+    "gpu_behavior": [
+        "`rmfield` performs metadata updates on the host. Values that already reside on the GPU—such as `gpuArray` tensors stored in other fields—stay on the device. Because this builtin only rewrites struct metadata it does not require or invoke acceleration provider hooks."
+    ],
+    "key": "rmfield",
+    "slug": "rmfield",
+    "categoryPath": [
+        "structs",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rmfield.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rmfield.js","sourceRoot":"","sources":["../../../src/generated/builtins/rmfield.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,cAAc;IAC1B,UAAU,EAAE;QACV,SAAS;QACT,cAAc;QACd,QAAQ;QACR,cAAc;QACd,UAAU;KACX;IACD,SAAS,EAAE,iEAAiE;IAC5E,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,wFAAwF;KAClG;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,yCAAyC;QACjD,aAAa,EAAE,yEAAyE;KACzF;IACD,aAAa,EAAE,uMAAuM;IACtN,WAAW,EAAE;QACX,6FAA6F;QAC7F,iJAAiJ;QACjJ,gKAAgK;QAChK,iJAAiJ;QACjJ,+HAA+H;KAChI;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,kGAAkG;YAC3G,QAAQ,EAAE,wBAAwB;SACnC;QACD;YACE,aAAa,EAAE,oDAAoD;YACnE,OAAO,EAAE,+HAA+H;YACxI,QAAQ,EAAE,uCAAuC;SAClD;QACD;YACE,aAAa,EAAE,uDAAuD;YACtE,OAAO,EAAE,2LAA2L;YACpM,QAAQ,EAAE,mDAAmD;SAC9D;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,oJAAoJ;YAC7J,QAAQ,EAAE,wCAAwC;SACnD;QACD;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,qJAAqJ;YAC9J,QAAQ,EAAE,qCAAqC;SAChD;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,2CAA2C;YACvD,QAAQ,EAAE,2KAA2K;SACtL;QACD;YACE,UAAU,EAAE,oDAAoD;YAChE,QAAQ,EAAE,0OAA0O;SACrP;QACD;YACE,UAAU,EAAE,qCAAqC;YACjD,QAAQ,EAAE,wHAAwH;SACnI;QACD;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,wJAAwJ;SACnK;QACD;YACE,UAAU,EAAE,kEAAkE;YAC9E,QAAQ,EAAE,wHAAwH;SACnI;QACD;YACE,UAAU,EAAE,yDAAyD;YACrE,QAAQ,EAAE,4JAA4J;SACvK;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,cAAc;SACtB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,aAAa;YACtB,KAAK,EAAE,eAAe;SACvB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,8DAA8D;QACvE,KAAK,EAAE,2GAA2G;KACnH;IACD,eAAe,EAAE,kNAAkN;IACnO,cAAc,EAAE;QACd,4QAA4Q;KAC7Q;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,SAAS;QACT,MAAM;KACP;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/rmpath.js

@@ -0,0 +1,215 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rmpath",
+    "category": "io/repl_fs",
+    "keywords": [
+        "rmpath",
+        "search path",
+        "matlab path",
+        "remove folder",
+        "toolbox cleanup"
+    ],
+    "summary": "Remove folders from the MATLAB search path used by RunMat.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/rmpath.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. gpuArray text inputs are gathered automatically before processing."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 8,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::rmpath::tests",
+        "integration": "builtins::io::repl_fs::rmpath::tests::rmpath_accepts_string_containers"
+    },
+    "description": "`rmpath` removes folders from the MATLAB search path that RunMat consults when resolving functions, scripts, classes, and data files. The change is applied immediately and mirrors MATLAB semantics, including error reporting when a folder is missing or not currently on the path.",
+    "behaviors": [
+        "Folder arguments may be character vectors, string scalars, string arrays, or cell arrays of character vectors or strings. Multi-row char arrays contribute one folder per row (trailing padding is stripped).",
+        "Multiple folders can be passed inside a single argument using the platform path separator (`:` on Linux/macOS, `;` on Windows); this is compatible with `genpath` output.",
+        "RunMat accepts any ordering of arguments. Each requested folder is removed at most once even if it appears repeatedly.",
+        "Inputs are resolved to absolute, normalised paths. Relative inputs are interpreted relative to the current working directory, and `~` expands to the user’s home directory.",
+        "Folders must exist and must currently be present on the MATLAB path. RunMat raises `rmpath: folder '<name>' not found` when a directory cannot be located, or `rmpath: folder '<name>' not on search path` when the directory exists locally but is absent from the current search path.",
+        "`rmpath` returns the previous path so callers can restore it later via `path(old)`, matching RunMat’s `addpath` and `path` builtins."
+    ],
+    "examples": [
+        {
+            "description": "Removing a single folder from the MATLAB search path",
+            "input": "old = rmpath(\"util/toolbox\");\ndisp(old);\npath()",
+            "output": "old =\n    '/Users/you/runmat/toolbox:util/toolbox'\n% The folder util/toolbox no longer appears in the active search path."
+        },
+        {
+            "description": "Removing multiple folders at once",
+            "input": "rmpath(\"shared/filters\", \"shared/signal\");\npath()",
+            "output": "% shared/filters and shared/signal are both removed from the MATLAB path."
+        },
+        {
+            "description": "Removing folders produced by `genpath`",
+            "input": "tree = genpath(\"third_party/toolchain\");\nrmpath(tree)",
+            "output": "% Every directory returned by genpath is pruned from the search path."
+        },
+        {
+            "description": "Removing folders specified in a cell array",
+            "input": "folders = {'src/algorithms', 'src/visualization'};\nrmpath(folders{:});\npath()",
+            "output": "% Both folders are removed from the MATLAB search path."
+        },
+        {
+            "description": "Capturing and restoring the previous path after removal",
+            "input": "old = rmpath(\"analysis/utilities\");\n% ... run experiments ...\npath(old);   % Restore the previous path\npath()",
+            "output": "% The original search path is restored when you call path(old)."
+        },
+        {
+            "description": "Handling attempts to remove folders that are not on the path",
+            "input": "rmpath(\"nonexistent/toolbox\")"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `rmpath` insist on absolute paths?",
+            "answer": "No. Relative inputs are resolved against the current working directory and stored as absolute paths before matching against the path."
+        },
+        {
+            "question": "What happens with duplicate folders in the argument list?",
+            "answer": "Each folder is processed once per call. Duplicate input values are ignored after the first removal."
+        },
+        {
+            "question": "How do I confirm removal succeeded?",
+            "answer": "Call `path()` or `which` to confirm that the folder (or files within it) no longer appear on the MATLAB search path."
+        },
+        {
+            "question": "Does `rmpath` update the `RUNMAT_PATH` environment variable?",
+            "answer": "Yes. Changes are reflected immediately so other RunMat tooling observes the new path."
+        },
+        {
+            "question": "Can I remove folders that were added via `path(newPath)`?",
+            "answer": "Yes. `rmpath` matches entries exactly as they appear in the stored search path string, regardless of how they were inserted."
+        },
+        {
+            "question": "Will `rmpath` accept GPU strings?",
+            "answer": "Yes. Inputs are gathered automatically, then processed on the CPU."
+        },
+        {
+            "question": "What happens if the folder exists locally but is not on the search path?",
+            "answer": "RunMat raises `rmpath: folder '<name>' not on search path`, matching MATLAB’s expectation that only active path entries are removed."
+        },
+        {
+            "question": "Does `rmpath` return the new or previous path?",
+            "answer": "It returns the previous path so you can restore it later with `path(old)`."
+        },
+        {
+            "question": "Is there a bulk reset option?",
+            "answer": "To clear the path entirely call `path(\"\")`. `rmpath` intentionally targets specific folders."
+        }
+    ],
+    "links": [
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "which",
+            "url": "./which"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "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/rmpath.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/rmpath.rs"
+    },
+    "gpu_residency": "No. `rmpath` operates entirely on CPU-side strings. Supplying `gpuArray` text inputs offers no benefit—RunMat gathers them automatically before processing.",
+    "gpu_behavior": [
+        "`rmpath` manipulates host-side configuration. If any input value resides on the GPU, RunMat gathers it back to the host before parsing. No acceleration provider hooks or kernels are involved."
+    ],
+    "key": "rmpath",
+    "slug": "rmpath",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rmpath.js.map

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

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

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

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

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

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

package/dist/generated/builtins/rng.js

@@ -0,0 +1,138 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rng",
+    "category": "stats/random",
+    "keywords": [
+        "rng",
+        "seed",
+        "twister",
+        "shuffle",
+        "random state"
+    ],
+    "summary": "Seed, shuffle, and query the global random number generator.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Synchronizes the active acceleration provider's RNG state when supported."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "none"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::stats::random::rng::tests",
+        "integration": null
+    },
+    "description": "`rng` queries or reconfigures the global pseudorandom number generator that powers `rand`, `randn`, `randi`, and `randperm`. RunMat mirrors MATLAB's semantics: you can reset to the default generator, seed with a specific integer, shuffle based on the system clock, or save/restore the full generator state.",
+    "behaviors": [
+        "`rng()` returns a structure describing the current generator (fields `Type`, `Seed`, and `State`).",
+        "`rng(seed)` switches to the default generator with the supplied non-negative integer seed. Passing `0` reproduces MATLAB's `rng('default')`.",
+        "`rng('default')` restores the default generator and seed (`twister`, seed `0`).",
+        "`rng('shuffle')` seeds the generator with entropy derived from the current time.",
+        "`rng(seed, 'twister')` explicitly names the generator. RunMat currently supports `twister`, matching MATLAB's default stream.",
+        "`rng(S)` restores a state structure previously returned by `rng`.\n\nWhenever an acceleration provider is active, RunMat also pushes the new seed to the provider so GPU-resident random calls remain in sync with CPU sampling. Providers that lack `set_rng_state` simply fall back to their existing behaviour, which is documented below."
+    ],
+    "examples": [
+        {
+            "description": "Resetting the generator for reproducible simulation runs",
+            "input": "rng(0);\nrand(1, 4)",
+            "output": "    0.3969    0.8408    0.4221    0.6260"
+        },
+        {
+            "description": "Saving and restoring RNG state around a computation",
+            "input": "s = rng;\nrng(1337);\nA = randn(2, 2);\nrng(s);            % restore original stream\nB = randn(2, 2);   % continues from the saved state",
+            "output": "A =\n    0.6406   -0.8022\n    0.2222   -0.7161\n\nB =\n    0.3969    0.8408\n    0.4221    0.6260"
+        },
+        {
+            "description": "Scrambling the generator with the system clock",
+            "input": "rng('shuffle');\nu = rand(1, 3)",
+            "output": "u =\n    0.1378    0.7086    0.8463"
+        },
+        {
+            "description": "Keeping CPU and GPU random draws in sync",
+            "input": "rng(2024);\nG = gpuArray(rand(1, 3));\nC = gather(G);\nH = rand(1, 3);         % same values as C",
+            "output": "C =\n    0.6554    0.7501    0.6046\n\nH =\n    0.6554    0.7501    0.6046"
+        },
+        {
+            "description": "Creating deterministic permutations with `rng` and `randperm`",
+            "input": "rng(42);\np = randperm(6);\nrng(42);\nq = randperm(6)",
+            "output": "p =\n     6     2     1     4     3     5\n\nq =\n     6     2     1     4     3     5"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What generators does RunMat support?",
+            "answer": "RunMat currently exposes MATLAB's default `'twister'` stream. Additional generators (`'philox'`, `'combRecursive'`, etc.) will surface as the underlying engines land."
+        },
+        {
+            "question": "What numeric range is valid for seeds?",
+            "answer": "Any finite, non-negative integer representable exactly in double precision (`0 <= seed <= 2^53`) is accepted. Values outside this range produce an error."
+        },
+        {
+            "question": "How can I force a specific seed for `rng('shuffle')` in tests?",
+            "answer": "Set the environment variable `RUNMAT_RNG_SHUFFLE_SEED` to an unsigned integer before calling `rng('shuffle')`. RunMat uses that value instead of system time."
+        },
+        {
+            "question": "Does `rng` affect GPU random numbers?",
+            "answer": "Yes—if the active acceleration provider implements `set_rng_state`. The bundled in-process reference provider and the WGPU backend both honour this hook."
+        },
+        {
+            "question": "How do I restore a saved state structure?",
+            "answer": "Pass the structure back to `rng`: `s = rng; ...; rng(s);` resumes where the original state left off, matching MATLAB behaviour."
+        },
+        {
+            "question": "What is stored in the `State` field?",
+            "answer": "RunMat serialises the 64-bit internal state into a 1×2 double tensor containing the low and high 32-bit words. Feeding that tensor back to `rng` recreates the exact state."
+        },
+        {
+            "question": "Can I create independent streams?",
+            "answer": "Not yet. RunMat exposes MATLAB-compatible `RandStream` APIs in a separate roadmap item; for now `rng` operates on the single global stream."
+        },
+        {
+            "question": "Does `rng` change automatically when I call other random functions?",
+            "answer": "No. Only explicit calls to `rng`, `RandStream`, or provider-specific utilities reconfigure the seed. Sampling routines (`rand`, `randn`, `randperm`, etc.) consume the current stream but do not reseed it."
+        }
+    ],
+    "links": [
+        {
+            "label": "rand",
+            "url": "./rand"
+        },
+        {
+            "label": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "randi",
+            "url": "./randi"
+        },
+        {
+            "label": "randperm",
+            "url": "./randperm"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/stats/random/rng.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/stats/random/rng.rs"
+    },
+    "gpu_residency": "RunMat pushes the configured seed to the active acceleration provider whenever `rng` changes the host generator. Providers that expose `set_rng_state` (`runmat-accelerate`'s in-process and WGPU backends) therefore produce the same sequences as CPU `rand`/`randn` when seeded via `rng`. If a provider omits this hook, RunMat logs a debug message and continues with the provider's internal seed stream; in that case GPU draws may differ from CPU draws even after calling `rng`. You do not need to call `gpuArray` explicitly for residency purposes—RunMat keeps GPU streams in sync automatically whenever the provider supports RNG state injection.",
+    "key": "rng",
+    "slug": "rng",
+    "categoryPath": [
+        "stats",
+        "random"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rng.js.map

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

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

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

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

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

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