runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/rank.js

@@ -0,0 +1,181 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rank",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "rank",
+        "singular value decomposition",
+        "tolerance",
+        "matrix rank",
+        "gpu"
+    ],
+    "summary": "Compute the numerical rank of a matrix using SVD with MATLAB-compatible tolerance handling.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/rank.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Providers may implement a dedicated rank hook; current backends gather to the host and reuse the shared SVD path."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::rank::tests",
+        "gpu": "builtins::math::linalg::solve::rank::tests::rank_gpu_round_trip",
+        "wgpu": "builtins::math::linalg::solve::rank::tests::rank_wgpu_matches_cpu"
+    },
+    "description": "`r = rank(A)` returns the numerical rank of a real or complex matrix `A`. The rank equals the number of singular values greater than a tolerance derived from the matrix size and the largest singular value. RunMat mirrors MATLAB’s logic exactly so that results agree bit-for-bit with the reference implementation.",
+    "behaviors": [
+        "Inputs must behave like 2-D matrices. Trailing singleton dimensions are accepted; other higher ranks result in `\"rank: inputs must be 2-D matrices or vectors\"`.",
+        "The default tolerance is `tol = max(size(A)) * eps(max(s))`, where `s` are the singular values from an SVD of `A`. You can override this by supplying a second argument: `rank(A, tol)`.",
+        "When you provide an explicit tolerance it must be a finite, non-negative scalar. Non-scalars, `NaN`, `Inf`, or negative values raise MATLAB-compatible errors.",
+        "Logical and integer inputs are promoted to double precision before taking the SVD.",
+        "`rank([])` returns `0`. Rank is always reported as a double scalar (e.g., `2.0`).",
+        "Complex inputs use a complex SVD so that conjugate transposes and magnitudes follow MATLAB’s conventions."
+    ],
+    "examples": [
+        {
+            "description": "Determining the rank of a full matrix",
+            "input": "A = [1 2; 3 4];\nrk = rank(A)",
+            "output": "rk = 2"
+        },
+        {
+            "description": "Detecting rank deficiency in a singular matrix",
+            "input": "B = [1 2; 2 4];\nrk = rank(B)",
+            "output": "rk = 1"
+        },
+        {
+            "description": "Applying a custom tolerance to suppress tiny singular values",
+            "input": "C = diag([1, 1e-12]);\nrk_default = rank(C);          % counts both singular values (rank 2)\nrk_custom  = rank(C, 1e-9);    % treats the small value as zero (rank 1)"
+        },
+        {
+            "description": "Computing the rank of a tall matrix",
+            "input": "A = [1 0; 0 0; 0 1];\nrk = rank(A)",
+            "output": "rk = 2"
+        },
+        {
+            "description": "Evaluating the rank of a complex matrix",
+            "input": "Z = [1+1i 0; 0 2-3i];\nrk = rank(Z)",
+            "output": "rk = 2"
+        },
+        {
+            "description": "Checking the rank of an empty matrix",
+            "input": "E = [];\nrk = rank(E)",
+            "output": "rk = 0"
+        },
+        {
+            "description": "Using `rank` with `gpuArray` data",
+            "input": "G = gpuArray([1 2 3; 3 6 9; 0 1 0]);\nrk = rank(G);      % Computation stays on the GPU when the provider supports it\nrk_host = gather(rk)",
+            "output": "rk_host = 2"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is the default tolerance chosen?",
+            "answer": "RunMat computes the default tolerance exactly as MATLAB: `max(size(A)) * eps(max(s))`, where `s` are the singular values of `A`. This scales the cutoff with matrix size and magnitude."
+        },
+        {
+            "question": "What does `rank([])` return?",
+            "answer": "The rank of the empty matrix is `0`. This matches MATLAB’s convention that an empty product has neutral value."
+        },
+        {
+            "question": "Does `rank` return an integer or a double?",
+            "answer": "`rank` returns a double-precision scalar, mirroring MATLAB’s numeric tower. The value is always an integer-valued double."
+        },
+        {
+            "question": "How does `rank` behave for vectors or scalars?",
+            "answer": "Scalars are treated as `1×1` matrices. `rank([0])` returns `0`, while `rank([5])` returns `1`. Row or column vectors behave as matrices with one dimension equal to 1."
+        },
+        {
+            "question": "Can `rank` detect symbolic rank or exact arithmetic?",
+            "answer": "No. Like MATLAB, RunMat’s `rank` relies on floating-point SVD and is subject to the chosen tolerance. For symbolic or exact arithmetic you would use a computer algebra system."
+        },
+        {
+            "question": "Will `rank` participate in fusion or auto-offload?",
+            "answer": "No. `rank` is a residency sink that eagerly computes an SVD. Fusion groups terminate before the call, and the planner treats the builtin as a scalar reduction."
+        },
+        {
+            "question": "Is the tolerance argument optional?",
+            "answer": "Yes. `rank(A)` uses the default tolerance and mirrors MATLAB. Supplying `rank(A, tol)` overrides the cutoff. Non-scalar or negative tolerances raise MATLAB-compatible errors."
+        },
+        {
+            "question": "What happens if the matrix contains NaNs or Infs?",
+            "answer": "Singular values involving `NaN` propagate and typically produce a rank of `0`. Infinite values yield infinite singular values and therefore produce a rank equal to the number of infinite entries above tolerance, matching MATLAB’s behaviour."
+        },
+        {
+            "question": "Does `rank` allocate large temporary buffers?",
+            "answer": "Only enough memory for the SVD factors. For host execution this is handled by `nalgebra` (and LAPACK when enabled). GPU providers are free to reuse buffers or stream the computation."
+        }
+    ],
+    "links": [
+        {
+            "label": "pinv",
+            "url": "./pinv"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        },
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cond",
+            "url": "./cond"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        },
+        {
+            "label": "rcond",
+            "url": "./rcond"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/math/linalg/solve/rank.rs",
+        "url": "crates/runmat-runtime/src/builtins/math/linalg/solve/rank.rs"
+    },
+    "gpu_residency": "RunMat’s planner automatically keeps matrices on the GPU when a provider implements the `rank` hook. If the hook is missing, the builtin transparently gathers the matrix, computes the SVD on the CPU, and uploads the scalar result so later GPU work remains resident. You can still seed residency manually with `gpuArray` for MATLAB compatibility, but it is rarely required.",
+    "gpu_behavior": [
+        "When a GPU acceleration provider is active, RunMat first offers the computation through the reserved `rank` provider hook. Backends that implement it can stay fully on-device and return a `gpuTensor` scalar. Providers without that hook—including today’s WGPU backend—gather the matrix to host memory, reuse the shared SVD logic, and then re-upload the scalar rank so downstream kernels continue on the GPU without user intervention. Auto-offload treats the builtin as an eager sink, so any fused producers flush before `rank` executes and residency bookkeeping remains consistent."
+    ],
+    "key": "rank",
+    "slug": "rank",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rank.js.map

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

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

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

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

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

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

