fft_plan.h File Reference

Reusable 1D and 2D complex FFT plans for operator implementations. More...

#include "oakfield/field.h"
#include <complex.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for fft_plan.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	FFTPow2Plan
	Reusable radix-2 complex FFT plan for power-of-two transform lengths. More...
struct	FFTPlan
	Reusable 1D complex FFT plan for arbitrary nonzero transform lengths. More...
struct	FFTPlan2D
	Separable 2D complex FFT plan built from row and column 1D plans. More...

Typedefs
typedef struct FFTPow2Plan	FFTPow2Plan
	Reusable radix-2 complex FFT plan for power-of-two transform lengths.
typedef struct FFTPlan	FFTPlan
	Reusable 1D complex FFT plan for arbitrary nonzero transform lengths.
typedef struct FFTPlan2D	FFTPlan2D
	Separable 2D complex FFT plan built from row and column 1D plans.

Functions
void	fft_pow2_plan_reset (FFTPow2Plan *plan)
	Reset a power-of-two FFT plan to an empty non-owning state.
void	fft_pow2_plan_destroy (FFTPow2Plan *plan)
	Free storage owned by a power-of-two FFT plan and reset it.
SimResult	fft_pow2_plan_init (FFTPow2Plan *plan, size_t n)
	Initialize a radix-2 FFT plan.
void	fft_pow2_execute (const FFTPow2Plan *plan, double complex *data, bool inverse)
	Execute an initialized radix-2 complex FFT in place.
void	fft_plan_reset (FFTPlan *plan)
	Reset a 1D FFT plan to an empty non-owning state.
void	fft_plan_destroy (FFTPlan *plan)
	Free storage owned by a 1D FFT plan and reset it.
SimResult	fft_plan_init (FFTPlan *plan, size_t n)
	Initialize a 1D complex FFT plan for any nonzero length.
SimResult	fft_plan_forward (const FFTPlan *plan, const double complex *input, double complex *output)
	Execute a 1D forward complex FFT.
SimResult	fft_plan_inverse (const FFTPlan *plan, const double complex *input, double complex *output)
	Execute a normalized 1D inverse complex FFT.
void	fft_plan2d_reset (FFTPlan2D *plan)
	Reset a 2D FFT plan to an empty non-owning state.
void	fft_plan2d_destroy (FFTPlan2D *plan)
	Free storage owned by a 2D FFT plan and reset it.
SimResult	fft_plan2d_init (FFTPlan2D *plan, size_t rows, size_t cols, size_t row_stride, size_t col_stride)
	Initialize a separable 2D complex FFT plan.
SimResult	fft_plan2d_forward (const FFTPlan2D *plan, const double complex *input, double complex *output)
	Execute a separable 2D forward complex FFT.
SimResult	fft_plan2d_inverse (const FFTPlan2D *plan, const double complex *input, double complex *output)
	Execute a normalized separable 2D inverse complex FFT.

Detailed Description

Reusable 1D and 2D complex FFT plans for operator implementations.

Power-of-two sizes use a radix-2 plan, while non-power-of-two 1D sizes use Bluestein convolution over an internal power-of-two plan. The 2D plan applies separable row and column transforms using caller-provided strides.

Typedef Documentation

FFTPlan

typedef struct FFTPlan FFTPlan

Reusable 1D complex FFT plan for arbitrary nonzero transform lengths.

Power-of-two lengths use FFTPow2Plan directly; other lengths own the Bluestein chirp/convolution scratch storage needed by fft_plan_forward() and fft_plan_inverse().

FFTPlan2D

typedef struct FFTPlan2D FFTPlan2D

Separable 2D complex FFT plan built from row and column 1D plans.

The plan owns its nested row/column plans and temporary row/column scratch buffers until fft_plan2d_destroy() is called.

FFTPow2Plan

typedef struct FFTPow2Plan FFTPow2Plan

Reusable radix-2 complex FFT plan for power-of-two transform lengths.

An initialized plan owns its bit-reversal table, twiddle storage, and optional vDSP scratch/setup resources until fft_pow2_plan_destroy() is called.

Function Documentation

fft_plan2d_destroy()

void fft_plan2d_destroy

(

FFTPlan2D *

plan

)

Free storage owned by a 2D FFT plan and reset it.

Parameters

plan	Plan to destroy; NULL is ignored.

fft_plan2d_forward()

SimResult fft_plan2d_forward	(	const FFTPlan2D *	plan,
		const double complex *	input,
		double complex *	output
	)

