Detailed Description

Provides FFTW-like planning routines atop Underling's pencil decomposition information via the underling_extents struct.

Go to the source code of this file.

Classes
struct	underling_fftw_extents
	A transparent type storing the local sizes, strides, and storage when the data is long in a particular direction `n0`, `n1`, or `n2`. More...

Creation, execution, and destruction of underling_fftw_plans
#define	UNDERLING_FFTW_PACKED_LONG_N2
	Flag indicating the FFT transform output and input for the "long in n2" direction is packed contiguously in memory. More...

#define	UNDERLING_FFTW_PACKED_LONG_N0
	Flag indicating the FFT transform output and input for the "long in n0" direction is packed contiguously in memory. More...

#define	UNDERLING_FFTW_PACKED_ALL
	Convenience flag indicating packed transform output whenever possible. More...

#define	UNDERLING_FFTW_PACKED_NONE
	Flag indicating the FFT transform output for no direction is necessarily packed contiguously in memory. More...

typedef struct underling_fftw_plan_s *	underling_fftw_plan
	A type encapsulating FFTW-like planning information. More...

underling_fftw_plan	underling_fftw_plan_create_c2c_forward (const underling_problem problem, int long_ni, underling_real in, underling_real out, unsigned fftw_rigor_flags, unsigned packed_flags)
	Create a plan to perform a forward complex-to-complex FFT on the given data when long in the `long_ni`th direction. More...

underling_fftw_plan	underling_fftw_plan_create_c2c_backward (const underling_problem problem, int long_ni, underling_real in, underling_real out, unsigned fftw_rigor_flags, unsigned packed_flags)
	Create a plan to perform a backward complex-to-complex FFT on the given data when long in the `long_ni`th direction. More...

underling_fftw_plan	underling_fftw_plan_create_r2c_forward (const underling_problem problem, int long_ni, underling_real in, underling_real out, unsigned fftw_rigor_flags, unsigned packed_flags)
	Create a plan to perform a forward real-to-complex FFT on the given data when long in the `long_ni`th direction. More...

underling_fftw_plan	underling_fftw_plan_create_c2r_backward (const underling_problem problem, int long_ni, underling_real in, underling_real out, unsigned fftw_rigor_flags, unsigned packed_flags)
	Create a plan to perform a backward complex-to-real FFT on the given data when long in the `long_ni`th direction. More...

underling_fftw_plan	underling_fftw_plan_create_inverse (const underling_fftw_plan plan_to_invert, underling_real in, underling_real out, unsigned fftw_rigor_flags)
	Create a plan to invert another underling_fftw_plan. More...

int	underling_fftw_plan_execute (const underling_fftw_plan plan, underling_real in, underling_real out)
	Perform a previously planned FFT. More...

void	underling_fftw_plan_destroy (underling_fftw_plan plan)
	Destroy all resources associated with the given plan. More...

void	underling_fftw_fprint_plan (const underling_fftw_plan plan, FILE *output_file)
	Dump an instance's internals in a debugging-friendly format. More...

Obtaining storage details for an underling_fftw_plan
const underling_fftw_extents	UNDERLING_FFTW_EXTENTS_INVALID
	A static instance used to communicate wholly invalid extents. More...

int	underling_fftw_extents_cmp (const underling_fftw_extents const e1, const underling_fftw_extents const e2)
	Compare two underling_fftw_extents instances using lexicographic ordering. More...

void	underling_fftw_fprint_extents (const underling_fftw_extents extents, FILE output_file)
	Dump an instance's internals in a debugging-friendly format. More...

underling_fftw_extents	underling_fftw_local_extents_input (const underling_fftw_plan plan)
	Obtain local size, stride, and storage information for the input data to a given plan. More...

underling_fftw_extents	underling_fftw_local_extents_output (const underling_fftw_plan plan)
	Obtain local size, stride, and storage information for the input data to a given plan. More...

