API 参考#

本节介绍支持的 FFTW API，并提供注释突出 NVPL FFT 和 FFTW3 库之间的差异，以及用于获取 NVPL FFT 库版本信息的附加服务 API。

注意

从 NVPL FFT 0.4.0 开始，NVPL 提供了现代和旧式 Fortran 接口，这些接口模仿了 FFTW3 提供的 Fortran 接口。有关如何使用这些接口的更多信息，请访问以下链接：旧式 Fortran API 和现代 Fortran API

版本信息#

int nvpl_fft_get_version()#

参数:

int – NVPL FFT 的版本。返回 NVPL_FFT_VERSION，它等效于 NVPL_FFT_VERSION_MAJOR * 10000 + NVPL_FFT_VERSION_MINOR * 100 + NVPL_FFT_VERSION_PATCH。

Plan 创建、执行和销毁#

警告

planner 标志 flags 参数在 NVPL FFT 中被忽略，并且无论其值如何，都返回相同的 plan。

警告

在 plan 创建或执行期间提供的输入和输出数据的指针（in 和 out）需要与单精度变换中的 fftwf_complex 数据类型和双精度变换中的 fftw_complex 类型对齐。

基本 plan 接口#

创建 fftw(f)_plan 以计算具有指定符号、大小和类型的 DFT。此接口集仅支持使用连续输入和输出数据的单批 FFT 执行。

复数输入到复数输出 (C2C)#

fftw_plan fftw_plan_dft_1d( int n0, fftw_complex *in, fftw_complex *out, int sign, unsigned flags, )#

fftw_plan fftw_plan_dft_2d( int n0, int n1, fftw_complex *in, fftw_complex *out, int sign, unsigned flags, )#

fftw_plan fftw_plan_dft_3d( int n0, int n1, int n2, fftw_complex *in, fftw_complex *out, int sign, unsigned flags, )#

fftw_plan fftw_plan_dft( int rank, const int *n, fftw_complex *in, fftw_complex *out, int sign, unsigned flags, )#

fftwf_plan fftwf_plan_dft_1d( int n0, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags, )#

fftwf_plan fftwf_plan_dft_2d( int n0, int n1, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags, )#

fftwf_plan fftwf_plan_dft_3d( int n0, int n1, int n2, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags, )#

fftwf_plan fftwf_plan_dft( int rank, const int *n, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags, )#

参数:

rank[in] – 变换的维度。它可以是 1、2 或 3。
n0[in] – 第 0 维（最外层维度）中的变换（input 和 output）大小。
n1[in] – 第 1 维中的变换（input 和 output）大小。
n2[in] – 第 2 维（最内层维度）中的变换（input 和 output）大小。
n[in] – 指向大小为 rank 的整数数组的指针。n[i] 是维度 i 中的变换（input 和 output）大小，i=0,...,rank-1。n[0] 和 n[rank-1] 分别是最外层和最内层维度的大小。
in[in] – 指向输入数据的指针。
out[out] – 指向输出数据的指针。如果值与 in 相同，则变换将就地完成。
sign[in] – DFT 公式中指数的符号。它可以是 -1 (FFTW_FORWARD) 或 1 (FFTW_INVERSE 或 FFTW_BACKWARD)。
flags[in] – planner 标志。可用选项为 FFTW_ESTIMATE、FFTW_MEASURE、FFTW_PATIENT、FFTW_EXHAUSTIVE、FFTW_WISDOM_ONLY。

返回值:

fftw(f)_plan – 创建的 fftw(f)_plan。如果 plan 创建失败，则为 nullptr。

实数输入到复数输出 (R2C)#

fftw_plan fftw_plan_dft_r2c_1d( int n0, double *in, fftw_complex *out, unsigned flags, )#

fftw_plan fftw_plan_dft_r2c_2d( int n0, int n1, double *in, fftw_complex *out, unsigned flags, )#

fftw_plan fftw_plan_dft_r2c_3d( int n0, int n1, int n2, double *in, fftw_complex *out, unsigned flags, )#

