runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/polyval.js

@@ -0,0 +1,165 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "polyval",
+    "category": "math/poly",
+    "keywords": [
+        "polyval",
+        "polynomial evaluation",
+        "prediction interval",
+        "polyfit",
+        "gpu"
+    ],
+    "summary": "Evaluate a polynomial at given points and optionally compute prediction intervals using polyfit output.",
+    "references": [
+        "title: \"MATLAB polyval documentation\"",
+        "title: \"Numerical Recipes: Polynomial fitting and evaluation\""
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Providers with Horner kernels keep real-valued workloads on the device; complex inputs and prediction intervals fall back to the CPU implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::poly::polyval::tests",
+        "integration": "builtins::math::poly::polyval::tests::polyval_gpu_roundtrip"
+    },
+    "description": "`polyval(p, x)` evaluates the polynomial defined by the coefficient vector `p` at every element of `x`. Coefficients follow MATLAB’s convention: `p(1)` is the highest-order term, `p(end)` is the constant term. Both real and complex inputs are supported, and the output matches the shape of `x`.",
+    "behaviors": [
+        "Accepts scalar, vector, or N-D coefficient inputs that have at most one non-singleton dimension.",
+        "Logical and integer coefficients are promoted to double precision; complex coefficients are kept exactly.",
+        "When `p` and `x` are real-valued and a provider is registered, RunMat issues a Horner-series GPU kernel via RunMat Accelerate. Mixed or complex inputs fall back to the reference CPU implementation, with purely real outputs re-uploaded to the device when residency makes sense.",
+        "`polyval(p, x, [], mu)` applies centering and scaling parameters from `polyfit`, evaluating the polynomial at `(x - mu(1)) / mu(2)`.",
+        "`[y, delta] = polyval(p, x, S, mu)` computes prediction intervals using the structure `S` produced by `polyfit`. RunMat mirrors MATLAB rules: `S` must contain the fields `R`, `normr`, and `df`, and the interval collapses to zeros when `df <= 0` or `normr == 0`.",
+        "Empty inputs yield empty outputs; an empty coefficient vector represents the zero polynomial.",
+        "MATLAB-compatible errors are raised for non-numeric inputs, invalid `mu` vectors, or malformed `S` structures."
+    ],
+    "examples": [
+        {
+            "description": "Evaluating a polynomial at scalar points",
+            "input": "p = [2 -3 5];   % 2x^2 - 3x + 5\ny = polyval(p, 4)",
+            "output": "y = 21"
+        },
+        {
+            "description": "Evaluating across a vector of inputs",
+            "input": "p = [1 0 -2 1];\nx = linspace(-2, 2, 5);\ny = polyval(p, x)",
+            "output": "y = [ -3   2   1   0   5 ]"
+        },
+        {
+            "description": "Evaluating a polynomial over a matrix grid",
+            "input": "[X, Y] = meshgrid(-1:1);\nZ = polyval([1 -3 2], X + Y)",
+            "output": "Z =\n    12     6     2\n     6     2     0\n     2     0     0"
+        },
+        {
+            "description": "Using centering and scaling parameters from `polyfit`",
+            "input": "x = -2:2;\nnoise = 0.05 * randn(size(x));\n[p, S, mu] = polyfit(x, sin(x) + noise, 3);\ny = polyval(p, x, [], mu)",
+            "output": "% y closely matches sin(x) + noise with polynomial smoothing"
+        },
+        {
+            "description": "Computing prediction intervals with polyfit output",
+            "input": "[p, S, mu] = polyfit((0:10)', exp((0:10)'/10), 3);\n[y, delta] = polyval(p, 5, S, mu)",
+            "output": "% y is the fitted value at x = 5\n% delta is the 1σ prediction interval (standard error)"
+        },
+        {
+            "description": "Handling complex coefficients and inputs",
+            "input": "p = [1+2i, -3, 4i];\nz = [-1+1i, 0, 1-2i];\ny = polyval(p, z)",
+            "output": "% Complex results that agree with MATLAB's polyval"
+        },
+        {
+            "description": "Evaluating on a gpuArray input",
+            "input": "x = gpuArray.linspace(-1, 1, 2048);\np = [1 0 1];\ny = polyval(p, x);    % Runs on the GPU for real-valued inputs",
+            "output": "y is a gpuArray because the result is real-valued."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Do coefficients need to be a row vector?",
+            "answer": "No. They can be row or column vectors (or any N-D shape with a single non-singleton dimension). The output always matches the shape of `x`."
+        },
+        {
+            "question": "What kinds of inputs are accepted?",
+            "answer": "Numeric scalars, vectors, matrices, N-D arrays, logical arrays, and complex data are all accepted. Logical and integer inputs are promoted to double precision automatically."
+        },
+        {
+            "question": "How do centering (`mu`) parameters work?",
+            "answer": "RunMat mirrors MATLAB: the polynomial is evaluated at `(x - mu(1)) / mu(2)`. The `mu` vector must contain at least two finite values, and the scale `mu(2)` must be non-zero."
+        },
+        {
+            "question": "Why does `[y, delta] = polyval(...)` require the structure `S`?",
+            "answer": "The prediction interval comes from the QR factorization stored in `S` by `polyfit`. The structure must include the fields `R`, `df`, and `normr`; without them the interval cannot be computed."
+        },
+        {
+            "question": "What happens when `df <= 0` or `normr == 0`?",
+            "answer": "The prediction interval collapses to zeros (RunMat matches MATLAB and Octave here). This typically occurs when the fit is exact or when there are insufficient degrees of freedom."
+        },
+        {
+            "question": "Can I keep results on the GPU?",
+            "answer": "Yes. RunMat re-uploads real-valued results to the active provider after the host evaluation. Complex outputs stay on the host until providers add complex buffer uploads."
+        },
+        {
+            "question": "Does `polyval` support sparse inputs?",
+            "answer": "Not yet. Dense inputs (including gpuArray tensors) are supported today. Sparse support will arrive once RunMat's sparse infrastructure stabilises."
+        }
+    ],
+    "links": [
+        {
+            "label": "polyfit",
+            "url": "./polyfit"
+        },
+        {
+            "label": "conv",
+            "url": "./conv"
+        },
+        {
+            "label": "deconv",
+            "url": "./deconv"
+        },
+        {
+            "label": "polyder",
+            "url": "./polyder"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "polyint",
+            "url": "./polyint"
+        },
+        {
+            "label": "roots",
+            "url": "./roots"
+        }
+    ],
+    "source": {
+        "label": "Open an issue",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "gpu_behavior": [
+        "When a GPU provider is active, RunMat first attempts to evaluate the polynomial in device memory using a dedicated Horner kernel. Coefficients and inputs are uploaded automatically when required. If the call requests complex arithmetic, prediction intervals, or otherwise falls outside the GPU kernel’s contract, RunMat gathers to the host, executes the CPU implementation, and (for real-valued results) pushes the output back to the GPU so downstream kernels retain residency."
+    ],
+    "key": "polyval",
+    "slug": "polyval",
+    "categoryPath": [
+        "math",
+        "poly"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=polyval.js.map

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

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

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

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

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

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

package/dist/generated/builtins/pow2.js

@@ -0,0 +1,231 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pow2",
+    "category": "math/elementwise",
+    "keywords": [
+        "pow2",
+        "ldexp",
+        "binary scaling",
+        "gpu"
+    ],
+    "summary": "Compute 2.^X or scale mantissas by binary exponents with MATLAB-compatible semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/pow2.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "pow2(X) and pow2(F,E) run on the GPU when providers implement unary_pow2 and pow2_scale for matching shapes; other cases fall back to the host automatically."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::pow2::tests",
+        "integration": "builtins::math::elementwise::pow2::tests::pow2_gpu_roundtrip",
+        "gpu": "builtins::math::elementwise::pow2::tests::pow2_wgpu_matches_cpu_unary"
+    },
+    "description": "`Y = pow2(X)` computes the element-wise power-of-two `2.^X`. With two inputs, `Z = pow2(F, E)` returns the element-wise product `F .* 2.^E`, mirroring MATLAB's `ldexp`-style scaling.",
+    "behaviors": [
+        "Accepts scalars, vectors, matrices, and N-D tensors with MATLAB's implicit expansion (broadcasting).",
+        "Logical inputs are promoted to double before applying `2.^X`.",
+        "Character arrays operate on their Unicode code points and return dense double tensors.",
+        "Complex exponents yield complex outputs using the identity `2^z = exp(z * ln(2))`.",
+        "`pow2(F, E)` supports scalar expansion on either argument and raises a dimension mismatch error when expansion is impossible.",
+        "Empty tensors propagate emptiness with the correct MATLAB-visible shape."
+    ],
+    "examples": [
+        {
+            "description": "Compute power-of-two for scalar exponents",
+            "input": "y = pow2(3)",
+            "output": "y = 8"
+        },
+        {
+            "description": "Apply `pow2` to a vector of exponents",
+            "input": "exponents = [-1 0 1 2];\nvalues = pow2(exponents)",
+            "output": "values = [0.5 1 2 4]"
+        },
+        {
+            "description": "Scale mantissas by binary exponents",
+            "input": "mantissa = [0.75 1.5];\nexponent = [4 5];\nscaled = pow2(mantissa, exponent)",
+            "output": "scaled = [12 48]"
+        },
+        {
+            "description": "Use complex exponents with `pow2`",
+            "input": "z = pow2(1 + 2i)",
+            "output": "z = -0.3667 + 0.8894i"
+        },
+        {
+            "description": "Run `pow2` on GPU arrays",
+            "input": "G = gpuArray([1 2 3]);\nresult_gpu = pow2(G);\nresult = gather(result_gpu)",
+            "output": "result = [2 4 8]"
+        },
+        {
+            "description": "Convert characters to power-of-two values",
+            "input": "codes = pow2('ABC')",
+            "output": "codes = [3.6893e+19 7.3787e+19 1.4757e+20]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `pow2` overflow for large exponents?",
+            "answer": "Results follow IEEE arithmetic. Very large positive exponents produce `Inf`; very negative exponents underflow to zero."
+        },
+        {
+            "question": "How are logical inputs handled?",
+            "answer": "Logical values convert to doubles (`true → 1`, `false → 0`) before applying the power."
+        },
+        {
+            "question": "Can I mix scalars and arrays?",
+            "answer": "Yes. MATLAB's implicit expansion applies: singleton dimensions expand to match the other operand."
+        },
+        {
+            "question": "What happens with complex inputs?",
+            "answer": "Complex exponents and/or mantissas produce complex outputs using `exp((re + i·im) * ln(2))`."
+        },
+        {
+            "question": "Will GPU and CPU results differ?",
+            "answer": "Double-precision providers match CPU results bit-for-bit. Single-precision providers may differ by expected floating-point round-off."
+        },
+        {
+            "question": "Does `pow2(F,E)` allocate a new array?",
+            "answer": "Yes. The builtin returns a fresh tensor (or complex tensor). Fusion can remove intermediates when the expression is part of a larger GPU kernel."
+        },
+        {
+            "question": "Can I use `pow2` for bit shifting?",
+            "answer": "Yes. `pow2(F, E)` mirrors `ldexp`, scaling mantissas by powers of two. Integer mantissas reproduce MATLAB's bit-shift style scaling in floating point."
+        }
+    ],
+    "links": [
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "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": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "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/pow2.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/pow2.rs"
+    },
+    "gpu_residency": "Explicit `gpuArray` calls are rarely needed. The acceleration planner keeps tensors on the GPU whenever providers handle `unary_pow2` / `pow2_scale`. When hooks are missing, the runtime gathers data, executes on the CPU, and continues seamlessly. You can still use `gpuArray` / `gather` to mirror MATLAB workflows or to interoperate with custom kernels.",
+    "gpu_behavior": [
+        "When tensors already reside on the GPU, RunMat Accelerate tries the following:\n\n1. **Unary form (`pow2(X)`):** Calls the provider hook `unary_pow2`. If the hook is unavailable, the runtime gathers `X`, computes on the host, and returns a CPU-resident tensor. 2. **Binary form (`pow2(F, E)`):** Calls `pow2_scale(F, E)` when both operands share identical shapes. Providers can implement a fused kernel (see the WGPU backend for an example). If the hook is missing or shapes require implicit expansion, RunMat gathers both tensors and performs the CPU implementation, guaranteeing MATLAB-compatible semantics.\n\nFuture providers can extend `pow2_scale` to support in-device broadcasting. Until then, fallbacks kick in transparently without user involvement."
+    ],
+    "key": "pow2",
+    "slug": "pow2",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pow2.js.map

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

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

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

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

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

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

package/dist/generated/builtins/power.js

@@ -0,0 +1,236 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "power",
+    "category": "math/elementwise",
+    "keywords": [
+        "power",
+        "element-wise power",
+        "dot caret",
+        "gpu",
+        "broadcasting"
+    ],
+    "summary": "Element-wise exponentiation A .^ B with MATLAB-compatible broadcasting, complex support, and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/power.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider elem_pow when both operands are gpuArrays of the same shape; gathers to the host for implicit expansion, complex inputs, or when elem_pow is unavailable."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::power::tests::power_scalar_numbers",
+        "integration": "builtins::math::elementwise::power::tests::power_matrix_broadcast",
+        "gpu": "builtins::math::elementwise::power::tests::power_gpu_pair_roundtrip",
+        "wgpu": "builtins::math::elementwise::power::tests::power_wgpu_matches_cpu_elementwise",
+        "like_gpu": "builtins::math::elementwise::power::tests::power_like_gpu_residency",
+        "like_complex": "builtins::math::elementwise::power::tests::power_like_complex_promotes_output"
+    },
+    "description": "`Y = power(A, B)` (or `A .^ B`) raises each element of `A` to the corresponding element of `B` using MATLAB's implicit-expansion rules. Scalars broadcast automatically, and complex inputs produce complex outputs that match MATLAB behaviour.",
+    "behaviors": [
+        "Supports scalars, vectors, matrices, and N-D tensors with the same shape or compatible singleton dimensions. Size mismatches raise the standard MATLAB error.",
+        "Logical and character inputs are promoted to double precision before powering (`'A'.^2` uses the Unicode code points of the characters).",
+        "Complex bases and/or exponents follow the analytic identity `z.^w = exp(w * log(z))`, so negative bases with fractional exponents return complex results instead of `NaN`.",
+        "Empty tensors propagate emptiness; the result uses the broadcasted size.",
+        "The optional `'like', prototype` arguments mirror the numeric flavour and residency (host vs gpuArray) of `prototype`, just like MATLAB."
+    ],
+    "examples": [
+        {
+            "description": "Raise a scalar to a power",
+            "input": "y = power(2, 5)",
+            "output": "y = 32"
+        },
+        {
+            "description": "Compute element-wise powers of a matrix",
+            "input": "A = [1 2 3; 4 5 6];\nB = power(A, 2)",
+            "output": "B =\n     1     4     9\n    16    25    36"
+        },
+        {
+            "description": "Broadcast exponents across rows",
+            "input": "base = (1:3)';\nexponent = [1 2 3];\nresult = power(base, exponent)",
+            "output": "result =\n     1     1     1\n     2     4     8\n     3     9    27"
+        },
+        {
+            "description": "Generate complex powers from negative bases",
+            "input": "values = power([-2 -1 0 1 2], 0.5)",
+            "output": "values = [0.0000 + 1.4142i, 0.0000 + 1.0000i, 0, 1, 1.4142]"
+        },
+        {
+            "description": "Keep GPU results with a `'like'` prototype",
+            "input": "proto = gpuArray.zeros(1, 1, 'single');\nx = [1 2 3];\ny = [2 3 4];\ndevicePowers = power(x, y, 'like', proto);\nresult = gather(devicePowers)",
+            "output": "devicePowers =\n  1x3 gpuArray  single\n     1     8    81\nresult =\n     1     8    81"
+        },
+        {
+            "description": "Convert character codes before powering",
+            "input": "codes = power('ABC', 2)",
+            "output": "codes = [4225 4356 4489]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `power` support MATLAB implicit expansion?",
+            "answer": "Yes. Singleton dimensions expand automatically, and size mismatches raise a dimension error with the usual MATLAB wording."
+        },
+        {
+            "question": "What numeric type does `power` return?",
+            "answer": "Real inputs produce doubles. Results promote to complex doubles whenever the exponentiation would leave the real line (for example `(-2).^0.5` or complex exponents)."
+        },
+        {
+            "question": "Can I mix scalars and arrays?",
+            "answer": "Absolutely. Scalars broadcast to match the other operand. This includes scalar gpuArrays."
+        },
+        {
+            "question": "What happens if only one operand is on the GPU?",
+            "answer": "If the other operand is a scalar, RunMat keeps everything on the GPU. Otherwise, it gathers the device operand, performs the computation on the host, and returns a host tensor (unless `'like'` instructs the runtime to re-upload the result)."
+        },
+        {
+            "question": "Does `power` modify the inputs in-place?",
+            "answer": "No. The builtin always allocates a fresh tensor (or complex tensor). Fusion can eliminate temporary allocations when the expression continues with other element-wise operations."
+        },
+        {
+            "question": "Can I force the result to stay on the GPU?",
+            "answer": "Yes—pass `'like', gpuArrayPrototype`. The runtime mirrors the residency of the prototype and uploads the result when necessary."
+        }
+    ],
+    "links": [
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "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": "plus",
+            "url": "./plus"
+        },
+        {
+            "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/power.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/power.rs"
+    },
+    "gpu_residency": "Most workflows do **not** require manual `gpuArray` calls. RunMat's auto-offload and fusion planner keep chains of element-wise operations on the GPU whenever the provider can satisfy them. When an operation needs a fallback (implicit expansion, complex inputs, or unsupported kernels), RunMat transparently gathers to the host, computes the MATLAB-accurate result, and honours any `'like'` residency hints you supplied.",
+    "gpu_behavior": [
+        "When both operands are gpuArrays with identical shapes, RunMat calls the provider's `elem_pow` hook. The WGPU backend uses a fused WGSL kernel, and the in-process provider executes on host data without leaving the GPU abstraction.",
+        "If only one operand lives on the GPU and the other is a scalar, RunMat materialises a device buffer for the scalar and still uses `elem_pow`.",
+        "Implicit expansion, complex operands, and providers that lack `elem_pow` automatically fall back to the host implementation. Results respect `'like'` residency hints, re-uploading to the GPU when requested."
+    ],
+    "key": "power",
+    "slug": "power",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=power.js.map