{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "FFT (Fast Fourier Transform) refers to a way the discrete Fourier Transform (DFT) can be calculated efficiently, by using symmetries in the calculated terms. The symmetry is highest when " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " is a power of 2, and the transform is therefore most efficient for these sizes. For poorly factorizable sizes, " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.fft", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.fft" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " uses Bluestein's algorithm " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " and so is never worse than O(" }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " log " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": "). Further performance improvements may be seen by zero-padding the input using " }, { "__type": "InlineRole", "__tag": 4003, "value": "next_fast_len", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is a 1d array, then the " }, { "__type": "CrossRef", "__tag": 4002, "value": "fft", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.fft" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is equivalent to " } ] }, { "__type": "Code", "__tag": 4050, "value": "y[k] = np.sum(x * np.exp(-2j * np.pi * k * np.arange(n)/n))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The frequency term " }, { "__type": "InlineCode", "__tag": 4051, "value": "f=k/n" }, { "__type": "Text", "__tag": 4046, "value": " is found at " }, { "__type": "InlineCode", "__tag": 4051, "value": "y[k]" }, { "__type": "Text", "__tag": 4046, "value": ". At " }, { "__type": "InlineCode", "__tag": 4051, "value": "y[n/2]" }, { "__type": "Text", "__tag": 4046, "value": " we reach the Nyquist frequency and wrap around to the negative-frequency terms. So, for an 8-point transform, the frequencies of the result are [0, 1, 2, 3, -4, -3, -2, -1]. To rearrange the fft output so that the zero-frequency component is centered, like [-4, -3, -2, -1, 0, 1, 2, 3], use " }, { "__type": "InlineRole", "__tag": 4003, "value": "fftshift", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Transforms can be done in single, double, or extended precision (long double) floating point. Half precision inputs will be converted to single precision and non-floating-point inputs will be converted to double precision." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the data type of " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is real, a \"real FFT\" algorithm is automatically used, which roughly halves the computation time. To increase efficiency a little further, use " }, { "__type": "InlineRole", "__tag": 4003, "value": "rfft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", which does the same calculation, but only outputs half of the symmetrical spectrum. If the data are both real and symmetrical, the " }, { "__type": "InlineRole", "__tag": 4003, "value": "dct", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can again double the efficiency, by generating half of the spectrum from half of the signal." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "overwrite_x=True" }, { "__type": "Text", "__tag": 4046, "value": " is specified, the memory referenced by " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " may be used by the implementation in any way. This may include reusing the memory for the result, but this is in no way guaranteed. You should not rely on the contents of " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " after the transform as this may change in future without warning." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "workers" }, { "__type": "Text", "__tag": 4046, "value": " argument specifies the maximum number of parallel jobs to split the FFT computation into. This will execute independent 1-D FFTs within " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ". So, " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " must be at least 2-D and the non-transformed axes must be large enough to split into chunks. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " is too small, fewer jobs may be used than requested." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "fft", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.fft" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ✅ \nPyTorch ✅ ✅ \nJAX ✅ ✅ \nDask ⚠️ computes graph n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "IndexError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "if " }, { "__type": "InlineRole", "__tag": 4003, "value": "axes", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is larger than the last axis of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "out", "annotation": "complex ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The truncated or zero-padded input, transformed along the axis indicated by " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": ", or the last one if " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " is not specified." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the 1-D discrete Fourier Transform." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input array, can be complex." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Length of the transformed axis of the output. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " is not given, the length of the input along the axis specified by " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axis over which to compute the FFT. If not given, the last axis is used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "norm", "annotation": "{\"backward\", \"ortho\", \"forward\"}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Normalization mode. Default is \"backward\", meaning no normalization on the forward transforms and scaling by " }, { "__type": "InlineCode", "__tag": 4051, "value": "1/n" }, { "__type": "Text", "__tag": 4046, "value": " on the " }, { "__type": "InlineRole", "__tag": 4003, "value": "ifft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". \"forward\" instead applies the " }, { "__type": "InlineCode", "__tag": 4051, "value": "1/n" }, { "__type": "Text", "__tag": 4046, "value": " factor on the forward transform. For " }, { "__type": "InlineCode", "__tag": 4051, "value": "norm=\"ortho\"" }, { "__type": "Text", "__tag": 4046, "value": ", both directions are scaled by " }, { "__type": "InlineCode", "__tag": 4051, "value": "1/sqrt(n)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.6.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "norm={\"forward\", \"backward\"}" }, { "__type": "Text", "__tag": 4046, "value": " options were added" } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "overwrite_x", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, the contents of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " can be destroyed; the default is False. See the notes below for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "workers", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of workers to use for parallel computation. If negative, the value wraps around from " }, { "__type": "InlineCode", "__tag": 4051, "value": "os.cpu_count()" }, { "__type": "Text", "__tag": 4046, "value": ". See below for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "plan", "annotation": "object, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This argument is reserved for passing in a precomputed plan provided by downstream FFT vendors. It is currently not used in SciPy." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.5.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function computes the 1-D " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "n" } ] }, { "__type": "Text", "__tag": 4046, "value": "-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/fft/_basic.py", "item_line": 25, "item_type": "_Function", "aliases": [ "scipy.fft.fft" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import scipy.fft\nimport numpy as np\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "scipy.fft.fft(np.exp(2j * np.pi * np.arange(8) / 8))\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIn this example, real input has an FFT which is Hermitian, i.e., symmetric\nin the real part and anti-symmetric in the imaginary part:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.fft import fft, fftfreq, fftshift\nimport matplotlib.pyplot as plt\nt = np.arange(256)\nsp = fftshift(fft(np.sin(t)))\nfreq = fftshift(fftfreq(t.shape[-1]))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(freq, sp.real, freq, sp.imag)\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-c5032b0a11de3dca.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "fft2", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "fft2" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The 2-D FFT." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "fftfreq", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "fftfreq" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Frequency bins for given FFT parameters." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "fftn", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "fftn" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The N-D FFT." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "ifft", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "ifft" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The inverse of " }, { "__type": "InlineRole", "__tag": 4003, "value": "fft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "next_fast_len", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "next_fast_len" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Size to pad input to for most efficient transforms" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "rfftn", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "rfftn" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The N-D FFT of real input." } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "n", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "-1" }, { "__type": "SigParam", "__tag": 4030, "name": "norm", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "overwrite_x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "workers", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "plan", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "fft" }, "references": [ ".. [1] Cooley, James W., and John W. Tukey, 1965, \"An algorithm for the", " machine calculation of complex Fourier series,\" *Math. Comput.*", " 19: 297-301.", ".. [2] Bluestein, L., 1970, \"A linear filtering approach to the", " computation of discrete Fourier transform\". *IEEE Transactions on", " Audio and Electroacoustics.* 18 (4): 451-455." ], "qa": "scipy.fft._basic:fft", "arbitrary": [], "local_refs": [ "axis", "n", "norm", "out", "overwrite_x", "plan", "workers", "x" ] }