runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/mrdivide.js

@@ -0,0 +1,155 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mrdivide",
+    "category": "math/linalg/ops",
+    "keywords": [
+        "mrdivide",
+        "matrix right division",
+        "linear systems",
+        "least squares",
+        "gpu"
+    ],
+    "summary": "Solve X * B = A using MATLAB's right-division operator (`/`).",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/double.mrdivide.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Prefers the accel provider's mrdivide hook; providers that lack it (including the current WGPU backend) gather to host, run the shared solver, then re-upload the result to keep residency transparent."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::ops::mrdivide::tests",
+        "gpu": "builtins::math::linalg::ops::mrdivide::tests::gpu_round_trip_matches_cpu",
+        "wgpu": "builtins::math::linalg::ops::mrdivide::tests::wgpu_round_trip_matches_cpu"
+    },
+    "description": "`X = A / B` (or `mrdivide(A, B)`) solves the right-sided linear system `X * B = A`. When `B` is square and nonsingular the solution matches `A * inv(B)`. Rectangular or rank-deficient matrices are handled via a minimum-norm least-squares solve, matching MATLAB's SVD-based semantics.",
+    "behaviors": [
+        "Scalars divide exactly: `A / s` scales `A` by `1/s`, while `s / B` requires `B` to be scalar.",
+        "Logical and integer inputs are promoted to double precision before solving.",
+        "Purely real operands produce real outputs; any complex operand promotes the computation (and result) to complex arithmetic.",
+        "Inputs must be effectively two-dimensional; trailing singleton dimensions are allowed.",
+        "The number of columns must agree (`size(A, 2) == size(B, 2)`), otherwise RunMat raises the MATLAB error `\"Matrix dimensions must agree.\"`",
+        "Underdetermined and overdetermined systems return the minimum-norm least-squares solution."
+    ],
+    "examples": [
+        {
+            "description": "Solving a square linear system",
+            "input": "A = [1 2; 3 4];\nB = [5 6; 7 8];\nX = A / B;\n\n% Verify the solution\nresidual = X * B",
+            "output": "X =\n     3    -2\n     2    -1\n\nresidual =\n     1     2\n     3     4"
+        },
+        {
+            "description": "Computing a least-squares right division",
+            "input": "A = [1 2 3];\nB = [1 0 1; 0 1 1];\nX = A / B",
+            "output": "X = [1 2]"
+        },
+        {
+            "description": "Dividing by a scalar",
+            "input": "A = [2 4 6];\nscaled = A / 2",
+            "output": "scaled = [1 2 3]"
+        },
+        {
+            "description": "Right division with complex inputs",
+            "input": "A = [1+2i 3-4i];\nB = [2-i 1+i];\nX = A / B",
+            "output": "X = -0.1429 - 0.2857i"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why must `A` and `B` share the number of columns?",
+            "answer": "Right division solves `X * B = A`; matrix multiplication requires `size(A, 2) == size(B, 2)`."
+        },
+        {
+            "question": "What happens if `B` is singular or rectangular?",
+            "answer": "RunMat matches MATLAB by computing the minimum-norm least-squares solution via singular-value decomposition—no explicit call to `pinv` is required."
+        },
+        {
+            "question": "Does `mrdivide` support higher-dimensional arrays?",
+            "answer": "No. Inputs must be effectively matrices (trailing singleton dimensions are allowed). Use `reshape` or `(:)` to flatten higher-dimensional data before calling `mrdivide`."
+        },
+        {
+            "question": "How are logical or integer arrays handled?",
+            "answer": "They are promoted to double precision (`true → 1`, `false → 0`) before solving, matching MATLAB semantics."
+        },
+        {
+            "question": "How does RunMat handle NaN or Inf values?",
+            "answer": "They propagate through the least-squares solve in the same way as MATLAB. NaNs in the inputs yield NaNs in the output wherever they influence the solution."
+        }
+    ],
+    "links": [
+        {
+            "label": "mtimes",
+            "url": "./mtimes"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        },
+        {
+            "label": "lu",
+            "url": "./lu"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ctranspose",
+            "url": "./ctranspose"
+        },
+        {
+            "label": "dot",
+            "url": "./dot"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "mpower",
+            "url": "./mpower"
+        },
+        {
+            "label": "trace",
+            "url": "./trace"
+        },
+        {
+            "label": "transpose",
+            "url": "./transpose"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/ops/mrdivide.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/ops/mrdivide.rs"
+    },
+    "gpu_residency": "No manual care is required. If both operands already reside on the GPU and the provider supports `mrdivide`, the solve stays on the device. When the provider falls back to the host (the current WGPU implementation), the runtime seamlessly gathers data, executes the solve, and re-uploads the result to keep downstream GPU pipelines working as expected.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active, RunMat first offers the solve to its `mrdivide` hook. The WGPU provider currently downloads the operands to the host, executes the same SVD-based solver used by the CPU implementation, then uploads the result back to the device so residency remains transparent. If no provider is available—or the provider declines the request—RunMat gathers any gpuArray inputs to the host, computes the solution, and returns a host tensor."
+    ],
+    "key": "mrdivide",
+    "slug": "mrdivide",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "ops"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mrdivide.js.map

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

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

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

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

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

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

