Improve OpenMP acceleration support, enable KissFFT OpenMP, and add build documentation (#601)

[samerzumot]

Description

Addresses #601 ("Performance tunning").

This PR focuses on the OpenMP performance and compilation subtasks outlined in #601:

• improve docs for building with openmp
• better openmp support
• check that dependencies like kissfft are compiled properly with all available optimizations

Summary of Improvements

1. Enable OpenMP Parallel Execution in KissFFT (src/data_handler/build.cmake):

   • When building with OpenMP enabled (-DUSE_OPENMP=ON / tools/build.py --use-openmp), src/data_handler/build.cmake previously did not pass KISSFFT_OPENMP=ON to KissFFT. KissFFT was always built in single-threaded mode even when OpenMP was explicitly requested.
   • Now, USE_OPENMP automatically sets KISSFFT_OPENMP ON, enabling multi-threaded radix butterfly calculations in KissFFT (kiss_fft.c).

2. Modernize KissFFT OpenMP Compiler Configuration (third_party/kissfft/build.cmake):

   • Modernized OpenMP linking in third_party/kissfft/build.cmake to leverage CMake's standard OpenMP::OpenMP_C target, properly configuring compiler flags, include paths, and runtime libraries across GCC, Clang, AppleClang, and MSVC.
   • Fixed a compiler detection bug where MSVC was previously nested inside a GNU|Clang|AppleClang check, causing MSVC OpenMP builds to fail.

3. macOS OpenMP Discovery & Native Architecture Support (CMakeLists.txt & tools/build.py):

   • On macOS, Homebrew installs libomp as a keg-only package. CMakeLists.txt now automatically detects Homebrew's libomp path (/opt/homebrew/opt/libomp or /usr/local/opt/libomp) if OpenMP_ROOT is not explicitly provided.
   • When running tools/build.py --use-openmp on macOS, the default architecture is automatically adjusted to the native machine architecture (arm64 on Apple Silicon, x86_64 on Intel) to match Homebrew's single-architecture bottle, enabling smooth out-of-the-box OpenMP builds without manual configuration flags.

4. Comprehensive OpenMP Build Documentation (docs/BuildBrainFlow.rst):

   • Added a dedicated OpenMP Acceleration section to docs/BuildBrainFlow.rst detailing:
     • The performance benefits of OpenMP multi-threading in BrainFlow (filters, wavelets, band powers, KissFFT).
     • Prerequisites for Linux (libomp-dev / libgomp), macOS (brew install libomp), and Windows (MSVC built-in).
     • Build commands using both tools/build.py --use-openmp and direct CMake invocation.
     • Architecture notes for Apple Silicon macOS.

Verification

• Verified cmake -B build_test -DUSE_OPENMP=ON and cmake --build build_test --target kissfft DataHandler on macOS (AppleClang 17 + Homebrew libomp 23.1).
• Verified python3 tools/build.py --use-openmp end-to-end build and installation.
• Verified standard (non-OpenMP) build compatibility remains intact (cmake -B build_test_default && cmake --build build_test_default --target DataHandler).