runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/ones.js

@@ -0,0 +1,191 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ones",
+    "category": "array/creation",
+    "keywords": [
+        "ones",
+        "array",
+        "logical",
+        "gpu",
+        "like"
+    ],
+    "summary": "Create arrays filled with ones within the MATLAB language.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider one-allocation hooks when available; otherwise fills via scalar add or uploads from the host."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::ones::tests",
+        "integration": "builtins::array::ones::tests::ones_gpu_like_alloc"
+    },
+    "description": "`ones` creates arrays filled with ones. RunMat mirrors MATLAB semantics across the scalar, vector, matrix, and N-D forms, including `'like'` and `'logical'` options.",
+    "behaviors": [
+        "`ones()` returns the scalar `1`.",
+        "`ones(n)` returns an `n × n` double array.",
+        "`ones(m, n, ...)` returns a dense double array with the requested dimensions.",
+        "`ones(sz)` accepts a size vector (row or column) and returns an array with `prod(sz)` elements arranged using MATLAB column-major ordering.",
+        "`ones(A)` returns an array of ones with the same size (and device residency) as `A`.",
+        "`ones(___, 'logical')` returns a logical array instead of double precision (all elements set to `true`).",
+        "`ones(___, 'like', prototype)` matches the device residency and numeric/logical flavour of `prototype`."
+    ],
+    "examples": [
+        {
+            "description": "Creating a 3x3 matrix of ones",
+            "input": "B = ones(3)",
+            "output": "B = [1 1 1; 1 1 1; 1 1 1]"
+        },
+        {
+            "description": "Creating a 4x1 logical matrix of ones",
+            "input": "mask = ones(4, 1, 'logical')",
+            "output": "mask = [1 1 1 1]"
+        },
+        {
+            "description": "Creating a 64x64 matrix of ones on a GPU",
+            "input": "H = ones(64, 64)",
+            "output": "H = [1 1 1 ... 1; 1 1 1 ... 1; ...; 1 1 1 ... 1]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I use the `ones` function?",
+            "answer": "Use `ones` whenever you need to create arrays pre-filled with the value `1`, such as for initializing weights, creating masks, or testing other algorithms. Preallocating with `ones` ensures correct type and shape throughout your code and helps prevent bugs caused by uninitialized arrays."
+        },
+        {
+            "question": "Does `ones` produce double arrays by default?",
+            "answer": "Yes, by default, `ones` creates dense double-precision arrays unless you explicitly specify a type such as `'logical'` or use the `'like'` argument to match a prototype array."
+        },
+        {
+            "question": "What does `ones(n)` return?",
+            "answer": "`ones(n)` returns an `n × n` dense double-precision matrix filled with ones. For example, `ones(3)` yields a 3-by-3 matrix of all ones."
+        },
+        {
+            "question": "How do I create a logical array of ones?",
+            "answer": "Pass `'logical'` as the last argument:\n```matlab:runnable\nmask = ones(5, 1, 'logical');\n```\nThis produces a 5x1 logical array, i.e., all elements have value `true` (`1` in binary)."
+        },
+        {
+            "question": "How do I match the type and device residency of an existing array?",
+            "answer": "Use the `'like', prototype` syntax:\n```matlab:runnable\nA = gpuArray(rand(2,2));\nB = ones(2, 2, 'like', A);\n```\n`B` will be a GPU array with the same type and shape as `A`."
+        },
+        {
+            "question": "Can I create N-dimensional arrays with ones?",
+            "answer": "Yes! Pass more than two dimension arguments (or a size vector):\n```matlab:runnable\nT = ones(2, 3, 4);\n```\nThis creates a 2×3×4 tensor of ones."
+        },
+        {
+            "question": "How does `ones(A)` behave?",
+            "answer": "If you call `ones(A)`, where `A` is an array, the result is a new array of ones with the same shape as `A`."
+        },
+        {
+            "question": "Is the output always dense?",
+            "answer": "Yes. `ones` always produces a dense array. For sparse matrices of ones, use `sparse` with appropriate arguments."
+        },
+        {
+            "question": "What if I call `ones` with no arguments?",
+            "answer": "`ones()` returns the scalar value `1`."
+        },
+        {
+            "question": "Can I use `ones` to preallocate arrays for later assignment?",
+            "answer": "Absolutely. Preallocating with `ones` (or `zeros`) and then filling in values is a recommended practice for efficiency and code clarity when the final values are known to overwrite the initial ones."
+        }
+    ],
+    "links": [
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        },
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "colon",
+            "url": "./colon"
+        },
+        {
+            "label": "false",
+            "url": "./false"
+        },
+        {
+            "label": "fill",
+            "url": "./fill"
+        },
+        {
+            "label": "linspace",
+            "url": "./linspace"
+        },
+        {
+            "label": "logspace",
+            "url": "./logspace"
+        },
+        {
+            "label": "magic",
+            "url": "./magic"
+        },
+        {
+            "label": "meshgrid",
+            "url": "./meshgrid"
+        },
+        {
+            "label": "rand",
+            "url": "./rand"
+        },
+        {
+            "label": "randi",
+            "url": "./randi"
+        },
+        {
+            "label": "randn",
+            "url": "./randn"
+        },
+        {
+            "label": "randperm",
+            "url": "./randperm"
+        },
+        {
+            "label": "range",
+            "url": "./range"
+        },
+        {
+            "label": "true",
+            "url": "./true"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/creation/ones.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/ones.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 `ones` 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 prototype or `'like'` argument is a GPU tensor, RunMat asks the active acceleration provider to allocate a one-filled buffer. Acceleration providers that do not yet support the dedicated hooks fall back to zero-allocation plus scalar fill or, as a last resort, upload a host tensor. This guarantees correct behaviour."
+    ],
+    "key": "ones",
+    "slug": "ones",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ones.js.map

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

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

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

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

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

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

