runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/pause.js

@@ -0,0 +1,121 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pause",
+    "category": "timing",
+    "keywords": [
+        "pause",
+        "sleep",
+        "wait",
+        "delay",
+        "press any key",
+        "execution"
+    ],
+    "summary": "Suspend execution until the user presses a key or a specified time elapses.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "pause executes entirely on the host CPU. GPU providers are never consulted and no residency changes occur."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::timing::pause::tests",
+        "integration": "builtins::timing::pause::tests::pause_gpu_duration_gathered"
+    },
+    "description": "`pause` suspends execution and mirrors MATLAB's timing semantics:\n\n- `pause` with no inputs waits for keyboard input (press any key) while pause mode is `on`. - `pause(t)` delays execution for `t` seconds (non-negative numeric scalar). `t = Inf` behaves like `pause` with no arguments. - `pause('on')` and `pause('off')` enable or disable pausing globally, returning the previous state (`'on'` or `'off'`). - `pause('query')` reports the current state (`'on'` or `'off'`). - `pause([])` is treated as `pause` with no arguments. - When pause mode is `off`, delays and key waits complete immediately.\n\nInvalid usages (negative times, non-scalar numeric inputs, or unknown strings) raise `RunMat:pause:InvalidInputArgument`, matching MATLAB diagnostics.",
+    "behaviors": [],
+    "examples": [
+        {
+            "description": "Pausing for a fixed duration",
+            "input": "tic;\npause(0.05);     % wait 50 milliseconds\nelapsed = toc"
+        },
+        {
+            "description": "Waiting for user input mid-script",
+            "input": "disp(\"Press any key to continue the demo...\");\npause;           % waits until the user presses a key (while pause is 'on')"
+        },
+        {
+            "description": "Temporarily disabling pauses in automated runs",
+            "input": "state = pause('off');   % returns previous state so it can be restored\ncleanup = onCleanup(@() pause(state));  % ensure state is restored\npause(1.0);             % returns immediately because pause is disabled"
+        },
+        {
+            "description": "Querying the current pause mode",
+            "input": "current = pause('query');   % returns 'on' or 'off'"
+        },
+        {
+            "description": "Using empty input to rely on the default behaviour",
+            "input": "pause([]);   % equivalent to calling pause with no arguments"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `pause` block forever when standard input is not interactive?",
+            "answer": "No. When RunMat detects a non-interactive standard input (for example, during automated tests), `pause` completes immediately even in `'on'` mode."
+        },
+        {
+            "question": "What happens if I call `pause` with a negative duration?",
+            "answer": "RunMat raises `RunMat:pause:InvalidInputArgument`, matching MATLAB."
+        },
+        {
+            "question": "Does `pause` accept logical or integer values?",
+            "answer": "Yes. Logical and integer inputs are converted to doubles before evaluating the delay."
+        },
+        {
+            "question": "Can I force pausing off globally?",
+            "answer": "Use `pause('off')` to disable pauses. Record the return value so you can restore the prior state with `pause(previousState)`."
+        },
+        {
+            "question": "Does `pause('query')` change the pause state?",
+            "answer": "No. It simply reports the current mode (`'on'` or `'off'`)."
+        },
+        {
+            "question": "Is `pause` affected by GPU fusion or auto-offload?",
+            "answer": "No. The builtin runs on the host regardless of fusion plans or acceleration providers."
+        },
+        {
+            "question": "What is the default pause state?",
+            "answer": "`'on'`. Every RunMat session starts with pausing enabled."
+        },
+        {
+            "question": "Can I pass a gpuArray as the duration?",
+            "answer": "Yes. RunMat gathers the scalar duration to the host before evaluating the delay."
+        }
+    ],
+    "links": [
+        {
+            "label": "tic",
+            "url": "./tic"
+        },
+        {
+            "label": "toc",
+            "url": "./toc"
+        },
+        {
+            "label": "timeit",
+            "url": "./timeit"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/timing/pause.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/timing/pause.rs"
+    },
+    "gpu_residency": "`pause` never runs on the GPU. When you pass GPU-resident values (for example, `pause(gpuArray(0.5))`), RunMat automatically gathers them to the host before evaluating the delay. No residency changes occur otherwise, and acceleration providers do not receive any callbacks.",
+    "gpu_behavior": [
+        "`pause` never runs on the GPU. When you pass GPU-resident values (for example, `pause(gpuArray(0.5))`), RunMat automatically gathers them to the host before evaluating the delay. No residency changes occur otherwise, and acceleration providers do not receive any callbacks."
+    ],
+    "key": "pause",
+    "slug": "pause",
+    "categoryPath": [
+        "timing"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pause.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../../src/generated/builtins/pause.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE;QACV,OAAO;QACP,OAAO;QACP,MAAM;QACN,OAAO;QACP,eAAe;QACf,WAAW;KACZ;IACD,SAAS,EAAE,6EAA6E;IACxF,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,4GAA4G;KACtH;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,gCAAgC;QACxC,aAAa,EAAE,6DAA6D;KAC7E;IACD,aAAa,EAAE,ovBAAovB;IACnwB,WAAW,EAAE,EAAE;IACf,UAAU,EAAE;QACV;YACE,aAAa,EAAE,8BAA8B;YAC7C,OAAO,EAAE,8DAA8D;SACxE;QACD;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,+HAA+H;SACzI;QACD;YACE,aAAa,EAAE,gDAAgD;YAC/D,OAAO,EAAE,qNAAqN;SAC/N;QACD;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,qDAAqD;SAC/D;QACD;YACE,aAAa,EAAE,oDAAoD;YACnE,OAAO,EAAE,8DAA8D;SACxE;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,oEAAoE;YAChF,QAAQ,EAAE,oJAAoJ;SAC/J;QACD;YACE,UAAU,EAAE,0DAA0D;YACtE,QAAQ,EAAE,qEAAqE;SAChF;QACD;YACE,UAAU,EAAE,gDAAgD;YAC5D,QAAQ,EAAE,uFAAuF;SAClG;QACD;YACE,UAAU,EAAE,mCAAmC;YAC/C,QAAQ,EAAE,+HAA+H;SAC1I;QACD;YACE,UAAU,EAAE,+CAA+C;YAC3D,QAAQ,EAAE,6DAA6D;SACxE;QACD;YACE,UAAU,EAAE,oDAAoD;YAChE,QAAQ,EAAE,wFAAwF;SACnG;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,2DAA2D;SACtE;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,kFAAkF;SAC7F;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,sDAAsD;QAC/D,KAAK,EAAE,mGAAmG;KAC3G;IACD,eAAe,EAAE,mRAAmR;IACpS,cAAc,EAAE;QACd,mRAAmR;KACpR;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,QAAQ;KACT;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/permute.js

@@ -0,0 +1,217 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "permute",
+    "category": "array/shape",
+    "keywords": [
+        "permute",
+        "dimension reorder",
+        "swap axes",
+        "gpu"
+    ],
+    "summary": "Reorder the dimensions of arrays, tensors, logical masks, and gpuArray values.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64",
+            "i32",
+            "bool"
+        ],
+        "broadcasting": "none",
+        "notes": "Providers may implement a dedicated permute hook; when unavailable the runtime gathers, permutes on the host, and re-uploads to keep results on the GPU."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::shape::permute::tests",
+        "integration": "builtins::array::shape::permute::tests::permute_gpu_roundtrip"
+    },
+    "description": "`permute(A, order)` rearranges the dimensions of `A` to match the order specified by the integer vector `order`. It works for numeric arrays, logical masks, complex arrays, string arrays, and gpuArray values. Dimensions not explicitly mentioned in the original array become size-one axes.",
+    "behaviors": [
+        "`order` must be a permutation of `1:n`, where `n = numel(order)`. Each dimension index appears exactly once.",
+        "The length of `order` must be at least `ndims(A)`. You can specify additional trailing dimensions; RunMat pads missing axes with size one.",
+        "Duplicate or zero dimension indices throw an error.",
+        "Works on empty arrays and arrays with zero-sized dimensions. The result preserves MATLAB's column-major ordering.",
+        "Logical, complex, and string arrays keep their types. Character arrays support 2-D permutations (transpose or identity).",
+        "gpuArray inputs stay on the GPU. If the provider lacks a native permute kernel, RunMat gathers once, permutes on the host, and uploads the result back to the device."
+    ],
+    "examples": [
+        {
+            "description": "Swapping the first two dimensions of a 3-D tensor",
+            "input": "A = reshape(1:24, [2 3 4]);\nB = permute(A, [2 1 3]);\nsize(B)",
+            "output": "ans = [3 2 4]"
+        },
+        {
+            "description": "Moving the last dimension to the front",
+            "input": "A = rand(4, 2, 5);\nC = permute(A, [3 1 2]);\nsize(C)",
+            "output": "ans = [5 4 2]"
+        },
+        {
+            "description": "Adding an explicit trailing singleton dimension",
+            "input": "row = 1:5;\nT = permute(row, [2 1 3]);\nsize(T)",
+            "output": "ans = [5 1 1]"
+        },
+        {
+            "description": "Permuting logical masks without losing type information",
+            "input": "mask = false(2, 1, 3);\nmask(1, 1, 2) = true;\nrotated = permute(mask, [3 1 2]);\nclass(rotated)",
+            "output": "ans = 'logical'"
+        },
+        {
+            "description": "Transposing character arrays",
+            "input": "C = ['r','u','n'; 'm','a','t'];\nCt = permute(C, [2 1])",
+            "output": "Ct =\n    'rm'\n    'ua'\n    'nt'"
+        },
+        {
+            "description": "Permuting gpuArray data while staying on the device",
+            "input": "G = gpuArray(rand(4, 2, 3));\nH = permute(G, [3 1 2]);\nisgpuarray(H)",
+            "output": "ans = logical 1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `order` have to contain every dimension exactly once?",
+            "answer": "Yes. `order` must be a true permutation of `1:n`. RunMat raises an error when dimensions repeat or are missing."
+        },
+        {
+            "question": "Can I introduce new singleton dimensions?",
+            "answer": "Yes. Set `order` to include additional trailing indices (e.g., `[1 2 3 4]` for a matrix) and RunMat will append size-one axes."
+        },
+        {
+            "question": "What happens with empty arrays or zero-sized dimensions?",
+            "answer": "They are preserved. The permutation still follows column-major ordering even when some dimensions are zero."
+        },
+        {
+            "question": "Can I use `permute` on character arrays?",
+            "answer": "Yes, but only for 2-D permutations (identity or transpose) because MATLAB character arrays are stored as 2-D matrices."
+        },
+        {
+            "question": "How does `permute` interact with gpuArray values?",
+            "answer": "RunMat keeps the result on the GPU. Providers that lack a native kernel trigger a gather-and-reupload fallback, which is documented above."
+        },
+        {
+            "question": "Is the operation in-place?",
+            "answer": "No. `permute` returns a new array; the original input remains unchanged."
+        },
+        {
+            "question": "How do I invert a permutation?",
+            "answer": "Use `ipermute` with the same `order` vector."
+        },
+        {
+            "question": "Does `permute` change data layout or ordering?",
+            "answer": "Only the dimension metadata changes. Column-major linearisation is preserved, so reshaping back with the inverse order recovers the original array."
+        },
+        {
+            "question": "Can cell arrays be permuted?",
+            "answer": "Cell arrays above two dimensions are not yet supported in RunMat; the builtin will report an error."
+        },
+        {
+            "question": "What if I pass a gpuArray as the `order` argument?",
+            "answer": "MATLAB requires numeric vectors on the host. RunMat mirrors this and reports an error if the order vector is gpu-resident."
+        }
+    ],
+    "links": [
+        {
+            "label": "`ipermute`",
+            "url": "./ipermute"
+        },
+        {
+            "label": "`reshape`",
+            "url": "./reshape"
+        },
+        {
+            "label": "`squeeze`",
+            "url": "./squeeze"
+        },
+        {
+            "label": "`size`",
+            "url": "./size"
+        },
+        {
+            "label": "`ndims`",
+            "url": "./ndims"
+        },
+        {
+            "label": "`gpuArray`",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "`gather`",
+            "url": "./gather"
+        },
+        {
+            "label": "cat",
+            "url": "./cat"
+        },
+        {
+            "label": "circshift",
+            "url": "./circshift"
+        },
+        {
+            "label": "diag",
+            "url": "./diag"
+        },
+        {
+            "label": "flip",
+            "url": "./flip"
+        },
+        {
+            "label": "fliplr",
+            "url": "./fliplr"
+        },
+        {
+            "label": "flipud",
+            "url": "./flipud"
+        },
+        {
+            "label": "horzcat",
+            "url": "./horzcat"
+        },
+        {
+            "label": "kron",
+            "url": "./kron"
+        },
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "rot90",
+            "url": "./rot90"
+        },
+        {
+            "label": "tril",
+            "url": "./tril"
+        },
+        {
+            "label": "triu",
+            "url": "./triu"
+        },
+        {
+            "label": "vertcat",
+            "url": "./vertcat"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/shape/permute.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/shape/permute.rs"
+    },
+    "gpu_behavior": [
+        "The runtime first asks the active acceleration provider for the `permute` hook. When implemented (e.g., a fused copy kernel), the permutation occurs entirely on the device. Otherwise RunMat falls back to a gather/permute/upload path. Either way, the result is returned as a gpuArray to match MATLAB behaviour."
+    ],
+    "key": "permute",
+    "slug": "permute",
+    "categoryPath": [
+        "array",
+        "shape"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=permute.js.map

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

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

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

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

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

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

package/dist/generated/builtins/pie.js

@@ -0,0 +1,66 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pie",
+    "category": "plotting",
+    "keywords": [
+        "pie",
+        "pie chart",
+        "exploded pie chart",
+        "slice labels",
+        "matlab pie"
+    ],
+    "summary": "Create pie charts for part-to-whole comparisons, exploded slices, and MATLAB `pie` workflows.",
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::pie::tests",
+        "integration": "runmat-plot/tests/renderer_tests.rs"
+    },
+    "description": "`pie` creates part-to-whole charts from numeric slice values. In RunMat it returns a pie handle, supports slice metadata and labels, and uses the shared plotting/replay/export stack so labels, explode state, and figure overlays stay consistent across interactive rendering and export paths.",
+    "behaviors": [
+        "Slice values determine the relative angular extent of each wedge.",
+        "Explode-style workflows and slice labels are part of the pie rendering path.",
+        "The returned value is a pie-handle object participating in the same broader plotting handle model used across the plotting stack.",
+        "Pie labels and overlay semantics survive replay/export because they are part of the shared event/scene path.",
+        "Pie charts are especially useful as the part-to-whole complement to bar and histogram-style quantitative plots."
+    ],
+    "examples": [
+        {
+            "description": "Create a basic pie chart",
+            "input": "pie([2 3 5]);"
+        },
+        {
+            "description": "Create an exploded pie chart",
+            "input": "values = [4 2 3 1];\nexplode = [1 0 1 0];\npie(values, explode);"
+        },
+        {
+            "description": "Use labels for slice names",
+            "input": "values = [5 3 2];\nlabels = {'compute', 'io', 'render'};\npie(values, labels);"
+        }
+    ],
+    "links": [
+        {
+            "label": "bar",
+            "url": "./bar"
+        },
+        {
+            "label": "histogram",
+            "url": "./histogram"
+        },
+        {
+            "label": "legend",
+            "url": "./legend"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/pie.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/pie.rs"
+    },
+    "key": "pie",
+    "slug": "pie",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pie.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pie.js","sourceRoot":"","sources":["../../../src/generated/builtins/pie.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,KAAK;QACL,WAAW;QACX,oBAAoB;QACpB,cAAc;QACd,YAAY;KACb;IACD,SAAS,EAAE,+FAA+F;IAC1G,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,gCAAgC;QACxC,aAAa,EAAE,qCAAqC;KACrD;IACD,aAAa,EAAE,oSAAoS;IACnT,WAAW,EAAE;QACX,mEAAmE;QACnE,8EAA8E;QAC9E,mIAAmI;QACnI,8GAA8G;QAC9G,iHAAiH;KAClH;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,0BAA0B;YACzC,OAAO,EAAE,eAAe;SACzB;QACD;YACE,aAAa,EAAE,8BAA8B;YAC7C,OAAO,EAAE,kEAAkE;SAC5E;QACD;YACE,aAAa,EAAE,4BAA4B;YAC3C,OAAO,EAAE,gFAAgF;SAC1F;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,0DAA0D;QACnE,KAAK,EAAE,uGAAuG;KAC/G;IACD,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/pinv.js

@@ -0,0 +1,167 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pinv",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "pinv",
+        "pseudoinverse",
+        "least squares",
+        "svd",
+        "gpu"
+    ],
+    "summary": "Compute the Moore–Penrose pseudoinverse of a matrix using SVD with MATLAB-compatible tolerance handling.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/pinv.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Invokes the acceleration provider's pinv hook when available; the current WGPU backend gathers to the host, runs the shared SVD implementation, and re-uploads the result to keep downstream residency intact."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::pinv::tests",
+        "gpu": "builtins::math::linalg::solve::pinv::tests::pinv_gpu_round_trip_matches_cpu"
+    },
+    "description": "`X = pinv(A)` returns the Moore–Penrose pseudoinverse of `A`. For full-rank square matrices this matches `inv(A)`, while rank-deficient or rectangular inputs produce the minimum-norm solution that satisfies the four Moore–Penrose conditions. RunMat mirrors MATLAB's tolerance logic: `tol = max(size(A)) * eps(max(s))`, where `s` are the singular values returned by the internal SVD.",
+    "behaviors": [
+        "Supports scalars, vectors, and higher-dimensional inputs that behave like matrices (trailing singleton dimensions are allowed; other higher ranks must be reshaped first).",
+        "Logical and integer inputs are promoted to `double` before the SVD, matching MATLAB semantics.",
+        "Optional second argument `pinv(A, tol)` treats values in `tol` as the user-specified cutoff for singular values. Entries ≤ `tol` contribute zeros in the diagonal of `Σ⁺`.",
+        "Complex matrices are handled in full complex arithmetic via `A = U * Σ * Vᴴ`.",
+        "Empty matrices return the appropriately sized zero matrix (`size(pinv(A)) == fliplr(size(A))`).",
+        "The result always has size `n × m` if the input is `m × n`."
+    ],
+    "examples": [
+        {
+            "description": "Finding the pseudoinverse of a tall matrix",
+            "input": "A = [1 0; 0 0; 0 1];\nX = pinv(A)",
+            "output": "X =\n     1     0     0\n     0     0     1"
+        },
+        {
+            "description": "Solving an overdetermined least-squares problem",
+            "input": "A = [1 1; 1 2; 1 3];\nb = [1; 0; 0];\nx = pinv(A) * b",
+            "output": "x =\n    1.1667\n   -0.5000"
+        },
+        {
+            "description": "Suppressing small singular values with a custom tolerance",
+            "input": "A = diag([1, 1e-10]);\nX = pinv(A, 1e-6)",
+            "output": "X =\n     1     0\n     0     0"
+        },
+        {
+            "description": "Pseudoinverse of a rank-deficient square matrix",
+            "input": "A = [1 2; 2 4];\nX = pinv(A)",
+            "output": "X =\n    0.0400    0.0800\n    0.0800    0.1600"
+        },
+        {
+            "description": "Pseudoinverse of a complex diagonal matrix",
+            "input": "A = diag([2+1i, 3-2i]);\nX = pinv(A)",
+            "output": "X =\n   0.4000 - 0.2000i         0\n         0   0.2308 + 0.1538i"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How is `pinv` different from `inv`?",
+            "answer": "`inv(A)` requires `A` to be square and full rank. `pinv(A)` works for any matrix shape and produces the minimum-norm solution even when `A` is singular or rectangular."
+        },
+        {
+            "question": "What tolerance does `pinv` use by default?",
+            "answer": "RunMat matches MATLAB: `max(size(A)) * eps(max(s))`, where `s` are the singular values. Values below this threshold are treated as zero when forming `Σ⁺`."
+        },
+        {
+            "question": "Can I recover the rank from the pseudoinverse?",
+            "answer": "Yes. Count the singular values greater than the effective tolerance (`rank` returns this directly). The same tolerance drives both `pinv` and `rank`."
+        },
+        {
+            "question": "Does `pinv` support complex inputs?",
+            "answer": "Absolutely. Complex matrices use a full complex SVD with conjugate transposes, matching MATLAB's definition."
+        },
+        {
+            "question": "Will calling `pinv` move my data off the GPU?",
+            "answer": "Only if the active provider lacks a native implementation. In that case RunMat gathers, computes, and re-uploads for you. Providers may expose native kernels to keep the entire computation on the device."
+        },
+        {
+            "question": "Is `pinv(A) * b` equivalent to `A \\\\ b`?",
+            "answer": "For full-rank systems, yes. `A \\\\ b` is typically faster and more numerically stable, but `pinv` remains useful for ill-conditioned or rank-deficient problems where the pseudoinverse is desired."
+        }
+    ],
+    "links": [
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "mrdivide",
+            "url": "./mrdivide"
+        },
+        {
+            "label": "svd",
+            "url": "./svd"
+        },
+        {
+            "label": "rank",
+            "url": "./rank"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cond",
+            "url": "./cond"
+        },
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        },
+        {
+            "label": "rcond",
+            "url": "./rcond"
+        }
+    ],
+    "source": {
+        "label": "Open an issue",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "gpu_residency": "Explicit residency management is rarely required. When inputs already live on the GPU and the provider implements `pinv`, the builtin executes entirely on the device. Providers without a native kernel (including the current WGPU backend) transparently download the matrix, run the shared CPU path, and re-upload the result so the caller continues working with a GPU tensor. `gpuArray` remains available for MATLAB compatibility or to seed GPU residency explicitly.",
+    "gpu_behavior": [
+        "When a GPU acceleration provider is active, RunMat offers the operation through its `pinv` hook, passing along any explicit tolerance. Providers may implement a native GPU kernel; otherwise, they can gather to the host, invoke the shared SVD routine, and re-upload the result. The shipping WGPU backend follows this gather/compute/upload pattern today, so downstream GPU work retains residency without MATLAB-level changes."
+    ],
+    "key": "pinv",
+    "slug": "pinv",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pinv.js.map

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

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

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

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

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

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