runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/quiver.js

@@ -0,0 +1,102 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "quiver",
+    "category": "plotting",
+    "keywords": [
+        "quiver",
+        "vector field",
+        "arrow plot",
+        "flow field",
+        "matlab quiver",
+        "direction field"
+    ],
+    "summary": "Visualize 2-D vector fields with scalable arrows, GPU-aware execution, and MATLAB `quiver` call forms.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`quiver` uses a GPU-backed geometry path and can keep vector-field inputs resident on device when the shared plotting device is available."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 4,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::quiver::tests",
+        "integration": "runmat-plot/src/gpu/quiver.rs::tests"
+    },
+    "description": "`quiver` visualizes 2-D vector fields as arrows anchored at data points. In RunMat it returns a quiver handle, supports MATLAB-style `quiver(U, V)` and `quiver(X, Y, U, V)` call forms, and uses GPU-backed geometry generation together with the plotting object, replay, and export systems.",
+    "behaviors": [
+        "`quiver(U, V)` builds the default coordinate grid from the shape of `U` and `V`.",
+        "`quiver(X, Y, U, V)` accepts explicit coordinate vectors or meshgrid-style axes, depending on the input layout.",
+        "The returned value is a quiver-handle object that can be queried and updated through `get` and `set`.",
+        "Auto-scale factor, head size, line width, color, and display-name workflows are all part of the plotting property path.",
+        "Dedicated GPU geometry generation keeps vector-field rendering on device when plotting-compatible buffers are available."
+    ],
+    "options": [
+        "`'AutoScaleFactor'` / `'Scale'` controls arrow scaling.",
+        "`'MaxHeadSize'` / `'HeadSize'` controls the size of arrowheads.",
+        "Line-style color and width workflows are supported through the same style parsing and handle/property path used by other line-like plots."
+    ],
+    "examples": [
+        {
+            "description": "Create a vector field from `U` and `V` only",
+            "input": "[X, Y] = meshgrid(-2:0.5:2, -2:0.5:2);\nU = -Y;\nV = X;\nquiver(U, V);",
+            "output": "% RunMat infers the coordinate grid from the vector-field shape"
+        },
+        {
+            "description": "Provide explicit coordinates for a flow field",
+            "input": "[X, Y] = meshgrid(-2:0.5:2, -2:0.5:2);\nU = -Y;\nV = X;\nquiver(X, Y, U, V);"
+        },
+        {
+            "description": "Adjust arrow scaling and head size through the handle",
+            "input": "[X, Y] = meshgrid(-2:0.5:2, -2:0.5:2);\nU = -Y;\nV = X;\nh = quiver(X, Y, U, V);\nset(h, 'AutoScaleFactor', 1.5, 'MaxHeadSize', 0.2, 'DisplayName', 'rotation');\nlegend;"
+        }
+    ],
+    "links": [
+        {
+            "label": "area",
+            "url": "./area"
+        },
+        {
+            "label": "plot",
+            "url": "./plot"
+        },
+        {
+            "label": "legend",
+            "url": "./legend"
+        },
+        {
+            "label": "get",
+            "url": "./get"
+        },
+        {
+            "label": "set",
+            "url": "./set"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/quiver.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/quiver.rs"
+    },
+    "gpu_residency": "`quiver` preserves GPU residency on the direct path by building arrow geometry from exported GPU buffers. If the direct geometry path is unavailable for the active input combination, RunMat falls back while preserving the same quiver semantics and handle behavior.",
+    "gpu_behavior": [
+        "The direct quiver path emits renderer-ready arrow geometry from GPU buffers on the happy path.",
+        "Axes-local state, handle/property workflows, and replay/export behavior stay aligned across GPU and fallback rendering paths."
+    ],
+    "key": "quiver",
+    "slug": "quiver",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=quiver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quiver.js","sourceRoot":"","sources":["../../../src/generated/builtins/quiver.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,QAAQ;IACjB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,QAAQ;QACR,cAAc;QACd,YAAY;QACZ,YAAY;QACZ,eAAe;QACf,iBAAiB;KAClB;IACD,SAAS,EAAE,wGAAwG;IACnH,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,4IAA4I;KACtJ;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,mCAAmC;QAC3C,aAAa,EAAE,sCAAsC;KACtD;IACD,aAAa,EAAE,iSAAiS;IAChT,WAAW,EAAE;QACX,kFAAkF;QAClF,iHAAiH;QACjH,uGAAuG;QACvG,yHAAyH;QACzH,0HAA0H;KAC3H;IACD,SAAS,EAAE;QACT,yDAAyD;QACzD,iEAAiE;QACjE,2IAA2I;KAC5I;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,wEAAwE;YACjF,QAAQ,EAAE,iEAAiE;SAC5E;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,8EAA8E;SACxF;QACD;YACE,aAAa,EAAE,uDAAuD;YACtE,OAAO,EAAE,2KAA2K;SACrL;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,6DAA6D;QACtE,KAAK,EAAE,0GAA0G;KAClH;IACD,eAAe,EAAE,0QAA0Q;IAC3R,cAAc,EAAE;QACd,gGAAgG;QAChG,+HAA+H;KAChI;IACD,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/rand.js

@@ -0,0 +1,186 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rand",
+    "category": "array/creation",
+    "keywords": [
+        "rand",
+        "random",
+        "uniform",
+        "gpu",
+        "like"
+    ],
+    "summary": "Uniform random numbers on (0, 1) within the MATLAB language.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider random_uniform hooks when available; otherwise uploads host-generated samples to keep GPU residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "none"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::rand::tests",
+        "integration": "builtins::array::rand::tests::rand_gpu_like_uniform"
+    },
+    "description": "`rand` produces uniformly distributed pseudorandom numbers over the open interval (0, 1). RunMat mirrors MATLAB semantics across scalar, vector, matrix, and N-D invocations, including `'like'` prototypes that control data type and device residency.",
+    "behaviors": [
+        "`rand()` returns a scalar double drawn from `U(0, 1)`.",
+        "`rand(n)` returns an `n × n` double matrix.",
+        "`rand(m, n, ...)` returns a dense double array of the requested dimensions.",
+        "`rand(sz)` accepts a size vector (row or column) and returns a tensor whose shape is `sz`.",
+        "`rand(A)` or `rand(___, 'like', A)` matches the shape and residency of `A`, including GPU tensors when an acceleration provider is active.",
+        "`rand(___, 'double')` leaves the output as double precision (default). `'single'` returns single-precision results that mirror MATLAB's behaviour."
+    ],
+    "examples": [
+        {
+            "description": "Creating a 3x3 matrix of random numbers",
+            "input": "R = rand(3);         % 3x3 doubles in (0, 1)",
+            "output": "R = [0.8147 0.9134 0.1270; 0.9058 0.6324 0.0975; 0.1270 0.0975 0.2785]"
+        },
+        {
+            "description": "Creating a 2x4x3 matrix of random numbers",
+            "input": "sz = [2 4 3];\nT = rand(sz)",
+            "output": "T = [0.8147 0.9134 0.1270 0.9058 0.6324 0.0975 0.1270 0.0975 0.2785; 0.9134 0.6324 0.0975 0.2785 0.0975 0.1270 0.9058 0.6324 0.0975]"
+        },
+        {
+            "description": "Creating a 128x128 matrix of random numbers on a GPU",
+            "input": "G = rand(128, 128)",
+            "output": "H = [0.8147 0.9134 0.1270 0.9058 0.6324 0.0975 0.1270 0.0975 0.2785; 0.9134 0.6324 0.0975 0.2785 0.0975 0.1270 0.9058 0.6324 0.0975]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use the `rand` function?",
+            "answer": "Use `rand` whenever you need to create arrays filled with random numbers over the open interval (0, 1). This is useful for Monte Carlo simulations, generating noise for testing, or creating random initial conditions for optimization."
+        },
+        {
+            "question": "Does `rand` produce double arrays by default?",
+            "answer": "Yes, by default, `rand` creates dense double-precision arrays unless you explicitly specify a type such as `'single'` or use the `'like'` argument to match a prototype array."
+        },
+        {
+            "question": "What does `rand(n)` return?",
+            "answer": "`rand(n)` returns an `n × n` dense double-precision matrix filled with random numbers over the open interval (0, 1). For example, `rand(3)` yields a 3-by-3 matrix of random numbers."
+        },
+        {
+            "question": "How do I create a single precision array of random numbers?",
+            "answer": "Pass `'single'` as the last argument:\n```matlab:runnable\nS = rand(5, 5, 'single');\n```\nThis produces a 5x5 single precision matrix of random numbers."
+        },
+        {
+            "question": "How do I match the type and device residency of an existing array?",
+            "answer": "Use the `'like', prototype` syntax:\n```matlab:runnable\nA = gpuArray(rand(2,2));\nB = rand(2, 2, 'like', A);\n```\n`B` will be a GPU array with the same type and shape as `A`."
+        },
+        {
+            "question": "Can I create N-dimensional arrays with `rand`?",
+            "answer": "Yes! Pass more than two dimension arguments (or a size vector):\n```matlab:runnable\nT = rand(2, 3, 4);\n```\nThis creates a 2×3×4 tensor of random numbers."
+        },
+        {
+            "question": "How does `rand(A)` behave?",
+            "answer": "If you call `rand(A)`, where `A` is an array, the result is a new array of random numbers with the same shape as `A`."
+        },
+        {
+            "question": "Is the output always dense?",
+            "answer": "Yes. `rand` always produces a dense array. For sparse matrices of random numbers, use `sparse` with appropriate arguments."
+        },
+        {
+            "question": "What if I call `rand` with no arguments?",
+            "answer": "`rand()` returns a scalar double drawn from `U(0, 1)`."
+        }
+    ],
+    "links": [
+        {
+            "label": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "randi",
+            "url": "./randi"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "colon",
+            "url": "./colon"
+        },
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "false",
+            "url": "./false"
+        },
+        {
+            "label": "fill",
+            "url": "./fill"
+        },
+        {
+            "label": "linspace",
+            "url": "./linspace"
+        },
+        {
+            "label": "logspace",
+            "url": "./logspace"
+        },
+        {
+            "label": "magic",
+            "url": "./magic"
+        },
+        {
+            "label": "meshgrid",
+            "url": "./meshgrid"
+        },
+        {
+            "label": "ones",
+            "url": "./ones"
+        },
+        {
+            "label": "randperm",
+            "url": "./randperm"
+        },
+        {
+            "label": "range",
+            "url": "./range"
+        },
+        {
+            "label": "true",
+            "url": "./true"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/creation/rand.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/rand.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, in the above example, the result of the `rand` call will already be on the GPU when the fusion planner has detected a net benefit to operating the fused expression it is part of on the GPU.\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": [
+        "When the prototype lives on the GPU, RunMat first asks the active acceleration provider for a device-side random buffer via `random_uniform` / `random_uniform_like`. If the provider lacks those hooks, RunMat generates samples on the host and uploads them to maintain GPU residency. This guarantees MATLAB-compatible behaviour while documenting the extra transfer cost."
+    ],
+    "key": "rand",
+    "slug": "rand",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rand.js.map

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

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

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

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

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

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

