runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/mean.js

@@ -0,0 +1,209 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mean",
+    "category": "math/reduction",
+    "keywords": [
+        "mean",
+        "average",
+        "reduction",
+        "gpu",
+        "omitnan",
+        "like",
+        "native"
+    ],
+    "summary": "Average elements of scalars, vectors, matrices, or N-D tensors with MATLAB-compatible options.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": true,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to host whenever 'omitnan' is requested or the active provider lacks mean reductions."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::reduction::mean::tests",
+        "integration": "builtins::math::reduction::mean::tests::mean_gpu_provider_roundtrip"
+    },
+    "description": "`mean(x)` computes the arithmetic mean of scalars, vectors, matrices, and higher-dimensional tensors. When no dimension is supplied, the reduction runs along the first non-singleton dimension.",
+    "behaviors": [
+        "`mean(X)` on an `m × n` matrix returns a row vector (`1 × n`) with column averages.",
+        "`mean(X, 2)` returns a column vector (`m × 1`) containing row averages.",
+        "`mean(X, 'all')` collapses every dimension and returns a scalar average of all elements.",
+        "`mean(X, vecdim)` accepts a vector of dimensions (e.g., `[1 3]`) and reduces each listed axis in one call while preserving the others.",
+        "Complex inputs are supported and follow MATLAB's rule `mean(a + bi) = mean(real(a + bi)) + i·mean(imag(a + bi))`, propagating `NaN` through either component.",
+        "Logical inputs are promoted to double precision (`true → 1.0`, `false → 0.0`).",
+        "`mean(..., 'omitnan')` ignores `NaN` values; if every element in the slice is `NaN`, the result is `NaN`.",
+        "`mean(..., 'includenan')` (default) propagates `NaN` when any element in the slice is `NaN`.",
+        "`mean(___, outtype)` accepts `'double'`, `'default'`, or `'native'` to control the output numeric class. Integer outputs round to the nearest integer, matching MATLAB.",
+        "`mean(___, 'like', prototype)` matches the numeric class and residency of `prototype`, including GPU tensors and complex arrays.",
+        "Empty slices produce `NaN` outputs that follow MATLAB's shape semantics.",
+        "Dimensions larger than `ndims(X)` leave the input unchanged."
+    ],
+    "examples": [
+        {
+            "description": "Computing the mean of a matrix",
+            "input": "A = [1 2 3; 4 5 6];\ncolMeans = mean(A);      % column averages\nrowMeans = mean(A, 2);   % row averages",
+            "output": "colMeans = [2.5 3.5 4.5];\nrowMeans = [2; 5]"
+        },
+        {
+            "description": "Computing the mean of a vector with NaN values",
+            "input": "values = [1 NaN 3];\navg = mean(values, 'omitnan')",
+            "output": "avg = 2"
+        },
+        {
+            "description": "Computing the overall mean across all elements",
+            "input": "B = reshape(1:12, [3 4]);\noverall = mean(B, 'all')",
+            "output": "overall = 6.5"
+        },
+        {
+            "description": "Reducing across multiple dimensions at once",
+            "input": "C = cat(3, [1 2; 3 4], [5 6; 7 8]);\nslice_means = mean(C, [1 3]);   % reduce rows and pages, keep columns",
+            "output": "slice_means = [4 5]"
+        },
+        {
+            "description": "Matching a prototype with `'like'`",
+            "input": "G = gpuArray(single([1 3; 5 7]));\nmu = mean(G, 'all', 'like', G);\nresult = gather(mu)",
+            "output": "result = single(4)"
+        },
+        {
+            "description": "Computing the mean of a matrix on a GPU",
+            "input": "G = gpuArray([1 2 NaN; 3 4 5]);\nmeans = mean(G, 2, 'omitnan');\nresult = gather(means)",
+            "output": "result = [1.5; 4]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use the `mean` function?",
+            "answer": "Use `mean` whenever you need to compute the arithmetic mean of a tensor. This is useful for calculating averages, central tendencies, or performing statistical analysis."
+        },
+        {
+            "question": "What does `mean(A)` return?",
+            "answer": "If you call `mean(A)`, where `A` is an array, the result is a new array of the same shape as `A` with the mean of each slice along the first non-singleton dimension. For example, if `A` is a 2x3 matrix, `mean(A)` will return a 1x3 matrix with the mean of each column."
+        },
+        {
+            "question": "How do I compute the mean of a specific dimension?",
+            "answer": "You can use the `dim` argument to specify the dimension along which to compute the mean. For example, `mean(A, 2)` will return a 2x1 matrix with the mean of each row."
+        },
+        {
+            "question": "How do I average across multiple dimensions at once?",
+            "answer": "Pass a vector of dimensions such as `mean(A, [1 3])`. RunMat reduces each listed axis in a single pass, leaving the remaining dimensions unchanged."
+        },
+        {
+            "question": "What happens if the slice contains only NaN values?",
+            "answer": "When you specify `'omitnan'`, slices that contain only `NaN` still return `NaN`, mirroring MATLAB. With `'includenan'` (the default), any `NaN` in the slice forces the result to `NaN`."
+        },
+        {
+            "question": "Does `mean` support GPU arrays automatically?",
+            "answer": "Yes. If a GPU provider is registered, device-resident tensors remain on the GPU and run through `reduce_mean_dim`/`reduce_mean`. Calls that the provider cannot satisfy—most notably `'omitnan'` and unsupported dimension combinations—are gathered to the CPU transparently."
+        },
+        {
+            "question": "How are complex numbers handled?",
+            "answer": "RunMat averages the real and imaginary components separately. If either component in a slice is `NaN`, the result for that slice becomes complex `NaN`, matching MATLAB's behaviour."
+        },
+        {
+            "question": "How can I control the output type?",
+            "answer": "By default, RunMat promotes inputs to double precision. Use the optional outtype argument to override this behaviour: pass `'native'` to round back to the input's integer class, or `'double'`/`'default'` to force double precision explicitly. `'like', prototype` matches the numeric flavour and residency of `prototype`, including complex outputs."
+        },
+        {
+            "question": "Can I keep the result on the GPU or match an existing prototype?",
+            "answer": "Yes. When you pass `'like', prototype`, RunMat mirrors both the class and residency of `prototype`. Providing a GPU tensor keeps the result on the device even when the reduction itself had to fall back to the host (for example with `'omitnan'`)."
+        }
+    ],
+    "links": [
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "median",
+            "url": "./median"
+        },
+        {
+            "label": "cumsum",
+            "url": "./cumsum"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "all",
+            "url": "./all"
+        },
+        {
+            "label": "any",
+            "url": "./any"
+        },
+        {
+            "label": "cummax",
+            "url": "./cummax"
+        },
+        {
+            "label": "cummin",
+            "url": "./cummin"
+        },
+        {
+            "label": "cumprod",
+            "url": "./cumprod"
+        },
+        {
+            "label": "diff",
+            "url": "./diff"
+        },
+        {
+            "label": "max",
+            "url": "./max"
+        },
+        {
+            "label": "min",
+            "url": "./min"
+        },
+        {
+            "label": "nnz",
+            "url": "./nnz"
+        },
+        {
+            "label": "prod",
+            "url": "./prod"
+        },
+        {
+            "label": "std",
+            "url": "./std"
+        },
+        {
+            "label": "var",
+            "url": "./var"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/reduction/mean.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/reduction/mean.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the fusion planner keeps residency on GPU in branches of fused expressions. As such, in the above example, the result of the `mean` call will already be on the GPU when the fusion planner has detected a net benefit to operating the fused expression it is part of on the GPU.\n\nTo preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call `gpuArray` explicitly to move data to the GPU if you want to be explicit about the residency.\n\nSince MathWorks MATLAB does not have a fusion planner, and they kept their parallel execution toolbox separate from the core language, as their toolbox is a separate commercial product, MathWorks MATLAB users need to call `gpuArray` to move data to the GPU manually whereas RunMat users can rely on the fusion planner to keep data on the GPU automatically.",
+    "gpu_behavior": [
+        "When the input tensor lives on the GPU, RunMat first asks the active acceleration provider for a device-side result via `reduce_mean_dim` or (when the entire tensor collapses) `reduce_mean`. If the provider lacks those hooks or the call specifies `'omitnan'`, RunMat gathers the data back to the host and evaluates the mean with the CPU reference implementation. Output templates are then applied: `'native'` restores integer classes, and `'like'` mirrors both the numeric class and residency—re-uploading to the GPU when the prototype is device-resident."
+    ],
+    "key": "mean",
+    "slug": "mean",
+    "categoryPath": [
+        "math",
+        "reduction"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mean.js.map

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

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

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

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

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

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

package/dist/generated/builtins/median.js

@@ -0,0 +1,197 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "median",
+    "category": "math/reduction",
+    "keywords": [
+        "median",
+        "reduction",
+        "omitnan",
+        "includenan",
+        "statistics",
+        "gpu"
+    ],
+    "summary": "Median of scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": true,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Executes on-device when providers expose median reducers; otherwise falls back to host for compatibility."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::reduction::median::tests",
+        "integration": "builtins::math::reduction::median::tests::median_gpu_provider_roundtrip"
+    },
+    "description": "`median(x)` returns the middle value of scalars, vectors, matrices, and higher-dimensional tensors. When no dimension is supplied, the reduction runs along the first non-singleton dimension.",
+    "behaviors": [
+        "`median(X)` on an `m × n` matrix returns a row vector (`1 × n`) containing the column medians.",
+        "`median(X, 2)` returns a column vector (`m × 1`) containing the row medians.",
+        "`median(X, 'all')` reduces across every element in `X` and returns a scalar.",
+        "`median(X, vecdim)` accepts a row or column vector of dimensions (for example `[1 3]`) and reduces each listed axis in a single call while preserving the others.",
+        "Even-length slices return the average of the two center elements after sorting.",
+        "Logical inputs are promoted to double precision (`true → 1.0`, `false → 0.0`) before computing the median.",
+        "`median(..., 'omitnan')` ignores `NaN` values; if every element is `NaN`, the result is `NaN`.",
+        "`median(..., 'includenan')` (default) propagates `NaN` when any value in the slice is `NaN`.",
+        "Empty slices return `NaN` values that preserve MATLAB-compatible shape semantics.",
+        "Dimensions larger than `ndims(X)` leave the input unchanged."
+    ],
+    "examples": [
+        {
+            "description": "Finding the median of an odd-length vector",
+            "input": "x = [7 2 9 4 5];\nm = median(x)",
+            "output": "m = 5"
+        },
+        {
+            "description": "Computing the median of an even-length vector with averaging",
+            "input": "x = [1 4 9 10];\nm = median(x)",
+            "output": "m = 6.5"
+        },
+        {
+            "description": "Column-wise median of a matrix",
+            "input": "A = [1 3 5; 7 9 11; 2 4 6];\ncolMedians = median(A)",
+            "output": "colMedians = [2 4 6]"
+        },
+        {
+            "description": "Row medians while ignoring NaN values",
+            "input": "A = [1 NaN 3; 4 5 NaN];\nrowMedians = median(A, 2, 'omitnan')",
+            "output": "rowMedians = [2; 4.5]"
+        },
+        {
+            "description": "Median of all elements in a matrix",
+            "input": "A = reshape(1:6, [3 2]);\noverall = median(A, 'all')",
+            "output": "overall = 3.5"
+        },
+        {
+            "description": "Median of all elements on a GPU-backed tensor",
+            "input": "G = gpuArray(randn(2048, 2048));\noverall = median(G, 'omitnan');\nresult = gather(overall)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use the `median` function?",
+            "answer": "Use `median` when you need a robust measure of central tendency that resists outliers better than the mean."
+        },
+        {
+            "question": "How are NaN values handled?",
+            "answer": "Use `'omitnan'` to ignore `NaN` entries. The default `'includenan'` propagates `NaN` if any element in the slice is `NaN`."
+        },
+        {
+            "question": "Does `median` convert logical values?",
+            "answer": "Yes. Logical arrays are converted to double precision before the median is taken, matching MATLAB."
+        },
+        {
+            "question": "What happens with even-length slices?",
+            "answer": "Even-length slices return the arithmetic mean of the two middle values after sorting, matching MATLAB behaviour."
+        },
+        {
+            "question": "Can I compute the median along a specific dimension?",
+            "answer": "Yes. Pass a dimension index (`>= 1`) as the second argument: `median(A, 2)` reduces across rows."
+        },
+        {
+            "question": "What if I ask for a dimension larger than `ndims(A)`?",
+            "answer": "RunMat treats trailing dimensions as having size 1, so the result is the original array unchanged."
+        },
+        {
+            "question": "Does `median` fully execute on the GPU today?",
+            "answer": "When the active provider implements the `reduce_median*` hooks (e.g., the WGPU backend), the reduction stays on the device. Otherwise the runtime gathers to the CPU to guarantee MATLAB-compatible semantics."
+        }
+    ],
+    "links": [
+        {
+            "label": "mean",
+            "url": "./mean"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "prod",
+            "url": "./prod"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "all",
+            "url": "./all"
+        },
+        {
+            "label": "any",
+            "url": "./any"
+        },
+        {
+            "label": "cummax",
+            "url": "./cummax"
+        },
+        {
+            "label": "cummin",
+            "url": "./cummin"
+        },
+        {
+            "label": "cumprod",
+            "url": "./cumprod"
+        },
+        {
+            "label": "cumsum",
+            "url": "./cumsum"
+        },
+        {
+            "label": "diff",
+            "url": "./diff"
+        },
+        {
+            "label": "max",
+            "url": "./max"
+        },
+        {
+            "label": "min",
+            "url": "./min"
+        },
+        {
+            "label": "nnz",
+            "url": "./nnz"
+        },
+        {
+            "label": "std",
+            "url": "./std"
+        },
+        {
+            "label": "var",
+            "url": "./var"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/reduction/median.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/reduction/median.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the fusion planner keeps residency on GPU in branches of fused expressions. As such, in the above example, the result of the `median` call will already be on the GPU when the fusion planner has detected a net benefit to operating the fused expression it is part of on the GPU.\n\nTo preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call `gpuArray` explicitly to move data to the GPU if you want to be explicit about the residency.\n\nSince MathWorks MATLAB does not have a fusion planner, and they kept their parallel execution toolbox separate from the core language, as their toolbox is a separate commercial product, MathWorks MATLAB users need to call `gpuArray` to move data to the GPU manually whereas RunMat users can rely on the fusion planner to keep data on the GPU automatically.",
+    "gpu_behavior": [
+        "When RunMat Accelerate is active, tensors that already live on the GPU remain on the device. The runtime asks providers for a dedicated median reduction. If the provider cannot supply one or cannot honour `omitnan`, RunMat gathers GPU data back to the host and executes the CPU path to preserve MATLAB semantics (including even-length averaging and ordering ties)."
+    ],
+    "key": "median",
+    "slug": "median",
+    "categoryPath": [
+        "math",
+        "reduction"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=median.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"median.js","sourceRoot":"","sources":["../../../src/generated/builtins/median.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,QAAQ;IACjB,UAAU,EAAE,gBAAgB;IAC5B,UAAU,EAAE;QACV,QAAQ;QACR,WAAW;QACX,SAAS;QACT,YAAY;QACZ,YAAY;QACZ,KAAK;KACN;IACD,SAAS,EAAE,uDAAuD;IAClE,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,IAAI;QACjB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,2GAA2G;KACrH;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,0CAA0C;QAClD,aAAa,EAAE,yEAAyE;KACzF;IACD,aAAa,EAAE,gMAAgM;IAC/M,WAAW,EAAE;QACX,gGAAgG;QAChG,8EAA8E;QAC9E,8EAA8E;QAC9E,mKAAmK;QACnK,iFAAiF;QACjF,4GAA4G;QAC5G,gGAAgG;QAChG,8FAA8F;QAC9F,mFAAmF;QACnF,8DAA8D;KAC/D;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,iCAAiC;YAC1C,QAAQ,EAAE,OAAO;SAClB;QACD;YACE,aAAa,EAAE,8DAA8D;YAC7E,OAAO,EAAE,gCAAgC;YACzC,QAAQ,EAAE,SAAS;SACpB;QACD;YACE,aAAa,EAAE,gCAAgC;YAC/C,OAAO,EAAE,qDAAqD;YAC9D,QAAQ,EAAE,sBAAsB;SACjC;QACD;YACE,aAAa,EAAE,uCAAuC;YACtD,OAAO,EAAE,+DAA+D;YACxE,QAAQ,EAAE,uBAAuB;SAClC;QACD;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,sDAAsD;YAC/D,QAAQ,EAAE,eAAe;SAC1B;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,6FAA6F;SACvG;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,6GAA6G;SACxH;QACD;YACE,UAAU,EAAE,6BAA6B;YACzC,QAAQ,EAAE,4HAA4H;SACvI;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,oGAAoG;SAC/G;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,kHAAkH;SAC7H;QACD;YACE,UAAU,EAAE,sDAAsD;YAClE,QAAQ,EAAE,kGAAkG;SAC7G;QACD;YACE,UAAU,EAAE,uDAAuD;YACnE,QAAQ,EAAE,oGAAoG;SAC/G;QACD;YACE,UAAU,EAAE,+CAA+C;YAC3D,QAAQ,EAAE,gNAAgN;SAC3N;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;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;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,+DAA+D;QACxE,KAAK,EAAE,4GAA4G;KACpH;IACD,eAAe,EAAE,i8BAAi8B;IACl9B,cAAc,EAAE;QACd,8WAA8W;KAC/W;IACD,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,cAAc,EAAE;QACd,MAAM;QACN,WAAW;KACZ;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/mesh.js

@@ -0,0 +1,90 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "mesh",
+    "category": "plotting",
+    "keywords": [
+        "mesh",
+        "wireframe plot",
+        "wireframe surface",
+        "matlab mesh",
+        "3-D grid visualization"
+    ],
+    "summary": "Create wireframe surface plots for grids, height fields, and MATLAB `mesh` style visualization.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`mesh` reuses the shared surface pipeline with wireframe-oriented rendering semantics."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::mesh::tests"
+    },
+    "description": "`mesh` creates wireframe surface plots from vector axes or meshgrid-style coordinates plus a height grid. In RunMat it shares the same surface/object infrastructure as `surf`, but presents the data as a wireframe-style surface rather than a shaded filled surface, matching MATLAB `mesh` expectations.",
+    "behaviors": [
+        "`mesh(Z)` uses implicit axes, while `mesh(X, Y, Z)` accepts vector axes or meshgrid-style coordinate matrices.",
+        "The builtin returns a surface handle, so mesh plots can still be inspected through the graphics-object system.",
+        "`mesh` is the wireframe-oriented companion to `surf`; for combined wireframe plus contour overlays, use `meshc`.",
+        "RunMat uses the shared surface pipeline for mesh rendering, so view, z-axis labeling, and subplot-local state behave consistently across the surface family.",
+        "GPU-backed rendering is preferred when the plotting device can consume exported buffers directly."
+    ],
+    "examples": [
+        {
+            "description": "Create a wireframe mesh from a height field",
+            "input": "[X, Y] = meshgrid(linspace(-2, 2, 60), linspace(-2, 2, 60));\nZ = sin(X.^2 + Y.^2);\nmesh(X, Y, Z);"
+        },
+        {
+            "description": "Compare wireframe presentation with subplot-local state",
+            "input": "subplot(1, 2, 1);\n[X, Y] = meshgrid(linspace(-2, 2, 40), linspace(-2, 2, 40));\nZ = cos(X) .* sin(Y);\nmesh(X, Y, Z);\nview(3);\nsubplot(1, 2, 2);\nsurf(X, Y, Z);\nview(3);"
+        },
+        {
+            "description": "Inspect the returned surface handle from mesh",
+            "input": "[X, Y] = meshgrid(1:20, 1:20);\nZ = X + Y;\nh = mesh(X, Y, Z);\nget(h, 'Type')",
+            "output": "ans =\n    'surface'"
+        }
+    ],
+    "links": [
+        {
+            "label": "surf",
+            "url": "./surf"
+        },
+        {
+            "label": "meshc",
+            "url": "./meshc"
+        },
+        {
+            "label": "view",
+            "url": "./view"
+        },
+        {
+            "label": "zlabel",
+            "url": "./zlabel"
+        },
+        {
+            "label": "colormap",
+            "url": "./colormap"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/mesh.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/mesh.rs"
+    },
+    "key": "mesh",
+    "slug": "mesh",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=mesh.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.js","sourceRoot":"","sources":["../../../src/generated/builtins/mesh.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,MAAM;QACN,gBAAgB;QAChB,mBAAmB;QACnB,aAAa;QACb,wBAAwB;KACzB;IACD,SAAS,EAAE,iGAAiG;IAC5G,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,wFAAwF;KAClG;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,iCAAiC;KAC1C;IACD,aAAa,EAAE,8SAA8S;IAC7T,WAAW,EAAE;QACX,gHAAgH;QAChH,gHAAgH;QAChH,kHAAkH;QAClH,8JAA8J;QAC9J,mGAAmG;KACpG;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,qGAAqG;SAC/G;QACD;YACE,aAAa,EAAE,yDAAyD;YACxE,OAAO,EAAE,+KAA+K;SACzL;QACD;YACE,aAAa,EAAE,+CAA+C;YAC9D,OAAO,EAAE,gFAAgF;YACzF,QAAQ,EAAE,sBAAsB;SACjC;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,2DAA2D;QACpE,KAAK,EAAE,wGAAwG;KAChH;IACD,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/meshc.js

@@ -0,0 +1,90 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "meshc",
+    "category": "plotting",
+    "keywords": [
+        "meshc",
+        "mesh with contour",
+        "wireframe contour plot",
+        "composite mesh plot",
+        "matlab meshc"
+    ],
+    "summary": "Create composite wireframe-and-contour plots for scalar fields with MATLAB `meshc` semantics and contour overlays.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`meshc` combines the shared wireframe surface path with the modern contour path instead of using a parallel legacy composite implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::meshc::tests"
+    },
+    "description": "`meshc` combines a `mesh`-style wireframe surface with contour lines projected onto the base plane. In RunMat the returned handle is the primary surface handle for the wireframe component, while the contour overlay is attached as the secondary composite plot content.",
+    "behaviors": [
+        "`meshc` shares the same wireframe surface semantics as `mesh` for the primary surface object.",
+        "The returned handle is the surface handle for the wireframe component of the composite.",
+        "Contour overlays are produced through the shared contour path.",
+        "View state, colormaps, and subplot-local metadata all flow through the shared axes model.",
+        "GPU-aware execution applies where supported to both the surface and contour sides of the composite."
+    ],
+    "examples": [
+        {
+            "description": "Create a wireframe surface with contour overlays",
+            "input": "[X, Y] = meshgrid(linspace(-2, 2, 50), linspace(-2, 2, 50));\nZ = sin(X.^2 + Y.^2);\nmeshc(X, Y, Z);"
+        },
+        {
+            "description": "Compare wireframe/composite behavior with camera controls",
+            "input": "[X, Y] = meshgrid(linspace(-3, 3, 60), linspace(-3, 3, 60));\nZ = cos(X) .* sin(Y);\nh = meshc(X, Y, Z);\nview(3);\ncolormap('parula');"
+        },
+        {
+            "description": "Inspect the returned primary surface handle",
+            "input": "[X, Y] = meshgrid(1:20, 1:20);\nZ = X - Y;\nh = meshc(X, Y, Z);\nget(h, 'Type')",
+            "output": "ans =\n    'surface'"
+        }
+    ],
+    "links": [
+        {
+            "label": "mesh",
+            "url": "./mesh"
+        },
+        {
+            "label": "surfc",
+            "url": "./surfc"
+        },
+        {
+            "label": "contour",
+            "url": "./contour"
+        },
+        {
+            "label": "contourf",
+            "url": "./contourf"
+        },
+        {
+            "label": "view",
+            "url": "./view"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/meshc.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/meshc.rs"
+    },
+    "key": "meshc",
+    "slug": "meshc",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=meshc.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meshc.js","sourceRoot":"","sources":["../../../src/generated/builtins/meshc.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,OAAO;QACP,mBAAmB;QACnB,wBAAwB;QACxB,qBAAqB;QACrB,cAAc;KACf;IACD,SAAS,EAAE,oHAAoH;IAC/H,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,8IAA8I;KACxJ;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,kCAAkC;KAC3C;IACD,aAAa,EAAE,6QAA6Q;IAC5R,WAAW,EAAE;QACX,+FAA+F;QAC/F,yFAAyF;QACzF,gEAAgE;QAChE,2FAA2F;QAC3F,qGAAqG;KACtG;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,kDAAkD;YACjE,OAAO,EAAE,sGAAsG;SAChH;QACD;YACE,aAAa,EAAE,2DAA2D;YAC1E,OAAO,EAAE,yIAAyI;SACnJ;QACD;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,iFAAiF;YAC1F,QAAQ,EAAE,sBAAsB;SACjC;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,4DAA4D;QACrE,KAAK,EAAE,yGAAyG;KACjH;IACD,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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