{"id":13647546,"url":"https://github.com/xtensor-stack/xtensor-fftw","last_synced_at":"2025-05-06T06:33:32.063Z","repository":{"id":49188586,"uuid":"97943732","full_name":"xtensor-stack/xtensor-fftw","owner":"xtensor-stack","description":"FFTW bindings for the xtensor C++14 multi-dimensional array library","archived":false,"fork":false,"pushed_at":"2025-04-29T14:47:39.000Z","size":589,"stargazers_count":48,"open_issues_count":29,"forks_count":17,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-29T14:51:34.631Z","etag":null,"topics":["cplusplus-14","cpp","fft","fftw","fftw3-binding","library","numpy","template-metaprogramming","xtensor"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xtensor-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-21T12:05:13.000Z","updated_at":"2025-04-29T13:52:04.000Z","dependencies_parsed_at":"2022-08-26T08:00:36.972Z","dependency_job_id":null,"html_url":"https://github.com/xtensor-stack/xtensor-fftw","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtensor-stack%2Fxtensor-fftw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtensor-stack%2Fxtensor-fftw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtensor-stack%2Fxtensor-fftw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtensor-stack%2Fxtensor-fftw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xtensor-stack","download_url":"https://codeload.github.com/xtensor-stack/xtensor-fftw/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252633909,"owners_count":21779944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus-14","cpp","fft","fftw","fftw3-binding","library","numpy","template-metaprogramming","xtensor"],"created_at":"2024-08-02T01:03:38.104Z","updated_at":"2025-05-06T06:33:31.746Z","avatar_url":"https://github.com/xtensor-stack.png","language":"Jupyter Notebook","readme":"# ![xtensor-fftw](xtensor-fftw.svg)\n\n[FFTW](http://www.fftw.org/) bindings for the [xtensor](https://github.com/xtensor-stack/xtensor) C++ multi-dimensional array library.\n\n[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/xtensor-stack/xtensor-fftw/stable?filepath=notebooks%2Fintensely_edgy_cat.ipynb)\n[![Join the Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/QuantStack/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n[![Travis](https://travis-ci.org/xtensor-stack/xtensor-fftw.svg?branch=master)](https://travis-ci.org/xtensor-stack/xtensor-fftw)\n[![Appveyor](https://ci.appveyor.com/api/projects/status/6h369haechmjeofj/branch/master?svg=true)](https://ci.appveyor.com/project/egpbos/xtensor-fftw-ivn9w/branch/master)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/18861a283cf84b2e95886ba79c66e028)](https://www.codacy.com/app/egpbos/xtensor-fftw?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=egpbos/xtensor-fftw\u0026amp;utm_campaign=Badge_Grade)\n[![Coverage Status](https://coveralls.io/repos/github/egpbos/xtensor-fftw/badge.svg)](https://coveralls.io/github/egpbos/xtensor-fftw)\n\n[![Anaconda-Server Badge](https://anaconda.org/conda-forge/xtensor-fftw/badges/version.svg)](https://anaconda.org/conda-forge/xtensor-fftw)\n[![Anaconda-Server Badge](https://anaconda.org/conda-forge/xtensor-fftw/badges/downloads.svg)](https://anaconda.org/conda-forge/xtensor-fftw)\n\n## Introduction\n\n_xtensor-fftw_ enables easy access to Fast Fourier Transforms (FFTs) from the [FFTW library](http://www.fftw.org/) for use on `xarray` numerical arrays from the [_xtensor_](https://github.com/xtensor-stack/xtensor) library.\n\nSyntax and functionality are inspired by `numpy.fft`, the FFT module in the Python array programming library [NumPy](http://www.numpy.org/).\n\n## Installation\n\nUsing `mamba` (or conda):\n\n```bash\nmamba install xtensor-fftw -c conda-forge\n```\n\nThis automatically installs dependencies as well (see [list of dependencies](#dependencies) below).\n\nInstalling from source into `$PREFIX` (for instance `$CONDA_PREFIX` when in a conda environment, or `$HOME/.local`) after manually installing the [dependencies](#dependencies):\n\n```bash\ngit clone https://github.com/xtensor-stack/xtensor-fftw\ncd xtensor-fftw\nmkdir build\ncd build\ncmake .. -DCMAKE_INSTALL_PREFIX=$PREFIX\nmake install\n```\n\n## Dependencies\n\n* [xtensor](https://github.com/xtensor-stack/xtensor)\n* [xtl](https://github.com/xtensor-stack/xtl)\n* [FFTW](http://www.fftw.org/) version 3\n* A compiler supporting C++14\n\n| `xtensor-fftw` | `xtensor`        | `xtl`   | `fftw`  |\n|----------------|------------------|---------|---------|\n|  master        | \u003e=0.20.9,\u003c0.22   |  ^0.6.9 | ^3.3.8  |\n|  0.2.6         | \u003e=0.20.9,\u003c0.22   |  ^0.6.9 | ^3.3.8  |\n\n## Usage\n\n_xtensor-fftw_ is a header-only library.\nTo use, include one of the header files in the `include` directory, e.g. `xtensor-fftw/basic.hpp`, in your c++ code.\nTo compile, one should also include the paths to the FFTW header and libraries and link to the appropriate FFTW library.\n\nFFTW allows three modes of calculus : `float`, `double` and `long double`.  \nThe impact of the precision type can be see below in the benchmark results.  \nUse the following matrix to include, compile and link the right target:  \n\n| `#include`                         | `precision types`          | `xtensor-fftw compile options`    | `FFTW compile options`  |\n|------------------------------------|----------------------------|-----------------------------------|-------------------------|\n| xtensor-fftw/basic_float.hpp       | float                      | -DXTENSOR_FFTW_USE_FLOAT=ON       | -DENABLE_FLOAT=ON       |\n| xtensor-fftw/basic_double.hpp      | double                     | -DXTENSOR_FFTW_USE_DOUBLE=ON      | -DENABLE_DOUBLE=ON      |\n| xtensor-fftw/basic_long_double.hpp | long double                | -DXTENSOR_FFTW_USE_LONG_DOUBLE=ON | -DENABLE_LONGDOUBLE=ON  |\n| xtensor-fftw/basic_option.hpp      | depends by compile options | subset of above options           | subset of above options |\n| xtensor-fftw/basic.hpp             | all types                  | no option                         | all above options       |\n\nSpecify only the required precision type to reduce the dependencies size of your application (for example for a Mobile App it matters), in fact FFTW needs to compile a specific library for each precision thus creating:\n* `libfftw3f` for float precision\n* `libfftw3` for double precision\n* `libfftw3l` for long double precision\n\n\u003e__*Notes*__: FFTW allow SIMD instructions (SSE,SSE2,AVX,AVX2), OpenMP and Threads optimizations. Take a look to the availables options before compile it.  \n\nThe functions in `xtensor-fftw/basic.hpp` mimic the behavior of `numpy.fft` as much as possible.\nIn most cases transforms on identical input data should produce identical results within reasonable machine precision error bounds.\nHowever, there are a few differences that one should keep in mind:\n\n- Since FFTW expects row-major ordered arrays, _xtensor-fftw_ functions currently only accept `xarray`s with row-major layout.\nBy default, _xtensor_ containers use row-major layout, but take care when manually overriding this default.\n\n- The inverse real FFT functions in FFTW destroy the input arrays during the calculation, i.e. the `irfft` family of functions in _xtensor-fftw_.\n(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.)\n\n- _xtensor-fftw_ on Windows does not support `long double` precision.\nThe `long double` precision version of the FFTW library requires that `sizeof(long double) == 12`.\nIn recent versions of Visual Studio, `long double` is an alias of `double` and has size 8.\n\n### Example\n\nCalculate the derivative of a (discretized) field in Fourier space, e.g. a sine shaped field `sin`:\n\n```c++\n#include \u003cxtensor-fftw/basic.hpp\u003e   // rfft, irfft\n#include \u003cxtensor-fftw/helper.hpp\u003e  // rfftscale \n#include \u003cxtensor/xarray.hpp\u003e\n#include \u003cxtensor/xbuilder.hpp\u003e     // xt::arange\n#include \u003cxtensor/xmath.hpp\u003e        // xt::sin, cos\n#include \u003ccomplex\u003e\n#include \u003cxtensor/xio.hpp\u003e\n\n// generate a sinusoid field\ndouble dx = M_PI / 100;\nxt::xarray\u003cdouble\u003e x = xt::arange(0., 2 * M_PI, dx);\nxt::xarray\u003cdouble\u003e sin = xt::sin(x);\n\n// transform to Fourier space\nauto sin_fs = xt::fftw::rfft(sin);\n\n// multiply by i*k\nstd::complex\u003cdouble\u003e i {0, 1};\nauto k = xt::fftw::rfftscale\u003cdouble\u003e(sin.shape()[0], dx);\nxt::xarray\u003cstd::complex\u003cdouble\u003e\u003e sin_derivative_fs = xt::eval(i * k * sin_fs);\n\n// transform back to normal space\nauto sin_derivative = xt::fftw::irfft(sin_derivative_fs);\n\nstd::cout \u003c\u003c \"x:              \" \u003c\u003c x \u003c\u003c std::endl;\nstd::cout \u003c\u003c \"sin:            \" \u003c\u003c sin \u003c\u003c std::endl;\nstd::cout \u003c\u003c \"cos:            \" \u003c\u003c xt::cos(x) \u003c\u003c std::endl;\nstd::cout \u003c\u003c \"sin_derivative: \" \u003c\u003c sin_derivative \u003c\u003c std::endl;\n```\n\nWhich outputs (full output truncated):\n\n```\nx:              { 0.      ,  0.031416,  0.062832,  0.094248, ...,  6.251769}\nsin:            { 0.000000e+00,  3.141076e-02,  6.279052e-02,  9.410831e-02, ..., -3.141076e-02}\ncos:            { 1.000000e+00,  9.995066e-01,  9.980267e-01,  9.955620e-01, ...,  9.995066e-01}\nsin_derivative: { 1.000000e+00,  9.995066e-01,  9.980267e-01,  9.955620e-01, ...,  9.995066e-01}\n```\n\n### Interactive examples\nSee the [notebooks folder](https://github.com/xtensor-stack/xtensor-fftw/tree/master/notebooks) for interactive Jupyter notebook examples using the C++14 [_xeus-cling_](https://github.com/jupyter-xeus/xeus-cling) kernel. These can also be run from Binder, [e.g. this one](https://mybinder.org/v2/gh/xtensor-stack/xtensor-fftw/stable?filepath=notebooks%2Fintensely_edgy_cat.ipynb).\n\n\n## Building and running tests\n\nWhat follows are instructions for compiling and running the _xtensor-fftw_ tests.\nThese also serve as an example of how to do build your own code using _xtensor-fftw_ (excluding the GoogleTest specific parts).\n\n### Dependencies for building tests\n\nThe main dependency is a version of FFTW 3.\nTo enable all the precision types, FFTW must be compiled with the related flags:  \n`cmake -DENABLE_FLOAT:BOOL=ON -DENABLE_LONGDOUBLE:BOOL=ON /path/of/fftw3-src`\n\nCMake and _xtensor_ must also be installed in order to compile the _xtensor-fftw_ tests.\nBoth can either be installed through Conda or built/installed manually.\nWhen 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.\nIf _xtensor_ was installed in a default location, CMake should be able to find it without any command line options.\n\nOptionally, a GoogleTest installation can be used.\nHowever, it is recommended to use the built-in option to download GoogleTest automatically (see below).\n\n### Configure tests\n\nInside the _xtensor-fftw_ source directory, create a build directory and `cd` into it:\n```bash\nmkdir build\ncd build\n```\nIf `pkg-config` is present on your system and your FFTW installation can be found by it, then CMake can configure your build with command:\n```bash\ncmake .. -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON\n```\nIf you do not use `pkg-config`, the FFTW prefix, i.e. the base directory under which FFTW is installed, must be passed to CMake.\nEither set the `FFTWDIR` environment variable to the prefix path, or use the `FFTW_ROOT` CMake option variable.\nFor 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:\n```bash\nexport FFTWDIR=/home/username/.local\ncmake ..  -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON [other options]\n```\nor pass the path to CMake directly as such:\n```bash\ncmake .. -DFFTW_ROOT=/home/username/.local  -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON [other options]\n```\n\n### Compile tests\n\nAfter successful CMake configuration, run inside the build directory:\n```bash\nmake\n```\n\n### Run tests\n\nFrom the build directory, change to the test directory and run the tests:\n\n```bash\ncd test\n./test_xtensor-fftw\n```\n\n## Advanced Setting\n\nThis section shows how to configure `cmake` in order to exploit advanced settings.  \n\n### Use only Double precision\n\nAfter a standard installation of FFTW library without specify a particular options, this command allow to run Test and Benchmarks using only `double` precision: \n\n```cmake\ncmake -DBUILD_BENCHMARK=ON -DDOWNLOAD_GBENCH=ON -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON -DFFTW_USE_FLOAT=OFF  -DFFTW_USE_LONG_DOUBLE=OFF -DFFTW_USE_DOUBLE=ON  -DCMAKE_BUILD_TYPE=Release  ..\n```\n\nLet's see what `./bench/benchmark_xtensor-fftw` produce:\n\n```\nRun on (16 X 2300 MHz CPU s)\n-------------------------------------------------------------------------------\nBenchmark                                        Time           CPU Iterations\n-------------------------------------------------------------------------------\nrfft1Dxarray_double/TransformAndInvert         66375 ns      66354 ns      10149\nrfft1Dxarray_double/TransformAndInvert_nD      70856 ns      70829 ns      10128\nrfft2Dxarray_double/TransformAndInvert         61264 ns      61256 ns      11456\nrfft2Dxarray_double/TransformAndInvert_nD      62297 ns      62269 ns      10851\n```\n\n### Manually specify FFTW headers and link flags\n\nThis can be very useful: in this case FFTW is not required to be installed, just compiled.  \nThe following command produce the same results as before:  \n\n```cmake\ncmake -DBUILD_BENCHMARK=ON -DDOWNLOAD_GBENCH=ON -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON -DFFTW_USE_FLOAT=OFF -DFFTW_USE_LONG_DOUBLE=OFF -DFFTW_USE_DOUBLE=ON -DFFTW_INCLUDE_CUSTOM_DIRS=/path/to/fftw3/api -DFFTW_LINK_FLAGS=\"-L/path/to/fftw3/build -lfftw3\" ..\n```\n\n### Use Intel MKL\n\nSince 2018 Intel has release a version of his famous MKL (Math Kernel Library) with a C++ and Fortran wrapper of FFTW.  \nOnce MKL (or oneAPI MKL) installed on the system enter the following command with adjusted path to your system:\n\n```cmake\ncmake -DBUILD_BENCHMARK=ON -DDOWNLOAD_GBENCH=ON -DBUILD_TESTS=ON -DDOWNLOAD_GTEST=ON -DFFTW_USE_FLOAT=OFF  -DFFTW_USE_LONG_DOUBLE=OFF -DFFTW_USE_DOUBLE=ON -DFFTW_INCLUDE_CUSTOM_DIRS=/opt/intel/oneapi/mkl/2021.2.0/include/fftw -DFFTW_LINK_FLAGS=\"-L/opt/intel/oneapi/mkl/2021.2.0/lib -L/opt/intel/oneapi/compiler/2021.2.0/mac/compiler/lib -lmkl_core -lmkl_intel_thread -lmkl_intel_lp64 -liomp5\" -DRUN_HAVE_STD_REGEX=0 -DCMAKE_BUILD_TYPE=Release ..\n```\n\nLet's see what `./bench/benchmark_xtensor-fftw` now produce:\n\n```\nRun on (16 X 2300 MHz CPU s)\n-------------------------------------------------------------------------------\nBenchmark                                        Time           CPU Iterations\n-------------------------------------------------------------------------------\nrfft1Dxarray_double/TransformAndInvert          9265 ns       9258 ns      58371\nrfft1Dxarray_double/TransformAndInvert_nD       9636 ns       9602 ns      73961\nrfft2Dxarray_double/TransformAndInvert         34428 ns      34427 ns      20216\nrfft2Dxarray_double/TransformAndInvert_nD      37401 ns      37393 ns      19480\n```\n\n\u003e__*Note*__: Before running test or benchmark remember to export the intel library path, e.g. on OS X: `export DYLD_LIBRARY_PATH=/opt/intel/oneapi/mkl/2021.2.0/lib/:/opt/intel/oneapi/compiler/2021.2.0/mac/compiler/lib/`\n\n## License\n\nWe use a shared copyright model that enables all contributors to maintain the\ncopyright on their contributions.\n\nThis software is licensed under the BSD-3-Clause license. See the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtensor-stack%2Fxtensor-fftw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxtensor-stack%2Fxtensor-fftw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtensor-stack%2Fxtensor-fftw/lists"}