package/dist/generated/builtins/mtimes.js

@@ -0,0 +1,185 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mtimes",
+    "category": "math/linalg/ops",
+    "keywords": [
+        "mtimes",
+        "matrix multiplication",
+        "linear algebra",
+        "gpu"
+    ],
+    "summary": "Matrix multiplication (A * B) with MATLAB-compatible semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/mtimes.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Dispatches to the active acceleration provider via the matmul hook; otherwise gathers inputs and executes the CPU implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::ops::mtimes::tests",
+        "integration": "builtins::math::linalg::ops::mtimes::tests::mtimes_gpu_roundtrip",
+        "gpu_scalar": "builtins::math::linalg::ops::mtimes::tests::gpu_scalar_matrix_product",
+        "wgpu": "builtins::math::linalg::ops::mtimes::tests::mtimes_wgpu_matches_cpu"
+    },
+    "description": "`mtimes(A, B)` implements MATLAB's matrix multiplication operator (`A * B`). It supports scalars, vectors, matrices, and complex tensors while preserving MATLAB's column-major layout and dimension rules.",
+    "behaviors": [
+        "The inner dimensions must match: `size(A, 2) == size(B, 1)` for 2-D arrays. N-D tensors flatten the leading two dimensions into a matrix slice so MATLAB-style broadcasting semantics stay intact.",
+        "Row vectors (`1×N`) times column vectors (`N×1`) evaluate to a scalar; column-by-row produces the familiar outer product (`N×1` · `1×M` → `N×M`).",
+        "Scalars multiply every element of the other operand without changing shape; logical inputs are first converted to double precision (`true → 1`, `false → 0`).",
+        "Complex scalars, matrices, and tensors use full complex arithmetic, including real/complex mixes that promote the result to a complex tensor when necessary.",
+        "Empty matrices follow MATLAB semantics: multiplying an `m×0` by `0×n` yields an `m×n` zero matrix and any mismatch in inner dimensions raises `Inner matrix dimensions must agree`.",
+        "When either input is GPU-resident, RunMat consults the active acceleration provider; if its `matmul` hook supports the operands the computation stays on device, otherwise the runtime gathers inputs and executes the CPU fallback transparently."
+    ],
+    "examples": [
+        {
+            "description": "Multiply two 2-D matrices",
+            "input": "A = [1 2 3; 4 5 6];\nB = [7 8; 9 10; 11 12];\nC = A * B",
+            "output": "C = [58 64; 139 154]"
+        },
+        {
+            "description": "Compute a dot product with row and column vectors",
+            "input": "u = [1 2 3];\nv = [4; 5; 6];\ndotVal = u * v",
+            "output": "dotVal = 32"
+        },
+        {
+            "description": "Scale a matrix by a scalar using `mtimes`",
+            "input": "S = 0.5 * eye(3)",
+            "output": "S =\n    0.5000         0         0\n         0    0.5000         0\n         0         0    0.5000"
+        },
+        {
+            "description": "Multiply complex matrices",
+            "input": "A = [1+2i 3-4i; 5+6i 7+8i];\nB = [1-1i; 2+2i];\nC = A * B",
+            "output": "C =\n   17 - 1i\n    9 + 31i"
+        },
+        {
+            "description": "Perform matrix multiplication on GPU arrays",
+            "input": "G1 = gpuArray([1 2; 3 4]);\nG2 = gpuArray([5; 6]);\nG = G1 * G2;\nresult = gather(G)",
+            "output": "isa(G, 'gpuArray')   % logical 1\n\nresult =\n    17\n    39"
+        },
+        {
+            "description": "Dimension mismatch raises a MATLAB-style error",
+            "input": "A = rand(2, 3);\nB = rand(4, 2);\nC = A * B",
+            "output": "Error using  *\nInner matrix dimensions must agree."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `mtimes` different from `times` (`.*`)?",
+            "answer": "`mtimes` performs matrix multiplication (dot products, GEMM). Use `.*` for element-wise products with implicit expansion."
+        },
+        {
+            "question": "What happens when inner dimensions do not match?",
+            "answer": "RunMat raises `Inner matrix dimensions must agree`, matching MATLAB's error identifier and message."
+        },
+        {
+            "question": "Does `mtimes` support scalars and matrices together?",
+            "answer": "Yes. Scalars multiply every element of the matrix, returning a matrix of the same size."
+        },
+        {
+            "question": "Are complex numbers fully supported?",
+            "answer": "Yes. Mixed real/complex operands produce complex outputs using MATLAB's arithmetic rules."
+        },
+        {
+            "question": "Will results stay on the GPU?",
+            "answer": "When a provider implements `matmul`, results remain device-resident. Otherwise RunMat gathers data, computes on the CPU, and returns a host tensor."
+        },
+        {
+            "question": "Do vectors need to be explicitly shaped?",
+            "answer": "Like MATLAB, row vectors must be `1×N` and column vectors `N×1`. Use `.'` or `(:)` to reshape when needed."
+        },
+        {
+            "question": "Does RunMat use BLAS?",
+            "answer": "Yes. The host implementation uses RunMat's optimized inner loops today and will leverage BLAS/LAPACK when the optional feature is enabled."
+        },
+        {
+            "question": "Can `mtimes` fuse with other GPU ops?",
+            "answer": "Providers may fuse GEMM with adjacent operations; otherwise fusion falls back to the standard kernels."
+        }
+    ],
+    "links": [
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        },
+        {
+            "label": "ones",
+            "url": "./ones"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ctranspose",
+            "url": "./ctranspose"
+        },
+        {
+            "label": "dot",
+            "url": "./dot"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "mpower",
+            "url": "./mpower"
+        },
+        {
+            "label": "mrdivide",
+            "url": "./mrdivide"
+        },
+        {
+            "label": "trace",
+            "url": "./trace"
+        },
+        {
+            "label": "transpose",
+            "url": "./transpose"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/ops/mtimes.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/ops/mtimes.rs"
+    },
+    "gpu_residency": "When both operands already live on the GPU, the provider keeps intermediate buffers and the final result on the device. If RunMat needs to fall back to the CPU it gathers any gpuArray inputs, performs the multiplication, and returns a host tensor—apply `gpuArray` to the result if subsequent steps must stay on the device. Auto-offload heuristics will continue to expand, so explicit residency control is rarely required.",
+    "gpu_behavior": [
+        "1. The native auto-offload planner checks the active acceleration provider. When a backend with a `matmul` hook (for example, the WGPU provider) is registered, RunMat dispatches the operation there, keeping gpuArray inputs and the result resident on the device. 2. Mixed-residency calls automatically upload host tensors to the provider before invoking `matmul`, while pure scalar operands use the provider's `scalar_mul` hook to avoid unnecessary transfers. 3. If no GPU provider is registered or the backend declines the request (unsupported precision, shape, or size), RunMat gathers any gpuArray inputs, executes the CPU fallback in this module, and returns a host tensor. Reapply `gpuArray` if you need the result back on the device."
+    ],
+    "key": "mtimes",
+    "slug": "mtimes",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "ops"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mtimes.js.map

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

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

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

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

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

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

