FFTW bindings for the xtensor C++ multi-dimensional array library.
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.
Using conda:
conda install xtensor-fftw -c conda-forgeThis 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 installxtensor-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
irfftfamily 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 doubleprecision. Thelong doubleprecision version of the FFTW library requires thatsizeof(long double) == 12. In recent versions of Visual Studio,long doubleis an alias ofdoubleand has size 8.
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}
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.
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).
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-floatCMake 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).
Inside the xtensor-fftw source directory, create a build directory and cd into it:
mkdir build
cd buildIf 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=ONIf 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]After successful CMake configuration, run inside the build directory:
makeFrom the build directory, change to the test directory and run the tests:
cd test
./test_xtensor-fftwWe 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.