runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/filewrite.js

@@ -0,0 +1,161 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "filewrite",
+    "category": "io/filetext",
+    "keywords": [
+        "filewrite",
+        "io",
+        "write file",
+        "text file",
+        "append",
+        "encoding"
+    ],
+    "summary": "Write text or raw bytes to a file with optional encoding and write-mode control.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/filewrite.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Executes entirely on the host CPU. When either the file path or data reside on the GPU they are gathered before the write; providers are not involved."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::filewrite::tests",
+        "integration": "builtins::io::filetext::filewrite::tests::filewrite_writes_text_content"
+    },
+    "description": "`filewrite(filename, data)` writes text or raw byte content to a file, returning the number of bytes written. The builtin honours MATLAB semantics for overwrite versus append behaviour and supports the same encoding keywords that `fileread` recognises.",
+    "behaviors": [
+        "Accepts file names supplied as character vectors, string scalars, or scalar string arrays.",
+        "Accepts data supplied as character vectors, string scalars, string arrays, or numeric arrays of bytes (`uint8`/`double` values in the range 0–255). Logical arrays map to bytes `0` and `1`.",
+        "By default the file is truncated (overwrite mode). Pass `'WriteMode','append'` to add to an existing file.",
+        "Encoding is optional. Provide either a positional encoding argument or the `'Encoding', value` keyword pair. Supported encodings mirror `fileread`: `auto` (default), `utf-8`, `ascii`, `latin1`, and `raw`.",
+        "When writing text data with `filewrite` and `Encoding` set to `ascii` or `latin1`, an error is raised if any characters fall outside the permitted code page.",
+        "When writing raw numeric bytes, encoding is ignored except to validate ASCII requests.",
+        "Returns the number of bytes written as a double scalar. Ignoring the output behaves like MATLAB (data is still written)."
+    ],
+    "examples": [
+        {
+            "description": "Write Text To A New File",
+            "input": "bytes = filewrite(\"notes.txt\", \"Hello, RunMat!\")",
+            "output": "bytes = 14"
+        },
+        {
+            "description": "Append Text Without Overwriting",
+            "input": "filewrite(\"log.txt\", \"First line\\n\");\nbytes = filewrite(\"log.txt\", \"Second line\\n\", 'WriteMode', 'append')",
+            "output": "bytes = 13"
+        },
+        {
+            "description": "Specify A Particular Encoding",
+            "input": "bytes = filewrite(\"latin1.txt\", ['E' 's' 'p' 'a' char(241) 'a'], 'Encoding', 'latin1')",
+            "output": "bytes = 6"
+        },
+        {
+            "description": "Write Raw Bytes From A Numeric Array",
+            "input": "payload = [1 2 3 255];\nbytes = filewrite(\"data.bin\", payload, 'Encoding', 'raw')",
+            "output": "bytes = 4"
+        },
+        {
+            "description": "Export A String Array As Newline-Separated Text",
+            "input": "lines = [\"alpha\", \"beta\", \"gamma\"];\nbytes = filewrite(\"items.txt\", lines)",
+            "output": "bytes = 16"
+        },
+        {
+            "description": "Handle Invalid ASCII Characters",
+            "input": "try\n    filewrite(\"ascii.txt\", ['c' 'a' 'f' char(233)], 'Encoding', 'ascii');\ncatch err\n    disp(err.message);\nend",
+            "output": "filewrite: character 'é' (U+00E9) cannot be encoded as ASCII"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `filewrite` return?",
+            "answer": "It returns the number of bytes written as a double scalar. Omit the output argument when you do not need this information."
+        },
+        {
+            "question": "How are string arrays written?",
+            "answer": "Each element of the string array is written sequentially (column-major order), separated by newline characters. This mirrors MATLAB’s `filewrite` behaviour and matches what most users expect when exporting string arrays."
+        },
+        {
+            "question": "Does `filewrite` add a newline automatically?",
+            "answer": "No. Provide explicit newline characters (`\\n`) when you want line breaks. Appending mode (`'WriteMode','append'`) does not insert separators automatically."
+        },
+        {
+            "question": "How can I write binary data?",
+            "answer": "Provide a numeric array with values in the range 0–255 (for example `uint8`). Use `'Encoding','raw'` (or rely on the default) to bypass text encoding."
+        },
+        {
+            "question": "What happens if the file cannot be opened?",
+            "answer": "`filewrite` throws a descriptive error containing the system message (for example, permissions or directory-not-found issues)."
+        },
+        {
+            "question": "Does the builtin create directories?",
+            "answer": "No. The parent directory must already exist. Use `mkdir` before calling `filewrite` if you need to create folders."
+        }
+    ],
+    "links": [
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "string",
+            "url": "./string"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/filetext/filewrite.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/filetext/filewrite.rs"
+    },
+    "gpu_behavior": [
+        "`filewrite` performs synchronous host file I/O. If either the path or data reside on the GPU (for example through lazy residency), RunMat gathers those values before performing the write. No GPU kernels are launched and providers do not need to implement specialised hooks for this builtin."
+    ],
+    "key": "filewrite",
+    "slug": "filewrite",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=filewrite.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fill.js