int	underling_fftw_local_input (const underling_fftw_plan plan, int start, int size, int stride, int order)
	Obtain the processor-local sizes, storage details, and global starting offsets for the given plan's input data when long in the direction for which the plan was created. More...

int	underling_fftw_local_output (const underling_fftw_plan plan, int start, int size, int stride, int order)
	Obtain the processor-local sizes, storage details, and global starting offsets for the given plan's output data when long in the direction for which the plan was created. More...

Macro Definition Documentation

◆ UNDERLING_FFTW_PACKED_ALL

#define UNDERLING_FFTW_PACKED_ALL

Convenience flag indicating packed transform output whenever possible.

◆ UNDERLING_FFTW_PACKED_LONG_N0

#define UNDERLING_FFTW_PACKED_LONG_N0

Flag indicating the FFT transform output and input for the "long in n0" direction is packed contiguously in memory.

Transform input must likewise be packed. This flag may only be used for out-of-place transforms and likely will incur additional memory access cost with each transform. The flag is provided for situations where other compute kernels benefit greatly from having packed, contiguous storage and/or for compatibility with third party libraries.

When combined with UNDERLING_TRANSPOSED_LONG_N0, the FFT transform output and input is not stored row-major n0 x (n1/pB x * n2/pA) but rather is stored packed contiguously as (n1/pB x n2/pA) x n0. In-memory reshuffling is minimized in this circumstance.

See also: The documentation for underling_fftw_plan_create_c2c_forward, underling_fftw_plan_create_c2c_backward, underling_fftw_plan_create_r2c_forward, or underling_fftw_plan_create_c2r_backward for more details on creating plans.

◆ UNDERLING_FFTW_PACKED_LONG_N2

#define UNDERLING_FFTW_PACKED_LONG_N2

Flag indicating the FFT transform output and input for the "long in n2" direction is packed contiguously in memory.

Transform input must likewise be packed. This flag may only be used for out-of-place transforms and likely will incur additional memory access cost with each transform. The flag is provided for situations where other compute kernels benefit greatly from having packed, contiguous storage and/or for compatibility with third party libraries.

When combined with UNDERLING_TRANSPOSED_LONG_N2, the FFT transform output and input is not stored row-major n2 x (n0/pB x n1/pA) but rather is stored packed contiguously as (n0/pB x n1/pA) x n2. In-memory reshuffling is minimized in this circumstance.

See also: The documentation for underling_fftw_plan_create_c2c_forward, underling_fftw_plan_create_c2c_backward, underling_fftw_plan_create_r2c_forward, or underling_fftw_plan_create_c2r_backward for more details on creating plans.

◆ UNDERLING_FFTW_PACKED_NONE

#define UNDERLING_FFTW_PACKED_NONE

Flag indicating the FFT transform output for no direction is necessarily packed contiguously in memory.

Under some circumstances, transform output and input may be packed inadvertently (e.g. complex-to-complex transforms on regular grids).

See also: UNDERLING_FFTW_PACKED_LONG_N2, UNDERLING_FFTW_PACKED_LONG_N0, and UNDERLING_FFTW_PACKED_ALL for alternatives.

Typedef Documentation

◆ underling_fftw_plan

typedef struct underling_fftw_plan_s* underling_fftw_plan

A type encapsulating FFTW-like planning information.

Function Documentation

◆ underling_fftw_extents_cmp()

int underling_fftw_extents_cmp	(	const underling_fftw_extents *const	e1,
		const underling_fftw_extents *const	e2
	)

Compare two underling_fftw_extents instances using lexicographic ordering.

Parameters

e1	First instance to compare.
e2	Second instance to compare.

Returns: Returns an integer less than, equal to, or greater than zero if *e1 is found, respectively, to be less than, to match, or be greater than *e2.

◆ underling_fftw_fprint_extents()

void underling_fftw_fprint_extents	(	const underling_fftw_extents *	extents,
		FILE *	output_file
	)

Dump an instance's internals in a debugging-friendly format.

Parameters

