Add comprehensive documentation to instantiation system

Co-authored-by: ahuber21 <[email protected]>

Author: Copilot

include/svs/multi-arch/x86/avx2.cpp

@@ -14,6 +14,46 @@
  * limitations under the License.
  */
 
+///
+/// @file avx2.cpp
+/// @brief Explicit instantiations of distance implementations for AVX2
+///
+/// This file contains explicit template instantiations for distance computations
+/// optimized for Intel(R) AVX2 instructions. It is compiled with compiler flags
+/// targeting the Haswell microarchitecture (`-march=haswell`), which includes
+/// AVX2, FMA, and related extensions.
+///
+/// ## Purpose
+///
+/// By explicitly instantiating templates in this compilation unit with AVX2
+/// compiler flags, we enable runtime ISA dispatch: the library can detect at runtime
+/// whether the CPU supports AVX2 (but not AVX-512) and call these optimized
+/// implementations, while falling back to generic implementations if neither AVX-512
+/// nor AVX2 are available.
+///
+/// ## Architecture
+///
+/// Each distance implementation (L2Impl, IPImpl, CosineSimilarityImpl) is a thin
+/// wrapper around `generic_simd_op` which in turn uses SIMD operation structs like:
+/// - `L2FloatOp<8>` - L2 distance using AVX2 floating-point operations (SIMD width 8)
+/// - `IPFloatOp<8>` - Inner product using AVX2 floating-point operations
+/// - `CosineFloatOp<8>` - Cosine similarity using AVX2 floating-point operations
+///
+/// Note: AVX2 uses SIMD width 8 (256-bit vectors) vs AVX-512's width 16 (512-bit vectors).
+///
+/// These SIMD ops are defined in the distance headers and contain the actual AVX2
+/// intrinsics. The instantiations here ensure this AVX2 code is generated.
+///
+/// ## Dimensions Instantiated
+///
+/// We instantiate for the following dimensionalities:
+/// - Fixed: 64, 96, 100, 128, 160, 200, 512, 768
+/// - Dynamic: For runtime-determined dimensions
+///
+/// For each dimension, 16 type combinations are instantiated (4 element types × 4):
+/// float, int8_t, uint8_t, Float16
+///
+
 #if defined(__x86_64__)
 #include "svs/core/distance/cosine.h"
 #include "svs/core/distance/euclidean.h"
@@ -22,6 +62,10 @@
 namespace svs::distance {
 
 // TODO: connect with dim_supported_list
+
+// ============================================================================
+// L2 (Euclidean) Distance Instantiations
+// ============================================================================
 DISTANCE_L2_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX2);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX2);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX2);
@@ -32,6 +76,9 @@ DISTANCE_L2_INSTANTIATE_TEMPLATE(512, AVX_AVAILABILITY::AVX2);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(768, AVX_AVAILABILITY::AVX2);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(Dynamic, AVX_AVAILABILITY::AVX2);
 
+// ============================================================================
+// Inner Product Instantiations
+// ============================================================================
 DISTANCE_IP_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX2);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX2);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX2);
@@ -42,6 +89,9 @@ DISTANCE_IP_INSTANTIATE_TEMPLATE(512, AVX_AVAILABILITY::AVX2);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(768, AVX_AVAILABILITY::AVX2);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(Dynamic, AVX_AVAILABILITY::AVX2);
 
+// ============================================================================
+// Cosine Similarity Instantiations
+// ============================================================================
 DISTANCE_CS_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX2);
 DISTANCE_CS_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX2);
 DISTANCE_CS_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX2);

include/svs/multi-arch/x86/avx512.cpp

@@ -14,6 +14,44 @@
  * limitations under the License.
  */
 