fftw_plan fftw_plan_dft_r2c( int rank, const int *n, double *in, fftw_complex *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_r2c_1d( int n0, float *in, fftwf_complex *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_r2c_2d( int n0, int n1, float *in, fftwf_complex *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_r2c_3d( int n0, int n1, int n2, float *in, fftwf_complex *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_r2c( int rank, const int *n, float *in, fftwf_complex *out, unsigned flags, )#

参数:

rank[in] – 变换的维度。它可以是 1、2 或 3。
n0[in] – 第 0 维（最外层维度）中的变换（input）大小。
n1[in] – 第 1 维中的变换（input）大小。
n2[in] – 第 2 维（最内层维度）中的变换（input）大小。
n[in] – 指向大小为 rank 的整数数组的指针。n[i] 是维度 i 中的变换（input）大小，i=0,...,rank-1。n[0] 和 n[rank-1] 分别是最外层和最内层维度的大小。
in[in] – 指向输入数据的指针。
out[out] – 指向输出数据的指针。如果值与 in 相同，则变换将就地完成。
sign[in] – DFT 公式中指数的符号。它可以是 1 (FFTW_INVERSE 或 FFTW_BACKWARD)，-1 (FFTW_FORWARD)
flags[in] – planner 标志。可用选项为 FFTW_ESTIMATE、FFTW_MEASURE、FFTW_PATIENT、FFTW_EXHAUSTIVE、FFTW_WISDOM_ONLY。

返回值:

fftw(f)_plan – 创建的 fftw(f)_plan。如果 plan 创建失败，则为 nullptr。

注意

对于 R2C 变换，与 C2C 变换不同，输入和输出大小不同（特别是在最内层维度中）。此处的 n、n0、n1、n2 是输入数据（即实数数据）的大小。另请参阅 cuFFT 文档中的数据布局。

复数输入到实数输出 (C2R)#

fftw_plan fftw_plan_dft_c2r_1d( int n0, fftw_complex *in, double *out, unsigned flags, )#

fftw_plan fftw_plan_dft_c2r_2d( int n0, int n1, fftw_complex *in, double *out, unsigned flags, )#

fftw_plan fftw_plan_dft_c2r_3d( int n0, int n1, int n2, fftw_complex *in, double *out, unsigned flags, )#

fftw_plan fftw_plan_dft_c2r( int rank, const int *n, fftw_complex *in, double *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_c2r_1d( int n0, fftwf_complex *in, float *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_c2r_2d( int n0, int n1, fftwf_complex *in, float *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_c2r_3d( int n0, int n1, int n2, fftwf_complex *in, float *out, unsigned flags, )#

fftwf_plan fftwf_plan_dft_c2r( int rank, const int *n, fftwf_complex *in, float *out, unsigned flags, )#

参数:

rank[in] – 变换的维度。它可以是 1、2 或 3。
n0[in] – 第 0 维（最外层维度）中的变换（output）大小。
n1[in] – 第 1 维中的变换（output）大小。
n2[in] – 第 2 维（最内层维度）中的变换（output）大小。
n[in] – 指向大小为 rank 的整数数组的指针。n[i] 是维度 i 中的变换（output）大小，i=0,...,rank-1。n[0] 和 n[rank-1] 分别是最外层和最内层维度的大小。
in[in] – 指向输入数据的指针。
out[out] – 指向输出数据的指针。如果值与 in 相同，则变换将就地完成。
sign[in] – DFT 公式中指数的符号。它可以是 1 (FFTW_INVERSE 或 FFTW_BACKWARD)，-1 (FFTW_FORWARD)
flags[in] – planner 标志。可用选项为 FFTW_ESTIMATE、FFTW_MEASURE、FFTW_PATIENT、FFTW_EXHAUSTIVE、FFTW_WISDOM_ONLY。

返回值:

fftw(f)_plan – 创建的 fftw(f)_plan。如果 plan 创建失败，则为 nullptr。

注意

与 R2C 类似，对于 C2R 变换，输入和输出大小不同（特别是在最内层维度中）。此处的 n、n0、n1、n2 是输出数据的大小。另请参阅 cuFFT 文档中的数据布局。

注意

正如 cuFFT 文档中的傅里叶变换类型中指出的那样，C2R 变换接受复 Hermitian 输入。这意味着在最内层维度中，0th 元素和如果 n[rank-1] 是偶数，则 n[rank-1]/2 th 元素需要是实数值。如果未满足要求，则变换的行为未定义。

警告

实数到实数变换尚不支持。

高级 plan 接口#

创建 fftw(f)_plan 以计算具有指定维度、符号、大小、类型和步长的 DFT。它允许使用连续或步进的输入和输出数据执行批量 FFT。

fftw_plan fftw_plan_many_dft( int rank, const int *n, int batch, fftw_complex *in, const int *inembed, int istride, int idist, fftw_complex *out, const int *onembed, int ostride, int odist, int sign, unsigned flags, )#

fftw_plan fftw_plan_many_dft_r2c( int rank, const int *n, int batch, double *in, const int *inembed, int istride, int idist, fftw_complex *out, const int *onembed, int ostride, int odist, unsigned flags, )#

fftw_plan fftw_plan_many_dft_c2r( int rank, const int *n, int batch, fftw_complex *in, const int *inembed, int istride, int idist, double *out, const int *onembed, int ostride, int odist, unsigned flags, )#

fftwf_plan fftwf_plan_many_dft( int rank, const int *n, int batch, fftwf_complex *in, const int *inembed, int istride, int idist, fftwf_complex *out, const int *onembed, int ostride, int odist, int sign, unsigned flags, )#

fftwf_plan fftwf_plan_many_dft_r2c( int rank, const int *n, int batch, double *in, const int *inembed, int istride, int idist, fftwf_complex *out, const int *onembed, int ostride, int odist, unsigned flags, )#

fftwf_plan fftwf_plan_many_dft_c2r( int rank, const int *n, int batch, fftwf_complex *in, const int *inembed, int istride, int idist, double *out, const int *onembed, int ostride, int odist, unsigned flags, )#

参数:

rank[in] – 变换的维度。
n[in] – 指向大小为 rank 的整数数组的指针。n[i] 是维度 i 中的变换（output）大小，i=0,...,rank-1。n[0] 和 n[rank-1] 分别是最外层和最内层维度的大小。
batch[in] – 要计算的 DFT 批次数量。
inembed[in] – nullptr 或指向大小为 rank 的整数数组的指针。inembed[i] 是输入数据的维度 i 中的元素数量，i=0,...,rank-1。
istride[in] – 最内层维度中两个连续输入元素之间的距离。
idist[in] – 输入数据中两个连续批次的第一个元素之间的距离。
onembed[in] – nullptr 或指向大小为 rank 的整数数组的指针。onembed[i] 是输出数据的维度 i 中的元素数量，i=0,...,rank-1。
ostride[in] – 最内层维度中两个连续输出元素之间的距离。
odist[in] – 输出数据中两个连续批次的第一个元素之间的距离。
in[in] – 指向输入数据的指针。
out[out] – 指向输出数据的指针。如果值与 in 相同，则变换将就地完成。
sign[in] – DFT 公式中指数的符号。它可以是 1 (FFTW_INVERSE 或 FFTW_BACKWARD)，-1 (FFTW_FORWARD)
flags[in] – planner 标志。可用选项为 FFTW_ESTIMATE、FFTW_MEASURE、FFTW_PATIENT、FFTW_EXHAUSTIVE、FFTW_WISDOM_ONLY。

返回值:

fftw(f)_plan – 创建的 fftw(f)_plan。如果 plan 创建失败，则为 nullptr。

警告

尚不支持规划四维或更高维度的变换，即，我们要求 rank 小于或等于 3。

注意

为 inembed 和 onembed 传递 nullptr 等效于传递整数数组，其值分别是 inembed 和 onembed 的每个维度中的输入和输出元素数量。对于 C2C 变换，这意味着为 inembed 和 onembed 都传递 n。

警告

Guru plan 接口存在，但尚不可用。API 将始终返回 nullptr。

警告

对于 2 维和更高维度的 R2C 和 C2R 就地变换，与 FFTW 相比，数据布局存在其他约束：istride 和 ostride 必须匹配。FFTW 的约束也适用，因此数据必须填充到适应样本大小的变化。

执行接口#

执行 fftw(f)_plan。

void fftw_execute(const fftw_plan plan)#

void fftwf_execute(const fftwf_plan plan)#

此函数使用在 plan 创建期间作为参数传入的输入和输出数据。

参数:

plan[in] – 由 plan 创建 API 创建的 fftw(f)_plan。

void fftw_execute_dft( const fftw_plan plan, fftw_complex *idata, fftw_complex *odata, )#

void fftw_execute_dft_r2c( const fftw_plan plan, double *idata, fftw_complex *odata, )#

void fftw_execute_dft_c2r( const fftw_plan plan, fftwf_complex *idata, double *odata, )#

void fftwf_execute_dft( const fftwf_plan plan, fftwf_complex *idata, fftwf_complex *odata, )#

void fftwf_execute_dft_r2c( const fftwf_plan plan, float *idata, fftwf_complex *odata, )#

void fftwf_execute_dft_c2r( const fftwf_plan plan, fftwf_complex *idata, float *odata, )#

这些函数忽略在 plan 创建期间作为参数传入的输入和输出数据，并使用此处传入的输入和输出数据。

参数:

plan[in] – 由 plan 创建 API 创建的 fftw(f)_plan。
idata[in] – 指向输入数据的指针。数据类型取决于变换的类型。
odata[out] – 指向输出数据（即 DFT 结果）的指针。与 idata 相同，数据类型取决于变换的类型。

注意

idata 和 odata 需要与 fftw(f)_plan 在就地或异地变换方面保持一致，即，如果 fftw(f)_plan 是使用 in = out 创建的，则需要 idata = odata。

销毁接口#

释放与 fftw(f)_plan 关联的所有资源。

void fftw_destroy_plan(fftw_plan plan)#

void fftwf_destroy_plan(fftw_plan plan)#

参数:

plan[in] – 要销毁的 fftw(f)_plan。

线程控制#

警告

对于线程控制，NVPL FFT 遵循 FFTW 中的设计。另请参阅 FFTW3 文档中的多线程 FFTW 的用法。

int fftw_init_threads(void)#

int fftwf_init_threads(void)#

执行一次性初始化以在系统上使用线程。

返回值:: int – 如果初始化成功完成，则为非零值，否则为 0。

警告

使用 NVPL FFT 的多线程实现不是必需的。

void fftw_plan_with_nthreads(int nthreads)#

void fftwf_plan_with_nthreads(int nthreads)#

设置将在 fftw(f)_plan 中使用的线程数。请注意，设置线程数仅影响在调用此函数之后创建的 plan；它不会更改在调用 fftw(f)_init_nthreads 之前创建的 plan 的行为。

参数:

nthreads[输入] – 用于之后创建的 fftw(f)_plan (s) 的线程数。

注意

如果在应用程序中没有调用 fftw(f)_plan_with_nthreads，或者调用时 nthreads = 1，则将使用单线程实现。

int fftw_planner_nthreads(void)#

int fftwf_planner_nthreads(void)#

用于确定 fftw(f)_plan 可以使用的线程数。

返回值:: int – 之后创建的 fftw(f)_plan (s) 中将要使用的线程数。

void fftw_cleanup_threads(void)#

void fftwf_cleanup_threads(void)#: 类似于 fftw(f)_cleanup()，但用于清理线程相关的数据。

警告

此函数在 NVPL FFT 实现中不执行任何操作，不调用它也是安全的。

其他#

警告

本节中的 API 存在但 不起作用，即输出参数被设置为一些虚拟值，或者返回成功状态值。对于与 wisdom 相关的函数，无论是否调用 plan 创建 API，都返回相同的 plan。

void fftw_cleanup(void)#

void fftwf_cleanup(void)#

void fftw_print_plan(const fftw_plan plan)#

void fftwf_print_plan(const fftwf_plan plan)#

参数:

plan[in] – 由 plan 创建 API 创建的 fftw(f)_plan。

void fftw_set_timelimit(double seconds)#

void fftwf_set_timelimit(double seconds)#

参数:

second[输入] – plan 创建的时间限制。

double fftw_cost(const fftw_plan plan)#

double fftwf_cost(const fftw_plan plan)#

参数:

plan[in] – 由 plan 创建 API 创建的 fftw(f)_plan。

返回值:

double – 始终返回 1.0。

void fftw_flops( const fftw_plan plan, double *add, double *mul, double *fma, )#

void fftwf_flops( const fftwf_plan plan, double *add, double *mul, double *fma, )#

参数:

plan[in] – 由 plan 创建 API 创建的 fftw(f)_plan。
add[输出] – 始终设置为 1.0。
mul[输出] – 始终设置为 1.0。
fma[输出] – 始终设置为 1.0。

Wisdom 接口#

用于导出、导入和忘记受支持格式的 wisdom。请参阅 FFTW3 文档中的 Wisdom。

void fftw_export_wisdom( void (*write_char)(char c, void*), void *data, )#

void fftw_export_wisdom_to_file(FILE *output_file)#

char *fftw_export_wisdom_to_string(void)#

int fftw_import_wisdom(int (*read_char)(void*), void *data)#

int fftw_import_wisdom_from_file(FILE *input_file)#

int fftw_import_wisdom_from_string(const char *input_string)#

int fftw_import_system_wisdom(void)#

void fftw_forget_wisdom(void)#

void fftwf_export_wisdom( void (*write_char)(char c, void*), void *data, )#

void fftwf_export_wisdom_to_file(FILE *output_file)#

char *fftwf_export_wisdom_to_string(void)#

int fftwf_import_wisdom(int (*read_char)(void*), void *data)#

int fftwf_import_wisdom_from_file(FILE *input_file)#

int fftwf_import_wisdom_from_string(const char *input_string)#

int fftwf_import_system_wisdom(void)#

void fftwf_forget_wisdom(void)#