extents	Extents to dump.
output_file	Desired output handle, which may be `stdout` or `stderr`.

◆ underling_fftw_fprint_plan()

void underling_fftw_fprint_plan	(	const underling_fftw_plan	plan,
		FILE *	output_file
	)

Dump an instance's internals in a debugging-friendly format.

Parameters

plan	Plan to be dumped.
output_file	Desired output handle, which may be `stdout` or `stderr`.

◆ underling_fftw_local_extents_input()

underling_fftw_extents underling_fftw_local_extents_input ( const underling_fftw_plan plan )

Obtain local size, stride, and storage information for the input data to a given plan.

This information should be used to "load" the data prior to executing the plan with underling_fftw_plan_execute.

Parameters

plan	Plan for which to retrieve information.

Returns: a valid underling_fftw_extents structure on success. On failure, calls underling_error and returns UNDERLING_EXTENTS_INVALID.

See also: The method underling_fftw_local_input for a way to obtain only a subset of this information, or for a more Fortran-ready interface.

◆ underling_fftw_local_extents_output()

underling_fftw_extents underling_fftw_local_extents_output ( const underling_fftw_plan plan )

Obtain local size, stride, and storage information for the input data to a given plan.

This information should be used to process the data after executing the plan with underling_fftw_plan_execute.

Parameters

plan	Plan for which to retrieve information.

Returns: a valid underling_fftw_extents structure on success. On failure, calls underling_error and returns UNDERLING_EXTENTS_INVALID.

See also: The method underling_fftw_local_output for a way to obtain only a subset of this information, or for a more Fortran-ready interface.

◆ underling_fftw_local_input()

int underling_fftw_local_input	(	const underling_fftw_plan	plan,
		int *	start,
		int *	size,
		int *	stride,
		int *	order
	)

Obtain the processor-local sizes, storage details, and global starting offsets for the given plan's input data when long in the direction for which the plan was created.

This is identical to the data obtainable via underling_fftw_local_extents_input but is provided in a more Fortran-ready interface. All strides and sizes are given in units of underling_real.

Parameters

[in]	plan	Plan for which to retrieve information.
[in,out]	start	If non-NULL on entry, contains underling_extents.start on successful return.
[in,out]	size	If non-NULL on entry, contains underling_extents.size on successful return.
[in,out]	stride	If non-NULL on entry, contains underling_extents.stride on successful return.
[in,out]	order	If non-NULL on entry, contains underling_extents.order on successful return.

Returns: UNDERLING_SUCCESS (zero) on success and non-zero on failure.

See also: The method underling_fftw_local_extents_input for a more C-friendly and const-correct capable way to obtain all of this information.

◆ underling_fftw_local_output()

int underling_fftw_local_output	(	const underling_fftw_plan	plan,
		int *	start,
		int *	size,
		int *	stride,
		int *	order
	)

Obtain the processor-local sizes, storage details, and global starting offsets for the given plan's output data when long in the direction for which the plan was created.

This is identical to the data obtainable via underling_fftw_local_extents_output but is provided in a more Fortran-ready interface. All strides and sizes are given in units of underling_real.

Parameters

[in]	plan	Plan for which to retrieve information.
[in,out]	start	If non-NULL on entry, contains underling_extents.start on successful return.
[in,out]	size	If non-NULL on entry, contains underling_extents.size on successful return.
[in,out]	stride	If non-NULL on entry, contains underling_extents.stride on successful return.
[in,out]	order	If non-NULL on entry, contains underling_extents.order on successful return.

Returns: UNDERLING_SUCCESS (zero) on success and non-zero on failure.

See also: The method underling_fftw_local_extents_output for a more C-friendly and const-correct capable way to obtain all of this information.

◆ underling_fftw_plan_create_c2c_backward()

underling_fftw_plan underling_fftw_plan_create_c2c_backward	(	const underling_problem	problem,
		int	long_ni,
		underling_real *	in,
		underling_real *	out,
		unsigned	fftw_rigor_flags,
		unsigned	packed_flags
	)

