runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/randn.js

@@ -0,0 +1,199 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "randn",
+    "category": "array/creation",
+    "keywords": [
+        "randn",
+        "random",
+        "normal",
+        "gaussian",
+        "gpu",
+        "like"
+    ],
+    "summary": "Standard normal random numbers that mirror MATLAB semantics.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider random_normal hooks when available; otherwise generates samples on the host and uploads them to keep GPU residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "none"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::creation::randn::tests",
+        "integration": "builtins::array::creation::randn::tests::randn_gpu_like_roundtrip"
+    },
+    "description": "`randn` draws pseudorandom samples from the standard normal distribution (`μ = 0`, `σ = 1`). RunMat matches MATLAB call patterns for scalars, explicit dimension lists, size vectors, and `'like'` prototypes while honouring GPU residency whenever an acceleration provider is active.",
+    "behaviors": [
+        "`randn()` returns a scalar double drawn from `𝒩(0, 1)`.",
+        "`randn(n)` returns an `n × n` dense double matrix.",
+        "`randn(m, n, ...)` accepts an arbitrary number of dimension arguments.",
+        "`randn(sz)` accepts a size vector (row or column) and returns an array with shape `sz`.",
+        "`randn(A)` or `randn(___, 'like', A)` matches both the shape and residency of `A`, including GPU tensors and complex prototypes.",
+        "Complex prototypes yield complex Gaussian samples with independent `𝒩(0, 1)` real and imaginary parts.",
+        "Class specifiers currently support `'double'`; other classes (e.g., `'single'`) emit descriptive errors until native representations land."
+    ],
+    "examples": [
+        {
+            "description": "Drawing a single standard normal variate",
+            "input": "rng(0);\nz = randn()",
+            "output": "z = 1.8179"
+        },
+        {
+            "description": "Creating a matrix of Gaussian noise",
+            "input": "rng(0);\nE = randn(2, 3)",
+            "output": "E =\n    1.8179    0.3895    0.9838\n   -1.1645    0.4175    0.1386"
+        },
+        {
+            "description": "Specifying dimensions with a size vector",
+            "input": "rng(0);\nshape = [2 2 2];\nT = randn(shape)",
+            "output": "T(:, :, 1) =\n    1.8179    0.3895\n   -1.1645    0.4175\n\nT(:, :, 2) =\n    0.9838   -1.1226\n    0.1386    2.7430"
+        },
+        {
+            "description": "Matching an existing `gpuArray` prototype",
+            "input": "rng(0);\nG = gpuArray.zeros(512, 512);\nnoise = randn('like', G);\nstats = [mean(gather(noise(:))) std(gather(noise(:)))]",
+            "output": "size(noise)\nans =\n       512   512\n\nstats =\n   -0.0009    0.9986"
+        },
+        {
+            "description": "Generating complex Gaussian samples",
+            "input": "rng(0);\nz = randn(3, 1, 'like', 1 + 1i)",
+            "output": "z =\n   1.8179 - 1.1645i\n   0.3895 + 0.4175i\n   0.9838 + 0.1386i"
+        },
+        {
+            "description": "Producing reproducible noise for Monte Carlo tests",
+            "input": "rng(0);\nsamples = randn(1, 5)",
+            "output": "samples = [1.8179  -1.1645   0.3895   0.4175   0.9838]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What distribution does `randn` use?",
+            "answer": "`randn` returns samples from the standard normal distribution with mean `0` and standard deviation `1`."
+        },
+        {
+            "question": "How is `randn` different from `rand`?",
+            "answer": "`randn` draws from a Gaussian distribution, whereas `rand` draws from the uniform distribution over `(0, 1)`."
+        },
+        {
+            "question": "How do I control reproducibility?",
+            "answer": "Use the MATLAB-compatible `rng` builtin before calling `randn` to seed the global generator."
+        },
+        {
+            "question": "Does `randn(___, 'like', A)` work with complex prototypes?",
+            "answer": "Yes. When `A` is complex, RunMat emits complex Gaussian samples whose real and imaginary parts are independent `𝒩(0, 1)` variates."
+        },
+        {
+            "question": "What happens if I request `'single'` precision?",
+            "answer": "RunMat currently supports double precision. Supplying `'single'` raises a descriptive error until native single-precision tensors land."
+        },
+        {
+            "question": "How does `randn` behave on the GPU?",
+            "answer": "If the active acceleration provider implements normal RNG hooks, samples are generated directly on device. Otherwise RunMat produces them on the host, uploads once, and continues execution on the GPU."
+        },
+        {
+            "question": "Can I request zero-sized dimensions?",
+            "answer": "Yes. Any dimension argument equal to zero yields an empty array, matching MATLAB semantics."
+        },
+        {
+            "question": "Does `randn` fuse with other operations?",
+            "answer": "No. Random generation is treated as a sink operation and excluded from fusion planning to preserve statistical properties."
+        }
+    ],
+    "links": [
+        {
+            "label": "rand",
+            "url": "./rand"
+        },
+        {
+            "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/randn.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/randn.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly in RunMat. The fusion planner keeps results on the GPU when downstream work benefits from device residency. However, for MATLAB compatibility—and when you want deterministic control—you can still use `gpuArray` to seed GPU execution manually.\n\nMathWorks MATLAB lacks an integrated fusion planner and ships GPU acceleration as a separate toolbox, so MATLAB users move data manually. RunMat automates this to streamline accelerated workflows.",
+    "gpu_behavior": [
+        "When the output or `'like'` prototype lives on the GPU, RunMat calls into the active acceleration provider via `random_normal` / `random_normal_like`. Providers without these hooks fall back to host generation followed by a single upload, ensuring the resulting tensor still resides on device even if samples were produced on the CPU."
+    ],
+    "key": "randn",
+    "slug": "randn",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=randn.js.map

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

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

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

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

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

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

package/dist/generated/builtins/randperm.js

@@ -0,0 +1,188 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "randperm",
+    "category": "array/creation",
+    "keywords": [
+        "randperm",
+        "permutation",
+        "random",
+        "indices",
+        "gpu",
+        "like"
+    ],
+    "summary": "Random permutations of the integers 1:n with MATLAB-compatible semantics.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Falls back to host-side generation followed by an upload when providers lack a dedicated permutation kernel."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "none"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::creation::randperm::tests",
+        "integration": "builtins::array::creation::randperm::tests::randperm_gpu_like_roundtrip"
+    },
+    "description": "`randperm(n)` returns a uniformly random permutation of the integers `1:n`. `randperm(n, k)` selects `k` unique integers from `1:n` without replacement. RunMat mirrors MATLAB's behaviour, including RNG seeding through `rng`, GPU-aware `'like'` prototypes, and deterministic results during testing.",
+    "behaviors": [
+        "`randperm(n)` produces a row vector whose length is `n` and whose entries are a random ordering of `1:n`.",
+        "`randperm(n, k)` returns the first `k` entries of the permutation without replacement (`0 ≤ k ≤ n`). The result is a `1 × k` row vector.",
+        "`randperm(n, ___, 'like', A)` matches the numeric class and residency of `A` when possible (e.g., GPU tensors).",
+        "`randperm(n, ___, 'double')` keeps the default double-precision output.",
+        "`randperm` errors when `n` or `k` are non-integers, negative, or exceed the IEEE `double` integer precision limit (`2^53`).",
+        "Empty permutations (e.g., `randperm(0)` or `randperm(n, 0)`) return a `1×0` tensor."
+    ],
+    "examples": [
+        {
+            "description": "Getting a random permutation of integers 1 through N",
+            "input": "rng(0);\np = randperm(6)",
+            "output": "p = [1 6 2 4 3 5]"
+        },
+        {
+            "description": "Selecting K unique indices without replacement",
+            "input": "rng(0);\nidx = randperm(10, 3)",
+            "output": "idx = [1 10 9]"
+        },
+        {
+            "description": "Generating a reproducible permutation after seeding RNG",
+            "input": "rng(42);\np1 = randperm(8);\nrng(42);\np2 = randperm(8)",
+            "output": "isequal(p1, p2)\nans = logical\n     1"
+        },
+        {
+            "description": "Creating a GPU-resident random permutation",
+            "input": "G = gpuArray.zeros(4, 4);\np = randperm(12, 4, 'like', G);\npeek = gather(p)",
+            "output": "isa(p, 'gpuArray')\nans = logical\n     1"
+        },
+        {
+            "description": "Working with empty permutations",
+            "input": "p = randperm(0);\nq = randperm(5, 0)",
+            "output": "size(p)\nans =\n     1     0\n\nsize(q)\nans =\n     1     0"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What ranges does `randperm` draw from?",
+            "answer": "`randperm(n)` always returns integers in the inclusive range `1:n`. The optional second argument `k` picks the first `k` elements of that permutation."
+        },
+        {
+            "question": "Can `k` be zero?",
+            "answer": "Yes. `randperm(n, 0)` returns a `1×0` empty row vector without consuming any additional random numbers."
+        },
+        {
+            "question": "Does `randperm` support `'single'` or integer output types?",
+            "answer": "Not yet. The builtin currently emits double-precision arrays. Supplying `'single'` or integer class names raises a descriptive error."
+        },
+        {
+            "question": "How does `randperm` interact with `rng`?",
+            "answer": "`randperm` consumes the shared RunMat RNG stream. Use the MATLAB-compatible `rng` builtin to seed or restore the generator for reproducible permutations."
+        },
+        {
+            "question": "Why is there a `2^53` limit?",
+            "answer": "All outputs are stored in IEEE `double`. Values beyond `2^53` cannot be represented exactly, so RunMat rejects inputs larger than `2^53` to avoid duplicate entries."
+        },
+        {
+            "question": "Does the GPU path stay device-resident?",
+            "answer": "Yes—when a provider is active RunMat uploads the host permutation after it is generated. Providers that later add a dedicated permutation kernel can replace the fallback without changing user code."
+        }
+    ],
+    "links": [
+        {
+            "label": "rand",
+            "url": "./rand"
+        },
+        {
+            "label": "randi",
+            "url": "./randi"
+        },
+        {
+            "label": "rng",
+            "url": "./rng"
+        },
+        {
+            "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": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "range",
+            "url": "./range"
+        },
+        {
+            "label": "true",
+            "url": "./true"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/creation/randperm.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/randperm.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the fusion planner and acceleration layer keep residency on the GPU whenever downstream computation benefits from it. When you request a permutation `'like'` a GPU tensor, RunMat asks the active acceleration provider to generate and shuffle the permutation directly on the device. If the provider does not implement the permutation hook, RunMat falls back to host generation and performs a single upload so later GPU work still sees a device-resident array.\n\nTo preserve backwards compatibility with MathWorks MATLAB—and for situations where you want to be explicit—you can always wrap inputs in `gpuArray`.",
+    "gpu_behavior": [
+        "When the `'like'` prototype lives on the GPU, RunMat asks the active acceleration provider for a device-side permutation via the dedicated `random_permutation_like` hook. The bundled WGPU provider executes the entire selection and shuffle in a compute kernel, keeping the data resident on the device. Providers that do not advertise this hook fall back to the host implementation and upload the result once, preserving correctness while highlighting the extra transfer cost."
+    ],
+    "key": "randperm",
+    "slug": "randperm",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=randperm.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"randperm.js","sourceRoot":"","sources":["../../../src/generated/builtins/randperm.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,gBAAgB;IAC5B,UAAU,EAAE;QACV,UAAU;QACV,aAAa;QACb,QAAQ;QACR,SAAS;QACT,KAAK;QACL,MAAM;KACP;IACD,SAAS,EAAE,2EAA2E;IACtF,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;SACN;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,8GAA8G;KACxH;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,4CAA4C;QACpD,aAAa,EAAE,yEAAyE;KACzF;IACD,aAAa,EAAE,2SAA2S;IAC1T,WAAW,EAAE;QACX,2GAA2G;QAC3G,0IAA0I;QAC1I,iHAAiH;QACjH,yEAAyE;QACzE,6HAA6H;QAC7H,qFAAqF;KACtF;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,sDAAsD;YACrE,OAAO,EAAE,0BAA0B;YACnC,QAAQ,EAAE,mBAAmB;SAC9B;QACD;YACE,aAAa,EAAE,gDAAgD;YAC/D,OAAO,EAAE,gCAAgC;YACzC,QAAQ,EAAE,gBAAgB;SAC3B;QACD;YACE,aAAa,EAAE,yDAAyD;YACxE,OAAO,EAAE,yDAAyD;YAClE,QAAQ,EAAE,wCAAwC;SACnD;QACD;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,8EAA8E;YACvF,QAAQ,EAAE,2CAA2C;SACtD;QACD;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,sCAAsC;YAC/C,QAAQ,EAAE,8DAA8D;SACzE;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,wJAAwJ;SACnK;QACD;YACE,UAAU,EAAE,kBAAkB;YAC9B,QAAQ,EAAE,yGAAyG;SACpH;QACD;YACE,UAAU,EAAE,6DAA6D;YACzE,QAAQ,EAAE,uIAAuI;SAClJ;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,2JAA2J;SACtK;QACD;YACE,UAAU,EAAE,8BAA8B;YAC1C,QAAQ,EAAE,sKAAsK;SACjL;QACD;YACE,UAAU,EAAE,yCAAyC;YACrD,QAAQ,EAAE,uMAAuM;SAClN;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,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;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,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;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,iEAAiE;QAC1E,KAAK,EAAE,8GAA8G;KACtH;IACD,eAAe,EAAE,gsBAAgsB;IACjtB,cAAc,EAAE;QACd,4dAA4d;KAC7d;IACD,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,cAAc,EAAE;QACd,OAAO;QACP,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/range.js

@@ -0,0 +1,216 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "range",
+    "category": "array/creation",
+    "keywords": [
+        "range",
+        "max",
+        "min",
+        "spread",
+        "omitnan",
+        "gpu"
+    ],
+    "summary": "Compute the difference between the maximum and minimum values (max - min).",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": true,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider min/max reductions when available; falls back to the host when omitnan is requested or when multi-dimension reductions are unsupported."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::creation::range::tests",
+        "integration": "builtins::array::creation::range::tests::range_gpu_provider_roundtrip",
+        "gpu": "builtins::array::creation::range::tests::range_wgpu_dim2_matches_cpu"
+    },
+    "description": "`range(X)` returns the span (maximum minus minimum) of the elements in `X`. For arrays, the calculation happens along the first non-singleton dimension unless you specify one. The output keeps MATLAB's column-major shape conventions.",
+    "behaviors": [
+        "Operates on scalars, vectors, matrices, and N-D tensors.",
+        "`range(X)` measures the spread along the first non-singleton dimension.",
+        "`range(X, dim)` targets a specific dimension.",
+        "`range(X, vecdim)` reduces across multiple dimensions at once.",
+        "`range(X, 'all')` collapses all elements to a single scalar result.",
+        "`range(___)` is equivalent to `max(___) - min(___)` over the requested slice.",
+        "`vecdim` accepts a row or column vector of positive integers; duplicate entries are ignored.",
+        "`range(___, 'omitnan')` ignores `NaN` values (resulting in `NaN` if a slice has no finite values).",
+        "`range(___, 'includenan')` (default) returns `NaN` for any slice containing `NaN`.",
+        "Works with `gpuArray` inputs; the runtime keeps residency on the GPU when provider hooks are available."
+    ],
+    "examples": [
+        {
+            "description": "Measuring column-wise range of a matrix",
+            "input": "A = [1 4 2; 3 7 5];\nspread = range(A)",
+            "output": "% Each column's maximum minus minimum\nspread = [2 3 3]"
+        },
+        {
+            "description": "Selecting a dimension explicitly",
+            "input": "A = [1 4 2; 3 7 5];\nrow_spread = range(A, 2)",
+            "output": "row_spread = [3; 4]"
+        },
+        {
+            "description": "Collapsing all elements with 'all'",
+            "input": "temperatures = [68 72 75; 70 74 78];\noverall = range(temperatures, 'all')",
+            "output": "overall = 10"
+        },
+        {
+            "description": "Ignoring NaNs when computing range",
+            "input": "samples = [2 NaN 5; 4 6 NaN];\nspread = range(samples, 1, 'omitnan')",
+            "output": "spread = [2 0 0]"
+        },
+        {
+            "description": "Keeping gpuArray results on the device",
+            "input": "G = gpuArray([1 10 3; 2 8 4]);\ncolumn_spread = range(G);\ngather(column_spread)",
+            "output": "ans =\n     1     2     1"
+        },
+        {
+            "description": "Handling higher-dimensional inputs",
+            "input": "data = reshape(1:24, [3, 4, 2]);\nslice_spread = range(data, [1 2])",
+            "output": "slice_spread(:,:,1) =\n    11\n\nslice_spread(:,:,2) =\n    11"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `range(X)` return for scalars?",
+            "answer": "The range of a scalar is always `0`, because the maximum and minimum coincide."
+        },
+        {
+            "question": "How are NaN values treated by default?",
+            "answer": "By default (`'includenan'`), any slice containing `NaN` yields `NaN`. Use `'omitnan'` to ignore them."
+        },
+        {
+            "question": "Can I supply multiple dimensions?",
+            "answer": "Yes. Pass a vector such as `[1 3]` to reduce across both the first and third dimensions simultaneously."
+        },
+        {
+            "question": "What happens if I request a dimension larger than `ndims(X)`?",
+            "answer": "RunMat mirrors MATLAB: a size-1 dimension produces zeros (or `NaN` when the lone value is `NaN`)."
+        },
+        {
+            "question": "Does `range` support integer and logical inputs?",
+            "answer": "Yes. The inputs are promoted to double precision internally, matching MATLAB semantics."
+        },
+        {
+            "question": "How does `range` interact with `gpuArray`?",
+            "answer": "The runtime asks the active provider for min/max reductions. When unavailable, it gathers the data and computes on the CPU."
+        },
+        {
+            "question": "Why is the output sometimes a scalar and sometimes a vector?",
+            "answer": "The output collapses the selected dimensions to size `1`, leaving other dimensions unchanged. A single remaining element becomes a scalar."
+        },
+        {
+            "question": "How can I inspect the range across all elements quickly?",
+            "answer": "Use `range(X, 'all')` to flatten all dimensions into a single scalar spread."
+        }
+    ],
+    "links": [
+        {
+            "label": "max",
+            "url": "./max"
+        },
+        {
+            "label": "min",
+            "url": "./min"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "mean",
+            "url": "./mean"
+        },
+        {
+            "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": "rand",
+            "url": "./rand"
+        },
+        {
+            "label": "randi",
+            "url": "./randi"
+        },
+        {
+            "label": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "randperm",
+            "url": "./randperm"
+        },
+        {
+            "label": "true",
+            "url": "./true"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/creation/range.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/range.rs"
+    },
+    "gpu_residency": "You generally do **not** need to call `gpuArray` explicitly in RunMat. When the input is already on the GPU, the planner keeps the result on-device if the active provider exposes `reduce_min`, `reduce_max`, the corresponding `*_dim` reductions, and elementwise subtraction. Current providers specialise 2-D reductions; multi-axis reductions, tensors with more than two dimensions, or `'omitnan'` requests gather back to the host for correctness. When a required hook is missing, RunMat gathers the data automatically, computes on the CPU, and returns a standard tensor.",
+    "key": "range",
+    "slug": "range",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=range.js.map

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

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

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

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

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

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