runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/tic.js

@@ -0,0 +1,110 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "tic",
+    "category": "timing",
+    "keywords": [
+        "tic",
+        "timer",
+        "profile",
+        "benchmark",
+        "performance"
+    ],
+    "summary": "Start a high-resolution stopwatch and optionally return a handle for toc.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Stopwatch helpers always run on the host CPU; GPU providers are not consulted."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::timing::tic::tests",
+        "integration": "runmat_runtime::io::tests::test_tic_toc"
+    },
+    "description": "`tic` starts a high-resolution stopwatch. Calls to `toc` report the elapsed time in seconds. When you assign the return value (for example, `t = tic;`), the resulting handle can be passed to `toc(t)` to measure a different code region while keeping the global stopwatch untouched.",
+    "behaviors": [
+        "Uses the host's monotonic clock for nanosecond-resolution timing.",
+        "Supports nested timers: each call pushes a new start time on an internal stack. `toc` without inputs always reads the most recent `tic` and removes it, leaving earlier timers intact so outer scopes continue measuring.",
+        "Returns an opaque scalar handle (a `double`) that encodes the monotonic timestamp. The handle can be stored or passed explicitly to `toc`.",
+        "Executes entirely on the CPU. There are no GPU variants because `tic` interacts with wall-clock state.",
+        "Calling `toc` before `tic` raises the MATLAB-compatible error `RunMat:toc:NoMatchingTic`."
+    ],
+    "examples": [
+        {
+            "description": "Measuring a simple loop",
+            "input": "tic;\nfor k = 1:1e5\n    sqrt(k);\nend\nelapsed = toc"
+        },
+        {
+            "description": "Capturing and reusing the tic handle",
+            "input": "t = tic;\nheavyComputation();\nelapsed = toc(t)"
+        },
+        {
+            "description": "Nesting timers for staged profiling",
+            "input": "tic;              % Outer stopwatch\nstage1();         % Work you want to measure once\ninner = tic;      % Nested stopwatch\nstage2();\ninnerT = toc(inner);  % Elapsed time for stage2 only\nouterT = toc;         % Elapsed time for everything since the first tic"
+        },
+        {
+            "description": "Measuring asynchronous work",
+            "input": "token = tic;\nfuture = backgroundTask();\nwait(future);\nelapsed = toc(token)"
+        },
+        {
+            "description": "Resetting the stopwatch after a measurement",
+            "input": "elapsed1 = toc(tic);  % Equivalent to separate tic/toc calls\npause(0.1);\nelapsed2 = toc(tic);  % Starts a new timer immediately"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `tic` print anything when called without a semicolon?",
+            "answer": "No. `tic` is marked as a sink builtin, so scripts do not display the returned handle unless you assign it or explicitly request output."
+        },
+        {
+            "question": "Is the returned handle portable across sessions?",
+            "answer": "No. The handle encodes a monotonic timestamp that is only meaningful within the current RunMat process. Passing it to another session or saving it to disk is undefined behaviour, matching MATLAB."
+        },
+        {
+            "question": "Can I run `tic` on a worker thread?",
+            "answer": "Yes. Each thread shares the same stopwatch stack. Nested `tic`/`toc` pairs remain well-defined, but you should serialise access at the script level to avoid interleaving unrelated timings."
+        },
+        {
+            "question": "How accurate is the measurement?",
+            "answer": "`tic` relies on a monotonic clock (via `runmat_time::Instant`), typically providing microsecond or better precision. The actual resolution depends on your operating system. There is no artificial jitter or throttling introduced by RunMat."
+        },
+        {
+            "question": "Does `tic` participate in GPU fusion?",
+            "answer": "No. Timer builtins are tagged as CPU-only. Expressions containing `tic` are always executed on the host, and any GPU-resident tensors are gathered automatically by surrounding code when necessary."
+        }
+    ],
+    "links": [
+        {
+            "label": "toc",
+            "url": "./toc"
+        },
+        {
+            "label": "timeit",
+            "url": "./timeit"
+        },
+        {
+            "label": "pause",
+            "url": "./pause"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/timing/tic.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/timing/tic.rs"
+    },
+    "key": "tic",
+    "slug": "tic",
+    "categoryPath": [
+        "timing"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=tic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tic.js","sourceRoot":"","sources":["../../../src/generated/builtins/tic.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE;QACV,KAAK;QACL,OAAO;QACP,SAAS;QACT,WAAW;QACX,aAAa;KACd;IACD,SAAS,EAAE,2EAA2E;IACtF,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,gFAAgF;KAC1F;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,8BAA8B;QACtC,aAAa,EAAE,yCAAyC;KACzD;IACD,aAAa,EAAE,0RAA0R;IACzS,WAAW,EAAE;QACX,mEAAmE;QACnE,2NAA2N;QAC3N,4IAA4I;QAC5I,wGAAwG;QACxG,2FAA2F;KAC5F;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,yBAAyB;YACxC,OAAO,EAAE,uDAAuD;SACjE;QACD;YACE,aAAa,EAAE,sCAAsC;YACrD,OAAO,EAAE,iDAAiD;SAC3D;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,wQAAwQ;SAClR;QACD;YACE,aAAa,EAAE,6BAA6B;YAC5C,OAAO,EAAE,+EAA+E;SACzF;QACD;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,mIAAmI;SAC7I;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,4DAA4D;YACxE,QAAQ,EAAE,yIAAyI;SACpJ;QACD;YACE,UAAU,EAAE,kDAAkD;YAC9D,QAAQ,EAAE,qMAAqM;SAChN;QACD;YACE,UAAU,EAAE,qCAAqC;YACjD,QAAQ,EAAE,8LAA8L;SACzM;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,gPAAgP;SAC3P;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,sMAAsM;SACjN;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,oDAAoD;QAC7D,KAAK,EAAE,iGAAiG;KACzG;IACD,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,cAAc,EAAE;QACd,QAAQ;KACT;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/timeit.js

@@ -0,0 +1,143 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "timeit",
+    "category": "timing",
+    "keywords": [
+        "timeit",
+        "benchmark",
+        "timing",
+        "performance",
+        "gpu"
+    ],
+    "summary": "Measure the execution time of a zero-argument function handle.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs purely on the host CPU; GPU work inside the timed function executes through the active provider."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::timing::timeit::tests",
+        "integration": "builtins::timing::timeit::tests::timeit_measures_time"
+    },
+    "description": "`t = timeit(f)` evaluates the zero-argument function handle `f` repeatedly and returns the median runtime (in seconds). RunMat accepts the optional `numOutputs` argument for MATLAB compatibility; today the handle executes with its default output arity (or none when you pass `0`) and all returned values are discarded.",
+    "behaviors": [
+        "Executes `f` repeatedly, adjusting the inner loop count until a single batch takes at least a few milliseconds or the function is slow enough.",
+        "Collects multiple samples (at least seven batches) and returns the median per-invocation time, which is robust against outliers.",
+        "Drops the outputs produced by `f`; you should perform any validation that depends on those outputs inside the handle. Multi-output dispatch will route through this helper once the runtime exposes multi-return `feval`.",
+        "Leaves GPU residency untouched—if `f` launches GPU kernels, they execute on the active provider. Insert `wait(gpuDevice)` inside the handle if you need explicit synchronisation."
+    ],
+    "examples": [
+        {
+            "description": "Timing a simple anonymous function",
+            "input": "f = @() sin(rand(1000, 1));\nt = timeit(f)"
+        },
+        {
+            "description": "Comparing two implementations",
+            "input": "A = rand(1e5, 1);\nslow = @() sum(A .* A);\nfast = @() sumsq(A);\n\nslowTime = timeit(slow);\nfastTime = timeit(fast)"
+        },
+        {
+            "description": "Timing a function that returns no outputs",
+            "input": "logMessage = @() fprintf(\"Iteration complete\\n\");\nt = timeit(logMessage, 0)"
+        },
+        {
+            "description": "Timing a multiple-output function",
+            "input": "svdTime = timeit(@() svd(rand(256)), 3)"
+        },
+        {
+            "description": "Measuring GPU-bound work",
+            "input": "gfun = @() gather(sin(gpuArray.rand(4096, 1)));\ntgpu = timeit(gfun)"
+        },
+        {
+            "description": "Timing a preallocation helper",
+            "input": "makeMatrix = @() zeros(2048, 2048);\nt = timeit(makeMatrix)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `timeit` return?",
+            "answer": "— A scalar double containing the median runtime per invocation in seconds."
+        },
+        {
+            "question": "How many runs does `timeit` perform?",
+            "answer": "— It automatically selects a loop count so each batch lasts a few milliseconds, collecting at least seven batches."
+        },
+        {
+            "question": "Does `timeit` synchronise GPU kernels?",
+            "answer": "— No. Insert `wait(gpuDevice)` inside the handle when you need explicit synchronisation."
+        },
+        {
+            "question": "Can I time functions that require inputs?",
+            "answer": "— Yes. Capture them in the handle, for example `timeit(@() myfun(A, B))`."
+        },
+        {
+            "question": "How do I time a function with multiple outputs?",
+            "answer": "— Pass `timeit(@() svd(A), 3)` to mirror MATLAB’s call signature. RunMat currently ignores values greater than zero until multi-output dispatch lands, but the handle still executes."
+        },
+        {
+            "question": "Why do successive runs differ slightly?",
+            "answer": "— Normal system jitter, cache effects, and GPU scheduling can change runtimes slightly; the median mitigates outliers."
+        },
+        {
+            "question": "Can `timeit` time scripts?",
+            "answer": "— Wrap the script body in a function handle so it becomes zero-argument, then call `timeit` on that handle."
+        },
+        {
+            "question": "Does `timeit` participate in fusion or JIT tiers?",
+            "answer": "— It simply executes the provided handle; any tiering or fusion happens inside the timed function."
+        },
+        {
+            "question": "What happens if the function errors?",
+            "answer": "— The error is propagated immediately and timing stops, matching MATLAB behaviour."
+        },
+        {
+            "question": "Is there a limit on runs?",
+            "answer": "— Yes. `timeit` caps the inner loop at about one million iterations to avoid runaway measurements."
+        }
+    ],
+    "links": [
+        {
+            "label": "tic",
+            "url": "./tic"
+        },
+        {
+            "label": "toc",
+            "url": "./toc"
+        },
+        {
+            "label": "pause",
+            "url": "./pause"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/timing/timeit.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/timing/timeit.rs"
+    },
+    "syntax": {
+        "example": {
+            "description": "Syntax",
+            "input": "t = timeit(f)\nt = timeit(f, numOutputs)"
+        },
+        "points": [
+            "`f` is a zero-argument function handle (for example, `@() myOp(A)`).",
+            "`numOutputs` is an optional nonnegative integer kept for MATLAB compatibility. Passing `0` suppresses outputs entirely; any other value currently executes the handle with its default output arity while discarding the result."
+        ]
+    },
+    "key": "timeit",
+    "slug": "timeit",
+    "categoryPath": [
+        "timing"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=timeit.js.map

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

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

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

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

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

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

package/dist/generated/builtins/times.js

@@ -0,0 +1,253 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "times",
+    "category": "math/elementwise",
+    "keywords": [
+        "times",
+        "element-wise multiply",
+        ".*",
+        "gpu",
+        "implicit expansion"
+    ],
+    "summary": "Element-wise multiplication A .* B with MATLAB-compatible implicit expansion, complex support, and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/times.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider elem_mul when both operands share a shape, scalar_mul when exactly one operand is a scalar, and gathers to host for implicit expansion or unsupported operand types."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::times::tests::times_scalar_numbers",
+        "integration": "builtins::math::elementwise::times::tests::times_row_column_broadcast",
+        "gpu": "builtins::math::elementwise::times::tests::times_gpu_pair_roundtrip",
+        "wgpu": "builtins::math::elementwise::times::tests::times_wgpu_matches_cpu_elementwise",
+        "like_gpu": "builtins::math::elementwise::times::tests::times_like_gpu_prototype_keeps_residency",
+        "like_host": "builtins::math::elementwise::times::tests::times_like_host_gathers_gpu_value",
+        "like_complex": "builtins::math::elementwise::times::tests::times_like_complex_prototype_yields_complex"
+    },
+    "description": "`times(A, B)` (or the operator form `A .* B`) multiplies corresponding elements of `A` and `B`, honouring MATLAB's implicit expansion rules so that scalars and singleton dimensions broadcast automatically.",
+    "behaviors": [
+        "Supports real, complex, logical, and character inputs; logical and character data are promoted to double precision before multiplication.",
+        "Implicit expansion works across any dimension, provided the non-singleton extents match. Size mismatches raise the standard MATLAB-compatible error.",
+        "Complex operands follow the analytic rule `(a + ib) .* (c + id) = (ac - bd) + i(ad + bc)`.",
+        "Empty dimensions propagate naturally—if either operand has a zero-sized dimension after broadcasting, the result is empty with the broadcasted shape.",
+        "Integer inputs currently promote to double precision, mirroring the behaviour of other RunMat arithmetic builtins.",
+        "The optional `'like'` prototype makes the output adopt the residency (host or GPU) and complexity characteristics of the prototype, which is particularly useful for keeping implicit-expansion expressions on the device."
+    ],
+    "examples": [
+        {
+            "description": "Multiply two matrices element-wise",
+            "input": "A = [1 2 3; 4 5 6];\nB = [7 8 9; 1 2 3];\nP = times(A, B)",
+            "output": "P =\n    7   16   27\n    4   10   18"
+        },
+        {
+            "description": "Scale a matrix by a scalar",
+            "input": "A = magic(3);\nscaled = times(A, 0.5)",
+            "output": "scaled =\n    4.5    0.5    3.5\n    1.5    5.0    9.0\n    8.0    6.5    2.0"
+        },
+        {
+            "description": "Use implicit expansion between a column and row vector",
+            "input": "col = (1:3)';\nrow = [10 20 30];\nm = times(col, row)",
+            "output": "m =\n    10    20    30\n    20    40    60\n    30    60    90"
+        },
+        {
+            "description": "Multiply complex inputs element-wise",
+            "input": "z1 = [1+2i, 3-4i];\nz2 = [2-1i, -1+1i];\nprod = times(z1, z2)",
+            "output": "prod =\n    4 + 3i   1 + 7i"
+        },
+        {
+            "description": "Multiply character codes by a numeric scalar",
+            "input": "letters = 'ABC';\ncodes = times(letters, 2)",
+            "output": "codes = [130 132 134]"
+        },
+        {
+            "description": "Execute `times` directly on gpuArray inputs",
+            "input": "G1 = gpuArray([1 2 3]);\nG2 = gpuArray([4 5 6]);\ndeviceProd = times(G1, G2);\nresult = gather(deviceProd)",
+            "output": "deviceProd =\n  1x3 gpuArray\n     4     10     18\nresult =\n     4    10    18"
+        },
+        {
+            "description": "Keep the result on the GPU with a `'like'` prototype",
+            "input": "proto = gpuArray.zeros(1, 1);\nA = [1 2 3];\nB = [4 5 6];\nC = times(A, B, 'like', proto);  % stays on the GPU for downstream work",
+            "output": "C =\n  1x3 gpuArray\n      4     10     18"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `times` support MATLAB implicit expansion?",
+            "answer": "Yes. Any singleton dimensions expand automatically. If a dimension has incompatible non-singleton extents, `times` raises the standard size-mismatch error."
+        },
+        {
+            "question": "What numeric type does `times` return?",
+            "answer": "Results are double precision for real inputs and complex double when either operand is complex. Logical and character inputs are promoted to double before multiplication."
+        },
+        {
+            "question": "Can I multiply gpuArrays and host scalars?",
+            "answer": "Yes. RunMat keeps the computation on the GPU when the scalar is numeric. For other host operand types, the runtime gathers the gpuArray and computes on the CPU."
+        },
+        {
+            "question": "Does `times` preserve gpuArray residency after a fallback?",
+            "answer": "When a fallback occurs (for example, implicit expansion that the provider does not implement), the current result remains on the host. Subsequent operations may move it back to the GPU when auto-offload decides it is profitable."
+        },
+        {
+            "question": "How can I force the result to stay on the GPU?",
+            "answer": "Provide a `'like'` prototype: `times(A, B, 'like', gpuArray.zeros(1, 1))` keeps the result on the device even if one of the inputs originated on the host."
+        },
+        {
+            "question": "How are empty arrays handled?",
+            "answer": "Empty dimensions propagate. If either operand has an extent of zero in the broadcasted shape, the result is empty with the broadcasted dimensions."
+        },
+        {
+            "question": "Are integer inputs supported?",
+            "answer": "Yes. Integers promote to double precision during the multiplication, matching other RunMat arithmetic builtins."
+        },
+        {
+            "question": "Can I mix complex and real operands?",
+            "answer": "Absolutely. The result is complex, with broadcasting rules identical to MATLAB."
+        },
+        {
+            "question": "What about string arrays?",
+            "answer": "String arrays are not numeric and therefore raise an error when passed to `times`."
+        }
+    ],
+    "links": [
+        {
+            "label": "mtimes",
+            "url": "./mtimes"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/times.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/times.rs"
+    },
+    "gpu_residency": "RunMat's auto-offload planner keeps tensors on the GPU whenever fused expressions benefit from device execution. Explicit `gpuArray` / `gather` calls are still supported for MATLAB code that manages residency manually. When the active provider lacks the kernels needed for a particular call (for example, implicit expansion between gpuArrays of different shapes), RunMat gathers back to the host, computes the MATLAB-accurate result, and resumes execution seamlessly.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active:\n\n1. If both operands are gpuArrays with identical shapes, RunMat dispatches to the provider's `elem_mul` hook. 2. If one operand is a scalar (host or device) and the other is a gpuArray, the runtime calls `scalar_mul` to keep the result on the device. 3. The fusion planner treats `times` as a fusible elementwise node, so adjacent elementwise producers/consumers can execute inside a single WGSL kernel or provider-optimised pipeline, avoiding spurious host↔device transfers. 4. Implicit-expansion workloads (e.g., mixing row and column vectors) or unsupported operand kinds gather transparently to host memory, compute the result with full MATLAB semantics, and return a host tensor. The documentation callouts below flag this fallback behaviour explicitly."
+    ],
+    "key": "times",
+    "slug": "times",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=times.js.map

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

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

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

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

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

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