runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/fullfile.js

@@ -0,0 +1,181 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fullfile",
+    "category": "io/repl_fs",
+    "keywords": [
+        "fullfile",
+        "join paths",
+        "path assembly",
+        "filesystem",
+        "filesep"
+    ],
+    "summary": "Build a platform-correct file path from multiple path segments.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fullfile.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. GPU-resident text inputs are gathered before path assembly."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 16,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::fullfile::tests",
+        "integration": "builtins::io::repl_fs::fullfile::tests::fullfile_joins_segments"
+    },
+    "description": "`fullfile` joins path segments using the platform-specific file separator, producing a single path string that matches MATLAB semantics. It accepts any number of path segments and returns a character row vector (`1xN`).",
+    "behaviors": [
+        "`fullfile(part1, part2, ...)` joins the inputs with the platform file separator (`/` on macOS and Linux, `\\` on Windows).",
+        "Absolute path segments reset the accumulated path, mirroring MATLAB and OS path rules.",
+        "Empty segments are ignored, so `fullfile(\"\", \"data\")` returns `data`.",
+        "Inputs must be character vectors or string scalars. Single-element string arrays are accepted. Other input types raise `fullfile: arguments must be character vectors or string scalars`.",
+        "The output is a character vector. Wrap the result with `string(...)` if you prefer string scalars."
+    ],
+    "examples": [
+        {
+            "description": "Join Relative Path Segments",
+            "input": "p = fullfile(\"data\", \"raw\", \"sample.dat\")",
+            "output": "p =\n    data/raw/sample.dat"
+        },
+        {
+            "description": "Use `fullfile` With `pwd`",
+            "input": "root = pwd;\nconfig = fullfile(root, \"config\", \"settings.json\")",
+            "output": "% Returns a full path rooted at the current working folder"
+        },
+        {
+            "description": "Build A Subfolder Path",
+            "input": "logDir = fullfile(\"logs\", \"2026\");\nstatus = mkdir(logDir)",
+            "output": "status =\n     1"
+        },
+        {
+            "description": "Create A File In A Nested Folder",
+            "input": "mkdir(fullfile(\"data\", \"raw\"));\nfid = fopen(fullfile(\"data\", \"raw\", \"sample.dat\"), \"w\");\nfclose(fid)",
+            "output": "% Creates data/raw/sample.dat"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Why does `fullfile` return a character vector instead of a string?",
+            "answer": "MATLAB returns character vectors for `fullfile`. RunMat mirrors that behavior for compatibility; use `string(fullfile(...))` if you prefer string scalars."
+        },
+        {
+            "question": "Does `fullfile` expand `~` to the home directory?",
+            "answer": "No. `fullfile` performs string assembly only. Use `cd` or filesystem APIs that expand `~` when you need home expansion."
+        },
+        {
+            "question": "What happens if a segment is absolute?",
+            "answer": "Absolute segments reset the accumulated path, matching MATLAB and OS path rules."
+        },
+        {
+            "question": "Can I pass numeric character codes?",
+            "answer": "Yes. Numeric arrays that represent character codes are accepted as long as they form a row vector, just like other RunMat text inputs."
+        },
+        {
+            "question": "Does `fullfile` run on the GPU?",
+            "answer": "No. It is a host-only utility and gathers GPU-resident inputs before processing."
+        }
+    ],
+    "links": [
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "savepath",
+            "url": "./savepath"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/fullfile.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/fullfile.rs"
+    },
+    "gpu_residency": "No. `fullfile` is a host-side path builder. GPU-resident text inputs are gathered automatically, so there is no benefit to keeping path strings on the GPU.",
+    "gpu_behavior": [
+        "`fullfile` performs string manipulation on the CPU only. Any GPU-resident inputs are gathered to the host before path assembly so the resulting character vector is always in CPU memory."
+    ],
+    "key": "fullfile",
+    "slug": "fullfile",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fullfile.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fwrite.js