package/dist/generated/builtins/ndims.js

@@ -0,0 +1,149 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ndims",
+    "category": "array/introspection",
+    "keywords": [
+        "ndims",
+        "number of dimensions",
+        "array rank",
+        "gpu metadata",
+        "MATLAB compatibility"
+    ],
+    "summary": "Return the number of dimensions of scalars, vectors, matrices, and N-D arrays.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Reads tensor metadata from handles; falls back to host when provider metadata is missing."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::introspection::ndims::tests",
+        "integration": "builtins::array::introspection::ndims::tests::ndims_gpu_tensor_reads_shape"
+    },
+    "description": "`ndims(A)` returns the number of dimensions (rank) of `A`, following MATLAB conventions. Scalars, vectors, matrices, and N-D tensors always report at least two dimensions; higher-rank arrays report their full dimension count. This behaviour matches MathWorks MATLAB for numeric, logical, char, string, cell, struct, and GPU arrays.",
+    "behaviors": [
+        "Scalars and vectors return `2`, because MATLAB treats them as `1×1` or `1×N`.",
+        "Matrices return `2` unless they have trailing dimensions beyond the second.",
+        "N-D arrays return the length of their dimension vector after trailing singleton dimensions are preserved.",
+        "Character arrays, string arrays, logical arrays, complex arrays, and cell arrays all follow their MATLAB array shape metadata.",
+        "GPU tensors report their rank without gathering when the provider populates shape metadata on the handle. When metadata is missing, RunMat downloads the tensor once to preserve correctness.",
+        "Objects, scalars, and other non-array values return `2`, consistent with MATLAB's scalar rules."
+    ],
+    "examples": [
+        {
+            "description": "Checking how many dimensions a scalar has",
+            "input": "n = ndims(42)",
+            "output": "n = 2"
+        },
+        {
+            "description": "Counting the dimensions of a matrix",
+            "input": "A = rand(5, 3);\nr = ndims(A)",
+            "output": "r = 2"
+        },
+        {
+            "description": "Detecting 3-D array dimensionality",
+            "input": "V = rand(4, 5, 6);\nr = ndims(V)",
+            "output": "r = 3"
+        },
+        {
+            "description": "Finding ndims for gpuArray data without gathering",
+            "input": "G = gpuArray(ones(16, 32, 2));\nr = ndims(G)",
+            "output": "r = 3"
+        },
+        {
+            "description": "Understanding ndims with cell arrays",
+            "input": "C = {1, 2, 3; 4, 5, 6};\nr = ndims(C)",
+            "output": "r = 2"
+        },
+        {
+            "description": "Verifying ndims on string arrays",
+            "input": "S = [\"alpha\"; \"beta\"; \"gamma\"];\nr = ndims(S)",
+            "output": "r = 2"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why does `ndims` return 2 for scalars and vectors?",
+            "answer": "MATLAB treats scalars and vectors as 2-D arrays (`1×1` or `1×N`). RunMat mirrors this behaviour, so `ndims(5)` and `ndims([1 2 3])` both return `2`."
+        },
+        {
+            "question": "Does `ndims` ignore trailing singleton dimensions?",
+            "answer": "No. MATLAB preserves trailing singletons when reporting the rank. If your tensor was explicitly created with size `10×1×1×4`, `ndims` returns `4`."
+        },
+        {
+            "question": "How does `ndims` behave for GPU tensors?",
+            "answer": "The runtime inspects shape metadata stored in the GPU tensor handle. When the provider populates that field, no gathering occurs. If metadata is absent, RunMat downloads the tensor to keep the answer correct."
+        },
+        {
+            "question": "Can I call `ndims` on cell arrays and structs?",
+            "answer": "Yes. `ndims` inspects the MATLAB array shape of the container, so cell arrays and struct arrays report their grid dimensions."
+        },
+        {
+            "question": "What about objects or scalars like strings and logical values?",
+            "answer": "Objects and scalar values follow MATLAB scalar rules and return `2`. Use specialised functions (like `isobject`) when you need more information about their type."
+        },
+        {
+            "question": "Does `ndims` participate in GPU fusion?",
+            "answer": "No. `ndims` returns a host scalar immediately and performs no computation on the GPU. It is safe to use inside expressions that also run on the GPU because it does not allocate device memory."
+        }
+    ],
+    "links": [
+        {
+            "label": "size",
+            "url": "./size"
+        },
+        {
+            "label": "length",
+            "url": "./length"
+        },
+        {
+            "label": "numel",
+            "url": "./numel"
+        },
+        {
+            "label": "ndims",
+            "url": "./ndims"
+        },
+        {
+            "label": "isempty",
+            "url": "./isempty"
+        },
+        {
+            "label": "ismatrix",
+            "url": "./ismatrix"
+        },
+        {
+            "label": "isscalar",
+            "url": "./isscalar"
+        },
+        {
+            "label": "isvector",
+            "url": "./isvector"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/introspection/ndims.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/introspection/ndims.rs"
+    },
+    "gpu_behavior": [
+        "`ndims` is a metadata query. When the input resides on the GPU, RunMat inspects the shape stored in `GpuTensorHandle.shape`. No kernels are launched, no buffers are allocated, and residency is not altered. If a provider leaves the shape empty, the runtime downloads the tensor a single time to reconstruct its dimensions before returning a host scalar. The builtin therefore preserves fusion pipelines while still providing MATLAB-compatible answers."
+    ],
+    "key": "ndims",
+    "slug": "ndims",
+    "categoryPath": [
+        "array",
+        "introspection"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ndims.js.map

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

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

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

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

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

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