+///
+/// @file avx512.cpp
+/// @brief Explicit instantiations of distance implementations for AVX-512
+///
+/// This file contains explicit template instantiations for distance computations
+/// optimized for Intel(R) AVX-512 instructions. It is compiled with compiler flags
+/// targeting the Cascade Lake microarchitecture (`-march=cascadelake`), which
+/// includes AVX-512F, AVX-512DQ, AVX-512CD, AVX-512BW, and AVX-512VL extensions.
+///
+/// ## Purpose
+///
+/// By explicitly instantiating templates in this compilation unit with AVX-512
+/// compiler flags, we enable runtime ISA dispatch: the library can detect at runtime
+/// whether the CPU supports AVX-512 and call these optimized implementations if
+/// available, while falling back to AVX2 or generic implementations otherwise.
+///
+/// ## Architecture
+///
+/// Each distance implementation (L2Impl, IPImpl, CosineSimilarityImpl) is a thin
+/// wrapper around `generic_simd_op` which in turn uses SIMD operation structs like:
+/// - `L2FloatOp<16>` - L2 distance using AVX-512 floating-point operations
+/// - `IPFloatOp<16>` - Inner product using AVX-512 floating-point operations
+/// - `L2VNNIOp<int16_t, 32>` - L2 using AVX-512 VNNI (integer operations)
+/// - `IPVNNIOp<int16_t, 32>` - Inner product using AVX-512 VNNI
+///
+/// These SIMD ops are defined in the distance headers and contain the actual AVX-512
+/// intrinsics. The instantiations here ensure this AVX-512 code is generated.
+///
+/// ## Dimensions Instantiated
+///
+/// We instantiate for the following dimensionalities:
+/// - Fixed: 64, 96, 100, 128, 160, 200, 512, 768
+/// - Dynamic: For runtime-determined dimensions
+///
+/// For each dimension, 16 type combinations are instantiated (4 element types × 4):
+/// float, int8_t, uint8_t, Float16
+///
+
 #if defined(__x86_64__)
 #include "svs/core/distance/cosine.h"
 #include "svs/core/distance/euclidean.h"
@@ -22,6 +60,10 @@
 namespace svs::distance {
 
 // TODO: connect with dim_supported_list
+
+// ============================================================================
+// L2 (Euclidean) Distance Instantiations
+// ============================================================================
 DISTANCE_L2_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX512);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX512);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX512);
@@ -32,6 +74,9 @@ DISTANCE_L2_INSTANTIATE_TEMPLATE(512, AVX_AVAILABILITY::AVX512);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(768, AVX_AVAILABILITY::AVX512);
 DISTANCE_L2_INSTANTIATE_TEMPLATE(Dynamic, AVX_AVAILABILITY::AVX512);
 
+// ============================================================================
+// Inner Product Instantiations
+// ============================================================================
 DISTANCE_IP_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX512);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX512);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX512);
@@ -42,6 +87,9 @@ DISTANCE_IP_INSTANTIATE_TEMPLATE(512, AVX_AVAILABILITY::AVX512);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(768, AVX_AVAILABILITY::AVX512);
 DISTANCE_IP_INSTANTIATE_TEMPLATE(Dynamic, AVX_AVAILABILITY::AVX512);
 
+// ============================================================================
+// Cosine Similarity Instantiations
+// ============================================================================
 DISTANCE_CS_INSTANTIATE_TEMPLATE(64, AVX_AVAILABILITY::AVX512);
 DISTANCE_CS_INSTANTIATE_TEMPLATE(96, AVX_AVAILABILITY::AVX512);
 DISTANCE_CS_INSTANTIATE_TEMPLATE(100, AVX_AVAILABILITY::AVX512);

include/svs/multi-arch/x86/preprocessor.h

@@ -16,6 +16,43 @@
 
 #pragma once
 
+///
+/// @file preprocessor.h
+/// @brief Macros for explicit instantiation of distance implementations
+///
+/// This file contains macros to systematically generate explicit template instantiations
+/// for distance implementations (L2Impl, IPImpl, CosineSimilarityImpl).
+///
+/// ## Why Explicit Instantiation?
+///
+/// The library supports runtime ISA dispatch - detecting AVX512/AVX2 support at runtime
+/// and calling the appropriate optimized implementation. This requires:
+/// 1. Separate compilation with architecture-specific compiler flags
+/// 2. Explicit instantiation of templates in those compilation units
+///
+/// Without explicit instantiation, the templates would be instantiated inline wherever
+/// used, which would prevent proper ISA-specific optimization.
+///
+/// ## Architecture
+///
+/// Distance implementations (e.g., `L2Impl`) are thin wrappers that call `generic_simd_op`
+/// with a SIMD operation struct (e.g., `L2FloatOp<16>`). The SIMD ops contain the actual
+/// AVX intrinsics. By explicitly instantiating the distance implementations in files
+/// compiled with `-march=cascadelake` or `-march=haswell`, we ensure the AVX code is
+/// generated with appropriate optimizations.
+///
+/// ## Type Combinations
+///
+/// Each macro instantiates 16 type combinations (4 element types × 4 element types):
+/// - float, int8_t, uint8_t, Float16
+///
+/// This covers all supported mixed-type distance computations.
+///
+
+/// Helper macro for L2 distance explicit instantiation
+/// @param SPEC Either `template` (for definitions) or `extern template` (for declarations)
+/// @param N Dimensionality (e.g., 64, 128, Dynamic)
+/// @param AVX AVX availability level (AVX_AVAILABILITY::AVX512 or AVX_AVAILABILITY::AVX2)
 #define DISTANCE_L2_TEMPLATE_HELPER(SPEC, N, AVX)               \
     SPEC struct L2Impl<N, float, float, AVX>;                   \
     SPEC struct L2Impl<N, float, int8_t, AVX>;                  \
