fcwt-lts

Long-Term Support distribution of the fCWT (fast Continuous Wavelet Transform) library. Upstream project: https://github.com/fastlib/fCWT

fcwt-lts provides a compact C99 implementation of the Continuous Wavelet Transform with optional SIMD acceleration and desktop/embedded build targets. This LTS line prioritizes stability, conservative updates, and predictable builds for production systems.

---

Highlights

• Portable C99 core with small footprint
• Morlet wavelet supported out of the box
• SIMD intrinsics for x86_64 (AVX2) and Arm (NEON/AArch64); Cortex-M4F path for MCUs
• OpenMP + FFTW (float + threads) on desktop for high throughput
• Zephyr RTOS support (native simulator & MCU targets)
• Clean CMake integration with an exported alias target CLFML::fcwt-lts

---

Getting Started

Quick Build (Desktop)

# Linux
sudo apt-get install libfftw3-dev libomp5 || true   # package names vary by distro
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# macOS (Homebrew)
brew install fftw libomp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# Windows (MSVC, x64)
cmake -S . -B build -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

On Windows, the build script fetches prebuilt FFTW DLLs and generates import libraries automatically.

Use from Your CMake Project

# Option 1: Subdirectory
add_subdirectory(external/fcwt-lts)

add_executable(myapp src/main.c)
target_link_libraries(myapp PRIVATE CLFML::fcwt-lts)

# Option 2: FetchContent
include(FetchContent)
FetchContent_Declare(fcwt
  GIT_REPOSITORY https://example.com/your/fcwt-lts.git
  GIT_TAG        vX.Y.Z   # pick a tagged release
)
FetchContent_MakeAvailable(fcwt)

add_executable(myapp src/main.c)
target_link_libraries(myapp PRIVATE CLFML::fcwt-lts)

Build Options

Option	Default	Description
CLFML_FCWT_LTS_BUILD_EXAMPLE_PROJECTS	ON*	Builds examples/native/simple_usage (automatically OFF when used as a subdirectory).
CLFML_FCWT_LTS_BUILD_TESTS	OFF	Enables tests (desktop).

Desktop features

• Requires OpenMP (linked via OpenMP::OpenMP_CXX)
• Requires FFTW3 (single-precision + threads): FFTW3::FFTW3F and FFTW3::FFTW3F_THREAD
• Optional AVX2/NEON flags if detected

Zephyr features

• BOARD=native_sim (x86_64 host): uses FFTW, x86 intrinsics; guards against 32-bit hosts
• MCU boards: uses Cortex-M4F intrinsics; no FFTW linkage

---

Directory Layout (simplified)

fcwt-lts/
├─ src/                          # core library sources and public headers
│  ├─ fcwt.c, fcwt_morlet.c, fcwt_scales.c, ...
│  └─ utility/intrinsics/        # x86_64, aarch64, cortex-m4f
├─ platforms/cmake/
│  ├─ os_desktop.cmake           # desktop flags, FFTW/OpenMP, SIMD
│  └─ zephyr.cmake               # Zephyr integration
├─ examples/native/simple_usage/ # minimal example (desktop)
└─ tests/pc/                     # optional tests

---

Performance Notes

• Two parallel layers may be active:

  1. FFTW threads, 2) OpenMP in fcwt-lts. Tune thread counts to avoid oversubscription (e.g., OMP_NUM_THREADS, FFTW planner thread API).

• Vector paths (AVX2/NEON) are enabled conditionally; ensure your deployment CPUs actually support the chosen instruction set.

---

Troubleshooting

• “FFTW not found”: install float + threads variants (package names often include fftw, fftwf, fftw3f-threads).
• Apple Clang + OpenMP errors: install libomp (brew install libomp) and rebuild.
• Link errors to fcwt symbols: confirm include paths and link order (... myapp.o ... -lfcwt-lts).
• All zeros / weak response: verify sampling rate, scale range, and that your target frequency is within the configured band.

---

Contributing

Issues and pull requests are welcome. Please keep changes focused and include a short rationale and tests where practical.

---

License

See LICENSE in this repository.

---

Acknowledgments

This work is based on the fCWT project. Upstream repository: https://github.com/fastlib/fCWT