runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/jsondecode.js

@@ -0,0 +1,159 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "jsondecode",
+    "category": "io/json",
+    "keywords": [
+        "jsondecode",
+        "json",
+        "parse json",
+        "struct from json",
+        "gpu gather"
+    ],
+    "summary": "Parse UTF-8 JSON text into MATLAB-compatible RunMat values.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/jsondecode.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "jsondecode gathers GPU-resident text operands to host memory before parsing and executes entirely on the CPU."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::json::jsondecode::tests",
+        "integration": [
+            "builtins::io::json::jsondecode::tests::jsondecode_matrix_to_tensor",
+            "builtins::io::json::jsondecode::tests::jsondecode_object_to_struct",
+            "builtins::io::json::jsondecode::tests::jsondecode_string_array",
+            "builtins::io::json::jsondecode::tests::jsondecode_mixed_array_returns_cell",
+            "builtins::io::json::jsondecode::tests::jsondecode_rectangular_cell_array_preserves_layout",
+            "builtins::io::json::jsondecode::tests::jsondecode_array_of_objects_returns_cell",
+            "builtins::io::json::jsondecode::tests::jsondecode_null_returns_empty_double",
+            "builtins::io::json::jsondecode::tests::jsondecode_round_trip_with_jsonencode"
+        ]
+    },
+    "description": "`jsondecode` converts UTF-8 JSON text into MATLAB-compatible data. Numbers become doubles, logicals become `logical`, character vectors become char arrays, objects become structs, and arrays expand to numeric/logical/string arrays when rectangular or cell arrays when heterogeneous.",
+    "behaviors": [
+        "Accepts a character vector or string scalar containing UTF-8 JSON data; leading and trailing whitespace is ignored.",
+        "JSON numbers decode to double-precision scalars or dense tensors that follow MATLAB's column-major layout.",
+        "JSON booleans decode to logical scalars or logical arrays with the same shape as the source JSON array.",
+        "JSON strings decode to char row vectors; homogeneous JSON arrays of strings become string arrays with matching dimensions.",
+        "JSON objects decode to scalar structs whose field names match the JSON keys; arrays of objects become cell arrays of structs that preserve element order.",
+        "JSON arrays decode to numeric, logical, or string arrays when every element shares the same type and the array is perfectly rectangular. Rectangular heterogeneous arrays (including those that mix `null` with other types) become cell arrays that preserve the original row/column layout, while irregular arrays fall back to 1-by-N cell vectors that keep element order.",
+        "JSON `null` decodes to the empty double `[]`. When it appears inside a heterogeneous array it becomes a cell element containing `[]`.",
+        "Invalid JSON raises `jsondecode: invalid JSON text (...)` with the underlying parser message."
+    ],
+    "examples": [
+        {
+            "description": "Parsing a scalar number",
+            "input": "value = jsondecode(\"42\")",
+            "output": "value = 42"
+        },
+        {
+            "description": "Decoding a matrix of doubles",
+            "input": "text = \"[[1,2,3],[4,5,6]]\";\nmatrix = jsondecode(text)",
+            "output": "matrix =\n     1     2     3\n     4     5     6"
+        },
+        {
+            "description": "Converting a JSON object into a struct",
+            "input": "person = jsondecode('{\"name\":\"Ada\",\"age\":37}');\ndisp(person.name);\ndisp(person.age)",
+            "output": "Ada\n    37"
+        },
+        {
+            "description": "Decoding an array of objects into a cell array",
+            "input": "text = '[{\"name\":\"Ada\",\"role\":\"Researcher\"},{\"name\":\"Grace\",\"role\":\"Engineer\"}]';\npeople = jsondecode(text);\npeople{1}.name\npeople{2}.role",
+            "output": "people =\n  1x2 cell array\n    {1x1 struct}    {1x1 struct}\n\nans = 'Ada'\nans = 'Engineer'"
+        },
+        {
+            "description": "Handling heterogeneous arrays with cell arrays",
+            "input": "text = '[\"RunMat\", 42, true]';\ndata = jsondecode(text)",
+            "output": "data =\n  1x3 cell array\n    {\"RunMat\"}    {[42]}    {[1]}"
+        },
+        {
+            "description": "Working with null and empty JSON values",
+            "input": "value = jsondecode(\"null\");\ndisp(value);\nisempty(value)",
+            "output": "[]\nans = logical 1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What encodings does `jsondecode` support?",
+            "answer": "JSON text must be UTF-8. RunMat preserves surrogate pairs and Unicode code points exactly as provided."
+        },
+        {
+            "question": "How are JSON objects represented?",
+            "answer": "As scalar structs. Array-of-object JSON values become cell arrays of structs to preserve ordering."
+        },
+        {
+            "question": "What happens with JSON numbers that overflow double?",
+            "answer": "Values must fit in the IEEE-754 double range. When a literal exceeds that range, the parser reports `number out of range`, which surfaces as a `jsondecode: invalid JSON text (...)` error."
+        },
+        {
+            "question": "Does `jsondecode` support comments or trailing commas?",
+            "answer": "No. The JSON must adhere to RFC 8259. The builtin reports an error when encountering comments or other non-standard extensions."
+        },
+        {
+            "question": "How are JSON arrays of strings represented?",
+            "answer": "Rectangular arrays of strings become `string` arrays. Mixed content falls back to cell arrays."
+        },
+        {
+            "question": "How does `jsondecode` treat `null`?",
+            "answer": "`null` decodes to the empty double `[]`. When it appears inside an otherwise homogeneous numeric array, the array is promoted to a cell array so that the `[]` value can be preserved alongside other elements."
+        },
+        {
+            "question": "Can I decode deeply nested arrays?",
+            "answer": "Yes. Rectangular arrays of numbers, logicals, or strings produce dense tensors/string arrays with the appropriate dimensionality. Irregular arrays return nested cell arrays."
+        },
+        {
+            "question": "What if the input is not valid JSON?",
+            "answer": "The builtin raises `jsondecode: invalid JSON text (...)` with the parser error message."
+        },
+        {
+            "question": "Does whitespace or newlines matter?",
+            "answer": "Leading and trailing whitespace is ignored, and embedded newlines are permitted as long as the text remains valid JSON."
+        }
+    ],
+    "links": [
+        {
+            "label": "jsonencode",
+            "url": "./jsonencode"
+        },
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "cell",
+            "url": "./cell"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/json/jsondecode.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/json/jsondecode.rs"
+    },
+    "gpu_residency": "You rarely need to manage residency manually. The auto-offload planner gathers GPU-resident text for `jsondecode` automatically. For MATLAB compatibility, you can still call `gather` yourself, but it is not required, and fusion graphs terminate at `jsondecode` so downstream results always live on the host.",
+    "gpu_behavior": [
+        "`jsondecode` does not execute on the GPU. Because the builtin registers as `accel = \"sink\"` and uses `ResidencyPolicy::GatherImmediately`, any `gpuArray` input is synchronously gathered to host memory through the active provider before parsing. Providers do not expose specialised hooks for JSON parsing, so all work stays on the CPU."
+    ],
+    "key": "jsondecode",
+    "slug": "jsondecode",
+    "categoryPath": [
+        "io",
+        "json"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=jsondecode.js.map

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

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

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

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

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

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

package/dist/generated/builtins/jsonencode.js

@@ -0,0 +1,173 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "jsonencode",
+    "category": "io/json",
+    "keywords": [
+        "jsonencode",
+        "json",
+        "serialization",
+        "struct to json",
+        "pretty print json",
+        "gpu gather"
+    ],
+    "summary": "Serialize MATLAB values to UTF-8 JSON text with MATLAB-compatible defaults.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/jsonencode.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "jsonencode gathers GPU-resident data to host memory before serialisation and executes entirely on the CPU."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::json::jsonencode::tests",
+        "integration": [
+            "builtins::io::json::jsonencode::tests::jsonencode_struct_round_trip",
+            "builtins::io::json::jsonencode::tests::jsonencode_gpu_tensor_gathers_host_data",
+            "builtins::io::json::jsonencode::tests::jsonencode_struct_options_enable_pretty_print",
+            "builtins::io::json::jsonencode::tests::jsonencode_convert_inf_and_nan_controls_null_output",
+            "builtins::io::json::jsonencode::tests::jsonencode_char_array_zero_rows_is_empty_array",
+            "builtins::io::json::jsonencode::tests::jsonencode_gpu_tensor_wgpu_gathers_host_data"
+        ]
+    },
+    "description": "Convert `NaN`, `Inf`, `-Inf` to `null`. Set `false` to raise an error when these values are encountered.",
+    "behaviors": [
+        "Returns a 1×N character array containing UTF-8 encoded JSON text.",
+        "Numeric and logical arrays become JSON arrays, preserving MATLAB column-major ordering.",
+        "Scalars encode as bare numbers/strings rather than single-element arrays.",
+        "Struct scalars become JSON objects; struct arrays become JSON arrays of objects.",
+        "Cell arrays map to JSON arrays, with nested arrays when the cell is 2-D.",
+        "String arrays and char arrays become JSON strings (1 element) or arrays of strings (multiple rows).",
+        "By default, `NaN`, `Inf`, and `-Inf` values encode as `null`. Set `'ConvertInfAndNaN'` to `false` to raise an error instead.",
+        "Pretty printing is disabled by default; enable it with the `'PrettyPrint'` option.",
+        "Inputs that reside on the GPU are gathered back to host memory automatically."
+    ],
+    "examples": [
+        {
+            "description": "Converting a MATLAB struct to JSON",
+            "input": "person = struct('name', 'Ada', 'age', 37);\nencoded = jsonencode(person)",
+            "output": "encoded = '{\"age\":37,\"name\":\"Ada\"}'"
+        },
+        {
+            "description": "Serialising a matrix with pretty printing",
+            "input": "A = magic(3);\nencoded = jsonencode(A, 'PrettyPrint', true)",
+            "output": "encoded =\n'[\n    [8,1,6],\n    [3,5,7],\n    [4,9,2]\n]'"
+        },
+        {
+            "description": "Encoding nested cell arrays",
+            "input": "C = {struct('task','encode','ok',true), {'nested', 42}};\nencoded = jsonencode(C)",
+            "output": "encoded = '[{\"ok\":true,\"task\":\"encode\"},[\"nested\",42]]'"
+        },
+        {
+            "description": "Handling NaN and Inf values",
+            "input": "data = [1 NaN Inf];\nencoded = jsonencode(data)",
+            "output": "encoded = '[1,null,null]'"
+        },
+        {
+            "description": "Rejecting NaN when ConvertInfAndNaN is false",
+            "input": "try\n    jsonencode(data, 'ConvertInfAndNaN', false);\ncatch err\n    disp(err.message);\nend",
+            "output": "jsonencode: ConvertInfAndNaN must be true to encode NaN or Inf values"
+        },
+        {
+            "description": "Serialising GPU-resident tensors",
+            "input": "G = gpuArray(eye(2));\nencoded = jsonencode(G)",
+            "output": "encoded = '[[1,0],[0,1]]'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What MATLAB types does `jsonencode` support?",
+            "answer": "Numeric, logical, string, char, struct, cell, and table-like structs are supported. Unsupported types such as function handles or opaque objects raise an error."
+        },
+        {
+            "question": "Why are my field names sorted alphabetically?",
+            "answer": "RunMat sorts struct field names to produce deterministic JSON (matching MATLAB when fields are stored as scalar structs)."
+        },
+        {
+            "question": "How are complex numbers encoded?",
+            "answer": "Complex scalars become objects with `real` and `imag` fields. Complex arrays become arrays of those objects, mirroring MATLAB."
+        },
+        {
+            "question": "Does `jsonencode` return a character array or string?",
+            "answer": "It returns a row character array (`char`) for MATLAB compatibility. Use `string(jsonencode(x))` if you prefer string scalars."
+        },
+        {
+            "question": "Can I pretty-print nested structures?",
+            "answer": "Yes. Pass `'PrettyPrint', true` to `jsonencode`. Indentation uses four spaces per nesting level, just like MATLAB's pretty-print mode."
+        },
+        {
+            "question": "How are empty arrays encoded?",
+            "answer": "Empty numeric, logical, char, and string arrays become `[]`. Empty structs become `{}` if scalar, or `[]` if they are empty arrays of structs."
+        },
+        {
+            "question": "Does `jsonencode` preserve MATLAB column-major ordering?",
+            "answer": "Yes. Arrays are emitted in MATLAB's logical row/column order, so reshaping on decode reproduces the original layout."
+        },
+        {
+            "question": "What happens when ConvertInfAndNaN is false?",
+            "answer": "Encountering `NaN`, `Inf`, or `-Inf` raises `jsonencode: ConvertInfAndNaN must be true to encode NaN or Inf values`."
+        },
+        {
+            "question": "How do I control the newline style?",
+            "answer": "`jsonencode` always emits `\\n` (LF) line endings when `PrettyPrint` is enabled, regardless of platform, matching MATLAB's behaviour."
+        },
+        {
+            "question": "Are Unicode characters escaped?",
+            "answer": "Printable Unicode characters are emitted verbatim. Control characters and quotes are escaped using standard JSON escape sequences."
+        }
+    ],
+    "links": [
+        {
+            "label": "jsondecode",
+            "url": "./jsondecode"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/json/jsonencode.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/json/jsonencode.rs"
+    },
+    "jsonencode_options": [
+        {
+            "name": "PrettyPrint",
+            "type": "logical",
+            "default": "false",
+            "description": "Emit indented, multi-line JSON output."
+        },
+        {
+            "name": "ConvertInfAndNaN",
+            "type": "logical",
+            "default": "true",
+            "description": "Convert `NaN`, `Inf`, `-Inf` to `null`. Set `false` to raise an error when these values are encountered."
+        }
+    ],
+    "gpu_residency": "For most workflows you do not need to call `gpuArray` explicitly before using `jsonencode`. The auto-offload planner and fusion system keep track of residency, so any GPU-backed tensors that flow into `jsonencode` are gathered automatically as part of this sink operation. If you prefer to control residency manually—or need MATLAB parity—you can still wrap data with `gpuArray` and call `gather` explicitly before serialising.",
+    "gpu_behavior": [
+        "`jsonencode` never launches GPU kernels. When the input contains `gpuArray` data, RunMat gathers those values back to host memory via the active acceleration provider and then serialises on the CPU. If no provider is registered, the builtin propagates the same gather error used by other residency sinks (`gather: no acceleration provider registered`)."
+    ],
+    "key": "jsonencode",
+    "slug": "jsonencode",
+    "categoryPath": [
+        "io",
+        "json"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=jsonencode.js.map

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

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

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

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

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

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

package/dist/generated/builtins/kron.js

@@ -0,0 +1,203 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "kron",
+    "category": "array/shape",
+    "keywords": [
+        "kron",
+        "kronecker product",
+        "tensor product",
+        "block matrix",
+        "gpu"
+    ],
+    "summary": "Compute the Kronecker (tensor) product of two scalars, vectors, matrices, or N-D arrays.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Providers may implement the kron hook to execute entirely on the device; the runtime gathers and evaluates on the host when the hook is missing."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::shape::kron::tests",
+        "integration": "builtins::array::shape::kron::tests::kron_gpu_roundtrip"
+    },
+    "description": "`kron(A, B)` forms the Kronecker (tensor) product of arrays `A` and `B`. Every element of `A` scales a copy of `B`, yielding a block-structured array whose size is `size(A) .* size(B)` when interpreted with MATLAB's column-major ordering.",
+    "behaviors": [
+        "Works with scalars, vectors, matrices, and higher-rank tensors; trailing singleton dimensions are honoured.",
+        "If either input is complex, the output is complex and uses MATLAB's complex arithmetic rules.",
+        "Logical and char inputs are promoted to double precision before multiplication.",
+        "Scalar arguments act as uniform scalars (`kron(a, B)` behaves like `a * B`).",
+        "Empty dimensions propagate; if any replicated dimension is zero, the result is empty along that axis.",
+        "Invalid inputs (non-numeric/non-logical, or values that would overflow the maximum size) raise descriptive MATLAB-style errors."
+    ],
+    "examples": [
+        {
+            "description": "Computing the Kronecker product of two matrices",
+            "input": "A = [1 2; 3 4];\nB = [0 5; 6 7];\nC = kron(A, B)",
+            "output": "C =\n     0     5     0    10\n     6     7    12    14\n     0    15     0    20\n    18    21    24    28"
+        },
+        {
+            "description": "Kronecker product with row and column vectors",
+            "input": "row = [1 2 3];\ncol = (1:3)';\nK = kron(row, col);\nsize(K)",
+            "output": "ans =\n     3     9"
+        },
+        {
+            "description": "Scaling a matrix with a scalar using `kron`",
+            "input": "A = [1 2; 3 4];\nS = kron(2, A)",
+            "output": "S =\n     2     4\n     6     8"
+        },
+        {
+            "description": "Building block-diagonal systems with `kron`",
+            "input": "I = eye(3);\nM = [1 0; 0 -1];\nblockDiag = kron(I, M)"
+        },
+        {
+            "description": "Kronecker product of complex matrices",
+            "input": "A = [1+2i 0; 0 3-1i];\nB = [0 1; 2 3i];\nC = kron(A, B)"
+        },
+        {
+            "description": "Using `kron` with logical masks",
+            "input": "mask = logical([1 0; 0 1]);\ntile = kron(mask, ones(2))"
+        },
+        {
+            "description": "Running `kron` on GPU-resident tensors",
+            "input": "G = gpuArray(rand(2));\nH = gpuArray([1 -1; -1 1]);\nK = kron(G, H);\nisgpuarray(K)",
+            "output": "ans = logical 1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use `kron` instead of standard matrix multiplication?",
+            "answer": "Use `kron` when you need block matrices built from every combination of two operands. Matrix multiplication collapses dimensions, while `kron` expands them."
+        },
+        {
+            "question": "Does `kron` preserve sparsity?",
+            "answer": "The current dense runtime converts inputs to dense double or complex tensors. Sparse fidelity is on the roadmap; today, sparse inputs are first densified."
+        },
+        {
+            "question": "Can I mix real and complex inputs?",
+            "answer": "Yes. If either operand is complex, the output is complex, with MATLAB-compatible real/imaginary components."
+        },
+        {
+            "question": "What happens with logical or boolean inputs?",
+            "answer": "Logical arrays are converted to doubles (0 and 1) before the Kronecker product, mirroring MATLAB's behaviour."
+        },
+        {
+            "question": "Are character arrays supported?",
+            "answer": "Yes. Character arrays are converted to their Unicode code points (double precision) before forming the product."
+        },
+        {
+            "question": "How big can the result be?",
+            "answer": "`kron` checks for overflow when multiplying dimension sizes. If the result would exceed the maximum addressable size, the builtin raises a descriptive error before allocating memory."
+        },
+        {
+            "question": "Does the GPU path always stay on-device?",
+            "answer": "When the provider supplies a `kron` hook, execution stays on-device. Otherwise RunMat gathers to the host, computes the product, and re-uploads the result when a provider is available."
+        }
+    ],
+    "links": [
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "reshape",
+            "url": "./reshape"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cat",
+            "url": "./cat"
+        },
+        {
+            "label": "circshift",
+            "url": "./circshift"
+        },
+        {
+            "label": "diag",
+            "url": "./diag"
+        },
+        {
+            "label": "flip",
+            "url": "./flip"
+        },
+        {
+            "label": "fliplr",
+            "url": "./fliplr"
+        },
+        {
+            "label": "flipud",
+            "url": "./flipud"
+        },
+        {
+            "label": "horzcat",
+            "url": "./horzcat"
+        },
+        {
+            "label": "ipermute",
+            "url": "./ipermute"
+        },
+        {
+            "label": "permute",
+            "url": "./permute"
+        },
+        {
+            "label": "rot90",
+            "url": "./rot90"
+        },
+        {
+            "label": "squeeze",
+            "url": "./squeeze"
+        },
+        {
+            "label": "tril",
+            "url": "./tril"
+        },
+        {
+            "label": "triu",
+            "url": "./triu"
+        },
+        {
+            "label": "vertcat",
+            "url": "./vertcat"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/array/shape/kron.rs",
+        "url": "crates/runmat-runtime/src/builtins/array/shape/kron.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's planner keeps values resident on the GPU whenever it is profitable. Explicit `gpuArray` calls remain supported for MATLAB compatibility and for users who want direct control over residency.",
+    "gpu_behavior": [
+        "When a GPU provider is active, RunMat first consults the provider's `kron` hook so the operation can run entirely on the device. Providers that have not implemented this hook fall back to a safe path: the runtime gathers both operands to host memory, performs the Kronecker product in Rust, and then attempts to upload the result back to the originating device so downstream GPU work can continue without additional copies."
+    ],
+    "key": "kron",
+    "slug": "kron",
+    "categoryPath": [
+        "array",
+        "shape"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=kron.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kron.js","sourceRoot":"","sources":["../../../src/generated/builtins/kron.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,aAAa;IACzB,UAAU,EAAE;QACV,MAAM;QACN,mBAAmB;QACnB,gBAAgB;QAChB,cAAc;QACd,KAAK;KACN;IACD,SAAS,EAAE,0FAA0F;IACrG,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,kJAAkJ;KAC5J;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,qCAAqC;QAC7C,aAAa,EAAE,yDAAyD;KACzE;IACD,aAAa,EAAE,gPAAgP;IAC/P,WAAW,EAAE;QACX,6GAA6G;QAC7G,+FAA+F;QAC/F,iFAAiF;QACjF,8EAA8E;QAC9E,uGAAuG;QACvG,iIAAiI;KAClI;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,iDAAiD;YAChE,OAAO,EAAE,kDAAkD;YAC3D,QAAQ,EAAE,6GAA6G;SACxH;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,6DAA6D;YACtE,QAAQ,EAAE,qBAAqB;SAChC;QACD;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,iCAAiC;YAC1C,QAAQ,EAAE,iCAAiC;SAC5C;QACD;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,uDAAuD;SACjE;QACD;YACE,aAAa,EAAE,uCAAuC;YACtD,OAAO,EAAE,yDAAyD;SACnE;QACD;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,yDAAyD;SACnE;QACD;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,qFAAqF;YAC9F,QAAQ,EAAE,iBAAiB;SAC5B;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,qEAAqE;YACjF,QAAQ,EAAE,8JAA8J;SACzK;QACD;YACE,UAAU,EAAE,gCAAgC;YAC5C,QAAQ,EAAE,4JAA4J;SACvK;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,6GAA6G;SACxH;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,+GAA+G;SAC1H;QACD;YACE,UAAU,EAAE,iCAAiC;YAC7C,QAAQ,EAAE,iHAAiH;SAC5H;QACD;YACE,UAAU,EAAE,4BAA4B;YACxC,QAAQ,EAAE,wLAAwL;SACnM;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,0LAA0L;SACrM;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;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,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;QACD;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,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,wDAAwD;QACjE,KAAK,EAAE,wDAAwD;KAChE;IACD,eAAe,EAAE,mQAAmQ;IACpR,cAAc,EAAE;QACd,yaAAya;KAC1a;IACD,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,cAAc,EAAE;QACd,OAAO;QACP,OAAO;KACR;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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