@@ -34,12 +71,18 @@
     SPEC struct L2Impl<N, svs::float16::Float16, uint8_t, AVX>; \
     SPEC struct L2Impl<N, svs::float16::Float16, svs::float16::Float16, AVX>;
 
+/// Instantiate L2 distance implementations (use in .cpp files)
 #define DISTANCE_L2_INSTANTIATE_TEMPLATE(N, AVX) \
     DISTANCE_L2_TEMPLATE_HELPER(template, N, AVX);
 
+/// Declare external L2 distance implementations (use in .h files)
 #define DISTANCE_L2_EXTERN_TEMPLATE(N, AVX) \
     DISTANCE_L2_TEMPLATE_HELPER(extern template, N, AVX);
 
+/// Helper macro for Inner Product explicit instantiation
+/// @param SPEC Either `template` (for definitions) or `extern template` (for declarations)
+/// @param N Dimensionality (e.g., 64, 128, Dynamic)
+/// @param AVX AVX availability level (AVX_AVAILABILITY::AVX512 or AVX_AVAILABILITY::AVX2)
 #define DISTANCE_IP_TEMPLATE_HELPER(SPEC, N, AVX)               \
     SPEC struct IPImpl<N, float, float, AVX>;                   \
     SPEC struct IPImpl<N, float, int8_t, AVX>;                  \
@@ -58,12 +101,18 @@
     SPEC struct IPImpl<N, svs::float16::Float16, uint8_t, AVX>; \
     SPEC struct IPImpl<N, svs::float16::Float16, svs::float16::Float16, AVX>;
 
+/// Instantiate Inner Product implementations (use in .cpp files)
 #define DISTANCE_IP_INSTANTIATE_TEMPLATE(N, AVX) \
     DISTANCE_IP_TEMPLATE_HELPER(template, N, AVX);
 
+/// Declare external Inner Product implementations (use in .h files)
 #define DISTANCE_IP_EXTERN_TEMPLATE(N, AVX) \
     DISTANCE_IP_TEMPLATE_HELPER(extern template, N, AVX);
 
+/// Helper macro for Cosine Similarity explicit instantiation
+/// @param SPEC Either `template` (for definitions) or `extern template` (for declarations)
+/// @param N Dimensionality (e.g., 64, 128, Dynamic)
+/// @param AVX AVX availability level (AVX_AVAILABILITY::AVX512 or AVX_AVAILABILITY::AVX2)
 #define DISTANCE_CS_TEMPLATE_HELPER(SPEC, N, AVX)                             \
     SPEC struct CosineSimilarityImpl<N, float, float, AVX>;                   \
     SPEC struct CosineSimilarityImpl<N, float, int8_t, AVX>;                  \
@@ -82,8 +131,10 @@
     SPEC struct CosineSimilarityImpl<N, svs::float16::Float16, uint8_t, AVX>; \
     SPEC struct CosineSimilarityImpl<N, svs::float16::Float16, svs::float16::Float16, AVX>;
 
+/// Instantiate Cosine Similarity implementations (use in .cpp files)
 #define DISTANCE_CS_INSTANTIATE_TEMPLATE(N, AVX) \
     DISTANCE_CS_TEMPLATE_HELPER(template, N, AVX);
 
+/// Declare external Cosine Similarity implementations (use in .h files)
 #define DISTANCE_CS_EXTERN_TEMPLATE(N, AVX) \
     DISTANCE_CS_TEMPLATE_HELPER(extern template, N, AVX);