Configuration

Configuration#

A “configuration” specifies FFT parameters, such as precision, shape, batch size, transform mode, etc. In the double-batched FFT library, all parameters are collected in the bbfft::configuration struct.

Main configuration#

struct configuration#

The unified configuration struct contains parameters for all plan types, including complex data, real data, and 1D to 3D FFTs.

Public Functions

void set_strides_default(bool inplace)#

Compute and set strides from shape assuming the default data layout.

See default_istride and default_ostride functions for a description of the default data layout.

Parameters:: inplace – Set to true for in-place transform.

std::string to_string() const#: convert configuration to FFT descriptor

Public Members

unsigned dim#: FFT dimension (1,2, …, max_fft_dim).

std::array<std::size_t, max_tensor_dim> shape#: Shape of the \(M \times N_1 \times \dots \times N_d \times K\) input tensor. The FFT is taken over the N-modes, M and K are batch modes. The column-major layout is assumed, therefore the M-mode varies fastest in memory and the K-mode varies slowest in memory. Set shape array to {M, N_1, …, N_d, K}.

precision fp#: Floating-point precision.

direction dir = direction::forward #: Forward or backward transform.

transform_type type = transform_type::c2c #: Select complex data or real data FFTs.

std::array<std::size_t, max_tensor_dim> istride = default_istride(dim, shape, type, true)#

Stride used for address calculation of the input array. For index \((m,n_1,...,n_d,k)\) the offset is calculated as

\[m s_0 + \sum_{i=1}^dn_i s_i + k s_{d+1},\]

where \(s_i\) are the entries of istride. The offset is measured in real if the input tensor is real and measured in complex if the input tensor is complex.

Note: \(s_0\neq 1\) currently not supported.

std::array<std::size_t, max_tensor_dim> ostride = default_ostride(dim, shape, type, true)#

Stride used for address calculation of the output array. For index \((m,n_1,...,n_d,k)\) the offset is calculated as

\[m s_0 + \sum_{i=1}^dn_i s_i + k s_{d+1},\]

where \(s_i\) are the entries of ostride. The offset is measured in real if the output tensor is real and measured in complex if the output tensor is complex.

Note: \(s_0\neq 1\) currently not supported.

user_module callbacks = {}#: User-provided load and store functions.

std::ostream &bbfft::operator<<(std::ostream &os, configuration const &info)#

Output configuration as FFT descriptor.

Parameters:

os – output stream
info – configuration

Returns:

Reference to os

Constants#

constexpr unsigned bbfft::max_fft_dim = 3#: Maximum supported FFT dimension.

constexpr unsigned bbfft::max_tensor_dim = max_fft_dim + 2#: Maximum supported tensor dimension with batch indices.

Enumerations#

Precision#

enum class bbfft::precision : int#

Floating-point precision.

The value is the number of bytes needed to store one floating-point number, e.g. static_cast<int>(precision::f32) = 4.

Values:

enumerator f32#: 32-bit (single)

enumerator f64#: 64-bit (double)

In templated code the following helper converts the data type to the precision value:

template<typename T> struct to_precision#

Convert C++ type to precision enum.

Template Parameters:: T – float or double

Specializations store the precision in the value member:

template<> struct to_precision<float>#

Specialization of to_precision for float.

Public Static Attributes

static constexpr precision value = precision::f32 #: Precision corresponding to float.

template<> struct to_precision<double>#

Specialization of to_precision for double.

Public Static Attributes

static constexpr precision value = precision::f64 #: Precision corresponding to double.

The following helper allows to write shorter code:

template<typename T> constexpr precision bbfft::to_precision_v = to_precision<T>::value#

Convenience wrapper for to_precision.

Example: precision p = to_precision_v<double>;

Template Parameters:: T – float or double

Direction#

enum class bbfft::direction : int#

The convention is adopted that the forward transform as negative sign and that the backward transform has positive sign.

Values:

enumerator forward#: Forward direction (-1)

enumerator backward#: Backward direction (+1)

Transform type#

enum class bbfft::transform_type : int#

Complex data and real data FFTs.

The “standard” FFT is c2c, that is complex-valued input and complex-valued output.

In practice, input data is often real-valued. Optimised plans for real-valued input or output data can be selected with transform_type.

Values:

enumerator c2c#: complex input, complex output

enumerator r2c#: real input, complex output

enumerator c2r#: complex input, real input

char const *bbfft::to_string(transform_type type)#: Convert transform type to string.

Stride computation#

auto bbfft::default_istride(unsigned dim, std::array<std::size_t, max_tensor_dim> const &shape, transform_type type, bool inplace) -> std::array<std::size_t, max_tensor_dim>#

Compute the default strides of the input tensor.

Let the shape be \((M,N_1,\dots,N_d,K)\), where d is the FFT dimension. For c2c transforms the first two three entries of the stride array are given by \(s_0=1\) and \(s_1=M\). Further entries are computed with

\[i=2,\dots,d+1: s_i = s_{i-1}N_{i-1}.\]

For out-of-place r2c transforms strides are the same as for c2c transforms. For in-place r2c transforms we have to pad the first FFT mode such that the output data fits into the input tensor. That is, we have \(N_1' = 2 (\lfloor N_1/2\rfloor+1)\). The stride computation goes according to the stride computation for c2c but with every instance of \(N_1\) replaced with \(N_1'\).

For c2r transform (both in-place and out-of-place) we expect that only \(N_1''=\lfloor N_1/2\rfloor+1\) complex numbers in the first FFT mode are stored (due to symmetry). The stride computation goes according to the stride computation for c2c but with every instance of \(N_1\) replaced with \(N_1''\).

Parameters:

dim – FFT dimension
shape – Input tensor Shape
type – complex or real-valued FFT
inplace – Is the transform in-place?

Returns:

Stride array

auto bbfft::default_ostride(unsigned dim, std::array<std::size_t, max_tensor_dim> const &shape, transform_type type, bool inplace) -> std::array<std::size_t, max_tensor_dim>#

Computes the default strides of the output tensor.

“Reverses” the role of default_istride in the following manner:

r2c: Same as default_istride called for type = c2r.
c2r: Same as default_istride called for type = r2c.
c2c: Same as default_istride.

Parameters:

dim – FFT dimension
shape – Output tensor Shape
type – complex or real-valued FFT
inplace – Is the transform in-place?

Returns:

Stride array

User callbacks#

enum class bbfft::kernel_language#

Language of user module.

Values:

enumerator opencl_c#: OpenCL-C language.

struct user_module#

Definition of user callbacks.

Public Functions

explicit operator bool() const noexcept#

Checks if user module is set up properly.

Returns:: Is user module valid?

Public Members

char const *data = nullptr#: Source code string.

std::size_t length = 0#: Length of source code string.

char const *load_function = nullptr#: Name of load function (C string)

char const *store_function = nullptr#: Name of store function (C string)

mem user_data = mem{nullptr, mem_type::buffer}#: User data passed to callbacks.

kernel_language language = kernel_language::opencl_c #: Language.

Configuration

Contents

Configuration#

Main configuration#

Constants#

Enumerations#

Precision#

Direction#

Transform type#

Stride computation#

User callbacks#