Add: Unified runtime hardware dispatch layer (Phase 5.6)

Replaces scattered compile-time #ifdef chains with a centralized runtime
hardware detection and backend selection module. CPUID probes AVX-512 at
runtime, CUDA/Metal availability checked via device queries, OpenMP thread
count detected dynamically. Backend can be overridden via FLEXAIDS_BACKEND
environment variable with automatic fallback to next-best available.

New files:
- LIB/hardware_dispatch.h  — HardwareBackend enum, HardwareCapabilities struct, API
- LIB/hardware_dispatch.cpp — CPUID, CUDA, Metal, OpenMP detection + selection logic

Updated:
- ShannonThermoStack now uses runtime dispatch for report strings and exposes
  active_shannon_backend() for programmatic backend queries
- CMakeLists.txt wires hardware_dispatch.cpp into all targets, fixes Eigen
  compile definition propagation for test_hardware_dispatch, adds SIMD
  configuration to test target
- 18 new tests covering runtime detection, backend selection, fallback logic,
  exclusion lists, edge cases (100k histograms, extreme ranges, single-bin)

All 63 hardware dispatch tests pass. Pre-existing StatMech tolerance test
(HighTemperatureFlattensWeights) unchanged.

https://claude.ai/code/session_015b2LFt2aRHwau6rv6hnHoZ

Author: claude

CMakeLists.txt

@@ -241,6 +241,7 @@ target_sources(FlexAID PRIVATE
         LIB/statmech.cpp
         LIB/encom.cpp             # ← NEW: ENCoM vibrational entropy
         # ── v1.5 thermodynamic + hardware acceleration modules ──
+        LIB/hardware_dispatch.cpp
         LIB/ShannonThermoStack/ShannonThermoStack.cpp
         LIB/LigandRingFlex/RingConformerLibrary.cpp
         LIB/LigandRingFlex/SugarPucker.cpp
@@ -488,22 +489,32 @@ if(BUILD_TESTING)
     endif()
     add_test(NAME StatMechTests COMMAND test_statmech)
 
-    # test_hardware_dispatch — ShannonThermoStack dispatch layer tests
+    # test_hardware_dispatch — ShannonThermoStack dispatch layer + unified runtime dispatch tests
     add_executable(test_hardware_dispatch
         tests/test_hardware_dispatch.cpp
         LIB/ShannonThermoStack/ShannonThermoStack.cpp
+        LIB/hardware_dispatch.cpp
         LIB/statmech.cpp
         LIB/tencm.cpp)
     target_include_directories(test_hardware_dispatch PRIVATE
         ${CMAKE_CURRENT_SOURCE_DIR}/LIB
         ${CMAKE_CURRENT_SOURCE_DIR}/LIB/ShannonThermoStack)
     target_link_libraries(test_hardware_dispatch PRIVATE GTest::gtest GTest::gtest_main)
-    target_compile_options(test_hardware_dispatch PRIVATE -O2)
+    if(MSVC)
+        target_compile_options(test_hardware_dispatch PRIVATE /O2)
+    else()
+        target_compile_options(test_hardware_dispatch PRIVATE -O2)
+    endif()
+    flexaids_configure_simd(test_hardware_dispatch)
     if(FLEXAIDS_USE_OPENMP AND OpenMP_CXX_FOUND)
         target_link_libraries(test_hardware_dispatch PRIVATE OpenMP::OpenMP_CXX)
     endif()
-    if(FLEXAIDS_HAS_EIGEN)
+    if(FLEXAIDS_USE_EIGEN AND Eigen3_FOUND)
         target_link_libraries(test_hardware_dispatch PRIVATE Eigen3::Eigen)
+        target_compile_definitions(test_hardware_dispatch PRIVATE FLEXAIDS_HAS_EIGEN)
+    elseif(FLEXAIDS_USE_EIGEN AND EIGEN3_FOUND)
+        target_include_directories(test_hardware_dispatch PRIVATE ${EIGEN3_INCLUDE_DIRS})
+        target_compile_definitions(test_hardware_dispatch PRIVATE FLEXAIDS_HAS_EIGEN)
     endif()
     add_test(NAME HardwareDispatchTests COMMAND test_hardware_dispatch)
 

LIB/ShannonThermoStack/ShannonThermoStack.cpp

@@ -1,14 +1,16 @@
 // ShannonThermoStack.cpp — multi-path implementation
 //
-// Hardware dispatch priority (runtime):
-//   1. CUDA GPU   (FLEXAIDS_USE_CUDA)
-//   2. Metal GPU  (FLEXAIDS_HAS_METAL_SHANNON, Apple Silicon)
-//   3. AVX-512    (__AVX512F__)  — 8 doubles/cycle histogram binning
-//   4. OpenMP     (_OPENMP)
+// Hardware dispatch priority (runtime, via hardware_dispatch.h):
+//   1. CUDA GPU   (FLEXAIDS_USE_CUDA + runtime device detected)
+//   2. Metal GPU  (FLEXAIDS_HAS_METAL_SHANNON + runtime device detected)
+//   3. AVX-512    (__AVX512F__ + CPUID confirmation at runtime)
+//   4. OpenMP     (_OPENMP + >1 thread available)
 //   5. Scalar     (always available)
 //
 // Eigen is used for vectorised log() / probability array ops on all CPU paths.
+// The active backend can be queried at runtime via active_shannon_backend().
 #include "ShannonThermoStack.h"
+#include "../hardware_dispatch.h"
 
 #ifdef FLEXAIDS_HAS_METAL_SHANNON
 #  include "ShannonMetalBridge.h"
@@ -278,29 +280,51 @@ FullThermoResult run_shannon_thermo_stack(
     double S_contrib    = -temperature_K * total_S;
     double final_dG     = base_deltaG + S_contrib;
 
-    const char* hw =
-#if defined(FLEXAIDS_USE_CUDA)
-        "CUDA";
-#elif defined(FLEXAIDS_HAS_METAL_SHANNON)
-        "Metal";
-#elif defined(__AVX512F__)
-        "AVX-512";
-#elif defined(_OPENMP)
-        "OpenMP";
-#else
-        "scalar";
-#endif
+    const auto backend = active_shannon_backend();
+    const char* hw = flexaids::backend_name(backend);
+
+    std::string eigen_tag;
+    if (flexaids::detect_hardware().has_eigen)
+        eigen_tag = "+Eigen";
 
     std::string report =
-        std::string("ShannonThermoStack[") + hw +
-#ifdef FLEXAIDS_HAS_EIGEN
-        "+Eigen"
-#endif
+        std::string("ShannonThermoStack[") + hw + eigen_tag +
         "]: S_conf=" + std::to_string(S_conf_bits) +
         " bits, S_vib=" + std::to_string(S_vib) +
         " kcal/mol/K, ΔG=" + std::to_string(final_dG) + " kcal/mol";
 
     return { final_dG, S_conf_bits, S_vib, S_contrib, report };
 }
 
+// ─── active_shannon_backend ─────────────────────────────────────────────────
+// Returns the backend that compute_shannon_entropy() actually uses for
+// histogram computation.  This mirrors the compile-time #ifdef chain but
+// also consults runtime detection for AVX-512 (CPUID) and OpenMP (thread
+// count) to avoid reporting a backend that would silently fall through.
+
+flexaids::HardwareBackend active_shannon_backend() {
+#if defined(FLEXAIDS_USE_CUDA)
+    if (flexaids::is_backend_available(flexaids::HardwareBackend::CUDA))
+        return flexaids::HardwareBackend::CUDA;
+#endif
+#if defined(FLEXAIDS_HAS_METAL_SHANNON)
+    if (flexaids::is_backend_available(flexaids::HardwareBackend::METAL))
+        return flexaids::HardwareBackend::METAL;
+#endif
+#if defined(__AVX512F__)
+    if (flexaids::is_backend_available(flexaids::HardwareBackend::AVX512)) {
+#  if defined(_OPENMP)
+        return flexaids::HardwareBackend::AVX512; // AVX-512 + OpenMP combined path
+#  else
+        return flexaids::HardwareBackend::AVX512;
+#  endif
+    }
+#endif
+#if defined(_OPENMP)
+    if (flexaids::is_backend_available(flexaids::HardwareBackend::OPENMP))
+        return flexaids::HardwareBackend::OPENMP;
+#endif
+    return flexaids::HardwareBackend::SCALAR;
+}
+
 } // namespace shannon_thermo