Create a plan to perform a backward complex-to-complex FFT on the given data when long in the long_nith direction.

The problem must have had howmany specified as a multiple of two at creation time, and it will be treated as howmany/2 complex fields. Note that the transform is not normalized.

Out-of-place plans are created by specifying input and output buffers such that in != out. Executing an out-of-place plan will always destroy the contents of the input buffer in. In-place plans can be created by specifying in == out. In-place plans always use less memory but may run more slowly than out-of-place plans.

Parameters

problem	Problem to use for layout and stride information.
long_ni	Direction across which to perform the FFT, which is assumed to be long whenever the returned plan is executed.
in	Input buffer containing the source data to be transformed.
out	Output buffer to contain the data after transformation.
fftw_rigor_flags	One of FFTW's rigor planning flags, e.g. FFTW_ESTIMATE. Specifying zero is equivalent to providing FFTW_MEASURE. Note that the buffers `in` and `out` are overwritten during the planning process for any value other than FFTW_ESTIMATE.
packed_flags	One of UNDERLING_FFTW_PACKED_LONG_N2, UNDERLING_FFTW_PACKED_LONG_N0, UNDERLING_FFTW_PACKED_ALL, or UNDERLING_FFTW_PACKED_NONE. Specifying zero is equivalent to providing UNDERLING_FFTW_PACKED_NONE. Note only UNDERLING_FFTW_PACKED_NONE is valid when creating an in-place plan.

Returns: On success, return a valid underling_fftw_plan. On failure, calls underling_error and returns NULL.

See also: The method underling_fftw_plan_destroy for how to destroy an instance.; The method underling_fftw_plan_create_inverse for how to create the corresponding inverse FFT. It is incorrect to use any other way to invert the return FFT.

◆ underling_fftw_plan_create_c2c_forward()

underling_fftw_plan underling_fftw_plan_create_c2c_forward	(	const underling_problem	problem,
		int	long_ni,
		underling_real *	in,
		underling_real *	out,
		unsigned	fftw_rigor_flags,
		unsigned	packed_flags
	)

Create a plan to perform a forward complex-to-complex FFT on the given data when long in the long_nith direction.

The problem must have had howmany specified as a multiple of two at creation time, and it will be treated as howmany/2 complex fields. Note that the transform is not normalized.

Out-of-place plans are created by specifying input and output buffers such that in != out. Executing an out-of-place plan will always destroy the contents of the input buffer in. In-place plans can be created by specifying in == out. In-place plans always use less memory but may run more slowly than out-of-place plans.

Parameters

problem	Problem to use for layout and stride information.
long_ni	Direction across which to perform the FFT, which is assumed to be long whenever the returned plan is executed.
in	Input buffer containing the source data to be transformed.
out	Output buffer to contain the data after transformation.
fftw_rigor_flags	One of FFTW's rigor planning flags, e.g. FFTW_ESTIMATE. Specifying zero is equivalent to providing FFTW_MEASURE. Note that the buffers `in` and `out` are overwritten during the planning process for any value other than FFTW_ESTIMATE.
packed_flags	One of UNDERLING_FFTW_PACKED_LONG_N2, UNDERLING_FFTW_PACKED_LONG_N0, UNDERLING_FFTW_PACKED_ALL, or UNDERLING_FFTW_PACKED_NONE. Specifying zero is equivalent to providing UNDERLING_FFTW_PACKED_NONE. Note only UNDERLING_FFTW_PACKED_NONE is valid when creating an in-place plan.

Returns: On success, return a valid underling_fftw_plan. On failure, calls underling_error and returns NULL.

See also: The method underling_fftw_plan_destroy for how to destroy an instance.; The method underling_fftw_plan_create_inverse for how to create the corresponding inverse FFT. It is incorrect to use any other way to invert the return FFT.

◆ underling_fftw_plan_create_c2r_backward()