package/dist/generated/builtins/rcond.js

@@ -0,0 +1,157 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rcond",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "rcond",
+        "reciprocal condition",
+        "condition number",
+        "linear algebra",
+        "gpu"
+    ],
+    "summary": "Estimate the reciprocal condition number of a square matrix (1 / cond(A)) with MATLAB-compatible behaviour.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/rcond.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "When a provider exposes a dense solver hook it may reuse that path; the shipping backends gather to the host, run the shared SVD-based estimator, and optionally re-upload the scalar."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::rcond::tests",
+        "gpu": "builtins::math::linalg::solve::rcond::tests::rcond_gpu_round_trip_matches_cpu",
+        "wgpu": "builtins::math::linalg::solve::rcond::tests::rcond_wgpu_matches_cpu"
+    },
+    "description": "`rc = rcond(A)` returns an estimate of the reciprocal of the condition number of a square matrix `A` in the 1-norm. Well-conditioned matrices yield values close to `1`, whereas singular or numerically singular matrices yield values near zero. The estimate mirrors MATLAB: it is based on the ratio of the smallest to largest singular values.",
+    "behaviors": [
+        "Inputs must be square matrices (scalars count as `1 × 1`). Non-square inputs trigger the MATLAB error `\"rcond: input must be a square matrix.\"`",
+        "For the empty matrix (`0 × 0`) the reciprocal condition number is `Inf`.",
+        "`rcond(0)` returns `0`. Non-zero scalars return `1`.",
+        "Logical and integer arrays are promoted to double precision before analysis.",
+        "Complex matrices are supported; the singular values are computed in complex arithmetic.",
+        "The implementation runs an SVD and computes `min(s) / max(s)`, honouring MATLAB's tolerance logic."
+    ],
+    "examples": [
+        {
+            "description": "Reciprocal condition of the identity matrix",
+            "input": "A = eye(3);\nrc = rcond(A)",
+            "output": "rc = 1"
+        },
+        {
+            "description": "Detecting a nearly singular matrix",
+            "input": "A = diag([1, 1e-8]);\nrc = rcond(A)",
+            "output": "rc = 1e-8"
+        },
+        {
+            "description": "Reciprocal condition of a singular matrix",
+            "input": "A = [1 2; 2 4];\nrc = rcond(A)",
+            "output": "rc = 0"
+        },
+        {
+            "description": "Reciprocal condition for a complex matrix",
+            "input": "A = [1+2i 0; 3i 2-1i];\nrc = rcond(A)",
+            "output": "rc = 0.1887"
+        },
+        {
+            "description": "Handling the empty matrix",
+            "input": "rc = rcond([])",
+            "output": "rc = Inf"
+        },
+        {
+            "description": "Estimating conditioning on GPU data",
+            "input": "G = gpuArray([2 0; 0 0.5]);\nrc_gpu = rcond(G);\nrc = gather(rc_gpu)",
+            "output": "rc = 0.25"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What range of values should I expect from `rcond`?",
+            "answer": "`rcond` returns a value in `[0, 1]`. Values near `1` indicate a well-conditioned matrix. Values near `0` indicate singular or ill-conditioned matrices."
+        },
+        {
+            "question": "Why does `rcond` return `Inf` for the empty matrix?",
+            "answer": "The empty matrix is perfectly conditioned by convention, so the reciprocal condition number is `Inf` (`1 / 0`)."
+        },
+        {
+            "question": "Does `rcond` warn me about singular systems automatically?",
+            "answer": "`rcond` itself does not issue warnings. Use the value to decide whether the matrix is singular to working precision, similar to MATLAB workflows (`if rcond(A) < eps, ...`)."
+        },
+        {
+            "question": "Is the SVD tolerance the same as MATLAB?",
+            "answer": "Yes. The estimator matches MATLAB's definition by deriving the result from the singular values. The same tolerance logic is shared with `pinv` and `rank`."
+        },
+        {
+            "question": "Will calling `rcond` move my data off the GPU?",
+            "answer": "Only if the active provider lacks a dedicated implementation. In that case RunMat transparently downloads the matrix, computes the estimate on the host, and re-uploads the scalar."
+        }
+    ],
+    "links": [
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "pinv",
+            "url": "./pinv"
+        },
+        {
+            "label": "rank",
+            "url": "./rank"
+        },
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cond",
+            "url": "./cond"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/math/linalg/solve/rcond.rs",
+        "url": "crates/runmat-runtime/src/builtins/math/linalg/solve/rcond.rs"
+    },
+    "gpu_residency": "Manually calling `gpuArray` is rarely necessary. When matrices already live on the device, RunMat invokes the provider hook if one exists, or automatically gathers, evaluates, and re-uploads the scalar result. This preserves MATLAB compatibility while keeping the runtime efficient and ergonomic.",
+    "gpu_behavior": [
+        "When the input resides on a GPU, RunMat first invokes the active provider's `rcond` hook that this builtin registers. When that hook is unavailable the runtime attempts to reuse the provider's `linsolve` factorisations to recover the reciprocal condition number. If neither path is implemented the matrix is gathered to the host, the shared SVD-based estimator is executed, and the scalar result is uploaded back to the device so subsequent GPU work keeps residency."
+    ],
+    "key": "rcond",
+    "slug": "rcond",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rcond.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rcond.js","sourceRoot":"","sources":["../../../src/generated/builtins/rcond.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,mBAAmB;IAC/B,UAAU,EAAE;QACV,OAAO;QACP,sBAAsB;QACtB,kBAAkB;QAClB,gBAAgB;QAChB,KAAK;KACN;IACD,SAAS,EAAE,6GAA6G;IACxH,YAAY,EAAE;QACZ,sDAAsD;KACvD;IACD,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,wLAAwL;KAClM;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,6CAA6C;QACrD,KAAK,EAAE,+EAA+E;QACtF,MAAM,EAAE,qEAAqE;KAC9E;IACD,aAAa,EAAE,sVAAsV;IACrW,WAAW,EAAE;QACX,mJAAmJ;QACnJ,0EAA0E;QAC1E,sDAAsD;QACtD,8EAA8E;QAC9E,yFAAyF;QACzF,oGAAoG;KACrG;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,4BAA4B;YACrC,QAAQ,EAAE,QAAQ;SACnB;QACD;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,qCAAqC;YAC9C,QAAQ,EAAE,WAAW;SACtB;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,gCAAgC;YACzC,QAAQ,EAAE,QAAQ;SACnB;QACD;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,uCAAuC;YAChD,QAAQ,EAAE,aAAa;SACxB;QACD;YACE,aAAa,EAAE,2BAA2B;YAC1C,OAAO,EAAE,gBAAgB;YACzB,QAAQ,EAAE,UAAU;SACrB;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,sEAAsE;YAC/E,QAAQ,EAAE,WAAW;SACtB;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,oDAAoD;YAChE,QAAQ,EAAE,yJAAyJ;SACpK;QACD;YACE,UAAU,EAAE,qDAAqD;YACjE,QAAQ,EAAE,iHAAiH;SAC5H;QACD;YACE,UAAU,EAAE,4DAA4D;YACxE,QAAQ,EAAE,8KAA8K;SACzL;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,4JAA4J;SACvK;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,qLAAqL;SAChM;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,+DAA+D;QACxE,KAAK,EAAE,+DAA+D;KACvE;IACD,eAAe,EAAE,0SAA0S;IAC3T,cAAc,EAAE;QACd,odAAod;KACrd;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,MAAM;QACN,QAAQ;QACR,OAAO;KACR;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/rdivide.js

