{"id":15716384,"url":"https://github.com/fastlib/fcwt","last_synced_at":"2025-05-15T03:07:48.603Z","repository":{"id":54289411,"uuid":"433519836","full_name":"fastlib/fCWT","owner":"fastlib","description":"The fast Continuous Wavelet Transform (fCWT) is a library for fast calculation of CWT.","archived":false,"fork":false,"pushed_at":"2025-01-06T13:36:25.000Z","size":19916,"stargazers_count":330,"open_issues_count":44,"forks_count":62,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-15T03:07:42.441Z","etag":null,"topics":["c","cpp","cwt","fast","matlab","optimization","signal-processing","time-frequency-analysis","wavelet-transform"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastlib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-30T17:17:03.000Z","updated_at":"2025-05-08T04:13:54.000Z","dependencies_parsed_at":"2025-04-12T17:18:44.550Z","dependency_job_id":"116cb74d-d14b-4f45-b8de-6e7b8d2242ad","html_url":"https://github.com/fastlib/fCWT","commit_stats":{"total_commits":87,"total_committers":3,"mean_commits":29.0,"dds":0.04597701149425293,"last_synced_commit":"7693c3ba517cba040e9a5d7531cde9d958ca19d3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastlib%2FfCWT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastlib%2FfCWT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastlib%2FfCWT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastlib%2FfCWT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastlib","download_url":"https://codeload.github.com/fastlib/fCWT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264769,"owners_count":22041794,"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":["c","cpp","cwt","fast","matlab","optimization","signal-processing","time-frequency-analysis","wavelet-transform"],"created_at":"2024-10-03T21:45:22.443Z","updated_at":"2025-05-15T03:07:43.557Z","avatar_url":"https://github.com/fastlib.png","language":"Jupyter Notebook","readme":"![](https://github.com/fastlib/fCWT/blob/main/img/githubart.png)\n\nThe fast Continuous Wavelet Transform (fCWT)\n====================================\n![Stable version](https://img.shields.io/badge/version-2.0.0-blue) ![PyPI version](https://badge.fury.io/py/fcwt.svg)\n\nThe fast Continuous Wavelet Transform (fCWT) is a highly optimized C++ library for very fast calculation of the CWT in C++, Matlab, and Python.\n\n**fCWT has been featured on the January 2022 cover of NATURE Computational Science**. In this article, fCWT is compared against eight competitor algorithms, tested on noise resistance and validated on synthetic electroencephalography and in vivo extracellular local field potential data.\n\n_Please cite our research paper using the sidebar button when using fCWT in your research project._\n\u003e Arts, L.P.A., van den Broek, E.L. The fast continuous wavelet transformation (fCWT) for real-time, high-quality, noise-resistant time–frequency analysis. _Nat Comput Sci_ **2**, 47–58 (2022). https://doi.org/10.1038/s43588-021-00183-z\n\nUPDATE (12-01-2023)\n===================\n\nNew version available:\n- fCWT can be seamlessly used in Python (see [Jupyter Notebook](https://github.com/fastlib/fCWT/blob/main/tutorial.ipynb))\n- Interface upgrade: Use frequencies instead of scales and octaves!\n- Fixed small memory allignment bugs\n\nFeatures\n========\n\n- Calculating CWT 34-120x faster than all competitors*\n- Very high time-frequency resolution (i.e., it does not rely on wavelet estimation)\n- Real-time CWT for signals having sample frequencies of up to 200kHz\n- Applicable in many applications ranging from audio and speech to engine vibration analysis\n- Easy Python integration via pip\n- Easy MATLAB integration via MEX-files\n\n|fCWT for real-time audio and speech analysis                    |fCWT for high-resolution in-vivo Neuropixel data analysis       |\n|:--------------------------------------------------------------:|:--------------------------------------------------------------:|\n|\u003cimg src=\"https://github.com/fastlib/fCWT/blob/main/img/audio.png\" alt=\"fcwtaudio\" width=\"400\"/\u003e|\u003cimg src=\"https://github.com/fastlib/fCWT/blob/main/img/eeg.png\" alt=\"fcwteeg\" width=\"400\"/\u003e|\n|**fCWT for real-time Electroencephalography (EEG) analysis**    |**fCWT for real-time engine diagnostics**                       |\n|\u003cimg src=\"https://github.com/fastlib/fCWT/blob/main/img/eeg2.png\" alt=\"fcwteeg2\" width=\"400\"/\u003e|\u003cimg src=\"https://github.com/fastlib/fCWT/blob/main/img/engine.png\" alt=\"fcwtengine\" width=\"400\"/\u003e|\n\n*Based on C++ performance. **fCWT is the fastest CWT library in C++, Python and Matlab!** Please see the benchmark section for more details. Raise an issue if you found a new/faster implementation. I will try to add it to benchmark! \n\nQuickstart \n============\n\nfCWT's implementation can be used to accelerate your C++, Python, and Matlab projects! Build the C++ library to achieve the highest efficiency or use the Matlab and Python packages to maximize integration possibilities. \n\nPython\n---\n\nInstall the Python package using pip:\n```\n$ pip install fcwt\n```\nor if you want to install from source:\n```\n$ git clone https://github.com/fastlib/fCWT.git\n$ cd fCWT\n$ pip install .\n```\nSee this [Jupyter Notebook](https://github.com/fastlib/fCWT/blob/main/tutorial.ipynb) for documentation.\n\nMatlab\n---\nBuild MEX-files from source:\n```\n$ git clone https://github.com/fastlib/fCWT.git\n$ cd fCWT\n$ mkdir -p build\n$ cd build\n$ cmake ../ -DBUILD_MATLAB=ON\n$ make \n```\nTwo .mex files should now have been created in the `MATLAB` folder. Run the `example.mlx` live script to see how to use fCWT in Matlab. fCWT has been tested in R2022b on an Intel Apple Macbook Pro.\n\nC++\n---\nBuild fCWT from source:\n```\n$ git clone https://github.com/fastlib/fCWT.git\n$ cd fCWT\n$ mkdir -p build\n$ cd build\n$ cmake ../ [-DBUILD_BENCHMARK=ON|OFF]\n$ make \n$ sudo make install\n```\nSee the Installation section for more details about building fCWT from source for both UNIX and Windows systems.\n\n\nBenchmark\n========\n\nColumns are formatted as X-Y, where X is signal length in samples and Y the number of frequencies. The benchmark has been performed on a MacBook Pro 2019 having a 2,3 GHz Intel Core i9 4.5 Ghz Boost, 16 GB 2400 MHz DDR4. See the 'Usage: Benchmark' section for more details about the C++ benchmark. See the [Benchmark Notebook](https://github.com/fastlib/fCWT/blob/main/benchmark.ipynb) for the fCWT Python benchmark.\n\n| Implementation        | 10k-300 | 10k-3000 | 100k-300 | 100k-3000 | Speedup factor |\n|-----------------------|---------|----------|----------|-----------|----------------|\n| fCWT (C++)            | 0.005s  | 0.04s    | 0.03s    | 0.32s     | -              |\n| fCWT (Python)         | 0.011s  | 0.089s   | 0.074s   | 0.66s     | -              | \n| fCWT (Matlab)         | 0.072s  | 0.44s    | 0.17s    | 1.55s     | -              |\n|                       |         |          |          |           |                |\n| [CCWT] (Python)       | 0.019s  | 0.11s    | 0.15s    | 3.40s     | 10.63x         |\n| [PyWavelets] (Python) | 0.10s   | 1.17s    | 1.06s    | 12.69s    | 34.29x         |\n| Matlab                | 0.75s   | 0.86s    | 1.06s    | 13.26s    | 35.85x         |\n| [SsqueezePy] (Python) | 0.04s   | 0.43s    | 1.16s    | 17.76s    | 48.00x         |\n| SciPy (Python)        | 0.19s   | 1.82s    | 2.11s    | 18.70s    | 50.54x         |\n| Rwave (C)             | 0.18s   | 1.84s    | 2.28s    | 23.22s    | 62.75x         |\n| Mathematica           | -       | -        | -        | 27.83s    | 75.20x         |\n| Wavelib (C++)         | 0.25s   | 2.55s    | 4.85s    | 45.04s    | 121.72x        |\n\n\nPython Example\n==============\n\n```Python\nimport fcwt\nimport numpy as np\nimport matplotlib.pyplot as plt\n\n#Initialize\nfs = 1000\nn = fs*100 #100 seconds\nts = np.arange(n)\n\n#Generate linear chirp\nsignal = np.sin(2*np.pi*((1+(20*ts)/n)*(ts/fs)))\n\nf0 = 1 #lowest frequency\nf1 = 101 #highest frequency\nfn = 200 #number of frequencies\n\n#Calculate CWT without plotting...\nfreqs, out = fcwt.cwt(signal, fs, f0, f1, fn)\n\n#... or calculate and plot CWT\nfcwt.plot(signal, fs, f0=f0, f1=f1, fn=fn)\n```\n\nOutput:\n![](https://github.com/fastlib/fCWT/blob/main/img/pythontest.png)\n\nC++ Example\n=======\n\n```cpp\n#include \u003ciostream\u003e\n#include \u003cvector\u003e\n#include \u003cmath.h\u003e\n#include \u003cfcwt.h\u003e\n\nint main(int argc, char * argv[]) {\n    \n    int n = 100000; //signal length\n    const int fs = 1000; //sampling frequency\n    float twopi = 2.0*3.1415;\n    \n    //3000 frequencies spread logartihmically between 1 and 32 Hz\n    const float f0 = 1;\n    const float f1 = 32;\n    const int fn = 3000;\n\n    //Define number of threads for multithreaded use\n    const int nthreads = 8;\n\n    //input: n real numbers\n    std::vector\u003cfloat\u003e sig(n);\n    \n    //output: n x scales\n    std::vector\u003ccomplex\u003cfloat\u003e\u003e tfm(n*fn);\n    \n    //initialize with 1 Hz cosine wave\n    for(auto\u0026 el : sig) {\n        el = cos(twopi*((float)(\u0026el - \u0026sig[0])/(float)fs));\n    }\n    \n    //Create a wavelet object\n    Wavelet *wavelet;\n    \n    //Initialize a Morlet wavelet having sigma=2.0;\n    Morlet morl(2.0f);\n    wavelet = \u0026morl;\n\n    //Create the continuous wavelet transform object\n    //constructor(wavelet, nthreads, optplan)\n    //\n    //Arguments\n    //wavelet   - pointer to wavelet object\n    //nthreads  - number of threads to use\n    //optplan   - use FFTW optimization plans if true\n    //normalization - take extra time to normalize time-frequency matrix\n    FCWT fcwt(wavelet, nthreads, true, false);\n\n    //Generate frequencies\n    //constructor(wavelet, dist, fs, f0, f1, fn)\n    //\n    //Arguments\n    //wavelet   - pointer to wavelet object\n    //dist      - FCWT_LOGSCALES | FCWT_LINFREQS for logarithmic or linear distribution frequency range\n    //fs        - sample frequency\n    //f0        - beginning of frequency range\n    //f1        - end of frequency range\n    //fn        - number of wavelets to generate across frequency range\n    Scales scs(wavelet, FCWT_LINFREQS, fs, f0, f1, fn);\n\n    //Perform a CWT\n    //cwt(input, length, output, scales)\n    //\n    //Arguments:\n    //input     - floating pointer to input array\n    //length    - integer signal length\n    //output    - floating pointer to output array\n    //scales    - pointer to scales object\n    fcwt.cwt(\u0026sig[0], n, \u0026tfm[0], \u0026scs);\n        \n    return 0;\n}\n```\n\n\nInstallation\n==========================\n\nDependencies\n------------\n\n- [Cmake] \u003e=3.10\n- C++17 compiler ([GCC] 10+, [Clang] or [Microsoft Visual C++][Visual_Studio] 15.7+);\n- [FFTW] \u003e=3.3  (if you choose to use own FFTW installation)\n- [OpenMP] \u003e=5\n\nfCWT has been tested on Mac OSX Mojave 10.14.5, Big Sur 11.6 (both on Intel and Apple Silicon), Windows 10, and Ubutnu 20.04. Please raise an issue if you experience issues running fCWT on these systems! We are working very hard on getting fCWT to run on as many platforms as possible. The benchmark has been performed on a MacBook Pro 2019 having a 2,3 GHz Intel Core i9, 16 GB 2400 MHz DDR4.\n\nBuild time settings\n-------------------\n\nSettings that may be specified at build time by using [CMake] variables are:\n  1. the flag to build a shared library instead of static (default is on);\n  2. whether or not you want to use your own FFTW installation*;\n  3. whether or not you want to build the `BENCHMARK` target;\n  4. whether or not you want to build the `MEX` files for MATLAB;\n  5. installation directories.\n\nDetails:\n\n|CMake variable|Possible values|Default on Unix|Default on Windows|\n|:-------------|:--------------|:--------------|:-----------------|\n|**The flag to build the shared library**||||\n|BUILD_SHARED_LIBS|On \\| Off|On|On|\n|**The flag to use own FFTW installation (e.g., via brew or apt-get)**||||\n|USE_OWN_FFTW *|On \\| Off|Off|Off|\n|**The flag to build benchmark target**||||\n|BUILD_BENCHMARK|On \\| Off|Off|Off|\n|**The flag to build MATLAB MEX files**||||\n|BUILD_MATLAB|On \\| Off|Off|Off|\n|**Installation directories**||||\n|FCWT_MATLAB_DIR|*a path relative to `build`*|\"../MATLAB\"|\"../MATLAB\"|\n|CMAKE_INSTALL_PREFIX|*an absolute path*|\"/usr/local\"|\"%ProgramFiles (x86)%\\fCWT\"|\n|FCWT_CMAKE_INSTALL_DIR|*a path relative to CMAKE_INSTALL_PREFIX*|\"share/fcwt/cmake\"|\"cmake\"|\n|FCWT_LIB_INSTALL_DIR|*a path relative to CMAKE_INSTALL_PREFIX*|\"lib\"|\"lib\"|\n|FCWT_INCLUDE_INSTALL_DIR|*a path relative to CMAKE_INSTALL_PREFIX*|\"include\"|\"include\"|\n\n* Please note that you'll need to configure FFTW to use OpenMP for multithreading and 256-bit vector instructions (e.g., AVX) to obtain comparable results to the benchmark. Standard configuration binaries obtained via `brew` or `apt-get` generally don't have AVX enabled. \n\nInstallation on Unix\n---------------------\n\n    $ git clone https://github.com/fastlib/fCWT.git\n    $ cd fCWT\n    $ mkdir -p build\n    $ cd build\n    $ cmake ../\n    $ make \n    $ sudo make install\n\nInstallation on Microsoft Windows\n---------------------------------\n\nRun the Developer Command Prompt for Visual Studio and type:\n\n    \u003e git clone https://github.com/fastlib/fCWT.git\n    \u003e cd fCWT\n    \u003e mkdir -p build\n    \u003e cd build\n    \u003e cmake -G \"Visual Studio 17 2022\" ..\n    \u003e cmake --build .\n\nA Visual Studio .SLN file has now been created in the build-folder. This project includes several build targets. To build a shared/static library of fCWT, build the 'fCWT' target. To run the example code, set the 'fCWT_example' target as the start-up project and run the code as 'release'.\n\nTo install fCWT, run the Elevated Command Prompt (i.e. the command prompt with administrator privileges) in the build-folder and type:\n\n    \u003e cmake -P cmake_install.cmake\n\nTo make the installed DLL available for *any* application that depends on it, the symbolic link to the\nfcwt.dll should be created:\n\n  - in %SYSTEMROOT%\\System32 for the 64-bit DLL on 64-bit host (or for 32-bit DLL on 32-bit host);\n  - in %SYSTEMROOT%\\SysWOW64 for the 32-bit DLL on 64-bit host.\n\nBenchmark target build\n----------------------\n\nIf you want to replicate the benchmark as presented in the paper, you can build the benchmark target from source using the `BUILD_BENCHMARK` flag. Additionally, you need Rafat's Wavelib library (https://github.com/rafat/wavelib). Follow its instructions to build a static library file and install the library on your system's header and library paths (/usr/local/include and /usr/local/lib for UNIX systems). \n\nUsage\n=====\n\nBenchmark code\n------------\n\nThere are several commands to use the benchmark build:\n\n`$ ./fCWT_benchmark -h`\nGet information about fCWT usage\n\n`$ ./fCWT_benchmark -fcwtoptimize [Length=100000] [Number of threads=8] [Optimization=estimate|measure|patient|exhaustive]`\nCalculate all optimization schemes for all powers of two up to the maximal power of two that is calculated based on the [Length] argument, using [Number of threads] threads and using the optimization method specified. If no optimization method is defined it will use the `measure` method. Estimate is the fastest but lowest quality optimization, exhaustive is the slowest but highest quality optimization. Warning: Exhaustive will take some time!\n\n`$ ./fCWT_benchmark -fcwt [Length=100000] [Number of threads=8]`\nCalculate the CWT using fCWT for three signals with length=[Length]. The signals are generated by a dynamic sine wave function, random function and non-smooth function generator, respectively. Depending on optimization usage and system hardware, a run-time in the order of seconds is expected for lengths up to 100.000. Furthermore, one will see that signal content is independent of performance. See the source code for more information.\n\n`$ ./fCWT_benchmark -wavelib [Length=100000] [Number of threads=8]`\nCalculate the CWT using Wavelib`s C implementation [1] for a signal with length=[Length]. Depending on system hardware, a run-time in the order of several minutes is expected for lengths up to 100.000.\n\n`$ ./fCWT_benchmark -rwave [Length=100000] [Number of threads=8]`\nCalculate the CWT using Rwave's C implementation [2] for a signal with length=[Length]. Depending on system hardware, a run-time in the order of several minutes is expected for lengths up to 100.000.\n\nBenchmark reproduction\n----------------------\n\nIf one wants to reproduce the benchmark results as stated in the article, one has to use a signal length of 100000, 8 threads and calculate optimization plans with the exhaustive method: `$ ./fCWT_example -fcwtoptimize 100000 8 exhaustive` After that:\n\n1. Run fCWT with: `$ ./fCWT_example -fcwt 100000 8`,\n2. Run RWave with: `$ ./fCWT_example -rwave 100000 8`,\n3. Run Wavelib with: `$ ./fCWT_example -wavelib 100000 8`,\n4. Run additional Python, Matlab and Mathematica scripts found in `/src/benchmark`\n\nBy default, the source code performs 10 runs for demonstration purposes. To match the number of runs in the paper, adjust the `runs` variable in `benchmark.cpp:132`. It is recommended to close any background processes. \n\nMATLAB\n---------\n\nIn the MATLAB-folder, we provided an example live-script titled `example.mlx`. The example includes basic MATLAB-implementation on how to generate fCWT optimization plans and calculate time-frequency matrices using fCWT. To use fCWT with MATLAB, make sure you generate the MEX-files using the commands listed in the `quickstart` section.\n\nNote: Expect a decrease in performance when using fCWT via MATLAB. The official benchmark tests MATLAB's CWT implementation via the MATLAB interface and fCWT via the command line. We advice to use fCWT's MATLAB interface solely for plotting purposes. \n\n\nLicense\n=======\n\nfCWT is distributed under Apache 2.0 license. For conditions of distribution and use, see file `LICENSE.TXT`\n\n\nReferences\n==========\n\n[1]     Rafat. Wavelib. https://github.com/rafat/wavelib. Accessed: 2020-04-22.\\\n[2]     R. Carmona, W.-L. Hwang, and B. Torresani.Practical Time-Frequency Analysis:  Gabor and wavelettransforms, with an implementation in S. Academic Press, 1998. [p1, 7, 10]\n\n[CMake]: https://cmake.org/\n[GCC]: https://gcc.gnu.org/\n[Clang]: https://clang.llvm.org/\n[OpenMP]: https://www.openmp.org/\n[FFTW]: https://www.fftw.org/\n[Visual_Studio]: https://www.visualstudio.com/\n[CCWT]: https://github.com/lichtso/CCWT\n[SsqueezePy]: https://github.com/OverLordGoldDragon/ssqueezepy\n[PyWavelets]: https://pywavelets.readthedocs.io/en/latest/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastlib%2Ffcwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastlib%2Ffcwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastlib%2Ffcwt/lists"}