@@ -0,0 +1,176 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fwrite",
+    "category": "io/filetext",
+    "keywords": [
+        "fwrite",
+        "binary write",
+        "io",
+        "precision",
+        "machine format",
+        "skip"
+    ],
+    "summary": "Write binary data to a file identifier with MATLAB-compatible precision, skip, and machine-format semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fwrite.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. When data or arguments live on the GPU, RunMat gathers them first; providers do not expose file-I/O hooks."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 4,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fwrite::tests",
+        "integration": [
+            "builtins::io::filetext::fwrite::tests::fwrite_double_precision_writes_native_endian",
+            "builtins::io::filetext::fwrite::tests::fwrite_gpu_tensor_gathers_before_write",
+            "builtins::io::filetext::fwrite::tests::fwrite_wgpu_tensor_roundtrip",
+            "builtins::io::filetext::fwrite::tests::fwrite_invalid_precision_errors",
+            "builtins::io::filetext::fwrite::tests::fwrite_negative_skip_errors"
+        ]
+    },
+    "description": "`fwrite` writes binary data to a file identifier obtained from `fopen`. It mirrors MATLAB's handling of precision strings, skip values, and machine-format overrides so existing MATLAB scripts can save data without modification. The builtin accepts numeric tensors, logical data, and character arrays; the bytes are emitted in column-major order to match MATLAB storage.",
+    "behaviors": [
+        "`count = fwrite(fid, A)` converts `A` to unsigned 8-bit integers and writes one byte per element.",
+        "`count = fwrite(fid, A, precision)` converts `A` to the requested precision before writing. Supported precisions are `double`, `single`, `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, and `char`. Shorthand aliases such as `uchar`, `byte`, and `real*8` are also recognised.",
+        "`count = fwrite(fid, A, precision, skip)` skips `skip` bytes after writing each element. RunMat applies the skip with a file seek, which produces sparse regions when the target position moves beyond the current end.",
+        "`count = fwrite(fid, A, precision, skip, machinefmt)` overrides the byte ordering used for the conversion. Supported machine formats are `'native'`, `'ieee-le'`, and `'ieee-be'`. When omitted, the builtin honours the format recorded by `fopen`.",
+        "Column-major ordering matches MATLAB semantics: tensors and character arrays write their first column completely before advancing to the next column. Scalars and vectors behave as 1-by-N matrices.",
+        "The return value `count` is the number of elements written, not the number of bytes. A zero-length input produces `count == 0`.",
+        "RunMat executes `fwrite` entirely on the host. When the data resides on a GPU (`gpuArray`), RunMat gathers the tensor to host memory before writing; providers do not currently implement device-side file I/O."
+    ],
+    "examples": [
+        {
+            "description": "Write unsigned bytes with the default precision",
+            "input": "fid = fopen('bytes.bin', 'w+b');\ncount = fwrite(fid, [1 2 3 255]);\nfclose(fid);\ncount",
+            "output": "count = 4"
+        },
+        {
+            "description": "Write double-precision values",
+            "input": "fid = fopen('values.bin', 'w+b');\ndata = [1.5 -2.25 42.0];\ncount = fwrite(fid, data, 'double');\nfclose(fid);\ncount",
+            "output": "count = 3"
+        },
+        {
+            "description": "Write 16-bit integers using big-endian byte ordering",
+            "input": "fid = fopen('sensor.be', 'w+b', 'ieee-be');\ncount = fwrite(fid, [258 772], 'uint16');\nfclose(fid);\ncount",
+            "output": "count = 2"
+        },
+        {
+            "description": "Insert padding bytes between samples",
+            "input": "fid = fopen('spaced.bin', 'w+b');\ncount = fwrite(fid, [10 20 30], 'uint8', 1);   % skip one byte between elements\nfclose(fid);\ncount",
+            "output": "count = 3"
+        },
+        {
+            "description": "Write character data without manual conversions",
+            "input": "fid = fopen('greeting.txt', 'w+b');\ncount = fwrite(fid, 'RunMat!', 'char');\nfclose(fid);\ncount",
+            "output": "count = 7"
+        },
+        {
+            "description": "Gather GPU data before writing",
+            "input": "fid = fopen('gpu.bin', 'w+b');\nG = gpuArray([1 2 3 4]);\ncount = fwrite(fid, G, 'uint16');\nfclose(fid);\ncount",
+            "output": "count = 4"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What precisions does `fwrite` support?",
+            "answer": "RunMat recognises the commonly used MATLAB precisions: `double`, `single`, `uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, and `char`, along with their documented aliases (`real*8`, `uchar`, etc.). The `precision => output` forms are accepted when both sides match; differing output classes are not implemented yet."
+        },
+        {
+            "question": "How are values converted before writing?",
+            "answer": "Numeric inputs are converted to the requested precision using MATLAB-style rounding (to the nearest integer) with saturation to the target range. Logical inputs map `true` to 1 and `false` to 0. Character inputs use their Unicode scalar values."
+        },
+        {
+            "question": "What does the return value represent?",
+            "answer": "`fwrite` returns the number of elements successfully written, not the total number of bytes. Multiply by the element size when you need to know the byte count."
+        },
+        {
+            "question": "Does `skip` insert bytes into the file?",
+            "answer": "`skip` seeks forward after each element is written. When the seek lands beyond the current end of file, the OS creates a sparse region (holes are zero-filled on most platforms). Use `skip = 0` (the default) to write densely."
+        },
+        {
+            "question": "How do machine formats affect the output?",
+            "answer": "The machine format controls byte ordering for multi-byte precisions. `'native'` uses the host endianness, `'ieee-le'` forces little-endian ordering, and `'ieee-be'` forces big-endian ordering regardless of the host."
+        },
+        {
+            "question": "Can I write directly to standard output?",
+            "answer": "Not yet. File identifiers 0, 1, and 2 (stdin, stdout, stderr) are reserved and raise a descriptive error. Use `fopen` to create a file handle before calling `fwrite`."
+        },
+        {
+            "question": "Are GPU tensors supported?",
+            "answer": "Yes. RunMat gathers GPU tensors to host memory before writing. The gather relies on the active provider; if no provider is registered, an informative error is raised."
+        },
+        {
+            "question": "Do string arrays insert newline characters?",
+            "answer": "RunMat joins string-array elements using newline (`'\\n'`) separators before writing. This mirrors how MATLAB flattens string arrays to character data for binary I/O."
+        },
+        {
+            "question": "What happens with `NaN` or infinite values?",
+            "answer": "`NaN` values map to zero for integer precisions and remain `NaN` for floating-point precisions. Infinite values saturate to the min/max integer representable by the target precision."
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/filetext/fwrite.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/filetext/fwrite.rs"
+    },
+    "gpu_residency": "You rarely need to move data with `gpuArray` purely for `fwrite`. RunMat keeps tensors on the GPU while compute stays in fused expressions, but explicit file I/O always happens on the host. If your data already lives on the device, `fwrite` performs an automatic gather, writes the bytes, and leaves residency unchanged for the rest of the program. You can still call `gpuArray` manually when porting MATLAB code verbatim—the builtin will gather it for you automatically.",
+    "gpu_behavior": [
+        "`fwrite` never launches GPU kernels. If any input value (file identifier, data, or optional arguments) is backed by a GPU tensor, RunMat gathers the value to host memory before performing the write. This mirrors MATLAB's own behaviour when working with `gpuArray` objects: data is moved to the CPU for I/O. When a provider is available, the gather occurs via the provider's `download` path; otherwise the builtin emits an informative error."
+    ],
+    "key": "fwrite",
+    "slug": "fwrite",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fwrite.js.map

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

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

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

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

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

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

package/dist/generated/builtins/gamma.js

@@ -0,0 +1,229 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "gamma",
+    "category": "math/elementwise",
+    "keywords": [
+        "gamma",
+        "factorial",
+        "special function",
+        "elementwise",
+        "gpu",
+        "complex"
+    ],
+    "summary": "Element-wise gamma function for scalars, vectors, matrices, and complex inputs.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses the provider unary_gamma hook (Lanczos approximation on WGPU); falls back to host evaluation when the hook is unavailable."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::gamma::tests",
+        "integration": "builtins::math::elementwise::gamma::tests::gamma_gpu_provider_fallback"
+    },
+    "description": "`Y = gamma(X)` evaluates the Euler gamma function element-by-element. For positive integers the result is `(n-1)!`, half-integers map to scaled square-roots of π, and complex arguments follow the analytic continuation `Γ(z) = ∫_0^∞ t^{z-1} e^{-t} dt`.",
+    "behaviors": [
+        "Respects MATLAB’s broadcasting rules for all dense tensor inputs.",
+        "Promotes logical and integer values to double precision before evaluation; character arrays are converted through their Unicode code points.",
+        "Computes complex values with a Lanczos approximation and the reflection identity so results match MATLAB for every quadrant.",
+        "Returns `Inf` at non-positive integers, mirroring the poles in the analytic definition.",
+        "Keeps real-valued GPU tensors on device when the provider implements `unary_gamma`; otherwise it gathers to the host, evaluates, and reapplies any requested residency via `'like'`."
+    ],
+    "examples": [
+        {
+            "description": "Converting integers to factorials automatically",
+            "input": "gamma(5)",
+            "output": "ans = 24"
+        },
+        {
+            "description": "Evaluating half-integer inputs",
+            "input": "gamma(0.5)",
+            "output": "ans = 1.7725"
+        },
+        {
+            "description": "Handling negative non-integers",
+            "input": "gamma(-0.5)",
+            "output": "ans = -3.5449"
+        },
+        {
+            "description": "Applying gamma element-wise to arrays",
+            "input": "A = [1 2; 3 4];\nB = gamma(A)",
+            "output": "B =\n     1     1\n     2     6"
+        },
+        {
+            "description": "Working with complex numbers",
+            "input": "z = 0.5 + 1i;\ng = gamma(z)",
+            "output": "g = 0.8182 - 0.7633i"
+        },
+        {
+            "description": "Using `gamma` with GPU tensors",
+            "input": "G = gpuArray([0.5 1.5 2.5]);\nout = gamma(G);\nresult = gather(out)",
+            "output": "result = [1.7725 0.8862 1.3293]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `gamma(n)` related to factorials?",
+            "answer": "For positive integers `n`, `gamma(n) = (n-1)!`. This identity underpins the factorial extension used throughout probability, statistics, and combinatorics."
+        },
+        {
+            "question": "What happens at non-positive integers?",
+            "answer": "`gamma` has simple poles at `0, -1, -2, ...`. RunMat mirrors MATLAB by returning `Inf` at those points and signalling the singularity without throwing an error."
+        },
+        {
+            "question": "Are half-integers supported exactly?",
+            "answer": "Yes. Values such as `gamma(0.5) = sqrt(pi)` are computed with a Lanczos approximation that provides double-precision accuracy consistent with MATLAB."
+        },
+        {
+            "question": "Do complex inputs work?",
+            "answer": "Absolutely. RunMat evaluates the analytic continuation using the reflection identity `Γ(z) = π / (sin(πz) Γ(1-z))` for `Re(z) < 0.5`, so complex arguments behave the same as in MATLAB."
+        },
+        {
+            "question": "Can I keep results on the GPU?",
+            "answer": "Yes for real-valued outputs whenever the active provider exposes `unary_gamma` (including the WGPU backend). If the provider lacks the hook, RunMat falls back to the host but re-uploads the tensor when you request a real-valued GPU prototype via `'like'`. Complex outputs stay on the host for now."
+        },
+        {
+            "question": "What about overflow?",
+            "answer": "Large positive inputs eventually overflow to `Inf`, just like MATLAB. Negative inputs near poles produce signed infinities consistent with the analytic behaviour."
+        },
+        {
+            "question": "Does `gamma` accept `'like'` prototypes?",
+            "answer": "Yes. Provide `'like', T` to control residency and numeric class. Complex prototypes are honoured on the host; GPU prototypes must be real."
+        }
+    ],
+    "links": [
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "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": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "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": "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/gamma.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/gamma.rs"
+    },
+    "gpu_residency": "Usually not. Accelerate keeps tensors on the GPU when the provider exposes a `unary_gamma` kernel (the default WGPU backend does). Otherwise RunMat gathers the tensor, evaluates the gamma function on the CPU, and uploads the result again only when you explicitly request GPU residency via `'like', gpuArray(...)`. Complex results remain on the host because today’s GPU providers operate on real buffers.",
+    "gpu_behavior": [
+        "RunMat Accelerate first calls the active provider’s `unary_gamma` hook. With the WGPU backend this kernel runs entirely on device using a Lanczos approximation. Providers that decline the hook trigger an automatic gather to the host. After computing the double-precision result, RunMat re-uploads the tensor when you pass `'like', gpuArray(...)`. Complex outputs always stay on the host because current providers expose real-valued buffers only."
+    ],
+    "key": "gamma",
+    "slug": "gamma",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=gamma.js.map

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

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

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

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

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

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