underling_fftw_plan underling_fftw_plan_create_c2r_backward	(	const underling_problem	problem,
		int	long_ni,
		underling_real *	in,
		underling_real *	out,
		unsigned	fftw_rigor_flags,
		unsigned	packed_flags
	)

Create a plan to perform a backward complex-to-real FFT on the given data when long in the long_nith direction.

The problem must have had howmany specified as a multiple of two at creation time, and it will be treated as howmany/2 complex fields. Note that the transform is not normalized.

Out-of-place plans are created by specifying input and output buffers such that in != out. Executing an out-of-place plan will always destroy the contents of the input buffer in. In-place plans can be created by specifying in == out. In-place plans always use less memory but may run more slowly than out-of-place plans.

Parameters

problem	Problem to use for layout and stride information.
long_ni	Direction across which to perform the FFT, which is assumed to be long whenever the returned plan is executed.
in	Input buffer containing the source data to be transformed.
out	Output buffer to contain the data after transformation.
fftw_rigor_flags	One of FFTW's rigor planning flags, e.g. FFTW_ESTIMATE. Specifying zero is equivalent to providing FFTW_MEASURE. Note that the buffers `in` and `out` are overwritten during the planning process for any value other than FFTW_ESTIMATE.
packed_flags	One of UNDERLING_FFTW_PACKED_LONG_N2, UNDERLING_FFTW_PACKED_LONG_N0, UNDERLING_FFTW_PACKED_ALL, or UNDERLING_FFTW_PACKED_NONE. Specifying zero is equivalent to providing UNDERLING_FFTW_PACKED_NONE. Note only UNDERLING_FFTW_PACKED_NONE is valid when creating an in-place plan.

Returns: On success, return a valid underling_fftw_plan. On failure, calls underling_error and returns NULL.

See also: The method underling_fftw_plan_destroy for how to destroy an instance.; The method underling_fftw_plan_create_inverse for how to create the corresponding inverse FFT. It is incorrect to use any other way to invert the return FFT.

◆ underling_fftw_plan_create_inverse()

underling_fftw_plan underling_fftw_plan_create_inverse	(	const underling_fftw_plan	plan_to_invert,
		underling_real *	in,
		underling_real *	out,
		unsigned	fftw_rigor_flags
	)

Create a plan to invert another underling_fftw_plan.

Inverse plans appropriately account for all input ordering issues stemming from use of flags like UNDERLING_TRANSPOSED_LONG_N2, UNDERLING_TRANSPOSED_LONG_N0, UNDERLING_FFTW_PACKED_LONG_N2, or UNDERLING_FFTW_PACKED_LONG_N0. Note that the inverse transform is not normalized. Plan pairs created using this method will have compatible input and output underling_fftw_extents information.

Out-of-place plans are created by specifying input and output buffers such that in != out. Executing an out-of-place plan will always destroy the contents of the input buffer in. In-place plans can be created by specifying in == out. In-place plans always use less memory but will often run more slowly than out-of-place plans.

Parameters

plan_to_invert	Prior plan to use for layout and stride information.
in	Input buffer containing the source data to be transformed.
out	Output buffer to contain the data after transformation.
fftw_rigor_flags	One of FFTW's rigor planning flags, e.g. FFTW_ESTIMATE. Specifying zero is equivalent to providing FFTW_MEASURE. Note that the buffers `in` and `out` are overwritten during the planning process for any value other than FFTW_ESTIMATE.

Returns: On success, return a valid underling_fftw_plan which inverts plan_to_invert up to normalization. On failure, calls underling_error and returns NULL.

See also: The method underling_fftw_plan_destroy for how to destroy an instance.

◆ underling_fftw_plan_create_r2c_forward()

underling_fftw_plan underling_fftw_plan_create_r2c_forward	(	const underling_problem	problem,
		int	long_ni,
		underling_real *	in,
		underling_real *	out,
		unsigned	fftw_rigor_flags,
		unsigned	packed_flags
	)

Create a plan to perform a forward real-to-complex FFT on the given data when long in the long_nith direction.

