velesdb-core 1.13.2

//! GPU-accelerated vector operations using wgpu (WebGPU).
//!
//! This module provides optional GPU acceleration for batch distance calculations.
//! Enable with feature flag `gpu`.
//!
//! # When to use GPU
//!
//! - **Batch operations** (100+ queries at once)
//! - **Large datasets** (500K+ vectors)
//! - **Index construction** (HNSW graph building)
//!
//! For single queries on datasets ≤100K, CPU SIMD remains faster.
//!
//! # Platform Support
//!
//! | Platform | Backend |
//! |----------|---------|
//! | Windows | DirectX 12 / Vulkan |
//! | macOS | Metal |
//! | Linux | Vulkan |
//! | Browser | WebGPU |

#[cfg(feature = "gpu")]
#[path = "gpu/helpers.rs"]
mod helpers;

#[cfg(feature = "gpu")]
#[path = "gpu/gpu_backend.rs"]
mod gpu_backend;

#[cfg(all(test, feature = "gpu"))]
#[path = "gpu/gpu_backend_tests.rs"]
mod gpu_backend_tests;

#[cfg(all(test, feature = "gpu"))]
#[path = "gpu/gpu_csr_tests.rs"]
mod gpu_csr_extended_tests;

#[cfg(feature = "gpu")]
#[path = "gpu/pq_gpu.rs"]
pub mod pq_gpu;

#[cfg(feature = "gpu")]
#[path = "gpu/gpu_csr.rs"]
pub mod gpu_csr;

#[cfg(feature = "gpu")]
#[path = "gpu/gpu_traversal_buffers.rs"]
mod gpu_traversal_buffers;

#[cfg(feature = "gpu")]
#[path = "gpu/gpu_traversal_pipelines.rs"]
mod gpu_traversal_pipelines;

#[cfg(feature = "gpu")]
#[path = "gpu/gpu_traversal.rs"]
pub mod gpu_traversal;

#[cfg(feature = "gpu")]
pub use gpu_backend::GpuAccelerator;
#[cfg(feature = "gpu")]
pub use gpu_traversal::{should_traverse_gpu, GpuTraversalContext, GpuTraversalStats};
#[cfg(feature = "gpu")]
pub use pq_gpu::{gpu_kmeans_assign, should_use_gpu, PqGpuContext};

/// Check if GPU dispatch is worthwhile (always false without gpu feature).
#[cfg(not(feature = "gpu"))]
#[must_use]
pub fn should_use_gpu(_n: usize, _k: usize, _subspace_dim: usize) -> bool {
    false
}

/// Check if GPU traversal is worthwhile (always false without gpu feature).
#[cfg(not(feature = "gpu"))]
#[must_use]
pub fn should_traverse_gpu(_num_vectors: usize, _dimension: usize) -> bool {
    false
}

/// Compute backend selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[allow(dead_code)] // Used only when `gpu` feature is active
pub(crate) enum ComputeBackend {
    /// CPU SIMD (default, always available)
    #[default]
    Simd,
    /// GPU via wgpu (requires `gpu` feature)
    #[cfg(feature = "gpu")]
    Gpu,
}

#[allow(dead_code)] // Used only when `gpu` feature is active
impl ComputeBackend {
    /// Returns the best available backend.
    ///
    /// Prefers GPU if available, falls back to SIMD.
    #[must_use]
    pub fn best_available() -> Self {
        #[cfg(feature = "gpu")]
        {
            if gpu_backend::GpuAccelerator::is_available() {
                return Self::Gpu;
            }
        }
        Self::Simd
    }

    /// Returns true if GPU backend is available.
    #[must_use]
    pub fn gpu_available() -> bool {
        #[cfg(feature = "gpu")]
        {
            gpu_backend::GpuAccelerator::is_available()
        }
        #[cfg(not(feature = "gpu"))]
        {
            false
        }
    }
}