runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/feof.js

@@ -0,0 +1,144 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "feof",
+    "category": "io/filetext",
+    "keywords": [
+        "feof",
+        "end of file",
+        "io",
+        "file identifier"
+    ],
+    "summary": "Query whether the file position indicator of a file identifier is at end-of-file.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/feof.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. Arguments that live on the GPU are gathered automatically, and file handles remain host-resident."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::feof::tests",
+        "integration": "builtins::io::filetext::feof::tests::feof_returns_true_after_reading_to_end"
+    },
+    "description": "`feof(fid)` reports whether the file position indicator associated with `fid` has reached the end of the file. It is most commonly used to terminate loops that repeatedly call `fread`, `fgets`, or `fscanf`.",
+    "behaviors": [
+        "`tf = feof(fid)` returns logical `1` when the file position indicator is at end-of-file and logical `0` otherwise.",
+        "`fid` must be a non-negative integer returned by `fopen`. Passing an invalid identifier raises the same error message as other file I/O builtins.",
+        "Standard input/output identifiers (`0`, `1`, `2`) always report `false` because RunMat does not yet expose end-of-file state for those streams.",
+        "`feof` preserves the file position indicator; checking the flag does not modify where subsequent reads continue.",
+        "When a file is empty, `feof` immediately returns `true` because the initial file position coincides with the end of the file."
+    ],
+    "examples": [
+        {
+            "description": "Check for end-of-file while reading line by line",
+            "input": "[fid, msg] = fopen('log.txt', 'r');\nassert(fid ~= -1, msg);\nwhile ~feof(fid)\n    line = fgets(fid);\n    disp(line);\nend\nfclose(fid)"
+        },
+        {
+            "description": "Detect the end of a binary stream read with fread",
+            "input": "[fid, msg] = fopen('payload.bin', 'rb');\nassert(fid ~= -1, msg);\nwhile ~feof(fid)\n    chunk = fread(fid, 1024, 'uint8');\n    process(chunk);\nend\nfclose(fid)"
+        },
+        {
+            "description": "Handle empty files gracefully",
+            "input": "[fid, msg] = fopen('empty.txt', 'r');\nassert(fid ~= -1, msg);\nisAtEnd = feof(fid);   % returns true immediately because the file is empty\nfclose(fid)"
+        },
+        {
+            "description": "Protect against invalid identifiers",
+            "input": "try\n    feof(9999);\ncatch err\n    disp(err.message);\nend"
+        },
+        {
+            "description": "Guard reads that rely on gpuArray identifiers",
+            "input": "fid = gpuArray(int32(fopen('samples.dat', 'rb')));\ntf = feof(fid);        % argument is gathered automatically before the check"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What kind of input does `feof` accept?",
+            "answer": "Pass a scalar numeric file identifier returned by `fopen`. The identifier must be non-negative and finite. Character vectors or strings are not accepted."
+        },
+        {
+            "question": "Does `feof` move the file position indicator?",
+            "answer": "No. The builtin queries the current position and restores it before returning, so subsequent reads resume where they left off."
+        },
+        {
+            "question": "How does `feof` behave for standard input/output?",
+            "answer": "RunMat currently reports `false` for identifiers `0`, `1`, and `2` because the standard streams are not integrated with the file registry. Use other platform APIs to detect end-of-file on those streams if necessary."
+        },
+        {
+            "question": "Does `feof` require a previous read attempt to return true?",
+            "answer": "No. RunMat compares the current position against the end of the file. As soon as the indicator reaches the end (for example after reading all bytes or when the file is empty), `feof` returns `true`."
+        },
+        {
+            "question": "Can I call `feof` on closed files?",
+            "answer": "No. Passing a closed or never-opened identifier raises `\"Invalid file identifier. Use fopen to generate a valid file ID.\"`"
+        },
+        {
+            "question": "How does `feof` interact with GPU execution?",
+            "answer": "`feof` itself never runs on the GPU. When the identifier is stored in a GPU array, the runtime gathers it before performing the host-only check."
+        }
+    ],
+    "links": [
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "Open an issue",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "gpu_residency": "No. File identifiers are always owned by the host-side registry maintained by `fopen`. Wrapping a scalar identifier in `gpuArray` does not keep the file handle on the GPU—the runtime gathers the scalar before performing the lookup. This means you can freely mix host and GPU code when driving file I/O loops, and `feof` remains inexpensive regardless of execution tier.",
+    "gpu_behavior": [
+        "`feof` is a host-only query. If `fid` resides on the GPU (for example inside a `gpuArray`), RunMat gathers the scalar to host memory before consulting the file registry. File handles always remain on the CPU, so there are no provider hooks or fusion paths for this builtin. The result is produced on the host as a logical scalar that mirrors MATLAB behaviour."
+    ],
+    "key": "feof",
+    "slug": "feof",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=feof.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fft.js

@@ -0,0 +1,163 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fft",
+    "category": "math/fft",
+    "keywords": [
+        "fft",
+        "fourier transform",
+        "complex",
+        "zero padding",
+        "gpu"
+    ],
+    "summary": "Compute the discrete Fourier transform (DFT) of vectors, matrices, or N-D tensors.",
+    "references": [
+        "title: \"MATLAB fft documentation\""
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to host execution when the active acceleration provider does not expose an FFT hook."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::fft::fft::tests",
+        "integration": "builtins::math::fft::fft::tests::fft_gpu_roundtrip_matches_cpu"
+    },
+    "description": "`fft(X)` computes the discrete Fourier transform (DFT) of the input data. When `X` is a vector, `fft` returns the frequency-domain representation of the vector. When `X` is a matrix or an N-D tensor, the transform is applied along the first non-singleton dimension unless another dimension is specified.",
+    "behaviors": [
+        "`fft(X)` transforms along the first dimension whose size is greater than 1.",
+        "`fft(X, n)` zero-pads or truncates `X` to length `n` before transforming along the default dimension.",
+        "`fft(X, n, dim)` applies the transform along dimension `dim`.",
+        "Real inputs produce complex outputs; complex inputs are handled element-wise with no additional conversion.",
+        "Empty inputs remain empty; zero-padding with `n` produces zero-valued spectra.",
+        "GPU arrays are gathered to the host when the selected provider has no FFT implementation."
+    ],
+    "examples": [
+        {
+            "description": "Computing the FFT of a real time-domain vector",
+            "input": "x = [1 2 3 4];\nY = fft(x)",
+            "output": "Y =\n  Columns 1 through 4\n   10 + 0i  -2 + 2i  -2 + 0i  -2 - 2i"
+        },
+        {
+            "description": "Applying fft column-wise to a matrix",
+            "input": "A = [1 2 3; 4 5 6];\nF = fft(A)",
+            "output": "F =\n   5 + 0i   7 + 0i   9 + 0i\n  -3 + 0i  -3 + 0i  -3 + 0i"
+        },
+        {
+            "description": "Zero-padding before the FFT",
+            "input": "x = [1 2 3];\nY = fft(x, 5)"
+        },
+        {
+            "description": "Selecting the transform dimension for a row vector",
+            "input": "x = [1 2 3 4];\nY = fft(x, [], 2)"
+        },
+        {
+            "description": "FFT of a complex-valued signal",
+            "input": "t = 0:3;\nx = exp(1i * pi/2 * t);\nY = fft(x)"
+        },
+        {
+            "description": "FFT with gpuArray inputs",
+            "input": "g = gpuArray(rand(1, 1024));  % Residency is on the GPU\nG = fft(g);                   % Falls back to host if provider FFT hooks are unavailable\nresult = gather(G)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `fft` always return complex values?",
+            "answer": "Yes. Even when the imaginary part is zero, the result is stored as a complex array to match MATLAB semantics."
+        },
+        {
+            "question": "What happens if I pass `[]` as the second argument?",
+            "answer": "Passing `[]` leaves the transform length unchanged. This is equivalent to omitting the `n` parameter."
+        },
+        {
+            "question": "Can I transform along a dimension larger than the current rank?",
+            "answer": "Yes. RunMat automatically treats trailing dimensions as length-1 and will create the requested dimension on output."
+        },
+        {
+            "question": "How does zero-padding work?",
+            "answer": "When `n` is larger than the size of `X` along the transform dimension, RunMat pads with zeros before evaluating the FFT."
+        },
+        {
+            "question": "What precision is used for the FFT?",
+            "answer": "RunMat computes FFTs in double precision on the host. Providers may use single or double precision depending on device capabilities."
+        },
+        {
+            "question": "Will RunMat run the FFT on my GPU automatically?",
+            "answer": "When a provider installs an FFT hook, RunMat executes on the GPU. Otherwise, the runtime gathers the data and performs the transform on the CPU."
+        },
+        {
+            "question": "Is inverse FFT (`ifft`) available?",
+            "answer": "`ifft` will be provided in a companion builtin. Until then, you can recover a time-domain signal by dividing by the length and taking the complex conjugate manually."
+        },
+        {
+            "question": "How do I compute multi-dimensional FFTs?",
+            "answer": "Call `fft` repeatedly along each dimension (`fft(fft(X, [], 1), [], 2)` for a 2-D FFT). Future releases will add dedicated helpers."
+        },
+        {
+            "question": "Does `fft` support complex strides or non-unit sampling intervals?",
+            "answer": "`fft` assumes unit spacing. You can multiply the result by appropriate phase factors to account for custom sampling intervals."
+        }
+    ],
+    "links": [
+        {
+            "label": "ifft",
+            "url": "./ifft"
+        },
+        {
+            "label": "fftshift",
+            "url": "./fftshift"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "fft2",
+            "url": "./fft2"
+        },
+        {
+            "label": "ifft2",
+            "url": "./ifft2"
+        },
+        {
+            "label": "ifftshift",
+            "url": "./ifftshift"
+        }
+    ],
+    "source": {
+        "label": "Open a ticket",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "key": "fft",
+    "slug": "fft",
+    "categoryPath": [
+        "math",
+        "fft"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fft.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fft2.js

@@ -0,0 +1,152 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fft2",
+    "category": "math/fft",
+    "keywords": [
+        "fft2",
+        "2d fft",
+        "two dimensional fourier transform",
+        "image frequency analysis",
+        "gpu"
+    ],
+    "summary": "Compute the two-dimensional discrete Fourier transform (DFT) of numeric or complex data.",
+    "references": [
+        "title: \"MATLAB fft2 documentation\""
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Runs two provider-backed fft_dim passes when available; otherwise the runtime gathers to the host."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::fft::fft2::tests",
+        "integration": "builtins::math::fft::fft2::tests::fft2_gpu_roundtrip_matches_cpu"
+    },
+    "description": "`fft2(X)` computes the two-dimensional discrete Fourier transform (DFT) of `X`. It is equivalent to applying `fft` along the first dimension and then along the second dimension, preserving MATLAB’s column-major ordering and output shape semantics.",
+    "behaviors": [
+        "`fft2(X)` transforms along the first and second dimensions that have size greater than one.",
+        "`fft2(X, M, N)` zero-pads or truncates `X` to `M` rows and `N` columns before evaluating the 2-D transform.",
+        "`fft2(X, SIZE)` accepts a two-element vector (or scalar) specifying the transform lengths.",
+        "Real inputs produce complex outputs; complex inputs are transformed element-wise with no additional conversion.",
+        "Higher-dimensional inputs are transformed slice-by-slice across trailing dimensions, matching MATLAB behaviour.",
+        "Empty dimensions yield empty outputs; zero padding with `0` produces a zero-sized complex tensor.",
+        "GPU arrays execute on-device when the provider advertises the `fft_dim` hook; otherwise RunMat gathers the data and performs the transform on the host using `rustfft`."
+    ],
+    "examples": [
+        {
+            "description": "Computing the 2-D FFT of a small matrix",
+            "input": "X = [1 2; 3 4];\nY = fft2(X)",
+            "output": "Y =\n    10 + 0i   -2 + 0i\n    -4 + 0i    0 + 0i"
+        },
+        {
+            "description": "Zero-padding an image patch before `fft2`",
+            "input": "patch = [1 0 1; 0 1 0; 1 0 1];\nF = fft2(patch, 8, 8)"
+        },
+        {
+            "description": "Specifying transform lengths with a size vector",
+            "input": "X = rand(4, 6);\nF = fft2(X, [8 4]);   % pad rows to 8 and truncate columns to 4"
+        },
+        {
+            "description": "Using `fft2` on `gpuArray` data",
+            "input": "G = gpuArray(rand(256, 256));\nF = fft2(G);\nR = gather(F)"
+        },
+        {
+            "description": "Applying `fft2` to each slice of a 3-D volume",
+            "input": "V = rand(64, 64, 10);\nspectra = fft2(V)"
+        },
+        {
+            "description": "Verifying `fft2` against sequential `fft` calls",
+            "input": "X = rand(5, 7);\nsequential = fft(fft(X, [], 1), [], 2);\ndirect = fft2(X)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Is `fft2(X)` the same as `fft(fft(X, [], 1), [], 2)`?",
+            "answer": "Yes. RunMat literally performs the two sequential transforms so the results match MATLAB exactly."
+        },
+        {
+            "question": "How do zero-length transform sizes behave?",
+            "answer": "Passing `0` for either `M` or `N` produces a complex tensor with zero elements along that dimension."
+        },
+        {
+            "question": "Can I use a single scalar for the size argument?",
+            "answer": "Yes. `fft2(X, K)` is shorthand for `fft2(X, [K K])`, padding or truncating both dimensions to `K`."
+        },
+        {
+            "question": "What happens when `X` has more than two dimensions?",
+            "answer": "RunMat applies `fft2` to every 2-D slice defined by the first two dimensions, leaving higher dimensions untouched."
+        },
+        {
+            "question": "Do I get complex outputs for real inputs?",
+            "answer": "Always. Even when the imaginary parts are zero, outputs are stored as complex tensors to mirror MATLAB semantics."
+        },
+        {
+            "question": "Will `fft2` run on the GPU automatically?",
+            "answer": "Yes if the active provider implements `fft_dim`. Otherwise RunMat gathers to the host and performs the transform with `rustfft`."
+        },
+        {
+            "question": "Does `fft2` normalise the output?",
+            "answer": "No. Like MATLAB, the forward FFT leaves scaling untouched; use `ifft2` for the inverse with `1/(M*N)` scaling."
+        },
+        {
+            "question": "Can I mix `[]` with explicit sizes (e.g., `fft2(X, [], 128)`)?",
+            "answer": "Yes. Passing `[]` leaves that dimension unchanged while applying the specified size to the other dimension."
+        }
+    ],
+    "links": [
+        {
+            "label": "fft",
+            "url": "./fft"
+        },
+        {
+            "label": "ifft",
+            "url": "./ifft"
+        },
+        {
+            "label": "fftshift",
+            "url": "./fftshift"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "ifft2",
+            "url": "./ifft2"
+        },
+        {
+            "label": "ifftshift",
+            "url": "./ifftshift"
+        }
+    ],
+    "source": {
+        "label": "Open a ticket",
+        "url": "https://github.com/runmat-org/runmat/issues/new/choose"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` manually. The fusion planner and native acceleration layer keep tensors on the GPU when a provider offers FFT kernels. If the provider lacks `fft_dim`, RunMat gathers inputs, evaluates the FFT pair on the host, and returns a MATLAB-compatible complex tensor. You can still use `gpuArray` for explicit residency control, particularly when interoperating with MATLAB code that expects it.",
+    "key": "fft2",
+    "slug": "fft2",
+    "categoryPath": [
+        "math",
+        "fft"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fft2.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fftshift.js

@@ -0,0 +1,150 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fftshift",
+    "category": "math/fft",
+    "keywords": [
+        "fftshift",
+        "fourier transform",
+        "frequency centering",
+        "spectrum",
+        "gpu"
+    ],
+    "summary": "Shift zero-frequency components to the center of a spectrum.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses the provider circshift hook when available; otherwise gathers once, shifts on the host, and re-uploads."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::fft::fftshift::tests",
+        "integration": "builtins::math::fft::fftshift::tests::fftshift_gpu_roundtrip"
+    },
+    "description": "`fftshift(X)` circularly shifts the output of an FFT so that the zero-frequency component moves to the center of each transformed dimension. This makes spectra easier to inspect and aligns with MATLAB's plotting conventions.",
+    "behaviors": [
+        "When called without a dimension list, `fftshift` shifts along every dimension by `floor(size(X, dim) / 2)`.",
+        "`fftshift(X, dims)` shifts only the specified dimensions. `dims` can be a scalar, vector, or logical mask.",
+        "Dimensions of length 0 or 1 are left unchanged.",
+        "Inputs can be real or complex and may already reside on the GPU (`gpuArray`)."
+    ],
+    "examples": [
+        {
+            "description": "Centering the spectrum of a 1-D FFT result with even length",
+            "input": "x = [0 1 2 3 4 5 6 7];\nfx = fft(x);\ny = fftshift(fx)",
+            "output": "y = [-4 -4-1.6569i -4-4i -4-9.6569i 28 -4+9.6569i -4+4i -4+1.6569i]"
+        },
+        {
+            "description": "Handling odd-length vectors",
+            "input": "x = 1:5;\ny = fftshift(x)",
+            "output": "y = [4 5 1 2 3]"
+        },
+        {
+            "description": "Centering both axes of a 2-D FFT",
+            "input": "A = [1 2 3; 4 5 6];\nC = fftshift(A)",
+            "output": "C =\n     6     4     5\n     3     1     2"
+        },
+        {
+            "description": "Shifting only one dimension of a matrix",
+            "input": "A = [1 2 3; 4 5 6];\nrowCentered = fftshift(A, 1)   % shift rows only",
+            "output": "rowCentered =\n     4     5     6\n     1     2     3"
+        },
+        {
+            "description": "Applying `fftshift` to a gpuArray spectrum",
+            "input": "G = gpuArray(0:7);\ncentered = fftshift(G);\nH = gather(centered)",
+            "output": "H = [4 5 6 7 0 1 2 3]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "When should I call `fftshift`?",
+            "answer": "Call `fftshift` whenever you need to center FFT outputs before visualising spectra, computing radial averages, or applying filters that expect zero frequency in the middle of the array."
+        },
+        {
+            "question": "Does `fftshift` modify the phase or magnitude of the FFT?",
+            "answer": "No. `fftshift` only reorders the samples. Magnitudes, phases, and the overall information content remain unchanged."
+        },
+        {
+            "question": "How do I undo `fftshift`?",
+            "answer": "Use `ifftshift`, which performs the inverse rearrangement. The sequence `ifftshift(fftshift(X))` returns `X` for all supported inputs."
+        },
+        {
+            "question": "Can I apply `fftshift` to only one dimension?",
+            "answer": "Yes. Pass a dimension index or vector, e.g. `fftshift(X, 2)` to shift column channels only."
+        },
+        {
+            "question": "Does `fftshift` work with gpuArray inputs?",
+            "answer": "Yes. RunMat keeps data on the GPU whenever the provider exposes the `circshift` hook, matching MATLAB's `gpuArray` behaviour."
+        },
+        {
+            "question": "How does `fftshift` handle empty inputs?",
+            "answer": "Empty arrays are returned unchanged with identical shape metadata."
+        },
+        {
+            "question": "Can I use `fftshift` on logical arrays?",
+            "answer": "Yes. Logical arrays are shifted without changing their logical element type."
+        }
+    ],
+    "links": [
+        {
+            "label": "fft",
+            "url": "./fft"
+        },
+        {
+            "label": "ifft",
+            "url": "./ifft"
+        },
+        {
+            "label": "ifftshift",
+            "url": "./ifftshift"
+        },
+        {
+            "label": "circshift",
+            "url": "./circshift"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "fft2",
+            "url": "./fft2"
+        },
+        {
+            "label": "ifft2",
+            "url": "./ifft2"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/fft/fftshift.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/fft/fftshift.rs"
+    },
+    "gpu_residency": "RunMat's auto-offload keeps FFT spectra on the GPU whenever the active provider exposes the `circshift` hook. In that case `fftshift` runs entirely on the device and downstream fused operations continue without a gather. If no GPU provider is registered—or it does not expose `circshift`—RunMat gathers the data once, performs the host shift, and uploads the result back to the device so subsequent work can still benefit from acceleration. You can always call `gpuArray` explicitly when you need MATLAB compatibility or want to guarantee a specific residency boundary.",
+    "gpu_behavior": [
+        "RunMat asks the active acceleration provider to execute `fftshift` via the `circshift` hook (with predetermined offsets). If the provider cannot satisfy the request, the tensor is gathered exactly once, shifted on the host, and optionally re-uploaded. Scalars remain on their existing device."
+    ],
+    "key": "fftshift",
+    "slug": "fftshift",
+    "categoryPath": [
+        "math",
+        "fft"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fftshift.js.map