LIB/ShannonThermoStack/ShannonThermoStack.h

@@ -3,14 +3,18 @@
 // Combines:
 //   – Shannon configurational entropy over GA ensemble (binned into 256 mega-clusters)
 //   – Torsional ENCoM vibrational entropy from NormalMode fluctuations (protein + nucleotide backbones)
-//   – Hardware-accelerated histogram computation (Metal on Apple Silicon, OpenMP/Eigen on other platforms)
+//   – Hardware-accelerated histogram computation (CUDA, Metal, AVX-512, OpenMP, scalar)
+//
+// Runtime backend selection via hardware_dispatch.h replaces compile-time #ifdef
+// chains.  The environment variable FLEXAIDS_BACKEND can override auto-selection.
 //
 // Reuses StatMechEngine (statmech.h) and TorsionalENM (tencm.h) without modification.
 // BindingPopulation is untouched; SugarPuckerGene flexibility is separate.
 #pragma once
 
 #include "../statmech.h"
 #include "../tencm.h"
+#include "../hardware_dispatch.h"
 #include <vector>
 #include <string>
 #include <cmath>
@@ -87,4 +91,9 @@ FullThermoResult run_shannon_thermo_stack(
     double                          base_deltaG,
     double                          temperature_K = TEMPERATURE_K);
 
+// ─── query the active backend at runtime ────────────────────────────────────
+// Returns the backend that compute_shannon_entropy() will use for histogram
+// computation, accounting for compile-time availability and runtime detection.
+flexaids::HardwareBackend active_shannon_backend();
+
 } // namespace shannon_thermo