PyTorch torch.fft 频谱变换完全指南从 FFT 到 Hermitian 变换的函数族、参数与实战【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch本指南以 PyTorch 仓库中的 docs/source/fft.md 频谱变换 API 参考页为核心系统梳理torch.fft模块下 18 个离散傅里叶变换DFT/FFT函数与 4 个频率辅助函数从 1D/ND 正逆变换、实数信号的紧凑单侧表示rfft 系列、Hermitian 对称输入的 hfft 系列到归一化模式、频率轴生成与频移重排。读完本文你将掌握每一类变换的适用场景、全部关键参数n/s/dim/norm/out的语义与默认值、奇偶长度信号的往返round-trip陷阱以及如何结合仓库源码 torch/fft/init.py 与测试 test/test_spectral_ops.py 验证结果的正确性。torch.fft 模块总览一张图看清 18 4 个接口torch.fft是 PyTorch 的离散傅里叶变换命名空间官方 API 参考页即本指南依据的 docs/source/fft.md将其划分为两大组快速傅里叶变换Fast Fourier Transformsfft、ifft、fft2、ifft2、fftn、ifftn、rfft、irfft、rfft2、irfft2、rfftn、irfftn、hfft、ihfft、hfft2、ihfft2、hfftn、ihfftn共 18 个。辅助函数Helper Functionsfftfreq、rfftfreq、fftshift、ifftshift共 4 个。这些函数在源码中通过torch._C._add_docstr将 Python 命名空间绑定到 C 层的torch._C._fft内建函数上见 torch/fft/init.py并完整声明在__all__中__all__ [ fft, ifft, fft2, ifft2, fftn, ifftn, rfft, irfft, rfft2, irfft2, rfftn, irfftn, hfft, ihfft, hfft2, ihfft2, hfftn, ihfftn, fftfreq, rfftfreq, fftshift, ifftshift, Tensor, ]命名规律非常清晰掌握后可举一反三后缀含义输入域输出域无后缀 /fft一维变换任意通常复数完整频谱2二维变换默认只变换最后两维任意完整频谱nN 维变换默认变换所有维任意完整频谱r前缀real实数输入实数时域单侧 Hermitian 频谱i前缀inverse逆变换频域时域h前缀HermitianHermitian 对称输入单侧 Hermitian时域实数频域ih前缀inverse Hermitian实数频域单侧 Hermitian时域其中rfft/irfft系列与hfft/ihfft系列互为镜像关系前者输入实数、输出具备 Hermitian 对称性的频谱后者输入 Hermitian 对称信号、输出实数。下面逐一展开。三大核心概念Hermitian 对称性、norm 归一化与逻辑变换长度在进入函数细节之前先掌握贯穿全部 18 个变换函数的三个基础概念它们决定了输出形状、数值语义与往返精度。1. 实信号的 Hermitian 对称性任何实数信号的傅里叶变换都满足 Hermitian 性质一维X[i] conj(X[-i])二维X[i, j] conj(X[-i, -j])N 维X[i_1, ..., i_n] conj(X[-i_1, ..., -i_n])这意味着实信号完整频谱的负频率一半是冗余的见 torch/fft/init.py 对fft的说明。fft/fft2/fftn始终返回包含正负频率的完整输出而rfft系列利用该性质只返回奈奎斯特频率以下的正频率部分输出更紧凑、计算更省。2. 三种归一化模式forward / backward / ortho所有变换函数都接受norm参数取值为forward、backward、ortho三者之一默认是backward。其含义在正、逆变换方向上互为对偶norm 模式正向变换fft/rfft/hfft逆变换ifft/irfft/ihfftforward除以1/n不归一化backward默认不归一化除以1/northo除以1/sqrt(n)除以1/sqrt(n)其中n是逻辑变换长度一维变换中即信号长度n多维变换中为n prod(s)即各变换维尺寸的乘积。关键性质是正逆变换使用相同的norm模式时两者之间的总归一化恰为1/n从而保证ifft(fft(x))是精确的逆运算见 torch/fft/init.py。ortho模式使变换成为正交酉变换正逆对称常用于数值稳定性要求高的场景。3. 信号长度 n / s补零、截断与往返的关键一维函数用nint若给定变换前输入会被零填充或截断到该长度。多维函数用stuple每个变换维dim[i]会被零填充或截断到s[i]其中指定-1表示该维不做填充。默认s [input.size(d) for d in dim]。n/s对irfft、irfft2/irfftn、hfft系列尤其关键由于单侧 Hermitian 输入的形状无法区分原始信号是奇长度还是偶长度默认会假设为偶数长度奇长度信号若不显式传n/s将无法正确往返。源码中的建议是始终显式传入信号长度见 torch/fft/init.py。一维变换fft 与 ifftfft计算输入的一维离散傅里叶变换ifft是其逆torch.fft.fft(input, nNone, dim-1, normNone, *, outNone) - Tensor torch.fft.ifft(input, nNone, dim-1, normNone, *, outNone) - Tensorinput输入张量n信号长度给定则先补零或截断dim执行一维 FFT 的维度默认-1最后一维norm归一化模式默认backwardout可选输出张量关键字参数。官方示例展示了最基本的用法来自 torch/fft/init.py t torch.arange(4) t tensor([0, 1, 2, 3]) torch.fft.fft(t) tensor([ 6.0.j, -2.2.j, -2.0.j, -2.-2.j]) t torch.tensor([0.1.j, 2.3.j, 4.5.j, 6.7.j]) torch.fft.fft(t) tensor([12.16.j, -8.0.j, -4.-4.j, 0.-8.j])逆变换示例torch/fft/init.py t torch.tensor([ 6.0.j, -2.2.j, -2.0.j, -2.-2.j]) torch.fft.ifft(t) tensor([0.0.j, 1.0.j, 2.0.j, 3.0.j])注意fft的结果中T[1] T[-1].conj()、T[2] T[-2].conj()的对称性一目了然这正是下文rfft压缩表示的依据。多维变换fft2 / ifft2 与 fftn / ifftnfft2/ifft2等价于fftn/ifftn只变换最后两维的版本fftn/ifftn默认变换所有维度是通用入口torch.fft.fft2(input, sNone, dim(-2, -1), normNone, *, outNone) - Tensor torch.fft.fftn(input, sNone, dimNone, normNone, *, outNone) - Tensors各变换维的信号尺寸dim[i]中的-1表示该维不填充dim要变换的维度fft2默认最后两维fftn默认所有维度若给了s则默认最后len(s)维多维时逻辑长度n prod(s)归一化语义与一维完全一致。多维 DFT 是可分离的因此fft2等价于沿两个维度依次做两次一维fft。官方示例用torch.testing.assert_close验证了这一等价性torch/fft/init.py x torch.rand(10, 10, dtypetorch.complex64) fft2 torch.fft.fft2(x) two_ffts torch.fft.fft(torch.fft.fft(x, dim0), dim1) torch.testing.assert_close(fft2, two_ffts, check_strideFalse)ifft2、ifftn与正向版本同构只是默认归一化方向相反默认backward即除以1/n。实数输入的紧凑表示rfft / irfft 系列对于实数输入完整频谱的负频率冗余因此rfft系列只返回正频率部分含零频与奈奎斯特项输出长度约为输入的一半既省内存又省计算。一维rfft / irffttorch.fft.rfft(input, nNone, dim-1, normNone, *, outNone) - Tensor torch.fft.irfft(input, nNone, dim-1, normNone, *, outNone) - Tensor对比示例torch/fft/init.py t torch.arange(4) torch.fft.rfft(t) tensor([ 6.0.j, -2.2.j, -2.0.j]) torch.fft.fft(t) # 完整输出作对比 tensor([ 6.0.j, -2.2.j, -2.0.j, -2.-2.j])可见对称元素T[-1] T[1].conj()被省略奈奎斯特频率处T[-2] T[2]是自身对称对因此必须为实数。irfft有两条重要约束见 torch/fft/init.py部分频率必须为实值才能满足 Hermitian 性质其虚部会被忽略——例如零频项的虚部永远无法体现在实数输出中。n默认取偶数值n 2 * (input.size(dim) - 1)若原始信号是奇长度不传n就无法正确往返。奇偶长度陷阱的官方示例torch/fft/init.py t torch.linspace(0, 1, 5) # 奇长度5 T torch.fft.rfft(t) T tensor([ 2.50000.0000j, -0.62500.8602j, -0.62500.2031j]) torch.fft.irfft(T) # 不传 n默认按偶长度 4 恢复结果错误 tensor([0.1562, 0.3511, 0.7812, 1.2114]) roundtrip torch.fft.irfft(T, t.numel()) # 显式传 n5正确往返 torch.testing.assert_close(roundtrip, t, check_strideFalse)多维rfft2 / irfft2、rfftn / irfftnrfft2/rfftn只压缩最后一个变换维的负频率其余维输出完整。例如对10 x 10实数张量rfft2输出形状为[10, 6] t torch.rand(10, 10) rfft2 torch.fft.rfft2(t) rfft2.size() torch.Size([10, 6]) fft2 torch.fft.fft2(t) torch.testing.assert_close(fft2[..., :6], rfft2, check_strideFalse)rfft2与两次一维变换等价torch/fft/init.py two_ffts torch.fft.fft(torch.fft.rfft(t, dim1), dim0) torch.testing.assert_close(rfft2, two_ffts, check_strideFalse)irfft2/irfftn的s默认在最后维取偶数值s[-1] 2 * (input.size(dim[-1]) - 1)并要求dim的最后一个是半 Hermitian 压缩维。官方示例同样演示了奇长度信号的往返修复torch/fft/init.py t torch.rand(10, 9) # 最后一维为奇长度 9 T torch.fft.rfft2(t) torch.fft.irfft2(T).size() # 默认输出 [10, 8]错误 torch.Size([10, 8]) roundtrip torch.fft.irfft2(T, t.size()) # 显式传 s 后正确 torch.testing.assert_close(roundtrip, t, check_strideFalse)Hermitian 对称输入hfft / ihfft 系列hfft/ihfft系列与rfft/irfft系列完全镜像rfft期望时域实数、得到频域 Hermitian 对称hfft期望时域 Hermitian 对称单侧表示、得到频域实数见 torch/fft/init.py。一维hfft / ihffttorch.fft.hfft(input, nNone, dim-1, normNone, *, outNone) - Tensor torch.fft.ihfft(input, nNone, dim-1, normNone, *, outNone) - Tensor官方示例完整展示了从实数频域信号到 Hermitian 时域、再用单侧输入恢复的闭环torch/fft/init.py t torch.linspace(0, 1, 5) T torch.fft.ifft(t) # 实数信号的 IFFT 产生 Hermitian 对称输出 T tensor([ 0.5000-0.0000j, -0.1250-0.1720j, -0.1250-0.0406j, -0.12500.0406j, -0.12500.1720j]) # T[1] T[-1].conj() 且 T[2] T[-2].conj()负频率冗余 torch.fft.hfft(T[:3], n5) # 只用正频率部分即可恢复实数频域信号 tensor([0.0000, 0.2500, 0.5000, 0.7500, 1.0000]) torch.fft.hfft(T[:3]) # 不传 n 时按偶长度恢复同样会出错 tensor([0.1250, 0.2809, 0.6250, 0.9691])ihfft是hfft的逆输入实数、输出单侧 Hermitiantorch/fft/init.py t torch.arange(5) torch.fft.ihfft(t) tensor([ 2.0000-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j]) torch.fft.ifft(t) # 完整输出作对比 tensor([ 2.0000-0.0000j, -0.5000-0.6882j, -0.5000-0.1625j, -0.50000.1625j, -0.50000.6882j])多维hfft2 / ihfft2、hfftn / ihfftn多维版本与rfft2/rfftn的规则完全对称hfft2/hfftn在最后一个变换维接收单侧 Hermitian 输入输出实数s默认最后维取偶数值s[-1] 2 * (input.size(dim[-1]) - 1)。官方示例torch/fft/init.py T torch.rand(10, 9) # 实数频域信号奇长度 t torch.fft.ihfft2(T) # 生成 Hermitian 时域信号 torch.fft.hfft2(t).size() # 默认输出 [10, 10]错误 torch.Size([10, 10]) roundtrip torch.fft.hfft2(t, T.size()) # 显式传 s 后正确往返 torch.allclose(roundtrip, T) True辅助函数频率轴与频谱重排fftfreq生成 FFT 样本频率torch.fft.fftfreq(n, d1.0, *, outNone, dtypeNone, layouttorch.strided, deviceNone, requires_gradFalse) - Tensor约定fft先返回正频率、再按逆序返回负频率因此频率序列为torch/fft/init.pyf [0, 1, ..., (n - 1) // 2, -(n // 2), ..., -1] / (d * n)nFFT 长度d采样间隔长度单位默认 1.0除以实际采样间隔即可换算为物理频率单位偶长度时奈奎斯特频率f[n/2]遵循 NumPy 惯例取负值torch/fft/init.py。 torch.fft.fftfreq(5) tensor([ 0.0000, 0.2000, 0.4000, -0.4000, -0.2000]) torch.fft.fftfreq(4) # 偶长度奈奎斯特频率 f[2] -0.5 tensor([ 0.0000, 0.2500, -0.5000, -0.2500])rfftfreq生成 rfft 样本频率torch.fft.rfftfreq(n, d1.0, *, outNone, dtypeNone, layouttorch.strided, deviceNone, requires_gradFalse) - Tensor与fftfreq的唯一区别rfft只返回正频率因此频率序列为f torch.arange((n 1) // 2) / (d * n)且偶长度下的奈奎斯特频率取正值与fftfreq符号相反torch/fft/init.py torch.fft.rfftfreq(5) tensor([0.0000, 0.2000, 0.4000]) torch.fft.rfftfreq(4) tensor([0.0000, 0.2500, 0.5000]) # 对比 fftfreq(4) 中为 -0.5fftshift / ifftshift零频居中与反操作torch.fft.fftshift(input, dimNone) - Tensor torch.fft.ifftshift(input, dimNone) - Tensorfftshift对 N 维 FFT 数据做周期性移位把原点(0, ..., 0)零频移到每个所选维度的input.shape[dim] // 2处使频率按从负到正升序排列dim默认所有维度也可指定部分维度。ifftshift是其逆运算二者组合构成恒等变换torch/fft/init.py f torch.fft.fftfreq(5) f tensor([ 0.0000, 0.2000, 0.4000, -0.4000, -0.2000]) shifted torch.fft.fftshift(f) torch.fft.ifftshift(shifted) tensor([ 0.0000, 0.2000, 0.4000, -0.4000, -0.2000])一个非常实用的场景是中心化网格数据若空间数据定义在中心化网格[-(N//2), (N-1)//2]上而标准 FFT 期望非中心化网格[0, N)则可用ifftshift前移、fftshift后移完成闭环torch/fft/init.py x_centered torch.arange(-5, 5) x_uncentered torch.fft.ifftshift(x_centered) # 空间域去中心化 fft_uncentered torch.fft.fft(x_uncentered) fft_centered torch.fft.fftshift(fft_uncentered) # 频域中心化 x_centered_2 torch.fft.fftshift(torch.fft.ifft(torch.fft.ifftshift(fft_centered))) torch.testing.assert_close(x_centered.to(torch.complex64), x_centered_2, check_strideFalse)参数速查18 个变换函数的签名总表函数签名默认变换维关键差异fft/ifft(input, nNone, dim-1, normNone, *, outNone)最后一维一维完整频谱fft2/ifft2(input, sNone, dim(-2, -1), normNone, *, outNone)最后两维二维完整频谱fftn/ifftn(input, sNone, dimNone, normNone, *, outNone)所有维N 维完整频谱rfft/irfft(input, nNone, dim-1, normNone, *, outNone)最后一维实数输入 / 单侧输出rfft2/irfft2(input, sNone, dim(-2, -1), normNone, *, outNone)最后两维仅压缩最后维rfftn/irfftn(input, sNone, dimNone, normNone, *, outNone)所有维仅压缩最后维hfft/ihfft(input, nNone, dim-1, normNone, *, outNone)最后一维Hermitian 输入 / 实数输出hfft2/ihfft2(input, sNone, dim(-2, -1), normNone, *, outNone)最后两维单侧输入最后维压缩hfftn/ihfftn(input, sNone, dimNone, normNone, *, outNone)所有维单侧输入最后维压缩共享参数语义小结input输入张量n一维/s多维变换前的补零或截断长度/尺寸s中-1表示该维不填充irfft/irfftn/hfft/hfftn系列默认按偶数长度推断dim变换维度逆变换系列要求最后一个变换维为压缩维normforward/backward默认/orthoout可选输出张量仅关键字fftfreq/rfftfreq额外支持dtype、layout、device、requires_grad等工厂参数语义与常规张量工厂函数一致见 torch/_torch_docs.py 中factory_common_args的定义。源码实现Python 命名空间如何连接到 C FFT 内核torch.fft的全部函数并非在 Python 中实现算法而是通过_add_docstr把文档字符串与 C 层torch._C._fft中的内建函数绑定见 torch/fft/init.pyimport torch from torch._C import _add_docstr, _fft # type: ignore[attr-defined] fft _add_docstr( _fft.fft_fft, rfft(input, nNone, dim-1, normNone, *, outNone) - Tensor ... )也就是说torch.fft.fft实际调用的是 C 层的torch._C._fft.fft_fft。源码注释明确指出这里不仅为频谱算子附加文档字符串更重要的是把 torch.fft Python 命名空间连接到 torch._C._fft 内建函数见 torch/fft/init.py。这意味着这些算子直接受益于 PyTorch 底层的自动微分、设备分派CPU/CUDA/MPS 等与内存管理机制。各函数的完整 docstring 均以_add_docstr形式内嵌在 torch/fft/init.py 中是 docs/source/fft.md 生成 API 文档的权威来源。精度与平台限制CUDA 上的 half / chalf 支持所有变换函数在文档中都声明了相同的精度限制见 torch/fft/init.py 等处的 NoteCUDA 上支持torch.halffloat16与torch.chalfcomplex32要求 GPU 架构为SM53 及以上但半精度下每个变换维的信号长度必须是 2 的幂对irfft、irfftn、hfft、hfftn系列默认参数下要求压缩维尺寸形如(2^n 1)因为默认输出按偶数长度2 * (size - 1)推断。这些限制是使用半精度加速时需要提前核对的关键前提与文档中给出的默认长度公式保持一致。结果验证与测试仓库中的测试入口为 test/test_spectral_ops.py是验证上述全部语义的权威参考。日常使用中官方文档推荐的三种验证手段往返测试用torch.testing.assert_close(roundtrip, x, check_strideFalse)验证ifft(fft(x))是否精确还原——注意 FFT 结果不保证与输入步长stride一致需关闭check_stride可分离性测试用assert_close(fft2, fft(fft(x, dim0), dim1), check_strideFalse)验证多维变换与一维变换组合的等价性对称性对比用assert_close(fft2[..., :6], rfft2, check_strideFalse)验证rfft系列输出正是完整频谱的正频率部分。将这三类断言融入自己的代码可以快速发现奇偶长度n/s传参错误、归一化模式不一致等高频踩坑点。实践要点总结选型输入为实数且只关心幅度谱优先rfft系列省一半内存与计算需要做频域滤波后还原成对使用rfft/irfft并始终显式传递原始信号长度n或形状s奇偶长度才能正确往返可视化频谱用fftfreq/rfftfreq生成频率轴用fftshift/ifftshift将零频居中二者是频域分析和滤波器设计的标准组合归一化默认backward下逆变换自带1/n追求正逆对称时统一改用ortho半精度CUDA 上启用torch.half/torch.chalf前确认架构不低于 SM53 且各变换维长度为 2 的幂权威参考每个函数完整的行为说明、示例与参数表格可直接查阅 docs/source/fft.md 的 API 参考页实现细节以 torch/fft/init.py 的 docstring 为准。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考