refactor(deglib): modularize header layout, add top-level facades and align test structure

- Restructure deglib headers into logical subdirectories (utils/, optimization/, graph/)
- Add top-level facade headers (optimization.h, graph.h) to eliminate deep directory includes for library users
- Extract CPU detection to utils/cpu.h while maintaining config.h macro compatibility
- Extract SearchGraph and MutableGraph interfaces into graph/
- Reorganize unit, integration, and regression test suites to mirror deglib layout 1:1

Author: Neiko2002

cpp/deglib/include/deglib/analysis.h

@@ -6,7 +6,7 @@
 #include <thread>
 
 #include "deglib/concurrent.h"
-#include "deglib/memory.h"
+#include "deglib/utils/memory.h"
 #include "deglib/search.h"
 #include "deglib/graph.h"
 

cpp/deglib/include/deglib/builder.h

@@ -17,7 +17,7 @@
 #include "deglib/concurrent.h"
 #include "deglib/analysis.h"
 #include "deglib/graph.h"
-#include "deglib/random.h"
+#include "deglib/utils/random.h"
 
 namespace deglib::builder
 {

cpp/deglib/include/deglib/config.h

@@ -35,86 +35,5 @@
 #endif
 #endif
 
-
-// ---------------------------------------------------------------------------
-// Runtime CPU feature detection
-// ---------------------------------------------------------------------------
-// Uses CPUID (via __cpuidex on MSVC, __cpuid_count on GCC/Clang) to detect
-// AVX2 and AVX-512F at runtime. Results are cached in a function-local static
-// so the CPUID query runs only once.
-//
-// AVX2 is the minimum x86 baseline requirement. F16C is always available on
-// CPUs that support AVX2, so it is not tracked separately.
-//
-// The distance headers compile all SIMD code paths unconditionally (the
-// intrinsic headers are always included below). At runtime, select_dist()
-// uses deglib::cpu::has_*() to dispatch to the best variant. This means there
-// is zero loop overhead — capability checks happen during variant selection,
-// not inside distance calculation loops.
-// ---------------------------------------------------------------------------
-
-namespace deglib::cpu {
-
-    namespace detail {
-
-#if defined(DEGLIB_X86)
-        // Query CPUID leaf/subleaf into a 4-element int array.
-        // Uses __cpuidex on MSVC and __cpuid_count on GCC/Clang.
-        inline void cpuid(int leaf, int subleaf, int cpu_info[4]) {
-#if defined(_MSC_VER)
-            __cpuidex(cpu_info, leaf, subleaf);
-#else
-            __cpuid_count(leaf, subleaf, cpu_info[0], cpu_info[1], cpu_info[2], cpu_info[3]);
-#endif
-        }
-#endif
-
-        // Cached hardware feature flags, populated on first call via a function-local static.
-        struct CpuFeatures {
-            bool avx2{false};
-            bool avx512f{false};
-
-            CpuFeatures() {
-#if defined(DEGLIB_X86)
-                int cpu_info[4] = {0};
-
-                // Leaf 7, subleaf 0: extended feature flags in EBX and ECX
-                cpuid(7, 0, cpu_info);
-                avx2    = (cpu_info[1] & (1 << 5)) != 0;
-                avx512f = (cpu_info[1] & (1 << 16)) != 0;
-#endif
-            }
-        };
-
-        inline const CpuFeatures& features() {
-            static CpuFeatures cached;
-            return cached;
-        }
-
-    } // namespace detail
-
-    enum class InstructionSet : uint8_t {
-        Auto   = 0,
-        Scalar = 1,
-        AVX2   = 2,
-        AVX512 = 3
-    };
-
-    inline const char* instruction_set_to_string(InstructionSet inst) {
-        switch (inst) {
-            case InstructionSet::Auto:   return "Auto";
-            case InstructionSet::Scalar: return "Scalar";
-            case InstructionSet::AVX2:   return "AVX2";
-            case InstructionSet::AVX512: return "AVX512";
-        }
-        return "Unknown";
-    }
-
-    // Runtime CPU feature detection — safe to call from any translation unit.
-    // These checks are performed once (cached) and have zero cost per call thereafter.
-
-    inline bool has_avx2()   { return detail::features().avx2; }
-    inline bool has_avx512() { return detail::features().avx512f; }
-
-} // namespace deglib::cpu
-
+// CPU detection utilities
+#include "deglib/utils/cpu.h"

cpp/deglib/include/deglib/deglib.h

@@ -1,14 +1,13 @@
 #pragma once
 
 #include "deglib/config.h"
-#include "deglib/memory.h"
+#include "deglib/utils/memory.h"
+#include "deglib/utils/random.h"
 #include "deglib/distances.h"
 #include "deglib/filter.h"
 #include "deglib/search.h"
 #include "deglib/repository.h"
 #include "deglib/graph.h"
 #include "deglib/analysis.h"
-#include "deglib/graph/readonly_graph.h"
-#include "deglib/graph/sizebounded_graph.h"
 #include "deglib/builder.h"
-#include "deglib/random.h"
+#include "deglib/optimization.h"

cpp/deglib/include/deglib/distances.h

@@ -283,4 +283,54 @@ namespace deglib {
         ~FloatSpace() {}
     };
 
+namespace distances {
+
+    /**
+     * Compute distance between two feature vectors in the given FloatSpace.
+     */
+    inline float compute_distance(const deglib::FloatSpace& space, const void* vec1, const void* vec2) {
+        if (vec1 == nullptr || vec2 == nullptr) {
+            throw std::invalid_argument("compute_distance: vec1 and vec2 must not be null");
+        }
+        const auto dist_func = space.get_dist_func();
+        const auto param = space.get_dist_func_param();
+        return dist_func(vec1, vec2, param);
+    }
+
+    /**
+     * Compute distances between queries and targets using the given FloatSpace.
+     */
+    inline void compute_distances(
+        const deglib::FloatSpace& space,
+        const void* queries,
+        size_t num_queries,
+        const void* targets,
+        size_t num_targets,
+        float* result_distances
+    ) {
+        if (queries == nullptr || targets == nullptr || result_distances == nullptr) {
+            throw std::invalid_argument("compute_distances: arguments must not be null");
+        }
+
+        const size_t byte_stride = space.get_data_size();
+        const uint8_t* q_ptr = static_cast<const uint8_t*>(queries);
+        const uint8_t* t_ptr = static_cast<const uint8_t*>(targets);
+
+        const auto param = space.get_dist_func_param();
+        space.compute([&](const auto& dist_func_obj) {
+            using DistType = std::decay_t<decltype(dist_func_obj)>;
+            for (size_t q = 0; q < num_queries; ++q) {
+                const uint8_t* current_query = q_ptr + q * byte_stride;
+                float* out_row = result_distances + q * num_targets;
+
+                for (size_t t = 0; t < num_targets; ++t) {
+                    out_row[t] = DistType::compare(current_query, t_ptr + t * byte_stride, param);
+                }
+            }
+        });
+    }
+
+} // namespace distances
+
 }  // end namespace deglib