package/dist/generated/builtins/randi.js

@@ -0,0 +1,199 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "randi",
+    "category": "array/creation",
+    "keywords": [
+        "randi",
+        "random",
+        "integer",
+        "gpu",
+        "like"
+    ],
+    "summary": "Uniform random integers with inclusive bounds.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider integer RNG hooks when available; otherwise generates samples on the host and uploads them to preserve GPU residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "none"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::creation::randi::tests",
+        "integration": "builtins::array::creation::randi::tests::randi_gpu_like_roundtrip"
+    },
+    "description": "`randi` draws uniformly distributed random integers from an inclusive range. RunMat mirrors MATLAB calling forms, supporting scalar upper bounds, two-element range vectors, explicit dimension lists, size vectors, and `'like'` prototypes that keep type and residency consistent with an existing array.",
+    "behaviors": [
+        "`randi(imax)` returns a scalar double selected uniformly from `1:imax`.",
+        "`randi(imax, m, n, ...)` creates dense arrays whose entries are in `1:imax`.",
+        "`randi([imin imax], sz)` accepts a two-element range vector plus either a size vector or explicit dimensions.",
+        "`randi(___, 'like', A)` matches both the shape and device residency of `A`, including GPU tensors when acceleration is enabled.",
+        "Negative lower bounds are supported so long as `imin <= imax`.",
+        "`randi(___, 'double')` is accepted for MATLAB compatibility and keeps the default double output.",
+        "`randi(___, 'logical')` emits a logical array when the inclusive range stays within `[0, 1]`.",
+        "RunMat diagnoses unsupported class specifiers (e.g., `'single'`, `'uint8'`) with descriptive errors until native representations land."
+    ],
+    "examples": [
+        {
+            "description": "Drawing a single die roll",
+            "input": "rng(0);\nroll = randi(6)",
+            "output": "roll = 1"
+        },
+        {
+            "description": "Creating a matrix of random indices",
+            "input": "rng(0);\nidx = randi(10, 2, 3)",
+            "output": "idx =\n     1     9     7\n    10     2     1"
+        },
+        {
+            "description": "Generating bounded integers with a size vector",
+            "input": "rng(0);\nshape = [3 4 2];\ntiles = randi([5 20], shape)",
+            "output": "tiles(:, :, 1) =\n     6     7     5    15\n    19    14     9    16\n    18     5    10    13\n\ntiles(:, :, 2) =\n    20     5    17     8\n    20    14     5     9\n    10     9    18     5"
+        },
+        {
+            "description": "Matching an existing `gpuArray`",
+            "input": "rng(0);\nG = gpuArray.zeros(4, 4);\nlabels = randi([0 3], 'like', G);\npeek = gather(labels)",
+            "output": "peek =\n     0     2     1     3\n     3     0     2     3\n     3     0     2     1\n     0     1     2     0\n\nisa(labels, 'gpuArray')\nans =\n     logical\n     1"
+        },
+        {
+            "description": "Building a random logical mask",
+            "input": "rng(0);\nmask = randi([0 1], 4, 4, 'logical')",
+            "output": "mask =\n     0     1     0     1\n     1     0     1     1\n     1     0     1     0\n     0     0     1     0"
+        },
+        {
+            "description": "Reproducible integer tensors inside tests",
+            "input": "rng(0);\np = randi([1 4], 1, 5)",
+            "output": "p = [1 4 4 1 3]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What range does `randi(imax)` use?",
+            "answer": "The call `randi(imax)` produces integers in the inclusive range `1:imax`. Use the two-element form `randi([imin imax], ...)` when you need a custom minimum."
+        },
+        {
+            "question": "Can the lower bound be negative?",
+            "answer": "Yes. `randi([imin imax], ...)` accepts negative bounds as long as `imin <= imax` and both bounds are integers."
+        },
+        {
+            "question": "Does `randi` return doubles or integer arrays?",
+            "answer": "RunMat matches MATLAB by storing results in double-precision tensors whose values are integers. Future releases will add direct integer array classes."
+        },
+        {
+            "question": "Can I request a logical result directly?",
+            "answer": "Yes. Pass `'logical'` as the final argument, and ensure the inclusive range stays within `[0, 1]`. Any other range produces an error because logical arrays can only store 0/1 values."
+        },
+        {
+            "question": "How do I control the array shape?",
+            "answer": "Pass either explicit dimensions (`randi(9, 4, 2)`) or a size vector (`randi(9, [4 2])`). Providing a `'like'` prototype also copies the prototype's shape automatically."
+        },
+        {
+            "question": "How does `randi` interact with `rng`?",
+            "answer": "`randi` consumes RunMat's global RNG stream. Use the MATLAB-compatible `rng` builtin to seed or restore the generator for reproducible simulations."
+        },
+        {
+            "question": "What happens if the provider lacks integer RNG hooks?",
+            "answer": "RunMat falls back to host generation followed by a single upload. The resulting array still lives on the GPU; only the initial samples are produced on the CPU."
+        },
+        {
+            "question": "Does `randi` support `'single'` or integer output classes?",
+            "answer": "Not yet. The `randi` builtin currently supports doubles only. Supplying `'single'` or integer class names raises a descriptive error."
+        }
+    ],
+    "links": [
+        {
+            "label": "rand",
+            "url": "./rand"
+        },
+        {
+            "label": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "colon",
+            "url": "./colon"
+        },
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "false",
+            "url": "./false"
+        },
+        {
+            "label": "fill",
+            "url": "./fill"
+        },
+        {
+            "label": "linspace",
+            "url": "./linspace"
+        },
+        {
+            "label": "logspace",
+            "url": "./logspace"
+        },
+        {
+            "label": "magic",
+            "url": "./magic"
+        },
+        {
+            "label": "meshgrid",
+            "url": "./meshgrid"
+        },
+        {
+            "label": "ones",
+            "url": "./ones"
+        },
+        {
+            "label": "randperm",
+            "url": "./randperm"
+        },
+        {
+            "label": "range",
+            "url": "./range"
+        },
+        {
+            "label": "true",
+            "url": "./true"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/creation/randi.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/randi.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, in the examples above, the result of `randi` remains on the GPU whenever the planner determines that downstream work benefits from staying on device.\n\nTo preserve backwards compatibility with MathWorks MATLAB—and when you want to be explicit about residency—you can call `gpuArray` yourself to seed GPU execution.\n\nBecause MathWorks MATLAB lacks a fusion planner and ships GPU support as a separate toolbox, MATLAB users must move data manually. RunMat automates residency to streamline accelerated workflows.",
+    "gpu_behavior": [
+        "When the target output or `'like'` prototype resides on the GPU, RunMat first asks the active acceleration provider for device-side generation via `random_integer_like` (shape reuse) or `random_integer_range` (explicit shape). Providers that do not expose these hooks fall back to host-side sampling followed by a single upload, ensuring correctness while still keeping the resulting tensor on the GPU."
+    ],
+    "key": "randi",
+    "slug": "randi",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=randi.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"randi.js","sourceRoot":"","sources":["../../../src/generated/builtins/randi.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,gBAAgB;IAC5B,UAAU,EAAE;QACV,OAAO;QACP,QAAQ;QACR,SAAS;QACT,KAAK;QACL,MAAM;KACP;IACD,SAAS,EAAE,gDAAgD;IAC3D,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,qIAAqI;KAC/I;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,MAAM;KACpB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,yCAAyC;QACjD,aAAa,EAAE,mEAAmE;KACnF;IACD,aAAa,EAAE,8SAA8S;IAC7T,WAAW,EAAE;QACX,yEAAyE;QACzE,8EAA8E;QAC9E,+GAA+G;QAC/G,iIAAiI;QACjI,gEAAgE;QAChE,kGAAkG;QAClG,+FAA+F;QAC/F,wIAAwI;KACzI;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,2BAA2B;YAC1C,OAAO,EAAE,0BAA0B;YACnC,QAAQ,EAAE,UAAU;SACrB;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,gCAAgC;YACzC,QAAQ,EAAE,+CAA+C;SAC1D;QACD;YACE,aAAa,EAAE,gDAAgD;YAC/D,OAAO,EAAE,yDAAyD;YAClE,QAAQ,EAAE,kMAAkM;SAC7M;QACD;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,8FAA8F;YACvG,QAAQ,EAAE,wKAAwK;SACnL;QACD;YACE,aAAa,EAAE,gCAAgC;YAC/C,OAAO,EAAE,+CAA+C;YACxD,QAAQ,EAAE,gHAAgH;SAC3H;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,iCAAiC;YAC1C,QAAQ,EAAE,iBAAiB;SAC5B;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,8JAA8J;SACzK;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,gHAAgH;SAC3H;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,wJAAwJ;SACnK;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,wLAAwL;SACnM;QACD;YACE,UAAU,EAAE,mCAAmC;YAC/C,QAAQ,EAAE,0KAA0K;SACrL;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,qJAAqJ;SAChK;QACD;YACE,UAAU,EAAE,uDAAuD;YACnE,QAAQ,EAAE,iKAAiK;SAC5K;QACD;YACE,UAAU,EAAE,4DAA4D;YACxE,QAAQ,EAAE,uIAAuI;SAClJ;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,8DAA8D;QACvE,KAAK,EAAE,2GAA2G;KACnH;IACD,eAAe,EAAE,qrBAAqrB;IACtsB,cAAc,EAAE;QACd,oZAAoZ;KACrZ;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,OAAO;QACP,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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