@@ -0,0 +1,231 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fill",
+    "category": "array/creation",
+    "keywords": [
+        "fill",
+        "constant",
+        "array",
+        "gpu",
+        "like"
+    ],
+    "summary": "Create MATLAB arrays filled with a constant value.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses provider fill hooks for constant buffers; falls back to host upload when unavailable."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "uniform"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::creation::fill::tests",
+        "integration": "builtins::array::creation::fill::tests::fill_gpu_like_alloc"
+    },
+    "description": "`fill(value, size, ...)` constructs dense MATLAB arrays whose entries are all the supplied `value`. It aligns with the MATLAB-compatible RunMat array creation suite (`zeros`, `ones`, `eye`, etc.) while supporting GPU residency, `'like'` prototypes, and logical/complex outputs.",
+    "behaviors": [
+        "`fill(v)` returns the scalar `v`.",
+        "`fill(v, n)` returns an `n × n` matrix with every element equal to `v`.",
+        "`fill(v, m, n, ...)` supports arbitrary N-D dimensions.",
+        "`fill(v, sz)` accepts a size vector (row or column).",
+        "`fill(v, A)` uses the shape (and default type) of `A`.",
+        "`fill(v, ___, 'logical')` produces a logical array where each element is `v ~= 0`.",
+        "`fill(v, ___, 'like', prototype)` matches the type, device residency, and shape of `prototype`.",
+        "When a GPU prototype or `'like'` argument is provided, RunMat keeps the result on the device. When provider hooks are incomplete, it falls back to uploading a host tensor to guarantee correctness."
+    ],
+    "examples": [
+        {
+            "description": "Creating a 3x3 matrix of 2.5s",
+            "input": "A = fill(2.5, 3)",
+            "output": "A = [2.5 2.5 2.5; 2.5 2.5 2.5; 2.5 2.5 2.5]"
+        },
+        {
+            "description": "Filling a rectangular matrix with -4",
+            "input": "B = fill(-4, 2, 5)",
+            "output": "B = [-4 -4 -4 -4 -4; -4 -4 -4 -4 -4]"
+        },
+        {
+            "description": "Filling using a size vector",
+            "input": "sz = [2 3 4];\nC = fill(10, sz)",
+            "output": "size(C)  % 2-by-3-by-4"
+        },
+        {
+            "description": "Creating a logical mask with `fill`",
+            "input": "mask = fill(3, 4, 1, 'logical')",
+            "output": "mask = [1; 1; 1; 1]"
+        },
+        {
+            "description": "Matching an existing array with `'like'`",
+            "input": "prototype = rand(2, 3, 'like', gpuArray(1));\nD = fill(pi, 2, 3, 'like', prototype);\ngather(D)",
+            "output": "3.1416 3.1416 3.1416 3.1416 3.1416 3.1416"
+        },
+        {
+            "description": "Filling a complex array",
+            "input": "E = fill(1 + 2i, 2, 2, 'complex')",
+            "output": "E = [1+2i 1+2i; 1+2i 1+2i]"
+        },
+        {
+            "description": "Using a prototype to infer shape automatically",
+            "input": "F = rand(4, 2);\nG = fill(7, F)",
+            "output": "isequal(size(G), [4 2])  % true"
+        },
+        {
+            "description": "Filling an empty matrix",
+            "input": "H = fill(0, 0, 5)",
+            "output": "size(H)  % 0-by-5"
+        },
+        {
+            "description": "Keeping GPU residency without explicit `gpuArray`",
+            "input": "A = rand(512, 512);\nJ = fill(0.5, size(A), 'like', gpuArray(A))",
+            "output": "isa(J, 'gpuArray')  % true"
+        },
+        {
+            "description": "Filling with boolean semantics",
+            "input": "K = fill(false, [2 2], 'logical')",
+            "output": "K = [0 0; 0 0]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which argument order does `fill` support?",
+            "answer": "The first argument is always the scalar value. Remaining arguments specify dimensions, size vectors, or options (`'logical'`, `'like'`, `'double'`, `'complex'`)."
+        },
+        {
+            "question": "Does `fill` accept non-scalar values?",
+            "answer": "No. The fill value must be numeric, logical, or complex scalar. Use `repmat` when you need to tile an array."
+        },
+        {
+            "question": "How does `fill` behave with complex values?",
+            "answer": "If you request complex output (explicitly or via `'like'`), the real and imaginary parts are copied verbatim. Otherwise the imaginary component must be zero."
+        },
+        {
+            "question": "How do logical arrays handle nonzero values?",
+            "answer": "Logical outputs treat any nonzero real or complex magnitude as `true`, matching MATLAB semantics."
+        },
+        {
+            "question": "Can I match GPU residency automatically?",
+            "answer": "Yes. Pass a GPU prototype via `'like'` and `fill` will allocate on the device. It falls back to host allocation and upload when the provider cannot construct the constant directly."
+        },
+        {
+            "question": "What happens when I omit dimensions?",
+            "answer": "If you only pass the value, `fill` returns a scalar. When you pass a prototype (e.g., `fill(v, A)`), the prototype shape is reused. Otherwise RunMat follows MATLAB's default of `1 × 1`."
+        },
+        {
+            "question": "Are string or char outputs supported?",
+            "answer": "Not yet. `fill` currently targets numeric, logical, and complex arrays. Use string-manipulation functions for text."
+        },
+        {
+            "question": "How do I create empty outputs?",
+            "answer": "Include a zero dimension (`fill(value, 0, n)` or `fill(value, [0 n])`). RunMat returns an empty array of the requested size and type."
+        },
+        {
+            "question": "Does `fill` honour `'single'` outputs?",
+            "answer": "Single precision outputs are not implemented yet. The function returns an error mirroring other array creation builtins."
+        },
+        {
+            "question": "Is the GPU path deterministic?",
+            "answer": "Yes. Providers either execute the constant fill entirely on the GPU or RunMat uploads a deterministic host tensor, ensuring identical results."
+        }
+    ],
+    "links": [
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        },
+        {
+            "label": "ones",
+            "url": "./ones"
+        },
+        {
+            "label": "repmat",
+            "url": "./repmat"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "colon",
+            "url": "./colon"
+        },
+        {
+            "label": "eye",
+            "url": "./eye"
+        },
+        {
+            "label": "false",
+            "url": "./false"
+        },
+        {
+            "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/fill.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/fill.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nA = rand(512, 512);\nJ = fill(0.5, size(A), 'like', gpuArray(A));\n```\n\nExpected output:\n\n```matlab\nisa(J, 'gpuArray')  % true\n```",
+    "gpu_behavior": [
+        "RunMat asks the active acceleration provider to materialise the constant directly via the dedicated `fill` hook. Providers that do not supply this capability fall back to a zero buffer plus scalar add or, as a last resort, upload the fully materialised host tensor. This guarantees MATLAB-compatible results while still benefiting from GPU residency whenever possible."
+    ],
+    "key": "fill",
+    "slug": "fill",
+    "categoryPath": [
+        "array",
+        "creation"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fill.js.map

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

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

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

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

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

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

@@ -0,0 +1,156 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "filter",
+    "category": "math/signal",
+    "keywords": [
+        "filter",
+        "IIR",
+        "FIR",
+        "difference equation",
+        "initial conditions",
+        "gpu"
+    ],
+    "summary": "Apply an IIR/FIR digital filter to scalars, vectors, or tensors with MATLAB-compatible semantics.",
+    "references": [
+        "title: \"MATLAB filter documentation\""
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "RunMat invokes the provider hook `iir_filter` when available. Real-valued operands run entirely on the device when the hook is implemented; complex coefficients or signals fall back to the host automatically."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::signal::filter::tests",
+        "integration": "builtins::math::signal::filter::tests::filter_gpu_matches_cpu"
+    },
+    "description": "`filter` evaluates the causal linear difference equation\n\n```\na(1) * y(n) = b(1) * x(n) + b(2) * x(n-1) + … + b(nb) * x(n-nb+1)\n              - a(2) * y(n-1) - … - a(na) * y(n-na+1)\n```\n\nwith MATLAB-compatible handling of scalars, row/column vectors, N-D tensors, complex numbers, and user-supplied initial conditions. RunMat normalises the coefficients internally so that `a(1)` becomes `1`, mirroring MATLAB.",
+    "behaviors": [
+        "`filter(b, a, X)` applies the filter along the first non-singleton dimension of `X` (column-wise for matrices).",
+        "The numerator `b` and denominator `a` must be non-empty vectors. `a(1)` must be non-zero; the runtime divides both coefficient vectors by `a(1)` automatically.",
+        "Optional initial conditions `zi` must have the same size as the output `zf` (the dimension being filtered is replaced by `max(numel(b), numel(a)) - 1`). Use `[]` to indicate zero initial state.",
+        "`filter(b, a, X, zi, dim)` processes `X` along dimension `dim`. Dimensions beyond `ndims(X)` are treated as length-one axes, exactly as in MATLAB.",
+        "Complex coefficients or inputs are supported; results follow MATLAB semantics for real/imaginary propagation.",
+        "The function returns a single output `y` by default. Request two outputs (`[y, zf] = filter(...)`) to obtain the final internal states `zf`."
+    ],
+    "examples": [
+        {
+            "description": "Smoothing a signal with an FIR moving-average filter",
+            "input": "b = ones(1, 3) / 3;\na = 1;\nx = [1 5 2 0 3];\ny = filter(b, a, x)",
+            "output": "y =\n    0.3333    2.0000    2.6667    2.3333    1.6667"
+        },
+        {
+            "description": "Applying a first-order IIR low-pass filter",
+            "input": "alpha = 0.8;\nb = 1 - alpha;\na = [1 -alpha];\nimp = [1 zeros(1, 4)];\ny = filter(b, a, imp)",
+            "output": "y =\n    0.2000    0.1600    0.1280    0.1024    0.0819"
+        },
+        {
+            "description": "Continuing a filtered stream with explicit initial conditions",
+            "input": "b = ones(1, 3) / 3;\na = 1;\nx1 = [1 5 2];\n[y1, zf] = filter(b, a, x1);   % First chunk\n\nx2 = [0 3];\n[y2, zf2] = filter(b, a, x2, zf);  % Resume with stored state",
+            "output": "y1 = [0.3333 2.0000 2.6667]\nzf  = [2.3333 0.6667]\n\ny2 = [2.3333 1.6667]\nzf2 = [1.0000 1.0000]"
+        },
+        {
+            "description": "Filtering along matrix rows (dimension 2)",
+            "input": "X = [1  2  3  4;\n     0  1  0  1];\nb = [1 -1];   % simple differentiator\na = 1;\nY = filter(b, a, X, [], 2)",
+            "output": "Y =\n     1     1     1     1\n     0     1    -1     1"
+        },
+        {
+            "description": "Filtering complex-valued data",
+            "input": "b = [1 1i];\na = 1;\nt = 0:3;\nx = exp(1i * pi/4 * t);\ny = filter(b, a, x)",
+            "output": "y =\n   1.0000 + 0.0000i   0.7071 + 1.7071i  -0.7071 + 1.7071i  -1.7071 + 0.7071i"
+        },
+        {
+            "description": "Executing a real filter on the GPU",
+            "input": "g = gpuArray([1 5 2 0 3]);\nb = ones(1, 3) / 3;\na = 1;\n[y_gpu, zf_gpu] = filter(b, a, g);\ny = gather(y_gpu)",
+            "output": "y =\n    0.3333    2.0000    2.6667    2.3333    1.6667"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What happens if `a(1)` is not 1.0?",
+            "answer": "RunMat (like MATLAB) divides every coefficient in `a` and `b` by `a(1)` internally so that `a(1)` becomes `1`. You only need to ensure `a(1)` is non-zero."
+        },
+        {
+            "question": "How large should `zi` be?",
+            "answer": "`zi` must have the same size as `zf` (the returned final state). Replace the filtered dimension with `max(numel(b), numel(a)) - 1`; all other dimensions match `X`. Use `[]` for a zero state."
+        },
+        {
+            "question": "Can I filter along a dimension greater than `ndims(X)`?",
+            "answer": "Yes. Just like MATLAB, RunMat treats missing higher dimensions as length-one axes. `filter(b, a, X, [], 5)` is valid even if `X` is a vector."
+        },
+        {
+            "question": "Does `filter` support complex coefficients or signals?",
+            "answer": "Absolutely. The host implementation handles complex arithmetic exactly. GPU acceleration is currently limited to real-valued filters; complex inputs fall back to the CPU automatically."
+        },
+        {
+            "question": "Do I need to initialise the GPU path manually?",
+            "answer": "No. If the signal is a `gpuArray` value and the active provider supports `iir_filter`, RunMat keeps the entire computation on the device. Otherwise, the runtime gathers operands to the host, ensuring MATLAB-compatible results without extra user code."
+        },
+        {
+            "question": "What shape does `zf` have?",
+            "answer": "`zf` matches `zi` (or the default zero state). The filtered dimension is replaced by `max(numel(b), numel(a)) - 1`; other dimensions mirror the input."
+        },
+        {
+            "question": "How are empty signals handled?",
+            "answer": "When `X` is empty, `y` is empty and `zf` equals the supplied `zi` (or zeros). No arithmetic is performed, matching MATLAB."
+        },
+        {
+            "question": "Are logical and integer inputs supported?",
+            "answer": "Yes. They are promoted to double precision before filtering, exactly as in MATLAB."
+        },
+        {
+            "question": "How do I resume filtering a long stream chunk-by-chunk?",
+            "answer": "Call `[y, zf] = filter(...)` on each chunk and pass `zf` as the fourth argument for the next chunk. The example above shows the pattern."
+        },
+        {
+            "question": "Can I accelerate filtering with the planner’s auto-offload?",
+            "answer": "The planner leverages the same provider hook under the hood. As long as the operands are real and the provider implements `iir_filter`, auto-offload keeps the filter on the GPU."
+        }
+    ],
+    "links": [
+        {
+            "label": "conv",
+            "url": "./conv"
+        },
+        {
+            "label": "deconv",
+            "url": "./deconv"
+        },
+        {
+            "label": "fft",
+            "url": "./fft"
+        },
+        {
+            "label": "conv2",
+            "url": "./conv2"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/signal/filter.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/signal/filter.rs"
+    },
+    "gpu_behavior": [
+        "The input signal already resides on the GPU (for example, via `gpuArray`) and all operands are real-valued.",
+        "The active provider implements `iir_filter` (both the in-process provider and the WGPU backend do).\n\nUnder those conditions the entire evaluation—including final-state propagation—stays on the device. If the hook is absent, or if any operand is complex, RunMat transparently gathers to the host, evaluates the filter with the scalar reference implementation, and returns MATLAB-compatible results. Auto-offload and fusion residency reuse the same hook, so high-level code does not need to differentiate between CPU and GPU execution."
+    ],
+    "key": "filter",
+    "slug": "filter",
+    "categoryPath": [
+        "math",
+        "signal"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=filter.js.map

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

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

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

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

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

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