The problem must have had howmany specified as a multiple of two at creation time, and it will be treated as howmany/2 complex fields. Note that the transform is not normalized.

Out-of-place plans are created by specifying input and output buffers such that in != out. Executing an out-of-place plan will always destroy the contents of the input buffer in. In-place plans can be created by specifying in == out. In-place plans always use less memory but may run more slowly than out-of-place plans.

Parameters

problem	Problem to use for layout and stride information.
long_ni	Direction across which to perform the FFT, which is assumed to be long whenever the returned plan is executed.
in	Input buffer containing the source data to be transformed.
out	Output buffer to contain the data after transformation.
fftw_rigor_flags	One of FFTW's rigor planning flags, e.g. FFTW_ESTIMATE. Specifying zero is equivalent to providing FFTW_MEASURE. Note that the buffers `in` and `out` are overwritten during the planning process for any value other than FFTW_ESTIMATE.
packed_flags	One of UNDERLING_FFTW_PACKED_LONG_N2, UNDERLING_FFTW_PACKED_LONG_N0, UNDERLING_FFTW_PACKED_ALL, or UNDERLING_FFTW_PACKED_NONE. Specifying zero is equivalent to providing UNDERLING_FFTW_PACKED_NONE. Note only UNDERLING_FFTW_PACKED_NONE is valid when creating an in-place plan.

Returns: On success, return a valid underling_fftw_plan. On failure, calls underling_error and returns NULL.

See also: The method underling_fftw_plan_destroy for how to destroy an instance.; The method underling_fftw_plan_create_inverse for how to create the corresponding inverse FFT. It is incorrect to use any other way to invert the return FFT.

◆ underling_fftw_plan_destroy()

void underling_fftw_plan_destroy ( underling_fftw_plan plan )

Destroy all resources associated with the given plan.

Parameters

plan	Plan to be destroyed.

◆ underling_fftw_plan_execute()

int underling_fftw_plan_execute	(	const underling_fftw_plan	plan,
		underling_real *	in,
		underling_real *	out
	)

Perform a previously planned FFT.

Appropriate calls to the underlying FFT implementation will occur. The input and output buffers must be aligned identically to the input and output buffers provided during planning.

Parameters

plan	Plan to be executed.
in	Input buffer on which to execute the plan. For out-of-place transforms, this buffer's contents will be destroyed.
out	Output buffer on which to execute the plan. For in-place transforms, one must specify `out == in`.

Returns: UNDERLING_SUCCESS (zero) on success and non-zero on failure.

Variable Documentation

◆ UNDERLING_FFTW_EXTENTS_INVALID

const underling_fftw_extents UNDERLING_FFTW_EXTENTS_INVALID

A static instance used to communicate wholly invalid extents.

Detailed Description

Classes

Creation, execution, and destruction of underling_fftw_plans

Obtaining storage details for an underling_fftw_plan

Macro Definition Documentation

◆ UNDERLING_FFTW_PACKED_ALL

◆ UNDERLING_FFTW_PACKED_LONG_N0

◆ UNDERLING_FFTW_PACKED_LONG_N2

◆ UNDERLING_FFTW_PACKED_NONE

Typedef Documentation

◆ underling_fftw_plan

Function Documentation

◆ underling_fftw_extents_cmp()

◆ underling_fftw_fprint_extents()

◆ underling_fftw_fprint_plan()

◆ underling_fftw_local_extents_input()

◆ underling_fftw_local_extents_output()

◆ underling_fftw_local_input()

◆ underling_fftw_local_output()

◆ underling_fftw_plan_create_c2c_backward()

◆ underling_fftw_plan_create_c2c_forward()

◆ underling_fftw_plan_create_c2r_backward()

◆ underling_fftw_plan_create_inverse()

◆ underling_fftw_plan_create_r2c_forward()

◆ underling_fftw_plan_destroy()

◆ underling_fftw_plan_execute()

Variable Documentation

◆ UNDERLING_FFTW_EXTENTS_INVALID