runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/char.js

@@ -0,0 +1,177 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "char",
+    "category": "strings/core",
+    "keywords": [
+        "char",
+        "character array",
+        "string conversion",
+        "padding",
+        "gpu"
+    ],
+    "summary": "Convert text, numeric codes, and cell contents into MATLAB-style character arrays.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/char.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Conversion always runs on the CPU; GPU tensors are gathered to host memory before building the character array."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::strings::core::char::tests",
+        "integration": "builtins::strings::core::char::tests::char_gpu_tensor_round_trip"
+    },
+    "description": "`char` converts its inputs into a character array. Numeric inputs are interpreted as Unicode code points, text inputs become rows of characters, and cell elements or string scalars are padded with spaces when necessary so every row in the result has the same width.",
+    "behaviors": [
+        "`char(x)` with no arguments returns a `0×0` character array.",
+        "Numeric arrays must be real integers. The output character array has the same shape (up to two dimensions) as the numeric input.",
+        "String scalars and character vectors become individual rows. Rows are padded on the right with spaces to match the longest row.",
+        "String arrays with one or two dimensions contribute one row per element using MATLAB's column-major ordering.",
+        "Cell arrays must contain character vectors or string scalars. Each element becomes exactly one row in the result.",
+        "Inputs may be mixed and are vertically concatenated in the order they appear.",
+        "Complex inputs are unsupported and raise MATLAB-compatible errors."
+    ],
+    "examples": [
+        {
+            "description": "Converting a string scalar to a character row",
+            "input": "name = char(\"RunMat\")",
+            "output": "name =\n    'RunMat'"
+        },
+        {
+            "description": "Building a character matrix from multiple rows",
+            "input": "rows = char(\"alpha\", \"beta\")",
+            "output": "rows =\n    'alpha'\n    'beta '"
+        },
+        {
+            "description": "Transforming numeric codes to characters",
+            "input": "codes = [77 65 84 76 65 66];\nletters = char(codes)",
+            "output": "letters =\n    'MATLAB'"
+        },
+        {
+            "description": "Padding a string array into a character matrix",
+            "input": "animals = [\"cat\"; \"giraffe\"];\nC = char(animals)",
+            "output": "C =\n    'cat   '\n    'giraffe'"
+        },
+        {
+            "description": "Creating rows from a cell array of character vectors",
+            "input": "dirs = {'north', 'east', 'west'};\nchart = char(dirs)",
+            "output": "chart =\n    'north'\n    'east '\n    'west '"
+        },
+        {
+            "description": "Converting GPU-resident codes back to text",
+            "input": "G = gpuArray([82 85 78 77 65 84]);\nlabel = char(G)",
+            "output": "label =\n    'RUNMAT'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `char` accept numeric arrays with more than two dimensions?",
+            "answer": "No. Numeric inputs must be scalars, vectors, or two-dimensional matrices. Higher-dimensional arrays raise an error so MATLAB's behaviour is preserved."
+        },
+        {
+            "question": "How are rows padded when lengths differ?",
+            "answer": "Each row is right-padded with space characters so every row in the result has the same width as the longest row that was produced."
+        },
+        {
+            "question": "Can I convert cell arrays that contain empty text?",
+            "answer": "Yes. Empty strings or character vectors become rows with zero columns; they still participate in padding when combined with longer rows."
+        },
+        {
+            "question": "What happens if a numeric value is not an integer?",
+            "answer": "The builtin rejects non-integer numeric values. Use `round`, `floor`, or `uint32` beforehand if you need to convert floating-point values into valid code points."
+        },
+        {
+            "question": "Are code points above the Basic Multilingual Plane supported?",
+            "answer": "Yes. Any integer that represents a valid Unicode scalar value (`0..0x10FFFF`, excluding surrogates) is accepted and converted to the corresponding character."
+        },
+        {
+            "question": "Can `char` convert complex numbers?",
+            "answer": "No. Complex values are not supported because MATLAB also rejects them. Convert the data to real values before calling `char`."
+        },
+        {
+            "question": "Does `char` keep characters on the GPU?",
+            "answer": "No. After conversion the result is a CPU-resident character array. Use `gpuArray(char(...))` if you need to move the result back to the device."
+        }
+    ],
+    "links": [
+        {
+            "label": "string",
+            "url": "./string"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "compose",
+            "url": "./compose"
+        },
+        {
+            "label": "num2str",
+            "url": "./num2str"
+        },
+        {
+            "label": "sprintf",
+            "url": "./sprintf"
+        },
+        {
+            "label": "str2double",
+            "url": "./str2double"
+        },
+        {
+            "label": "strcmp",
+            "url": "./strcmp"
+        },
+        {
+            "label": "strcmpi",
+            "url": "./strcmpi"
+        },
+        {
+            "label": "string.empty",
+            "url": "./string.empty"
+        },
+        {
+            "label": "strings",
+            "url": "./strings"
+        },
+        {
+            "label": "strlength",
+            "url": "./strlength"
+        },
+        {
+            "label": "strncmp",
+            "url": "./strncmp"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/strings/core/char.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/core/char.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` manually for `char`. The runtime recognises that this builtin materialises text on the host, gathers GPU tensors automatically, and keeps the character array in CPU memory. Wrap the result in `gpuArray(char(...))` only when you explicitly want the characters back on the device for subsequent GPU pipelines.",
+    "gpu_behavior": [
+        "`char` gathers GPU tensors back to host memory using the active RunMat Accelerate provider before performing any conversion. The resulting character array always resides in host memory; providers do not need to supply specialised kernels."
+    ],
+    "key": "char",
+    "slug": "char",
+    "categoryPath": [
+        "strings",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=char.js.map

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

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

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

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

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

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

package/dist/generated/builtins/chol.js

@@ -0,0 +1,160 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "chol",
+    "category": "math/linalg/factor",
+    "keywords": [
+        "chol",
+        "cholesky",
+        "factorization",
+        "positive definite",
+        "lower",
+        "upper"
+    ],
+    "summary": "Cholesky factorization with MATLAB-compatible upper and lower forms.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider chol hook when available, otherwise gathers to host and re-uploads the factor."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::factor::chol::tests",
+        "integration": "builtins::math::linalg::factor::chol::tests::chol_gpu_provider_roundtrip"
+    },
+    "description": "`chol(A)` computes a Cholesky factorization of a Hermitian positive-definite matrix `A`. By default, it returns the upper-triangular factor `R` satisfying `R' * R = A`. The two-output form `[R, p] = chol(A)` reports whether the factorization succeeded: `p = 0` for success, and otherwise `p` equals the index of the first leading principal minor that is not positive definite.",
+    "behaviors": [
+        "Single output (`chol(A)`): Returns the upper-triangular factor. If `A` is not positive definite, a MATLAB-compatible error (`\"Matrix must be positive definite.\"`) is raised.",
+        "Two outputs (`[R, p] = chol(A)`): Returns the factor `R` and a flag `p`. When `p > 0`, `R` contains the partial factorization up to the `(p-1)`-th column.",
+        "Lower form (`chol(A, 'lower')`): Returns a lower-triangular factor `L` such that `L * L' = A`. The two-output variant `[L, p] = chol(A, 'lower')` follows the same failure semantics.",
+        "The option `'upper'` is accepted for completeness and matches the default behaviour.",
+        "Real logical inputs are promoted to double precision. Complex inputs must be Hermitian positive definite (HPD); the factor preserves complex values.",
+        "Scalar and `0×0` inputs are supported. `chol([])` returns an empty matrix with `p = 0`."
+    ],
+    "examples": [
+        {
+            "description": "Upper-triangular Cholesky factor of a symmetric positive-definite matrix",
+            "input": "A = [4 12 -16; 12 37 -43; -16 -43 98];\nR = chol(A)",
+            "output": "R =\n     2     6    -8\n     0     1     5\n     0     0     3"
+        },
+        {
+            "description": "Lower-triangular factor using the `'lower'` option",
+            "input": "A = [25 15 -5; 15 18  0; -5 0 11];\nL = chol(A, 'lower')",
+            "output": "L =\n     5     0     0\n     3     3     0\n    -1     1     3"
+        },
+        {
+            "description": "Detecting a non-positive-definite matrix with the two-output form",
+            "input": "A = [1 2; 2 1];\n[R, p] = chol(A)",
+            "output": "R =\n     1     2\n     0     0\n\np =\n     2"
+        },
+        {
+            "description": "Using the Cholesky factor to solve linear systems",
+            "input": "A = [10 2 3; 2 9 1; 3 1 7];\nb = [1; 2; 3];\n[R, p] = chol(A);\nif p == 0\n    y = R' \\ b;\n    x = R \\ y;\nend"
+        },
+        {
+            "description": "Cholesky factor of a complex Hermitian positive-definite matrix",
+            "input": "A = [5 1-2i; 1+2i 4];\n[R, p] = chol(A)",
+            "output": "R =\n    2.2361   0.4472 -0.8944i\n         0   1.7321\n\np =\n     0"
+        },
+        {
+            "description": "Running `chol` on a `gpuArray`",
+            "input": "G = gpuArray([6 2; 2 5]);\n[R, p] = chol(G);\nclass(R)",
+            "output": "ans =\n    'gpuArray'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does the second output `p` mean?",
+            "answer": "`p` is zero when the factorization succeeds. Otherwise, it is the index of the first leading principal minor that is not positive definite. The returned factor contains the partial result up to that point."
+        },
+        {
+            "question": "How do I request the lower-triangular factor?",
+            "answer": "Pass `'lower'` (case-insensitive) as the second argument: `[L, p] = chol(A, 'lower')`. The default behaviour (`chol(A)`) returns the upper-triangular factor."
+        },
+        {
+            "question": "Why do I get an error when using a single output on an indefinite matrix?",
+            "answer": "The single-output form matches MATLAB and throws an error when the matrix is not positive definite. Use the two-output form `[R, p]` to obtain the partial factor and inspect `p` without raising an error."
+        },
+        {
+            "question": "Does `chol` accept sparse matrices?",
+            "answer": "Not yet. RunMat currently implements the dense MATLAB semantics. Sparse support is planned in a future release."
+        },
+        {
+            "question": "Can I pass logical or integer arrays?",
+            "answer": "Yes. They are promoted to double precision before factorization, matching MATLAB behaviour."
+        },
+        {
+            "question": "Do complex inputs need to be Hermitian?",
+            "answer": "Yes. `chol` operates on Hermitian positive-definite matrices. If the matrix is not Hermitian, `p` will be non-zero in the two-output form, and the single-output form raises an error."
+        },
+        {
+            "question": "How should I interpret the result when `p > 0`?",
+            "answer": "Only the leading `(p-1)` columns/rows of the factor are valid. The remaining portions are zeros, mirroring MATLAB’s contract."
+        },
+        {
+            "question": "Does the GPU path return the same flag `p`?",
+            "answer": "Yes. Providers report the MATLAB-compatible failure index, and RunMat converts it into the scalar second output."
+        },
+        {
+            "question": "Is the factor unique?",
+            "answer": "The standard Cholesky factorization returns an upper-triangular matrix with positive diagonal entries. The lower-triangular form is the conjugate transpose of the upper form and is likewise unique under the same assumptions."
+        },
+        {
+            "question": "How should I choose between `chol` and `lu`/`qr`?",
+            "answer": "Use `chol` when the matrix is Hermitian positive definite—its triangular factors are cheaper to compute and exploit symmetry. Use `lu` or `qr` for more general matrices."
+        }
+    ],
+    "links": [
+        {
+            "label": "lu",
+            "url": "./lu"
+        },
+        {
+            "label": "qr",
+            "url": "./qr"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "eig",
+            "url": "./eig"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/linalg/factor/chol.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/factor/chol.rs"
+    },
+    "gpu_behavior": [
+        "When RunMat Accelerate is active, the planner keeps `gpuArray` inputs on device and asks the registered provider for a `chol` factorization. Providers that implement the hook (the WGPU and in-process backends included) return the MATLAB-compatible flag `p` while leaving the triangular factor resident on the GPU. If the provider lacks that hook or the matrix uses an unsupported precision/type, RunMat gathers the data, executes the CPU implementation, and re-uploads the factor when a provider is present. The flag output is always materialised as a host scalar."
+    ],
+    "key": "chol",
+    "slug": "chol",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "factor"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=chol.js.map

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

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

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

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

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

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

package/dist/generated/builtins/circshift.js

@@ -0,0 +1,223 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "circshift",
+    "category": "array/shape",
+    "keywords": [
+        "circshift",
+        "circular shift",
+        "rotate array",
+        "gpu",
+        "cyclic shift"
+    ],
+    "summary": "Rotate arrays circularly along one or more dimensions.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64",
+            "i32",
+            "bool"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses the provider circshift hook when available; otherwise gathers once, rotates on the host, and re-uploads."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::shape::circshift::tests",
+        "integration": "builtins::array::shape::circshift::tests::circshift_gpu_roundtrip"
+    },
+    "description": "`circshift(A, K)` rotates the elements of `A` circularly. Positive shifts move elements toward higher indices, wrapping values that fall off the end back to the beginning. Shifts can be specified per-dimension using vectors or paired with explicit dimension lists.",
+    "behaviors": [
+        "`circshift(A, k)` shifts by `k` positions along the first non-singleton dimension. Negative values shift in the opposite direction.",
+        "`circshift(A, shiftVec)` accepts a numeric vector that supplies a shift per dimension. Missing dimensions default to zero. Extra dimensions are treated as size-one axes, so they have no effect unless an explicit reshape added those dimensions previously.",
+        "`circshift(A, K, dims)` lets you target specific dimensions. `K` and `dims` must have the same length; each entry in `dims` is 1-based.",
+        "Works for numeric tensors, logical masks, complex arrays, string arrays, and character matrices. Character arrays only support dimensions one and two, mirroring MATLAB limitations.",
+        "Empty dimensions remain empty; shifting them is a no-op. Scalars are returned unchanged.",
+        "Shifts that are integer multiples of a dimension’s extent leave that axis unchanged. RunMat reduces each shift modulo the axis length, matching MATLAB."
+    ],
+    "examples": [
+        {
+            "description": "Shifting matrix rows downward by one location",
+            "input": "A = [1 2 3; 4 5 6; 7 8 9];\nB = circshift(A, 1)",
+            "output": "B =\n     7     8     9\n     1     2     3\n     4     5     6"
+        },
+        {
+            "description": "Shifting columns left by two positions",
+            "input": "A = reshape(1:12, [3 4]);\nC = circshift(A, [0 -2])",
+            "output": "C =\n     7    10     1     4\n     8    11     2     5\n     9    12     3     6"
+        },
+        {
+            "description": "Rotating a 3-D tensor along multiple dimensions",
+            "input": "T = reshape(1:8, [2 2 2]);\nU = circshift(T, [1 0 -1]);\nU(:, :, 1)\nU(:, :, 2)",
+            "output": "ans(:,:,1) =\n     6     8\n     5     7\n\nans(:,:,2) =\n     2     4\n     1     3"
+        },
+        {
+            "description": "Shifting along specific dimensions using the `dims` argument",
+            "input": "A = reshape(1:12, [3 4]);\nV = circshift(A, [2 -1], [1 2])",
+            "output": "V =\n     5     8    11     2\n     6     9    12     3\n     4     7    10     1"
+        },
+        {
+            "description": "Rotating a character matrix to cycle through rows and columns",
+            "input": "C = ['r','u','n'; 'm','a','t'];\nR = circshift(C, [0 1])",
+            "output": "R =\n    'nru'\n    'tma'"
+        },
+        {
+            "description": "Applying `circshift` to a gpuArray and keeping the result on the device",
+            "input": "G = gpuArray(reshape(1:12, [3 4]));\nH = circshift(G, [1 -2]);\nisgpuarray(H)",
+            "output": "ans = logical 1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Do `K` and `dims` need the same length?",
+            "answer": "Yes. When you supply the `dims` argument, the shift vector must have the same number of entries. Each shift is paired with the corresponding dimension."
+        },
+        {
+            "question": "Can I shift along dimensions that are currently size one?",
+            "answer": "You can, and the result matches MATLAB: the axis length is one so the shift has no visible effect."
+        },
+        {
+            "question": "How are negative shifts handled?",
+            "answer": "They rotate values toward lower indices. Internally RunMat reduces each shift modulo the axis length, so `-1` on a length-4 dimension is equivalent to `3`."
+        },
+        {
+            "question": "What happens with empty tensors?",
+            "answer": "The result remains empty with identical shape metadata. `circshift` never introduces new elements."
+        },
+        {
+            "question": "Are logical and string arrays supported?",
+            "answer": "Yes. Logical arrays stay logical, and string arrays preserve their individual strings while rotating their positions."
+        },
+        {
+            "question": "Can character arrays be shifted along the third dimension?",
+            "answer": "No. MATLAB character arrays are strictly two-dimensional; RunMat matches this restriction and raises an error if you request dimension three or higher."
+        },
+        {
+            "question": "Does `circshift` fuse with other GPU kernels?",
+            "answer": "When a provider supplies the hook, yes. Otherwise the rotation acts as a residency boundary in fused graphs."
+        },
+        {
+            "question": "How does `circshift` interact with complex numbers?",
+            "answer": "Real and imaginary parts move together. Scalars are unaffected, and arrays retain their complex entries without modification."
+        },
+        {
+            "question": "What if I pass non-integer shifts?",
+            "answer": "RunMat enforces MATLAB semantics: shifts must be finite integers. Fractional values raise an error."
+        },
+        {
+            "question": "Does the builtin allocate new GPU buffers?",
+            "answer": "Providers may reuse buffers internally, but from the user’s perspective the result is a fresh gpuArray handle that preserves residency information."
+        },
+        {
+            "question": "What does circshift do in MATLAB?",
+            "answer": "`circshift(A, K)` circularly shifts the elements of array `A` by `K` positions. Elements shifted off one end wrap around to the other. Negative shifts move elements in the opposite direction."
+        },
+        {
+            "question": "How do I shift rows and columns separately with circshift?",
+            "answer": "Use `circshift(A, [rowShift, colShift])` to shift rows and columns independently. For example, `circshift(A, [1, -2])` shifts rows down by 1 and columns left by 2."
+        },
+        {
+            "question": "Does circshift support GPU arrays?",
+            "answer": "Yes. In RunMat, `circshift` works on GPU arrays and can fuse with other GPU kernels for efficient execution without extra memory allocations."
+        }
+    ],
+    "links": [
+        {
+            "label": "`permute`",
+            "url": "./permute"
+        },
+        {
+            "label": "`rot90`",
+            "url": "./rot90"
+        },
+        {
+            "label": "`flip`",
+            "url": "./flip"
+        },
+        {
+            "label": "`gpuArray`",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "`gather`",
+            "url": "./gather"
+        },
+        {
+            "label": "cat",
+            "url": "./cat"
+        },
+        {
+            "label": "diag",
+            "url": "./diag"
+        },
+        {
+            "label": "fliplr",
+            "url": "./fliplr"
+        },
+        {
+            "label": "flipud",
+            "url": "./flipud"
+        },
+        {
+            "label": "horzcat",
+            "url": "./horzcat"
+        },
+        {
+            "label": "ipermute",
+            "url": "./ipermute"
+        },
+        {
+            "label": "kron",
+            "url": "./kron"
+        },
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "reshape",
+            "url": "./reshape"
+        },
+        {
+            "label": "squeeze",
+            "url": "./squeeze"
+        },
+        {
+            "label": "tril",
+            "url": "./tril"
+        },
+        {
+            "label": "triu",
+            "url": "./triu"
+        },
+        {
+            "label": "vertcat",
+            "url": "./vertcat"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/shape/circshift.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/shape/circshift.rs"
+    },
+    "gpu_residency": "No additional steps are required. RunMat’s auto-offload planner keeps tensors on the GPU whenever the provider exposes native support. If a provider falls back to the host implementation, the runtime gathers and re-uploads the data transparently so subsequent operations can continue on the GPU. Explicit calls to `gpuArray` remain available for MATLAB compatibility but are not mandatory.",
+    "gpu_behavior": [
+        "When RunMat Accelerate is active, the runtime first asks the selected provider for a native `circshift` implementation. Providers that implement the hook perform the rotation entirely on the device, preserving residency metadata and enabling fusion with subsequent GPU kernels. If the hook is missing, RunMat downloads the tensor once, rotates it on the host using the same semantics, and uploads the result back to the GPU so downstream work continues without manual intervention."
+    ],
+    "key": "circshift",
+    "slug": "circshift",
+    "categoryPath": [
+        "array",
+        "shape"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=circshift.js.map

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

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

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

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

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

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