runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/log1p.js

@@ -0,0 +1,233 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "log1p",
+    "category": "math/elementwise",
+    "keywords": [
+        "log1p",
+        "log(1+x)",
+        "natural logarithm",
+        "elementwise",
+        "gpu",
+        "precision"
+    ],
+    "summary": "Accurate element-wise computation of log(1 + x) for scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host when the provider lacks unary_log1p or reduce_min, or when complex outputs are required."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::log1p::tests",
+        "integration": "builtins::math::elementwise::log1p::tests::log1p_gpu_provider_roundtrip"
+    },
+    "description": "`Y = log1p(X)` evaluates `log(1 + X)` element-wise with high accuracy for values of `X` close to zero. It mirrors MATLAB semantics across scalars, vectors, matrices, logical arrays, character arrays, and complex inputs.",
+    "behaviors": [
+        "Logical inputs are promoted to double precision (`true -> 1.0`, `false -> 0.0`) before execution.",
+        "Character arrays are interpreted as their numeric code points and return dense double tensors.",
+        "Values equal to `-1` yield `-Inf`, matching MATLAB's handling of `log(0)`.",
+        "Inputs smaller than `-1` promote to complex outputs: `log1p(-2)` returns `0 + iπ`.",
+        "Complex inputs follow MATLAB's definition by computing the natural logarithm of `1 + z`.",
+        "Existing GPU tensors remain on the device when the registered provider implements `unary_log1p` alongside `reduce_min`. RunMat queries the device-side minimum to confirm the data stays within the real-valued domain; otherwise it gathers to the host, computes the exact result, and preserves residency metadata."
+    ],
+    "examples": [
+        {
+            "description": "Protecting precision when adding tiny percentages",
+            "input": "delta = 1e-12;\nvalue = log1p(delta)",
+            "output": "value = 9.999999999995e-13"
+        },
+        {
+            "description": "Computing log-growth factors from percentage changes",
+            "input": "rates = [-0.25 -0.10 0 0.10 0.25];\ngrowth = log1p(rates)",
+            "output": "growth = [-0.2877 -0.1054 0 0.0953 0.2231]"
+        },
+        {
+            "description": "Handling the branch cut at x = -1",
+            "input": "y = log1p(-1)",
+            "output": "y = -Inf"
+        },
+        {
+            "description": "Obtaining complex results for inputs less than -1",
+            "input": "data = [-2 -3 -5];\nresult = log1p(data)",
+            "output": "result = [0.0000 + 3.1416i, 0.6931 + 3.1416i, 1.3863 + 3.1416i]"
+        },
+        {
+            "description": "Executing log1p on GPU arrays with automatic residency",
+            "input": "G = gpuArray(linspace(-0.5, 0.5, 5));\nout = log1p(G);\nrealResult = gather(out)",
+            "output": "realResult = [-0.6931 -0.2877 0 0.2231 0.4055]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I prefer `log1p` over `log(1 + x)`?",
+            "answer": "Use `log1p` whenever `x` can be very close to zero. It avoids catastrophic cancellation and matches MATLAB's high-accuracy results for tiny magnitudes."
+        },
+        {
+            "question": "Does `log1p` change my tensor's shape?",
+            "answer": "No. The output has the same shape as the input, subject to MATLAB broadcasting semantics."
+        },
+        {
+            "question": "How are logical arrays handled?",
+            "answer": "Logical values convert to doubles before applying `log1p`, so `log1p([true false])` yields a double array `[log(2), 0]`."
+        },
+        {
+            "question": "What about inputs smaller than `-1`?",
+            "answer": "Values less than `-1` promote to complex results (`log(1 + x)` on the complex branch), matching MATLAB's behavior."
+        },
+        {
+            "question": "How does `log1p` interact with complex numbers?",
+            "answer": "Complex scalars and tensors compute `log(1 + z)` using the principal branch, returning both real and imaginary parts just like MATLAB."
+        },
+        {
+            "question": "What happens when the GPU provider lacks `unary_log1p`?",
+            "answer": "RunMat gathers the tensor to the host, computes the result in double precision, and returns it. This ensures users always see MATLAB-compatible behavior without manual residency management."
+        },
+        {
+            "question": "Is double precision guaranteed?",
+            "answer": "Yes. RunMat stores dense numeric tensors in double precision (`f64`). GPU providers may choose single precision internally but convert back to double when returning data to the runtime."
+        },
+        {
+            "question": "Can `log1p` participate in fusion?",
+            "answer": "Yes. The fusion planner recognizes `log1p` as an element-wise op. Providers that support fused kernels can materialize `log(1 + x)` directly in generated WGSL."
+        }
+    ],
+    "links": [
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "sin",
+            "url": "./sin"
+        },
+        {
+            "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": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/log1p.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/log1p.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nG = gpuArray(linspace(-0.5, 0.5, 5));\nout = log1p(G);\nrealResult = gather(out);\n```\n\nExpected output:\n\n```matlab\nrealResult = [-0.6931 -0.2877 0 0.2231 0.4055];\n```",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors resident on the GPU whenever the provider exposes the `unary_log1p` hook together with `reduce_min`. The runtime uses the device-side minimum to ensure that `1 + X` stays non-negative; when complex outputs are required or either hook is missing, RunMat automatically gathers the tensor, computes on the CPU using double precision, and returns the result with the expected MATLAB semantics."
+    ],
+    "key": "log1p",
+    "slug": "log1p",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=log1p.js.map

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

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

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

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

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

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

package/dist/generated/builtins/log2.js

@@ -0,0 +1,226 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "log2",
+    "category": "math/elementwise",
+    "keywords": [
+        "log2",
+        "base-2 logarithm",
+        "elementwise",
+        "gpu",
+        "complex"
+    ],
+    "summary": "Base-2 logarithm of scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host implementation when the provider lacks unary_log2 or when complex results are required."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::log2::tests",
+        "integration": "builtins::math::elementwise::log2::tests::log2_gpu_provider_roundtrip",
+        "gpu": "builtins::math::elementwise::log2::tests::log2_wgpu_matches_cpu_elementwise"
+    },
+    "description": "`Y = log2(X)` computes the base-2 logarithm of every element in `X`, following MATLAB's semantics for real, logical, character, and complex inputs. Negative real values promote to complex results so that `log2(-1)` yields `0 + i·π/ln(2)`.",
+    "behaviors": [
+        "`log2` operates element-wise with MATLAB broadcasting rules.",
+        "Logical inputs convert to doubles (`true → 1.0`, `false → 0.0`) before the logarithm is applied.",
+        "Character arrays are interpreted as their numeric code points and return dense double tensors of the same shape.",
+        "`log2(0)` returns `-Inf`; positive infinity stays `Inf`; `NaN` propagates unchanged.",
+        "Negative real values promote to complex results: `log2([-1 1])` returns `[0 + i·π/ln(2), 0]`.",
+        "Complex inputs follow MATLAB's definition `log2(z) = log(z) / ln(2)` and clamp subnormal imaginary parts to zero for readability."
+    ],
+    "examples": [
+        {
+            "description": "Computing base-2 logarithms of powers of two",
+            "input": "values = [1 2 4 8];\npowers = log2(values)",
+            "output": "powers = [0 1 2 3]"
+        },
+        {
+            "description": "Understanding how `log2` handles zero",
+            "input": "z = log2(0)",
+            "output": "z = -Inf"
+        },
+        {
+            "description": "Working with negative inputs using complex results",
+            "input": "neg = [-1 -2];\nout = log2(neg)",
+            "output": "out = [0.0000 + 4.5324i  1.0000 + 4.5324i]"
+        },
+        {
+            "description": "Checking power-of-two exponents for matrix sizes",
+            "input": "A = [64 128; 256 512];\nexponents = log2(A)",
+            "output": "exponents = [6 7; 8 9]"
+        },
+        {
+            "description": "Running `log2` on GPU-resident data",
+            "input": "G = gpuArray([1 4 16 64]);\nresult = log2(G);\nhost = gather(result)",
+            "output": "host = [0 2 4 6]"
+        },
+        {
+            "description": "Applying `log2` to character codes",
+            "input": "C = 'ABC';\nvalues = log2(C)",
+            "output": "values = [6.0224 6.0444 6.0661]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use `log2` instead of `log` or `log10`?",
+            "answer": "Use `log2` when you care about binary scalings—such as signal-processing bit widths, FFT sizes, or exponent analysis. Use `log` (natural logarithm) for exponential growth/decay and `log10` for decimal magnitudes."
+        },
+        {
+            "question": "What happens if an element is zero?",
+            "answer": "`log2(0)` returns negative infinity (`-Inf`), matching MATLAB behavior."
+        },
+        {
+            "question": "How does `log2` handle negative real numbers?",
+            "answer": "Negative values promote to complex numbers with an imaginary component of `π/ln(2)`. This preserves phase information instead of producing `NaN`."
+        },
+        {
+            "question": "Can I pass complex inputs to `log2`?",
+            "answer": "Yes. Complex scalars and tensors are handled as `log(z) / ln(2)`, matching MATLAB exactly."
+        },
+        {
+            "question": "Does the GPU implementation support complex outputs?",
+            "answer": "Current providers operate on real buffers. When complex outputs are required, RunMat gathers the tensor to the host while keeping fusion metadata consistent."
+        },
+        {
+            "question": "Is `log2` numerically stable for very small or large values?",
+            "answer": "Yes. The implementation promotes to 64-bit doubles throughout and clamps tiny imaginary parts to zero, mirroring MATLAB's behavior for well-conditioned inputs."
+        }
+    ],
+    "links": [
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        },
+        {
+            "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": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/log2.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/log2.rs"
+    },
+    "gpu_residency": "You typically do **not** need to call `gpuArray` yourself. The auto-offload planner keeps tensors on the GPU when profitable and the result stays real. When complex results are required, RunMat automatically gathers the data to the host to produce the precise MATLAB-compatible answer. Use `gpuArray`/`gather` only when you want to mirror MathWorks MATLAB workflows explicitly.",
+    "gpu_behavior": [
+        "RunMat Accelerate keeps tensors on the GPU when the active provider implements `unary_log2` and the data is known to remain in the real domain. If complex outputs are required (for example, negative inputs) or the provider lacks the hook, RunMat gathers the tensor to the host, computes the exact MATLAB-compatible result, updates residency metadata, and returns the host-resident value."
+    ],
+    "key": "log2",
+    "slug": "log2",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=log2.js.map

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

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

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

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

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

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

package/dist/generated/builtins/logical.js

@@ -0,0 +1,156 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "logical",
+    "category": "logical",
+    "keywords": [
+        "logical",
+        "boolean conversion",
+        "truth mask",
+        "gpuArray",
+        "mask array"
+    ],
+    "summary": "Convert scalars, arrays, and gpuArray values to MATLAB-compatible logical values.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Prefers a device-side elem\\_ne(X, 0) cast when the provider supports elem_ne and zeros_like; otherwise gathers to the host, converts, and re-uploads the logical result."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::logical::ops::tests",
+        "integration": "builtins::logical::ops::tests::logical_gpu_roundtrip"
+    },
+    "description": "`logical(X)` converts numeric, logical, character, and gpuArray inputs into MATLAB logical values (booleans). Any non-zero (or `NaN`/`Inf`) element maps to `true`, while zero maps to `false`. Logical inputs are returned unchanged.",
+    "behaviors": [
+        "`logical` accepts scalars, dense arrays, N-D tensors, and gpuArrays. Shapes are preserved bit-for-bit.",
+        "Non-zero numeric values, `NaN`, and `Inf` map to `true`; `0` and `-0` map to `false`.",
+        "Complex inputs are considered `true` when either the real or imaginary component is non-zero.",
+        "Character arrays are converted elementwise by interpreting code points (so `'A'` becomes `true`, `'\\0'` becomes `false`).",
+        "Strings, structs, cells, objects, and other non-numeric types raise MATLAB-compatible errors (`\"Conversion to logical from <type> is not possible\"`).",
+        "Scalar results become logical scalars (`true`/`false`); higher-rank arrays produce dense logical arrays."
+    ],
+    "examples": [
+        {
+            "description": "Creating a logical mask from numeric data",
+            "input": "values = [0 2 -3 0];\nmask = logical(values)",
+            "output": "mask =\n  1×4 logical array\n     0     1     1     0"
+        },
+        {
+            "description": "Building a logical mask from a matrix",
+            "input": "M = [-4 0 8; 0 1 0];\nmask = logical(M)",
+            "output": "mask =\n  2×3 logical array\n     1     0     1\n     0     1     0"
+        },
+        {
+            "description": "Treating NaN and Inf values as true",
+            "input": "flags = logical([NaN Inf 0])",
+            "output": "flags =\n  1×3 logical array\n     1     1     0"
+        },
+        {
+            "description": "Converting complex numbers to logical scalars",
+            "input": "z = logical(3 + 4i);\nw = logical(0 + 0i)",
+            "output": "z =\n     1\nw =\n     0"
+        },
+        {
+            "description": "Converting character arrays to logical values",
+            "input": "chars = ['A' 0 'C'];\nmask = logical(chars)",
+            "output": "mask =\n  1×3 logical array\n     1     0     1"
+        },
+        {
+            "description": "Keeping gpuArray inputs on the device",
+            "input": "G = gpuArray([0 1 2]);\nmaskGPU = logical(G);\nhostMask = gather(maskGPU)",
+            "output": "hostMask =\n  1×3 logical array\n     0     1     1"
+        },
+        {
+            "description": "Preserving empty shapes through logical conversion",
+            "input": "emptyVec = zeros(0, 3);\nlogicalEmpty = logical(emptyVec)",
+            "output": "logicalEmpty =\n  0×3 logical array\n     []"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which input types does `logical` support?",
+            "answer": "Numeric, logical, complex, character, and gpuArray values are accepted. Strings, structs, cells, objects, and function handles are rejected with MATLAB-compatible error messages."
+        },
+        {
+            "question": "How are NaN or Inf values treated?",
+            "answer": "They evaluate to `true`. MATLAB defines logical conversion as “non-zero”, and `NaN` / `Inf` both satisfy that rule."
+        },
+        {
+            "question": "How does `logical` handle complex numbers?",
+            "answer": "The result is `true` when either the real or imaginary component is non-zero (or `NaN`/`Inf`). Only `0 + 0i` converts to `false`."
+        },
+        {
+            "question": "Does the builtin change array shapes?",
+            "answer": "No. Shapes are preserved exactly, including empty dimensions and higher-rank tensors."
+        },
+        {
+            "question": "What happens to existing logical arrays?",
+            "answer": "They are returned verbatim. Logical gpuArrays remain on the device without triggering new allocations."
+        },
+        {
+            "question": "Can I convert strings with `logical`?",
+            "answer": "No. MATLAB rejects string inputs, and RunMat mirrors that behaviour: `\"logical: conversion to logical from string is not possible\"`."
+        },
+        {
+            "question": "What about structs, cells, or objects?",
+            "answer": "They raise the same conversion error as MATLAB. Use functions like `~cellfun(@isempty, ...)` to derive masks instead."
+        },
+        {
+            "question": "Does the GPU path allocate new buffers?",
+            "answer": "Only when the provider cannot operate in-place. The preferred path performs `elem_ne` against a zero tensor and reuses the resulting buffer. Fallback paths allocate a new gpuArray after gathering to the host."
+        },
+        {
+            "question": "Where can I learn more?",
+            "answer": "See the references below and the RunMat source for implementation details."
+        }
+    ],
+    "links": [
+        {
+            "label": "`islogical`",
+            "url": "./islogical"
+        },
+        {
+            "label": "`gpuArray`",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "`gather`",
+            "url": "./gather"
+        },
+        {
+            "label": "`find`",
+            "url": "./find"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/logical/ops.rs",
+        "url": "crates/runmat-runtime/src/builtins/logical/ops.rs"
+    },
+    "gpu_residency": "You rarely need to call `gpuArray` manually. When the acceleration provider is active, RunMat keeps logical conversions on the GPU by issuing `elem_ne(X, 0)` kernels (backed by `zeros_like` allocations) and flagging the handle as logical metadata. Explicit `gpuArray` calls are available for MATLAB compatibility or when you want to pin residency before interacting with external libraries. When the provider lacks the necessary hook, RunMat documents the fallback: it gathers the data, converts it on the host, and—if a provider is still available—re-uploads the logical mask so downstream GPU code continues to work without residency surprises.",
+    "gpu_behavior": [
+        "When a GPU provider implements `elem_ne` and `zeros_like`, RunMat performs the conversion in-place on the device by evaluating `elem_ne(X, 0)`, then marks the resulting handle as logical so predicates like `islogical` work without downloads.",
+        "If the provider cannot service the request (missing hooks, unsupported dtype, or allocation failure), the value is transparently gathered to the host, converted, and—when a provider is still available—re-uploaded as a logical gpuArray. The fallback is documented so users understand potential host/device transitions.",
+        "Handles that are already flagged as logical (`gpuArray.logical`) are returned without modification.",
+        "Scalars remain scalars: converting a `gpuArray` scalar preserves the residency and returns a logical gpuArray scalar."
+    ],
+    "key": "logical",
+    "slug": "logical",
+    "categoryPath": [
+        "logical"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=logical.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logical.js","sourceRoot":"","sources":["../../../src/generated/builtins/logical.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,SAAS;IACrB,UAAU,EAAE;QACV,SAAS;QACT,oBAAoB;QACpB,YAAY;QACZ,UAAU;QACV,YAAY;KACb;IACD,SAAS,EAAE,mFAAmF;IAC9F,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,2KAA2K;KACrL;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,+BAA+B;QACvC,aAAa,EAAE,sDAAsD;KACtE;IACD,aAAa,EAAE,wOAAwO;IACvP,WAAW,EAAE;QACX,wGAAwG;QACxG,uFAAuF;QACvF,+FAA+F;QAC/F,4HAA4H;QAC5H,yJAAyJ;QACzJ,0GAA0G;KAC3G;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,2CAA2C;YAC1D,OAAO,EAAE,8CAA8C;YACvD,QAAQ,EAAE,uDAAuD;SAClE;QACD;YACE,aAAa,EAAE,uCAAuC;YACtD,OAAO,EAAE,yCAAyC;YAClD,QAAQ,EAAE,qEAAqE;SAChF;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,8BAA8B;YACvC,QAAQ,EAAE,kDAAkD;SAC7D;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,2CAA2C;YACpD,QAAQ,EAAE,0BAA0B;SACrC;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,6CAA6C;YACtD,QAAQ,EAAE,iDAAiD;SAC5D;QACD;YACE,aAAa,EAAE,uCAAuC;YACtD,OAAO,EAAE,2EAA2E;YACpF,QAAQ,EAAE,qDAAqD;SAChE;QACD;YACE,aAAa,EAAE,oDAAoD;YACnE,OAAO,EAAE,2DAA2D;YACpE,QAAQ,EAAE,8CAA8C;SACzD;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,2CAA2C;YACvD,QAAQ,EAAE,oLAAoL;SAC/L;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,qHAAqH;SAChI;QACD;YACE,UAAU,EAAE,4CAA4C;YACxD,QAAQ,EAAE,mIAAmI;SAC9I;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,uFAAuF;SAClG;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,wGAAwG;SACnH;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,wIAAwI;SACnJ;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,uHAAuH;SAClI;QACD;YACE,UAAU,EAAE,yCAAyC;YACrD,QAAQ,EAAE,kNAAkN;SAC7N;QACD;YACE,UAAU,EAAE,yBAAyB;YACrC,QAAQ,EAAE,4EAA4E;SACvF;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,aAAa;YACtB,KAAK,EAAE,aAAa;SACrB;QACD;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,mDAAmD;QAC5D,KAAK,EAAE,mDAAmD;KAC3D;IACD,eAAe,EAAE,woBAAwoB;IACzpB,cAAc,EAAE;QACd,mPAAmP;QACnP,+TAA+T;QAC/T,qGAAqG;QACrG,uHAAuH;KACxH;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,SAAS;KACV;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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