N-dimensional distributed FFT plan with RAII semantics. More...

#include <shafft.hpp>

Public Member Functions
	FFTND () noexcept=default
	Default constructor. Creates an uninitialized plan.

	~FFTND () noexcept override
	Destructor. Releases all internal resources.

void	release () noexcept override
	Release all internal resources.

	FFTND (FFTND &&other) noexcept
	Move constructor.

FFTND &	operator= (FFTND &&other) noexcept
	Move assignment operator.

	FFTND (const FFTND &)=delete

FFTND &	operator= (const FFTND &)=delete

int	init (const std::vector< int > &commDims, const std::vector< size_t > &dimensions, FFTType type, MPI_Comm comm, TransformLayout output=TransformLayout::REDISTRIBUTED) noexcept
	Initialize plan with Cartesian process grid.

int	plan () noexcept override
	Create backend FFT plans.

int	setBuffers (complexf data, complexf work) noexcept
	Attach data and work buffers.

int	setBuffers (complexd data, complexd work) noexcept

int	getBuffers (complexf data, complexf work) noexcept
	Retrieve current buffer pointers.

int	getBuffers (complexd data, complexd work) noexcept

int	execute (FFTDirection direction) noexcept override
	Execute the FFT.

int	normalize () noexcept override
	Apply symmetric normalization (1/sqrt(N) per transform).

size_t	allocSize () const noexcept override
	Get required buffer size in complex elements.

size_t	globalSize () const noexcept override
	Get total global tensor size (product of dimensions).

int	ndim () const noexcept override
	Get number of dimensions.

FFTType	fftType () const noexcept override
	Get FFT precision (C2C or Z2Z).

int	getLayout (std::vector< size_t > &subsize, std::vector< size_t > &offset, TensorLayout layout=TensorLayout::CURRENT) const noexcept
	Query local tensor layout.

int	getAxes (std::vector< int > &ca, std::vector< int > &da, TensorLayout layout=TensorLayout::CURRENT) const noexcept
	Query axis distribution.

bool	isActive () const noexcept override
	Check if this rank participates in computation.

int	setBuffersRaw (void data, void work) noexcept override
	Attach buffers (type-erased).

int	getBuffersRaw (void data, void work) noexcept override
	Retrieve current buffer pointers (type-erased).

int	getCommunicator (MPI_Comm *outComm) const noexcept
	Get a duplicated communicator from this plan.

int	init (shafft_nd_config_t &cfg) noexcept
	Initialize plan from a resolved config object.

Public Member Functions inherited from shafft::FFT
	operator bool () const noexcept
	Check if the plan is valid (alias for isConfigured).

PlanState	state () const noexcept
	Get the current plan state.

bool	isConfigured () const noexcept
	Check if the plan is at least configured (init() succeeded).

bool	isPlanned () const noexcept
	Check if the plan is fully planned and ready for execution.

	FFT (const FFT &)=delete

FFT &	operator= (const FFT &)=delete

Detailed Description

Manages plan lifetime automatically. User owns data and work buffers.

Note

Typical usage flow:

Call configurationND() to compute decomposition parameters
Construct FFTND and call init() with the computed parameters
Allocate buffers using allocSize() and call setBuffers()
Call plan() to create backend FFT plans
Call execute() for forward/backward transforms
Call normalize() after a forward-backward pair to restore scale

Examples: example.cpp, example_portable.cpp, and example_portable_config.cpp.

Constructor & Destructor Documentation

◆ FFTND() [1/3]

shafft::FFTND::FFTND ( )

defaultnoexcept

◆ ~FFTND()

shafft::FFTND::~FFTND ( )

overridenoexcept

◆ FFTND() [2/3]

shafft::FFTND::FFTND ( FFTND && other )

noexcept

Transfers ownership of backend resources from other. The moved-from plan becomes uninitialized.

Parameters

other Plan to move from.

◆ FFTND() [3/3]

shafft::FFTND::FFTND ( const FFTND & )

delete

Member Function Documentation

◆ release()

void shafft::FFTND::release ( )

overridevirtualnoexcept

Call before MPI_Finalize() if the plan outlives MPI. After release(), the plan is uninitialized.

Implements shafft::FFT.

Examples: example.cpp, and example_portable.cpp.

◆ operator=() [1/2]

FFTND & shafft::FFTND::operator= ( FFTND && other )

noexcept

Releases current resources and takes ownership from other. The moved-from plan becomes uninitialized.

Parameters

other Plan to move from.

Returns: Reference to this plan.

◆ operator=() [2/2]

FFTND & shafft::FFTND::operator= ( const FFTND & )

delete

◆ init() [1/2]

int shafft::FFTND::init	(	const std::vector< int > &	commDims,
		const std::vector< size_t > &	dimensions,
		FFTType	type,
		MPI_Comm	comm,
		TransformLayout	output = `TransformLayout::REDISTRIBUTED`
	)

noexcept

Call configurationND() first to compute commDims. After init(), call setBuffers() then plan() before execute().

Parameters

commDims	Process grid dimensions.
dimensions	Global tensor dimensions.
type	FFT precision (C2C or Z2Z).
comm	MPI communicator.
output	Forward output-layout policy.

Returns: 0 on success, non-zero on error.

Examples: example.cpp, example_portable.cpp, and example_portable_config.cpp.

◆ plan()

int shafft::FFTND::plan ( )

overridevirtualnoexcept

Must be called after init(). For the FFTW backend, dummy buffers are allocated and used for planning if they are not already set.

