FFTW bindings for the xtensor C++ multi-dimensional array library.

Introduction

xtensor-fftw enables easy access to Fast Fourier Transforms (FFTs) from the FFTW library for use on xarray numerical arrays from the xtensor library.

Syntax and functionality are inspired by numpy.fft, the FFT module in the Python array programming library NumPy.

Installation

Using conda:

conda install xtensor-fftw -c conda-forge

This automatically installs dependencies as well (see list of dependencies below).

Installing from source into $PREFIX (for instance $CONDA_PREFIX when in a conda environment, or $HOME/.local) after manually installing the dependencies:

git clone https://github.com/xtensor-stack/xtensor-fftw
cd xtensor-fftw
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$PREFIX
make install

Dependencies

• xtensor
• xtl
• FFTW version 3
• A compiler supporting C++14

Usage

xtensor-fftw is a header-only library. To use, include one of the header files in the include directory, e.g. xtensor-fftw/basic.hpp, in your c++ code. To compile, one should also include the paths to the FFTW header and libraries and link to the appropriate FFTW library.

The functions in xtensor-fftw/basic.hpp mimic the behavior of numpy.fft as much as possible. In most cases transforms on identical input data should produce identical results within reasonable machine precision error bounds. However, there are a few differences that one should keep in mind:

• Since FFTW expects row-major ordered arrays, xtensor-fftw functions currently only accept xarrays with row-major layout. By default, xtensor containers use row-major layout, but take care when manually overriding this default.

• The inverse real FFT functions in FFTW destroy the input arrays during the calculation, i.e. the irfft family of functions in xtensor-fftw. (In fact, this does not always happen, depending on which algorithm FFTW decides is most efficient in your particular situation. Don't count on it, though.)

• xtensor-fftw on Windows does not support long double precision. The long double precision version of the FFTW library requires that sizeof(long double) == 12. In recent versions of Visual Studio, long double is an alias of double and has size 8.

Example

Calculate the derivative of a (discretized) field in Fourier space, e.g. a sine shaped field sin:

#include <xtensor-fftw/basic.hpp>   // rfft, irfft
#include <xtensor-fftw/helper.hpp>  // rfftscale 
#include <xtensor/xarray.hpp>
#include <xtensor/xbuilder.hpp>     // xt::arange
#include <xtensor/xmath.hpp>        // xt::sin, cos
#include <complex>
#include <xtensor/xio.hpp>

// generate a sinusoid field
double dx = M_PI / 100;
xt::xarray<double> x = xt::arange(0., 2 * M_PI, dx);
xt::xarray<double> sin = xt::sin(x);

// transform to Fourier space
auto sin_fs = xt::fftw::rfft(sin);

// multiply by i*k
std::complex<double> i {0, 1};
auto k = xt::fftw::rfftscale<double>(sin.shape()[0], dx);
xt::xarray<std::complex<double>> sin_derivative_fs = xt::eval(i * k * sin_fs);

// transform back to normal space
auto sin_derivative = xt::fftw::irfft(sin_derivative_fs);

std::cout << "x:              " << x << std::endl;
std::cout << "sin:            " << sin << std::endl;
std::cout << "cos:            " << xt::cos(x) << std::endl;
std::cout << "sin_derivative: " << sin_derivative << std::endl;

Which outputs (full output truncated):

x:              { 0.      ,  0.031416,  0.062832,  0.094248, ...,  6.251769}
sin:            { 0.000000e+00,  3.141076e-02,  6.279052e-02,  9.410831e-02, ..., -3.141076e-02}
cos:            { 1.000000e+00,  9.995066e-01,  9.980267e-01,  9.955620e-01, ...,  9.995066e-01}
sin_derivative: { 1.000000e+00,  9.995066e-01,  9.980267e-01,  9.955620e-01, ...,  9.995066e-01}

Interactive examples

See the notebooks folder for interactive Jupyter notebook examples using the C++14 xeus-cling kernel. These can also be run from Binder, e.g. this one.

Building and running tests

What follows are instructions for compiling and running the xtensor-fftw tests. These also serve as an example of how to do build your own code using xtensor-fftw (excluding the GoogleTest specific parts).

Dependencies for building tests

The main dependency is a version of FFTW 3. For the tests, we need the floating point version which is enabled in the FFTW configuration step using:

./configure --enable-float

CMake and xtensor must also be installed in order to compile the xtensor-fftw tests. Both can either be installed through Conda or built/installed manually. When using a non-Conda xtensor-install, make sure that the CMake find_package command can find xtensor, e.g. by passing something like -DCMAKE_MODULE_PATH="path_to_xtensorConfig.cmake" to CMake. If xtensor was installed in a default location, CMake should be able to find it without any command line options.

Optionally, a GoogleTest installation can be used. However, it is recommended to use the built-in option to download GoogleTest automatically (see below).

Configure tests

Inside the xtensor-fftw source directory, create a build directory and cd into it:

mkdir build
cd build

If pkg-config is present on your system and your FFTW installation can be found by it, then CMake can configure your build with command:

cmake .. -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON

If you do not use pkg-config, the FFTW prefix, i.e. the base directory under which FFTW is installed, must be passed to CMake. Either set the FFTWDIR environment variable to the prefix path, or use the FFTW_ROOT CMake option variable. For instance, if FFTW was installed using ./configure --prefix=/home/username/.local; make; make install, then either set the an environment variable in your shell before running CMake:

export FFTWDIR=/home/username/.local
cmake ..  -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON [other options]

or pass the path to CMake directly as such:

cmake .. -DFFTW_ROOT=/home/username/.local  -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON [other options]

Compile tests

After successful CMake configuration, run inside the build directory:

make

Run tests

From the build directory, change to the test directory and run the tests:

cd test
./test_xtensor-fftw

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the LICENSE file for details.