Execute a separable 2D forward complex FFT.

Parameters

	plan	Initialized 2D FFT plan.
	input	Input buffer addressed by the plan strides.
[out]	output	Output buffer addressed by the plan strides.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL or invalid plan data, or SIM_RESULT_INVALID_STATE for missing scratch storage.

fft_plan2d_init()

SimResult fft_plan2d_init	(	FFTPlan2D *	plan,
		size_t	rows,
		size_t	cols,
		size_t	row_stride,
		size_t	col_stride
	)

Initialize a separable 2D complex FFT plan.

Parameters

plan	Plan object to initialize.
rows	Number of rows; must be greater than zero.
cols	Number of columns; must be greater than zero.
row_stride	Element stride between adjacent rows.
col_stride	Element stride between adjacent columns.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for invalid inputs, or SIM_RESULT_OUT_OF_MEMORY on allocation failure.

fft_plan2d_inverse()

SimResult fft_plan2d_inverse	(	const FFTPlan2D *	plan,
		const double complex *	input,
		double complex *	output
	)

Execute a normalized separable 2D inverse complex FFT.

Parameters

	plan	Initialized 2D FFT plan.
	input	Input buffer addressed by the plan strides.
[out]	output	Output buffer addressed by the plan strides.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL or invalid plan data, or SIM_RESULT_INVALID_STATE for missing scratch storage.

fft_plan2d_reset()

void fft_plan2d_reset

(

FFTPlan2D *

plan

)

Reset a 2D FFT plan to an empty non-owning state.

Parameters

plan	Plan to reset; NULL is ignored.

fft_plan_destroy()

void fft_plan_destroy

(

FFTPlan *

plan

)

Free storage owned by a 1D FFT plan and reset it.

Parameters

plan	Plan to destroy; NULL is ignored.

fft_plan_forward()

SimResult fft_plan_forward	(	const FFTPlan *	plan,
		const double complex *	input,
		double complex *	output
	)

Execute a 1D forward complex FFT.

Parameters

	plan	Initialized 1D FFT plan.
	input	Input buffer with plan->n entries.
[out]	output	Output buffer with plan->n entries.

Returns

SIM_RESULT_OK on success or SIM_RESULT_INVALID_ARGUMENT for NULL inputs.

fft_plan_init()

SimResult fft_plan_init	(	FFTPlan *	plan,
		size_t	n
	)

Initialize a 1D complex FFT plan for any nonzero length.

Parameters

plan	Plan object to initialize.
n	Transform length; must be greater than zero.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for invalid inputs, or SIM_RESULT_OUT_OF_MEMORY on allocation failure.

fft_plan_inverse()

SimResult fft_plan_inverse	(	const FFTPlan *	plan,
		const double complex *	input,
		double complex *	output
	)

Execute a normalized 1D inverse complex FFT.

Parameters

	plan	Initialized 1D FFT plan.
	input	Input buffer with plan->n entries.
[out]	output	Output buffer with plan->n entries.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL inputs, or SIM_RESULT_INVALID_STATE for an incomplete plan.

fft_plan_reset()

void fft_plan_reset

(

FFTPlan *

plan

)

Reset a 1D FFT plan to an empty non-owning state.

Parameters

plan	Plan to reset; NULL is ignored.

fft_pow2_execute()

void fft_pow2_execute	(	const FFTPow2Plan *	plan,
		double complex *	data,
		bool	inverse
	)

Execute an initialized radix-2 complex FFT in place.

Parameters

plan	Initialized power-of-two plan.
data	Complex buffer with plan->n entries; transformed in place.
inverse	When true, compute the normalized inverse transform.

fft_pow2_plan_destroy()

void fft_pow2_plan_destroy

(

FFTPow2Plan *

plan

)

Free storage owned by a power-of-two FFT plan and reset it.

Parameters

plan	Plan to destroy; NULL is ignored.

fft_pow2_plan_init()

SimResult fft_pow2_plan_init	(	FFTPow2Plan *	plan,
		size_t	n
	)

Initialize a radix-2 FFT plan.

Parameters

plan	Plan object to initialize.
n	Transform length; must be nonzero and a power of two.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for invalid inputs, or SIM_RESULT_OUT_OF_MEMORY on allocation/setup failure.

fft_pow2_plan_reset()

void fft_pow2_plan_reset

(

FFTPow2Plan *

plan

)

Reset a power-of-two FFT plan to an empty non-owning state.

Parameters

plan	Plan to reset; NULL is ignored.