@@ -0,0 +1,257 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "rdivide",
+    "category": "math/elementwise",
+    "keywords": [
+        "rdivide",
+        "element-wise division",
+        "./",
+        "gpu",
+        "implicit expansion"
+    ],
+    "summary": "Element-wise division A ./ B with MATLAB-compatible implicit expansion, complex support, and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/rdivide.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Prefers provider elem_div/scalar_div/scalar_rdiv hooks; gathers to host for implicit expansion or unsupported operand types."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::rdivide::tests::rdivide_scalar_numbers",
+        "integration": "builtins::math::elementwise::rdivide::tests::rdivide_row_column_broadcast",
+        "gpu": "builtins::math::elementwise::rdivide::tests::rdivide_gpu_pair_roundtrip",
+        "wgpu": "builtins::math::elementwise::rdivide::tests::rdivide_wgpu_matches_cpu_elementwise",
+        "like_gpu": "builtins::math::elementwise::rdivide::tests::rdivide_like_gpu_prototype_keeps_residency",
+        "like_host": "builtins::math::elementwise::rdivide::tests::rdivide_like_host_gathers_gpu_value",
+        "like_complex": "builtins::math::elementwise::rdivide::tests::rdivide_like_complex_prototype_yields_complex"
+    },
+    "description": "`rdivide(A, B)` (or the operator form `A ./ B`) divides corresponding elements of `A` and `B`, honouring MATLAB's implicit expansion rules so that scalars and singleton dimensions broadcast automatically.",
+    "behaviors": [
+        "Supports real, complex, logical, and character inputs; logical and character data are promoted to double precision before division.",
+        "Implicit expansion works across any dimension, provided the non-singleton extents match. Size mismatches raise the standard MATLAB-compatible error.",
+        "Complex operands follow the analytic rule `(a + ib) ./ (c + id) = ((ac + bd) + i(bc - ad)) / (c^2 + d^2)`, matching MATLAB's behaviour for infinities and NaNs.",
+        "Empty dimensions propagate naturally—if the broadcasted shape contains a zero extent, the result is empty with that shape.",
+        "Integer inputs promote to double precision, mirroring the behaviour of other RunMat arithmetic builtins.",
+        "The optional `'like'` prototype makes the output adopt the residency (host or GPU) and complexity characteristics of the prototype, letting you keep implicit-expansion expressions on the device without manual `gpuArray` calls. When the prototype is complex, the result remains a complex host array (complex gpuArray prototypes are not yet supported)."
+    ],
+    "examples": [
+        {
+            "description": "Divide two matrices element-wise",
+            "input": "A = [8 12 18; 2 10 18];\nB = [2 3 6; 2 5 9];\nQ = rdivide(A, B)",
+            "output": "Q =\n    4     4     3\n    1     2     2"
+        },
+        {
+            "description": "Divide a matrix by a scalar",
+            "input": "A = magic(3);\nscaled = rdivide(A, 2)",
+            "output": "scaled =\n    4.5    0.5    3.5\n    1.5    5.0    9.0\n    8.0    6.5    2.0"
+        },
+        {
+            "description": "Use implicit expansion between a column and row vector",
+            "input": "col = (1:3)';\nrow = [10 20 30];\nratio = rdivide(col, row)",
+            "output": "ratio =\n    0.1    0.05    0.0333\n    0.2    0.10    0.0667\n    0.3    0.15    0.1000"
+        },
+        {
+            "description": "Divide complex inputs element-wise",
+            "input": "z1 = [1+2i, 3-4i];\nz2 = [2-1i, -1+1i];\nquot = rdivide(z1, z2)",
+            "output": "quot =\n    0.0 + 1.0i   -3.5 + 0.5i"
+        },
+        {
+            "description": "Divide character codes by a numeric scalar",
+            "input": "letters = 'ABC';\ncodes = rdivide(letters, 2)",
+            "output": "codes = [32.5 33 33.5]"
+        },
+        {
+            "description": "Execute `rdivide` directly on gpuArray inputs",
+            "input": "G1 = gpuArray([10 20 30]);\nG2 = gpuArray([2 5 10]);\ndeviceQuot = rdivide(G1, G2);\nresult = gather(deviceQuot)",
+            "output": "deviceQuot =\n  1x3 gpuArray\n     5     4     3\nresult =\n     5     4     3"
+        },
+        {
+            "description": "Keep the result on the GPU with a `'like'` prototype",
+            "input": "proto = gpuArray.zeros(1, 1);\nA = [1 2 3];\nB = [2 4 6];\nC = rdivide(A, B, 'like', proto);  % stays on the GPU for downstream work",
+            "output": "C =\n  1x3 gpuArray\n      0.5    0.5    0.5"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `rdivide` support MATLAB implicit expansion?",
+            "answer": "Yes. Any singleton dimensions expand automatically. If a dimension has incompatible non-singleton extents, `rdivide` raises the standard size-mismatch error."
+        },
+        {
+            "question": "What numeric type does `rdivide` return?",
+            "answer": "Results are double precision for real inputs and complex double when either operand is complex. Logical and character inputs are promoted to double before division."
+        },
+        {
+            "question": "How does `rdivide` handle division by zero?",
+            "answer": "RunMat follows IEEE rules: `finite ./ 0` produces signed infinity, while `0 ./ 0` yields `NaN`. Complex results follow MATLAB's analytic continuation rules."
+        },
+        {
+            "question": "Can I divide gpuArrays by host scalars?",
+            "answer": "Yes. RunMat keeps the computation on the GPU when the scalar is numeric. For other host operand types, the runtime gathers the gpuArray and computes on the CPU."
+        },
+        {
+            "question": "Does `rdivide` preserve gpuArray residency after a fallback?",
+            "answer": "When a fallback occurs (for example, implicit expansion that the provider does not implement), the current result remains on the host. Subsequent operations may move it back to the GPU when auto-offload decides it is profitable."
+        },
+        {
+            "question": "How can I force the result to stay on the GPU?",
+            "answer": "Provide a `'like'` prototype: `rdivide(A, B, 'like', gpuArray.zeros(1, 1))` keeps the result on the device even if one of the inputs originated on the host. Complex prototypes are honoured on the host today; supply a real gpuArray prototype when you need the result to remain device-resident."
+        },
+        {
+            "question": "How are empty arrays handled?",
+            "answer": "Empty dimensions propagate. If either operand has an extent of zero in the broadcasted shape, the result is empty with the broadcasted dimensions."
+        },
+        {
+            "question": "Are integer inputs supported?",
+            "answer": "Yes. Integers promote to double precision during the division, matching other RunMat arithmetic builtins."
+        },
+        {
+            "question": "Can I mix complex and real operands?",
+            "answer": "Absolutely. The result is complex, with broadcasting rules identical to MATLAB."
+        },
+        {
+            "question": "What about string arrays?",
+            "answer": "String arrays are not numeric and therefore raise an error when passed to `rdivide`."
+        }
+    ],
+    "links": [
+        {
+            "label": "times",
+            "url": "./times"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "mrdivide",
+            "url": "./mrdivide"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/rdivide.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/rdivide.rs"
+    },
+    "gpu_residency": "RunMat's auto-offload planner keeps tensors on the GPU whenever fused expressions benefit from device execution. Explicit `gpuArray` / `gather` calls are still supported for MATLAB code that manages residency manually. When the active provider lacks the kernels needed for a particular call (for example, implicit expansion between gpuArrays of different shapes), RunMat gathers back to the host, computes the MATLAB-accurate result, and resumes execution seamlessly.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active:\n\n1. If both operands are gpuArrays with identical shapes, RunMat dispatches to the provider's `elem_div` hook so the entire computation stays on device memory. 2. If one operand is a scalar (host or device) and the other is a gpuArray, the runtime calls `scalar_div` (`tensor ./ scalar`) or `scalar_rdiv` (`scalar ./ tensor`) accordingly. 3. The fusion planner treats `rdivide` as a fusible elementwise node, so adjacent elementwise producers or consumers can execute inside a single WGSL kernel or provider-optimised pipeline, reducing host↔device transfers. 4. Implicit-expansion workloads (for example, combining a row vector with a column vector) or unsupported operand kinds gather transparently to host memory, compute the result with full MATLAB semantics, and return a host tensor. When you request `'like'` with a complex prototype, RunMat gathers to the host, performs the conversion, and returns a complex host value so downstream code still sees MATLAB-compatible types."
+    ],
+    "key": "rdivide",
+    "slug": "rdivide",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=rdivide.js.map

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

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

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

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

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

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