+

cpp/deglib/include/deglib/graph.h

@@ -1,55 +1,13 @@
 #pragma once
 
-#include "deglib/search.h"
+// Graph Interfaces
+#include "deglib/graph/search_graph.h"
+#include "deglib/graph/mutable_graph.h"
+#include "deglib/graph/dynamic_graph.h"
 
-namespace deglib::graph
-{
+// Visited List Pool Helper
+#include "deglib/graph/visited_list_pool.h"
 
-class MutableGraph : public deglib::search::SearchGraph
-{
-  public:    
-
-   /**
-    * Add a new vertex. The neighbor indices will be prefilled with a self-loop, the weights will be 0.
-    * 
-    * @return the internal index of the new vertex
-    */
-    virtual uint32_t addVertex(const uint32_t external_label, const std::byte* feature_vector) = 0;
-
-   /**
-    * Remove an existing vertex and returns its list of neighbors
-    */
-    virtual std::vector<uint32_t> removeVertex(const uint32_t external_labelr) = 0;
-
-   /**
-    * Swap a neighbor with another neighbor and its weight.
-    * 
-    * @param internal_index vertex index which neighbors should be changed
-    * @param from_neighbor_index neighbor index to remove
-    * @param to_neighbor_index neighbor index to add
-    * @param to_neighbor_weight weight of the neighbor to add
-    * @return true if the from_neighbor_index was found and changed
-    */
-    virtual bool changeEdge(const uint32_t internal_index, const uint32_t from_neighbor_index, const uint32_t to_neighbor_index, const float to_neighbor_weight) = 0;
-
-
-    /**
-     * Change all edges of a vertex.
-     * The neighbor indices/weights and feature vectors will be copied.
-     * The neighbor array need to have enough neighbors to match the edge-per-vertex count of the graph.
-     * The indices in the neighbor_indices array must be sorted.
-     */
-    virtual void changeEdges(const uint32_t internal_index, const uint32_t* neighbor_indices, const float* neighbor_weights) = 0;
-
-
-    /**
-     * 
-     */
-    virtual const float* getNeighborWeights(const uint32_t internal_index) const = 0;    
-
-    virtual const float getEdgeWeight(const uint32_t from_neighbor_index, const uint32_t to_neighbor_index) const = 0;    
-
-    virtual const bool saveGraph(const char* path_to_graph) const = 0;
-};
-
-}  // end namespace deglib::graph
+// Concrete Graph Implementations
+#include "deglib/graph/readonly_graph.h"
+#include "deglib/graph/sizebounded_graph.h"