Returns: 0 on success, non-zero on error.

Implements shafft::FFT.

Examples: example.cpp, and example_portable.cpp.

◆ setBuffers() [1/2]

int shafft::FFTND::setBuffers	(	complexf *	data,
		complexf *	work
	)

noexcept

Parameters

data	Data buffer (allocSize() elements).
work	Work buffer (allocSize() elements).

Returns: 0 on success, non-zero on error.

Examples: example.cpp, and example_portable.cpp.

◆ setBuffers() [2/2]

int shafft::FFTND::setBuffers	(	complexd *	data,
		complexd *	work
	)

noexcept

◆ getBuffers() [1/2]

int shafft::FFTND::getBuffers	(	complexf **	data,
		complexf **	work
	)

noexcept

Buffers may be swapped after execute(); always call this to locate output.

Parameters

[out]	data	Current data buffer.
[out]	work	Current work buffer.

Returns: 0 on success, non-zero on error.

Examples: example.cpp, and example_portable.cpp.

◆ getBuffers() [2/2]

int shafft::FFTND::getBuffers	(	complexd **	data,
		complexd **	work
	)

noexcept

◆ execute()

int shafft::FFTND::execute ( FFTDirection direction )

overridevirtualnoexcept

Parameters

direction FORWARD or BACKWARD.

Returns: Status code (0 on success).

Implements shafft::FFT.

Examples: example.cpp, and example_portable.cpp.

◆ normalize()

int shafft::FFTND::normalize ( )

overridevirtualnoexcept

After a forward-backward pair, calling normalize() restores original scale.

Returns: 0 on success, non-zero on error.

Implements shafft::FFT.

Examples: example.cpp, and example_portable.cpp.

◆ allocSize()

size_t shafft::FFTND::allocSize ( ) const

overridevirtualnoexcept

Implements shafft::FFT.

Examples: example.cpp, and example_portable.cpp.

◆ globalSize()

size_t shafft::FFTND::globalSize ( ) const

overridevirtualnoexcept

Implements shafft::FFT.

◆ ndim()

int shafft::FFTND::ndim ( ) const

overridevirtualnoexcept

Implements shafft::FFT.

◆ fftType()

FFTType shafft::FFTND::fftType ( ) const

overridevirtualnoexcept

Implements shafft::FFT.

◆ getLayout()

int shafft::FFTND::getLayout	(	std::vector< size_t > &	subsize,
		std::vector< size_t > &	offset,
		TensorLayout	layout = `TensorLayout::CURRENT`
	)		const

noexcept

Parameters

[out]	subsize	Local extent per axis.
[out]	offset	Global offset per axis.
	layout	CURRENT, INITIAL, or REDISTRIBUTED.

Returns: 0 on success, non-zero on error.

◆ getAxes()

int shafft::FFTND::getAxes	(	std::vector< int > &	ca,
		std::vector< int > &	da,
		TensorLayout	layout = `TensorLayout::CURRENT`
	)		const

noexcept

Parameters

[out]	ca	Contiguous (non-distributed) axes.
[out]	da	Distributed axes.
	layout	CURRENT, INITIAL, or REDISTRIBUTED.

Returns: 0 on success, non-zero on error.

◆ isActive()

bool shafft::FFTND::isActive ( ) const

overridevirtualnoexcept

Inactive ranks have no local data; execute() and normalize() are no-ops.

Implements shafft::FFT.

◆ setBuffersRaw()

int shafft::FFTND::setBuffersRaw	(	void *	data,
		void *	work
	)

overridevirtualnoexcept

Parameters

data	Data buffer.
work	Work buffer.

Returns: 0 on success, non-zero on error.

Implements shafft::FFT.

◆ getBuffersRaw()

int shafft::FFTND::getBuffersRaw	(	void **	data,
		void **	work
	)

overridevirtualnoexcept

Parameters

[out]	data	Current data buffer.
[out]	work	Current work buffer.

Returns: 0 on success, non-zero on error.

Implements shafft::FFT.

◆ getCommunicator()

int shafft::FFTND::getCommunicator ( MPI_Comm * outComm ) const

noexcept

Returns MPI_COMM_NULL for inactive ranks. The caller must call MPI_Comm_free() on the returned communicator when done. Valid only after plan() succeeds.

Parameters

[out] outComm Receives duplicated communicator.

Returns: 0 on success, non-zero on error.

◆ init() [2/2]

int shafft::FFTND::init ( shafft_nd_config_t & cfg )

noexcept

Auto-resolves if SHAFFT_CONFIG_RESOLVED is not set. Communicator is read from the config struct (worldComm).

Parameters

cfg	Config struct (resolved or will be auto-resolved).

Returns: 0 on success, non-zero on error.

The documentation for this class was generated from the following file:

include/shafft/shafft.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FFTND() [1/3]

◆ ~FFTND()

◆ FFTND() [2/3]

◆ FFTND() [3/3]

Member Function Documentation

◆ release()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ init() [1/2]

◆ plan()

◆ setBuffers() [1/2]

◆ setBuffers() [2/2]

◆ getBuffers() [1/2]

◆ getBuffers() [2/2]

◆ execute()

◆ normalize()

◆ allocSize()

◆ globalSize()

◆ ndim()

◆ fftType()

◆ getLayout()

◆ getAxes()

◆ isActive()

◆ setBuffersRaw()

◆ getBuffersRaw()

◆ getCommunicator()

◆ init() [2/2]