package/dist/generated/builtins/or.js

@@ -0,0 +1,136 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "or",
+    "category": "logical/bit",
+    "keywords": [
+        "logical or",
+        "elementwise or",
+        "boolean or",
+        "MATLAB or",
+        "gpuArray or"
+    ],
+    "summary": "Element-wise logical OR for scalars, arrays, and gpuArray values.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Runs entirely on the GPU when the active provider implements `logical_or`; otherwise inputs gather back to the host automatically."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::logical::bit::or::tests",
+        "integration": "builtins::logical::bit::or::tests::or_gpu_roundtrip",
+        "gpu": "builtins::logical::bit::or::tests::or_wgpu_matches_host_path"
+    },
+    "description": "`or(A, B)` returns the element-wise logical OR of its inputs. Any non-zero value (including `NaN`) evaluates to `true`. The result is a logical scalar when the broadcasted shape has exactly one element, or a logical array otherwise.",
+    "behaviors": [
+        "Accepts logical, numeric, complex, and character arrays; character code points of zero evaluate to `false`.",
+        "Supports MATLAB-style implicit expansion so scalars and singleton dimensions broadcast automatically.",
+        "Propagates empty dimensions: if a broadcasted axis has length `0`, the output is an empty logical array with the same shape.",
+        "Treats `NaN` values as `true`, matching MATLAB's element-wise logical semantics.",
+        "Keeps `gpuArray` inputs on device when the active provider exposes the `logical_or` hook; otherwise the runtime gathers to host transparently."
+    ],
+    "examples": [
+        {
+            "description": "Check if either logical scalar is true",
+            "input": "result = or(true, false)",
+            "output": "result =\n     1"
+        },
+        {
+            "description": "Combine numeric arrays element-wise with logical OR",
+            "input": "A = [1 0 2 0];\nB = [3 4 0 0];\nC = or(A, B)",
+            "output": "C =\n  1×4 logical array\n     1     1     1     0"
+        },
+        {
+            "description": "Apply logical OR with automatic scalar expansion",
+            "input": "mask = [1; 0; 3; 0];\nflag = or(mask, 0)",
+            "output": "flag =\n  4×1 logical array\n     1\n     0\n     1\n     0"
+        },
+        {
+            "description": "Use logical OR with character arrays",
+            "input": "lhs = ['R' 'u' 0];\nrhs = ['R' 0 'n'];\nmatch = or(lhs, rhs)",
+            "output": "match =\n  1×3 logical array\n     1     1     1"
+        },
+        {
+            "description": "Run logical OR directly on the GPU",
+            "input": "G1 = gpuArray([0 2 0 4]);\nG2 = gpuArray([1 0 3 0]);\ndeviceResult = or(G1, G2)\nhostResult = gather(deviceResult)",
+            "output": "deviceResult =\n  1×4 gpuArray logical array\n     1     1     1     1\nhostResult =\n  1×4 logical array\n     1     1     1     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `or` return logical values?",
+            "answer": "Yes. The result is a logical scalar (`true`/`false`) when the broadcasted shape contains exactly one element; otherwise the function returns a logical array. On the GPU the kernel writes `0.0`/`1.0` elements, and the runtime converts them back to logical values when you gather."
+        },
+        {
+            "question": "How are `NaN` values handled?",
+            "answer": "`NaN` counts as `true`. For example, `or(NaN, 0)` returns `true` because at least one operand evaluates to non-zero."
+        },
+        {
+            "question": "Is implicit expansion supported?",
+            "answer": "Yes. The inputs follow MATLAB-style implicit expansion rules: dimensions of length `1` broadcast across the other input. Fully incompatible shapes raise a size-mismatch error."
+        },
+        {
+            "question": "Can I use `or` with complex numbers?",
+            "answer": "Yes. Real or complex inputs return `true` when either the real or imaginary component is non-zero. For example, `or(0 + 0i, 0 + 2i)` returns `true`."
+        },
+        {
+            "question": "How does `or` differ from the `|` operator?",
+            "answer": "They share the same element-wise semantics. The functional form is convenient for higher-order code (for example, `arrayfun(@or, ...)`) and for aligning with MATLAB documentation. Use `&&` or `||` for short-circuit scalar logic."
+        },
+        {
+            "question": "What happens when only one input is a `gpuArray`?",
+            "answer": "RunMat promotes the other input to the GPU before dispatch when the auto-offload planner decides it is profitable. If the provider lacks a device implementation, both operands gather to host automatically and the logical result executes on the CPU."
+        }
+    ],
+    "links": [
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "and",
+            "url": "./and"
+        },
+        {
+            "label": "not",
+            "url": "./not"
+        },
+        {
+            "label": "xor",
+            "url": "./xor"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/logical/bit/or.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/logical/bit/or.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's native auto-offload logic moves data to the GPU when a fused expression benefits from device execution, and results stay resident until you gather them or the planner needs host access. Call `gpuArray` only when you want to seed residency manually, or when you are porting MATLAB code that already uses explicit device transfers.",
+    "gpu_behavior": [
+        "When both operands reside on the GPU and the active provider implements the `logical_or` hook, RunMat lowers the call into a device kernel that writes `0` or `1` for each element. The fusion planner treats `or` as an element-wise operation, so fused expressions (for example, `or(A > 0, B)`) stay on device without intermediate gathers. If the provider lacks the hook, the runtime gathers the inputs to host memory automatically and executes the CPU implementation instead of failing."
+    ],
+    "key": "or",
+    "slug": "or",
+    "categoryPath": [
+        "logical",
+        "bit"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=or.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"or.js","sourceRoot":"","sources":["../../../src/generated/builtins/or.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,aAAa;IACzB,UAAU,EAAE;QACV,YAAY;QACZ,gBAAgB;QAChB,YAAY;QACZ,WAAW;QACX,aAAa;KACd;IACD,SAAS,EAAE,mEAAmE;IAC9E,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,oIAAoI;KAC9I;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,mCAAmC;QAC3C,aAAa,EAAE,qDAAqD;QACpE,KAAK,EAAE,8DAA8D;KACtE;IACD,aAAa,EAAE,0OAA0O;IACzP,WAAW,EAAE;QACX,6GAA6G;QAC7G,uGAAuG;QACvG,8HAA8H;QAC9H,kFAAkF;QAClF,gJAAgJ;KACjJ;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,0BAA0B;YACnC,QAAQ,EAAE,kBAAkB;SAC7B;QACD;YACE,aAAa,EAAE,qDAAqD;YACpE,OAAO,EAAE,8CAA8C;YACvD,QAAQ,EAAE,oDAAoD;SAC/D;QACD;YACE,aAAa,EAAE,kDAAkD;YACjE,OAAO,EAAE,0CAA0C;YACnD,QAAQ,EAAE,6DAA6D;SACxE;QACD;YACE,aAAa,EAAE,sCAAsC;YACrD,OAAO,EAAE,8DAA8D;YACvE,QAAQ,EAAE,kDAAkD;SAC7D;QACD;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,oHAAoH;YAC7H,QAAQ,EAAE,qIAAqI;SAChJ;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,wRAAwR;SACnS;QACD;YACE,UAAU,EAAE,+BAA+B;YAC3C,QAAQ,EAAE,sHAAsH;SACjI;QACD;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,iLAAiL;SAC5L;QACD;YACE,UAAU,EAAE,sCAAsC;YAClD,QAAQ,EAAE,sJAAsJ;SACjK;QACD;YACE,UAAU,EAAE,6CAA6C;YACzD,QAAQ,EAAE,sOAAsO;SACjP;QACD;YACE,UAAU,EAAE,mDAAmD;YAC/D,QAAQ,EAAE,0PAA0P;SACrQ;KACF;IACD,OAAO,EAAE;QACP;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,KAAK;YACd,KAAK,EAAE,OAAO;SACf;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,wDAAwD;QACjE,KAAK,EAAE,qGAAqG;KAC7G;IACD,eAAe,EAAE,+YAA+Y;IACha,cAAc,EAAE;QACd,seAAse;KACve;IACD,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,cAAc,EAAE;QACd,SAAS;QACT,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/orderfields.js

@@ -0,0 +1,156 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "orderfields",
+    "category": "structs/core",
+    "keywords": [
+        "orderfields",
+        "struct",
+        "reorder fields",
+        "alphabetical",
+        "struct array",
+        "field order"
+    ],
+    "summary": "Reorder structure field definitions alphabetically or according to a custom order.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host. When structs contain GPU-resident values, those handles remain on the device."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::structs::core::orderfields::tests",
+        "integration": null
+    },
+    "description": "`orderfields(S)` reorders the field definitions of a scalar struct or struct array. By default the fields are sorted alphabetically. Optional arguments let you match the order of another struct, provide an explicit list of names, or supply a permutation vector.",
+    "behaviors": [
+        "Works with scalar structs and struct arrays (RunMat stores struct arrays internally as cell arrays of structs).",
+        "The default behaviour `orderfields(S)` sorts field names alphabetically using MATLAB's case-insensitive ordering.",
+        "`orderfields(S, referenceStruct)` matches the order of `referenceStruct`. Both structs must contain the same field names.",
+        "`orderfields(S, {'b','a','c'})` or `orderfields(S, string(['b','a','c']))` uses the supplied list of field names.",
+        "`orderfields(S, [2 1 3])` reorders fields using a permutation vector that references the current field order.",
+        "`[T, P] = orderfields(S, ___)` returns the reordered struct (or struct array) `T` and a permutation vector `P` whose elements are the original 1-based field positions. Reuse `P` to apply the same order to other structs that share the field set.",
+        "The function never copies field contents unnecessarily—values (including GPU handles) are re-used and remain resident.",
+        "Errors are raised when requested field names do not match the struct, when indices are invalid, or when the input is not a struct."
+    ],
+    "examples": [
+        {
+            "description": "How to sort struct fields alphabetically",
+            "input": "s = struct(\"beta\", 2, \"alpha\", 1, \"gamma\", 3);\nt = orderfields(s);\nfieldnames(t)",
+            "output": "ans =\n    {'alpha'}\n    {'beta'}\n    {'gamma'}"
+        },
+        {
+            "description": "Match the field order of another struct",
+            "input": "source = struct(\"y\", 20, \"x\", 10);\ntemplate = struct(\"x\", 0, \"y\", 0);\n[aligned, order] = orderfields(source, template)"
+        },
+        {
+            "description": "Reorder fields with a cell array of names",
+            "input": "s = struct(\"a\", 1, \"b\", 2, \"c\", 3);\nu = orderfields(s, {\"c\", \"a\", \"b\"});\nfieldnames(u)",
+            "output": "ans =\n    {'c'}\n    {'a'}\n    {'b'}"
+        },
+        {
+            "description": "Reorder fields with an index vector",
+            "input": "s = struct(\"first\", 1, \"second\", 2, \"third\", 3);\npermuted = orderfields(s, [3 1 2]);\nfieldnames(permuted)",
+            "output": "ans =\n    {'third'}\n    {'first'}\n    {'second'}"
+        },
+        {
+            "description": "Apply a custom order to every element of a struct array",
+            "input": "records = struct(\"name\", {\"Ada\", \"Grace\"}, \"id\", {101, 102});\n[reordered, perm] = orderfields(records, {\"id\", \"name\"});\n{reordered.id}",
+            "output": "ans =\n    {[101]}    {[102]}"
+        },
+        {
+            "description": "Sort fields in descending alphabetical order",
+            "input": "s = struct(\"alpha\", 1, \"delta\", 4, \"beta\", 2);\nnames = string(fieldnames(s));\ndesc = orderfields(s, flip(names));\nfieldnames(desc)",
+            "output": "ans =\n    {'delta'}\n    {'beta'}\n    {'alpha'}"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What argument forms does `orderfields` accept?",
+            "answer": "You can pass a reference struct (scalar or struct array), a cell array or string array of field names, or a numeric permutation vector. Every variant must reference each existing field exactly once."
+        },
+        {
+            "question": "Does the reference struct have to contain the same fields?",
+            "answer": "Yes. RunMat mirrors MATLAB and requires that the reference struct contain exactly the same field names. Missing or extra fields raise an error."
+        },
+        {
+            "question": "Can I reorder struct arrays?",
+            "answer": "Yes. Every element in the struct array is reordered using the same field order. The array must contain structs only."
+        },
+        {
+            "question": "How are numeric vectors interpreted?",
+            "answer": "Numeric vectors are treated as permutations of the current field order. Values must be positive integers that reference each existing field exactly once."
+        },
+        {
+            "question": "What happens when I pass duplicate field names?",
+            "answer": "Duplicates are rejected with an error. Every field must appear exactly once in the requested order."
+        },
+        {
+            "question": "Does `orderfields` gather GPU data back to the CPU?",
+            "answer": "No. The builtin only reorders metadata in the struct. GPU handles remain on the device and are not touched."
+        },
+        {
+            "question": "Can I reorder an empty struct array?",
+            "answer": "Empty struct arrays are returned unchanged. Because RunMat stores field metadata per element, you must supply at least one element before an explicit order can be derived."
+        },
+        {
+            "question": "How do I maintain the existing order?",
+            "answer": "Capture the permutation output once: `[~, P] = orderfields(S);`. You can later call `orderfields(S, P)` (or apply the same `P` to another struct with identical fields) to reapply the original order."
+        },
+        {
+            "question": "Does `orderfields` affect nested structs?",
+            "answer": "Only the top-level struct passed to `orderfields` is reordered. Nested structs retain their current order."
+        }
+    ],
+    "links": [
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "fieldnames",
+            "url": "./fieldnames"
+        },
+        {
+            "label": "getfield",
+            "url": "./getfield"
+        },
+        {
+            "label": "setfield",
+            "url": "./setfield"
+        },
+        {
+            "label": "rmfield",
+            "url": "./rmfield"
+        },
+        {
+            "label": "isfield",
+            "url": "./isfield"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/structs/core/orderfields.rs",
+        "url": "crates/runmat-runtime/src/builtins/structs/core/orderfields.rs"
+    },
+    "gpu_residency": "No. Struct field reordering never moves or converts the values stored inside the struct. Existing GPU handles remain on the device. You can freely combine `orderfields` with `gpuArray`, `gather`, or auto-offload features without affecting residency.",
+    "gpu_behavior": [
+        "`orderfields` operates on host-side struct metadata only. When a struct contains GPU tensors or handles, the handles remain valid and resident on the device. No kernels are dispatched and no data is gathered or copied between host and device."
+    ],
+    "key": "orderfields",
+    "slug": "orderfields",
+    "categoryPath": [
+        "structs",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=orderfields.js.map

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

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

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

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

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

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