cpp/deglib/include/deglib/graph/mutable_graph.h

@@ -0,0 +1,59 @@
+#pragma once
+
+#include "deglib/graph/search_graph.h"
+
+#include <cstdint>
+#include <cstddef>
+#include <vector>
+
+namespace deglib::graph
+{
+
+class MutableGraph : public deglib::search::SearchGraph
+{
+  public:    
+
+   /**
+    * Add a new vertex. The neighbor indices will be prefilled with a self-loop, the weights will be 0.
+    * 
+    * @return the internal index of the new vertex
+    */
+    virtual uint32_t addVertex(const uint32_t external_label, const std::byte* feature_vector) = 0;
+
+   /**
+    * Remove an existing vertex and returns its list of neighbors
+    */
+    virtual std::vector<uint32_t> removeVertex(const uint32_t external_labelr) = 0;
+
+   /**
+    * Swap a neighbor with another neighbor and its weight.
+    * 
+    * @param internal_index vertex index which neighbors should be changed
+    * @param from_neighbor_index neighbor index to remove
+    * @param to_neighbor_index neighbor index to add
+    * @param to_neighbor_weight weight of the neighbor to add
+    * @return true if the from_neighbor_index was found and changed
+    */
+    virtual bool changeEdge(const uint32_t internal_index, const uint32_t from_neighbor_index, const uint32_t to_neighbor_index, const float to_neighbor_weight) = 0;
+
+
+    /**
+     * Change all edges of a vertex.
+     * The neighbor indices/weights and feature vectors will be copied.
+     * The neighbor array need to have enough neighbors to match the edge-per-vertex count of the graph.
+     * The indices in the neighbor_indices array must be sorted.
+     */
+    virtual void changeEdges(const uint32_t internal_index, const uint32_t* neighbor_indices, const float* neighbor_weights) = 0;
+
+
+    /**
+     * 
+     */
+    virtual const float* getNeighborWeights(const uint32_t internal_index) const = 0;    
+
+    virtual const float getEdgeWeight(const uint32_t from_neighbor_index, const uint32_t to_neighbor_index) const = 0;    
+
+    virtual const bool saveGraph(const char* path_to_graph) const = 0;
+};
+
+}  // end namespace deglib::graph

cpp/deglib/include/deglib/graph/readonly_graph.h

@@ -14,10 +14,10 @@
 
 #include "deglib/graph.h"
 #include "deglib/repository.h"
-#include "deglib/memory.h"
+#include "deglib/utils/memory.h"
 #include "deglib/distances.h"
 #include "deglib/search.h"
-#include "deglib/visited_list_pool.h"
+#include "deglib/graph/visited_list_pool.h"
 
 namespace deglib::graph
 {