Skip to main content

qualia_core_db/specialized_libs/linear_algebra/
computation.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3
4use super::core_types::*;
5use super::optimization::*;
6use super::privacy::*;
7
8/// Computation engine for matrix operations
9pub struct ComputationEngine {
10    pub operation_queue: Vec<MatrixOperation>,
11    pub execution_engine: ExecutionEngine,
12    pub parallel_executor: ParallelExecutor,
13    pub simd_optimizer: SIMDOptimizer,
14    pub privacy: PrivacyEngine,
15}
16
17/// Matrix operations
18#[derive(Debug, Clone)]
19pub enum MatrixOperation {
20    MatrixMultiply {
21        left: String,
22        right: String,
23        result: String,
24        alpha: f64,
25        beta: f64,
26    },
27    MatrixAdd {
28        left: String,
29        right: String,
30        result: String,
31        alpha: f64,
32    },
33    MatrixSubtract {
34        left: String,
35        right: String,
36        result: String,
37    },
38    MatrixTranspose {
39        input: String,
40        result: String,
41    },
42    MatrixInverse {
43        input: String,
44        result: String,
45    },
46    MatrixDecomposition {
47        input: String,
48        result: String,
49        decomposition_type: DecompositionType,
50    },
51    EigenvalueComputation {
52        input: String,
53        eigenvalues: String,
54        eigenvectors: String,
55    },
56    SolveLinearSystem {
57        matrix: String,
58        rhs: String,
59        solution: String,
60    },
61}
62
63/// Decomposition types
64#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
65pub enum DecompositionType {
66    LU,
67    QR,
68    SVD,
69    Cholesky,
70    Eigen,
71    Schur,
72}
73
74/// Operation scheduler
75pub struct OperationScheduler {}
76
77/// Execution engine
78pub struct ExecutionEngine {
79    pub engine_type: ExecutionEngineType,
80    pub computation_units: Vec<ComputationUnit>,
81    pub scheduler: OperationScheduler,
82}
83
84/// Execution engine types
85#[derive(Debug, Clone, PartialEq)]
86pub enum ExecutionEngineType {
87    CPU,
88    GPU,
89    CSD,
90    Hybrid,
91}
92
93/// Computation unit
94#[derive(Debug, Clone)]
95pub struct ComputationUnit {
96    pub unit_id: String,
97    pub unit_type: ComputationUnitType,
98    pub capabilities: ComputationCapabilities,
99    pub current_load: f64,
100    pub performance_metrics: PerformanceMetrics,
101}
102
103/// Computation unit types
104#[derive(Debug, Clone, PartialEq)]
105pub enum ComputationUnitType {
106    CPU,
107    GPU,
108    CSD,
109    NPU,
110    TPU,
111}
112
113/// Computation capabilities
114#[derive(Debug, Clone)]
115pub struct ComputationCapabilities {
116    pub max_matrix_size: (usize, usize),
117    pub supported_operations: Vec<MatrixOperation>,
118    pub data_types: Vec<DataType>,
119    pub memory_bandwidth: f64,
120    pub compute_throughput: f64,
121}
122
123/// Performance metrics
124#[derive(Debug, Clone)]
125pub struct PerformanceMetrics {
126    pub operations_per_second: f64,
127    pub memory_bandwidth_utilization: f64,
128    pub compute_utilization: f64,
129    pub power_consumption: f64,
130    pub thermal_state: f64,
131}
132
133/// Parallel executor
134pub struct ParallelExecutor {
135    pub thread_pool: Vec<WorkerThread>,
136    pub task_queue: Vec<MatrixTask>,
137    pub load_balancer: LoadBalancer,
138}
139
140/// Worker thread
141#[derive(Debug, Clone)]
142pub struct WorkerThread {
143    pub thread_id: String,
144    pub current_task: Option<MatrixTask>,
145    pub performance: ThreadPerformance,
146}
147
148/// Matrix task
149#[derive(Debug, Clone)]
150pub struct MatrixTask {
151    pub task_id: String,
152    pub operation: MatrixOperation,
153    pub priority: TaskPriority,
154    pub dependencies: Vec<String>,
155    pub estimated_time: u64,
156}
157
158/// Task priorities
159#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
160pub enum TaskPriority {
161    Low,
162    Normal,
163    High,
164    Critical,
165}
166
167/// A unit of parallelisable work submitted to [`ParallelExecutor::execute_parallel`].
168///
169/// This is the logical-task abstraction used by the parallel executor; it is
170/// distinct from [`MatrixTask`] (which carries a concrete [`MatrixOperation`]).
171/// A `ParallelTask` describes *what* to run, not *where* — the load balancer
172/// decides the worker assignment.
173#[derive(Debug, Clone)]
174pub struct ParallelTask {
175    /// Stable, caller-supplied task identifier.
176    pub task_id: usize,
177    /// The kind of operation this task represents.
178    pub operation: ParallelOperation,
179    /// Estimated work units (e.g. microseconds). Used for accounting only;
180    /// no real scheduling decision currently depends on it.
181    pub estimated_work: u64,
182    /// Relative priority of the task.
183    pub priority: TaskPriority,
184}
185
186/// The operation a [`ParallelTask`] performs. Mirrors the subset of
187/// [`MatrixOperation`] variants that are meaningful to dispatch in parallel,
188/// plus a `Custom` escape hatch.
189#[derive(Debug, Clone, PartialEq)]
190pub enum ParallelOperation {
191    MatrixMultiply,
192    MatrixAdd,
193    MatrixSubtract,
194    MatrixTranspose,
195    MatrixInverse,
196    Decomposition(DecompositionType),
197    EigenvalueComputation,
198    SolveLinearSystem,
199    Custom(String),
200}
201
202/// Status of a completed (or failed) parallel task.
203#[derive(Debug, Clone, PartialEq)]
204pub enum TaskStatus {
205    /// The task ran to completion.
206    Completed,
207    /// The task failed; the string carries a diagnostic.
208    Failed(String),
209    /// The task is still pending (not yet dispatched).
210    Pending,
211}
212
213/// The result of executing a [`ParallelTask`] via [`ParallelExecutor`].
214#[derive(Debug, Clone)]
215pub struct TaskResult {
216    /// Identifier of the task this result corresponds to.
217    pub task_id: usize,
218    /// Index of the logical worker the task was assigned to.
219    pub worker_index: usize,
220    /// Final status of the task.
221    pub status: TaskStatus,
222    /// Recorded execution time (currently the task's estimated work).
223    pub execution_time: u64,
224}
225
226/// Thread performance
227#[derive(Debug, Clone)]
228pub struct ThreadPerformance {
229    pub tasks_completed: u64,
230    pub average_execution_time: f64,
231    pub cache_hit_rate: f64,
232    pub efficiency: f64,
233}
234
235/// Load balancer
236///
237/// Distributes tasks across a fixed pool of logical workers according to a
238/// [`LoadBalancingStrategy`]. This is purely logical scheduling — no real
239/// threads are spawned (actual parallelism is a Phase 2 concern).
240#[derive(Debug, Clone)]
241pub struct LoadBalancer {
242    pub balancing_strategy: BalancingStrategy,
243    pub worker_metrics: HashMap<String, WorkerMetrics>,
244    /// Strategy used by [`LoadBalancer::assign_task`] to schedule tasks.
245    pub scheduling_strategy: LoadBalancingStrategy,
246    /// Number of logical workers to distribute tasks across.
247    pub num_workers: usize,
248    /// Total number of tasks in the current batch (used by `Static` partitioning).
249    pub total_tasks: usize,
250    /// Round-robin cursor: index of the next worker to assign (used by `RoundRobin`).
251    pub next_worker: usize,
252    /// Pending task count per worker (used by `WorkStealing`).
253    pub pending_tasks: Vec<usize>,
254}
255
256/// Balancing strategies
257#[derive(Debug, Clone, PartialEq)]
258pub enum BalancingStrategy {
259    RoundRobin,
260    LoadBased,
261    PerformanceBased,
262    Adaptive,
263}
264
265/// Load-balancing strategy for distributing parallel tasks across workers.
266///
267/// This is a logical scheduling policy — no real threads are spawned.
268#[derive(Debug, Clone, PartialEq)]
269pub enum LoadBalancingStrategy {
270    /// Cycle through workers in fixed order (task i → worker i mod N).
271    RoundRobin,
272    /// Assign each task to the worker with the fewest pending tasks (a simple
273    /// work-stealing approximation).
274    WorkStealing,
275    /// Pre-compute an equal contiguous partition of tasks across workers.
276    Static,
277}
278
279/// Worker metrics
280#[derive(Debug, Clone)]
281pub struct WorkerMetrics {
282    pub worker_id: String,
283    pub current_load: f64,
284    pub average_response_time: f64,
285    pub success_rate: f64,
286}
287
288/// SIMD optimizer
289pub struct SIMDOptimizer {
290    pub simd_capabilities: SIMDCapabilities,
291    pub optimization_level: OptimizationLevel,
292    pub vectorized_operations: HashMap<String, VectorizedOperation>,
293}
294
295/// SIMD capabilities
296#[derive(Debug, Clone)]
297pub struct SIMDCapabilities {
298    pub vector_width: usize,
299    pub supported_instructions: Vec<SIMDInstruction>,
300    pub alignment_requirements: usize,
301}
302
303/// SIMD instructions
304#[derive(Debug, Clone, PartialEq)]
305pub enum SIMDInstruction {
306    SSE,
307    SSE2,
308    SSE4_1,
309    SSE4_2,
310    AVX,
311    AVX2,
312    AVX512,
313    FMA,
314    NEON,
315    Custom(String),
316}
317
318/// Optimization levels
319#[derive(Debug, Clone, PartialEq)]
320pub enum OptimizationLevel {
321    None,
322    Basic,
323    Aggressive,
324    Maximum,
325}
326
327/// Vectorized operation
328#[derive(Debug, Clone)]
329pub struct VectorizedOperation {
330    pub operation_id: String,
331    pub vector_width: usize,
332    pub instruction_set: Vec<SIMDInstruction>,
333    pub performance_gain: f64,
334}
335
336impl ComputationEngine {
337    /// Creates a computation engine with default execution/SIMD/scheduler components.
338    pub fn new() -> Self {
339        Self {
340            operation_queue: Vec::new(),
341            execution_engine: ExecutionEngine::new(),
342            parallel_executor: ParallelExecutor::new(4),
343            simd_optimizer: SIMDOptimizer::new(),
344            privacy: PrivacyEngine::new(),
345        }
346    }
347
348    /// Initializes execution engine and scheduler; `LinearAlgebraError` propagates.
349    pub fn initialize(&mut self) -> Result<(), LinearAlgebraError> {
350        self.execution_engine.initialize()?;
351        self.parallel_executor.initialize()?;
352        self.simd_optimizer.initialize()?;
353        self.privacy.initialize()?;
354        Ok(())
355    }
356
357    /// Runs `alpha·A·B + beta·C` via the canonical dynamic GEMM — freshly allocated `result`, `beta` applies to `C` not the product.
358    pub fn execute_multiplication(
359        &mut self,
360        operation: &OptimizedMultiplication,
361        alpha: f64,
362        beta: f64,
363    ) -> Result<Vec<f64>, LinearAlgebraError> {
364        // Composition boundary: marshal the domain matrices into a caller-owned
365        // buffer and call the engine's canonical dynamic GEMM. No inline math here.
366        let m = operation.left.rows;
367        let n = operation.right.cols;
368        let k = operation.left.cols;
369
370        // C := alpha·A·B + beta·C, row-major. `result` is freshly zeroed, so it is
371        // the accumulator C; beta·0 = 0 (this entry point always produces a fresh
372        // product — there is no prior C to accumulate into). Routing here also fixes
373        // the old inline loop, which applied beta to the just-computed product
374        // (yielding alpha·AB·(1+beta) instead of the BLAS alpha·AB + beta·C).
375        let mut result = vec![0.0; m * n];
376        crate::solvers::linear_algebra::gemm::gemm(
377            crate::solvers::linear_algebra::gemm::Transpose::No,
378            crate::solvers::linear_algebra::gemm::Transpose::No,
379            m,
380            n,
381            k,
382            alpha,
383            &operation.left.data,
384            &operation.right.data,
385            beta,
386            &mut result,
387        )
388        .map_err(|_| {
389            LinearAlgebraError::InvalidDimensions(
390                "matrix dimensions incompatible for multiplication".to_string(),
391            )
392        })?;
393
394        Ok(result)
395    }
396}
397
398impl ExecutionEngine {
399    /// Creates a hybrid execution engine.
400    pub fn new() -> Self {
401        Self {
402            engine_type: ExecutionEngineType::Hybrid,
403            computation_units: Vec::new(),
404            scheduler: OperationScheduler::new(),
405        }
406    }
407
408    /// No-op returning `Ok(())`.
409    pub fn initialize(&mut self) -> Result<(), LinearAlgebraError> {
410        // Initialize computation units
411        Ok(())
412    }
413}
414
415impl ParallelExecutor {
416    /// Create a parallel executor with `num_workers` logical workers.
417    ///
418    /// The default load-balancing strategy is [`LoadBalancingStrategy::RoundRobin`].
419    /// No OS threads are spawned — workers are logical slots the load balancer
420    /// assigns tasks to. `num_workers == 0` is clamped to 1 so that task
421    /// assignment always has a valid target.
422    pub fn new(num_workers: usize) -> Self {
423        let workers = num_workers.max(1);
424        let thread_pool = (0..workers)
425            .map(|i| WorkerThread {
426                thread_id: format!("worker-{i}"),
427                current_task: None,
428                performance: ThreadPerformance {
429                    tasks_completed: 0,
430                    average_execution_time: 0.0,
431                    cache_hit_rate: 0.0,
432                    efficiency: 1.0,
433                },
434            })
435            .collect();
436        Self {
437            thread_pool,
438            task_queue: Vec::new(),
439            load_balancer: LoadBalancer::new(LoadBalancingStrategy::RoundRobin)
440                .with_workers(workers),
441        }
442    }
443
444    /// Returns the number of logical workers in the pool.
445    pub fn num_workers(&self) -> usize {
446        self.thread_pool.len()
447    }
448
449    /// `ParallelExecutor::initialize`.
450    pub fn initialize(&mut self) -> Result<(), LinearAlgebraError> {
451        Ok(())
452    }
453
454    /// Distribute `tasks` across the worker pool using the load balancer and
455    /// collect the results.
456    ///
457    /// Tasks are dispatched in input order and results are returned in the same
458    /// order (one [`TaskResult`] per input task). Execution is logical: each
459    /// task is marked [`TaskStatus::Completed`] with its estimated work recorded
460    /// as the execution time. No real threads are spawned.
461    ///
462    /// An empty task list yields an empty result list (no error).
463    pub fn execute_parallel(
464        &self,
465        tasks: &[ParallelTask],
466    ) -> Result<Vec<TaskResult>, LinearAlgebraError> {
467        if tasks.is_empty() {
468            return Ok(Vec::new());
469        }
470
471        // Clone the balancer so a shared `&self` executor does not mutate its
472        // own scheduling state across calls. Each batch starts from a clean slate.
473        let mut balancer = self.load_balancer.clone();
474        balancer.prepare(tasks.len());
475
476        let mut results = Vec::with_capacity(tasks.len());
477        for task in tasks {
478            let worker_index = balancer.assign_task(task.task_id);
479            results.push(TaskResult {
480                task_id: task.task_id,
481                worker_index,
482                status: TaskStatus::Completed,
483                execution_time: task.estimated_work,
484            });
485        }
486
487        Ok(results)
488    }
489}
490
491impl LoadBalancer {
492    /// Create a load balancer that uses `strategy` to assign tasks.
493    ///
494    /// The balancer starts with zero workers; call [`LoadBalancer::with_workers`]
495    /// (or set [`LoadBalancer::num_workers`] directly) before invoking
496    /// [`LoadBalancer::assign_task`].
497    pub fn new(strategy: LoadBalancingStrategy) -> Self {
498        Self {
499            balancing_strategy: BalancingStrategy::LoadBased,
500            worker_metrics: HashMap::new(),
501            scheduling_strategy: strategy,
502            num_workers: 0,
503            total_tasks: 0,
504            next_worker: 0,
505            pending_tasks: Vec::new(),
506        }
507    }
508
509    /// Builder-style setter for the worker count. Resizes the per-worker pending
510    /// task vector to match and resets scheduling cursors.
511    pub fn with_workers(mut self, num_workers: usize) -> Self {
512        self.set_workers(num_workers);
513        self
514    }
515
516    /// Set the worker count, resizing the per-worker pending task vector and
517    /// resetting scheduling cursors.
518    pub fn set_workers(&mut self, num_workers: usize) {
519        self.num_workers = num_workers;
520        self.pending_tasks = vec![0; num_workers];
521        self.next_worker = 0;
522    }
523
524    /// Prepare the balancer for a fresh batch of `total_tasks` tasks.
525    ///
526    /// Resets the round-robin cursor and per-worker pending counts, and records
527    /// the batch size used by [`LoadBalancingStrategy::Static`] partitioning.
528    /// [`ParallelExecutor::execute_parallel`] calls this before assigning tasks;
529    /// callers using [`LoadBalancer::assign_task`] directly should call it first
530    /// (notably for `Static`).
531    pub fn prepare(&mut self, total_tasks: usize) {
532        self.total_tasks = total_tasks;
533        self.next_worker = 0;
534        if self.pending_tasks.len() != self.num_workers {
535            self.pending_tasks = vec![0; self.num_workers];
536        } else {
537            for count in self.pending_tasks.iter_mut() {
538                *count = 0;
539            }
540        }
541    }
542
543    /// Return the worker index to assign the next task to.
544    ///
545    /// - [`LoadBalancingStrategy::RoundRobin`]: cycles through workers
546    ///   `0,1,…,N-1,0,1,…` regardless of `task_id`.
547    /// - [`LoadBalancingStrategy::WorkStealing`]: assigns to the worker with the
548    ///   fewest pending tasks (ties broken by lowest index) and increments that
549    ///   worker's pending count.
550    /// - [`LoadBalancingStrategy::Static`]: contiguous equal partition —
551    ///   `worker = task_id * num_workers / total_tasks` (falls back to
552    ///   `task_id % num_workers` when `total_tasks` is unset).
553    ///
554    /// Returns `0` when the balancer has no workers configured.
555    pub fn assign_task(&mut self, task_id: usize) -> usize {
556        if self.num_workers == 0 {
557            return 0;
558        }
559        match self.scheduling_strategy {
560            LoadBalancingStrategy::RoundRobin => {
561                let worker = self.next_worker % self.num_workers;
562                self.next_worker = (self.next_worker + 1) % self.num_workers;
563                worker
564            }
565            LoadBalancingStrategy::WorkStealing => {
566                let worker = (0..self.num_workers)
567                    .min_by_key(|&w| (self.pending_tasks[w], w))
568                    .expect("num_workers > 0");
569                self.pending_tasks[worker] += 1;
570                worker
571            }
572            LoadBalancingStrategy::Static => {
573                if self.total_tasks == 0 {
574                    task_id % self.num_workers
575                } else {
576                    (task_id * self.num_workers) / self.total_tasks
577                }
578            }
579        }
580    }
581}
582
583impl SIMDOptimizer {
584    /// Creates a SIMD optimizer.
585    pub fn new() -> Self {
586        Self {
587            simd_capabilities: SIMDCapabilities::new(),
588            optimization_level: OptimizationLevel::Maximum,
589            vectorized_operations: HashMap::new(),
590        }
591    }
592
593    /// Probe the running CPU and populate the SIMD capability set.
594    ///
595    /// On `x86_64` this queries SSE2, SSE4.1, SSE4.2, AVX, AVX2, AVX-512 and
596    /// FMA via `std::arch::is_x86_feature_detected!` (CPUID at runtime). On
597    /// `aarch64` it reports NEON. On any other architecture the capability set
598    /// is left empty (scalar fallback).
599    pub fn initialize(&mut self) -> Result<(), LinearAlgebraError> {
600        self.simd_capabilities = SIMDCapabilities::detect();
601        Ok(())
602    }
603
604    /// Returns a reference to the runtime-detected SIMD capabilities.
605    pub fn capabilities(&self) -> &SIMDCapabilities {
606        &self.simd_capabilities
607    }
608
609    /// Checks whether a specific SIMD instruction set is available on the
610    /// current CPU. Returns `true` when the given instruction was detected
611    /// during `initialize()` (or `SIMDCapabilities::detect()`).
612    pub fn has_feature(&self, instruction: &SIMDInstruction) -> bool {
613        self.simd_capabilities
614            .supported_instructions
615            .iter()
616            .any(|i| i == instruction)
617    }
618}
619
620impl SIMDCapabilities {
621    /// Creates default (detected) SIMD capabilities.
622    pub fn new() -> Self {
623        Self::detect()
624    }
625
626    /// Probe the running CPU for available SIMD instruction sets at runtime.
627    ///
628    /// The widest detected vector width and its natural alignment are recorded.
629    /// On `x86_64` detection uses `std::arch::is_x86_feature_detected!` (CPUID);
630    /// on `aarch64` it uses `std::arch::is_aarch64_feature_detected!`. On any
631    /// other architecture no SIMD instructions are reported and a scalar
632    /// (width 1, alignment 1) configuration is returned.
633    pub fn detect() -> Self {
634        #[allow(unused_mut)]
635        let mut instructions: Vec<SIMDInstruction> = Vec::new();
636        let mut vector_width = 0usize;
637        let mut alignment = 1usize;
638
639        #[cfg(target_arch = "x86_64")]
640        {
641            // SSE2 is mandatory in the x86_64 baseline, but probe anyway for
642            // uniformity with the rest of the feature set.
643            if is_x86_feature_detected!("sse2") {
644                instructions.push(SIMDInstruction::SSE2);
645                if vector_width < 128 {
646                    vector_width = 128;
647                    alignment = 16;
648                }
649            }
650            if is_x86_feature_detected!("sse4.1") {
651                instructions.push(SIMDInstruction::SSE4_1);
652            }
653            if is_x86_feature_detected!("sse4.2") {
654                instructions.push(SIMDInstruction::SSE4_2);
655            }
656            if is_x86_feature_detected!("avx") {
657                instructions.push(SIMDInstruction::AVX);
658                if vector_width < 256 {
659                    vector_width = 256;
660                    alignment = 32;
661                }
662            }
663            if is_x86_feature_detected!("avx2") {
664                instructions.push(SIMDInstruction::AVX2);
665            }
666            // AVX-512 Foundation; wider 512-bit registers require 64-byte alignment.
667            if is_x86_feature_detected!("avx512f") {
668                instructions.push(SIMDInstruction::AVX512);
669                if vector_width < 512 {
670                    vector_width = 512;
671                    alignment = 64;
672                }
673            }
674            if is_x86_feature_detected!("fma") {
675                instructions.push(SIMDInstruction::FMA);
676            }
677        }
678
679        #[cfg(target_arch = "aarch64")]
680        {
681            // NEON is mandatory in the ARMv8 baseline; confirm via the runtime
682            // probe for consistency with the x86_64 path.
683            if std::arch::is_aarch64_feature_detected!("neon") {
684                instructions.push(SIMDInstruction::NEON);
685                if vector_width < 128 {
686                    vector_width = 128;
687                    alignment = 16;
688                }
689            }
690        }
691
692        // Scalar fallback for architectures without a recognised SIMD baseline.
693        if vector_width == 0 {
694            vector_width = 1;
695            alignment = 1;
696        }
697
698        Self {
699            vector_width,
700            supported_instructions: instructions,
701            alignment_requirements: alignment,
702        }
703    }
704}
705
706impl OperationScheduler {
707    /// Creates an operation scheduler.
708    pub fn new() -> Self {
709        Self {}
710    }
711}
712
713// Supporting types
714
715#[derive(Debug, Clone)]
716pub struct OptimizedMultiplication {
717    pub left: Matrix,
718    pub right: Matrix,
719    pub optimization_strategy: OptimizationStrategy,
720    pub expected_performance_gain: f64,
721}
722
723#[cfg(test)]
724mod tests {
725    use super::*;
726
727    #[test]
728    fn test_simd_detection() {
729        let mut optimizer = SIMDOptimizer::new();
730        optimizer.initialize().expect("initialize should succeed");
731
732        #[cfg(target_arch = "x86_64")]
733        {
734            // SSE2 is mandatory in the x86_64 baseline, so it must always be
735            // detected at runtime.
736            assert!(
737                optimizer.has_feature(&SIMDInstruction::SSE2),
738                "SSE2 should be detected on x86_64"
739            );
740        }
741
742        #[cfg(target_arch = "aarch64")]
743        {
744            assert!(
745                optimizer.has_feature(&SIMDInstruction::NEON),
746                "NEON should be detected on aarch64"
747            );
748        }
749
750        // On architectures without a recognised SIMD baseline we simply verify
751        // that detection completed without panicking; an empty capability set
752        // is a valid "no SIMD" result.
753        #[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
754        {
755            let _ = optimizer.capabilities();
756        }
757    }
758
759    #[test]
760    fn test_simd_capabilities_report() {
761        let mut optimizer = SIMDOptimizer::new();
762        optimizer.initialize().expect("initialize should succeed");
763
764        let caps = optimizer.capabilities();
765        assert!(caps.vector_width >= 1, "vector width should be at least 1");
766        assert!(
767            caps.alignment_requirements >= 1,
768            "alignment requirements should be at least 1"
769        );
770
771        #[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
772        {
773            assert!(
774                !caps.supported_instructions.is_empty(),
775                "at least one SIMD instruction should be detected on x86_64/aarch64"
776            );
777        }
778    }
779
780    #[test]
781    fn test_simd_feature_check() {
782        let mut optimizer = SIMDOptimizer::new();
783        optimizer.initialize().expect("initialize should succeed");
784
785        // A known feature detected on this CPU must report as available.
786        #[cfg(target_arch = "x86_64")]
787        {
788            assert!(
789                optimizer.has_feature(&SIMDInstruction::SSE2),
790                "has_feature should report SSE2 as available on x86_64"
791            );
792        }
793
794        #[cfg(target_arch = "aarch64")]
795        {
796            assert!(
797                optimizer.has_feature(&SIMDInstruction::NEON),
798                "has_feature should report NEON as available on aarch64"
799            );
800        }
801
802        // An instruction that was never probed must report as unavailable.
803        assert!(
804            !optimizer.has_feature(&SIMDInstruction::Custom("nonexistent".to_string())),
805            "has_feature should report a non-probed custom instruction as unavailable"
806        );
807    }
808
809    #[test]
810    fn test_round_robin_assignment() {
811        let mut lb = LoadBalancer::new(LoadBalancingStrategy::RoundRobin).with_workers(2);
812        let assignments: Vec<usize> = (0..4).map(|i| lb.assign_task(i)).collect();
813        assert_eq!(
814            assignments,
815            vec![0, 1, 0, 1],
816            "round-robin over 2 workers should cycle 0,1,0,1"
817        );
818    }
819
820    #[test]
821    fn test_static_partition() {
822        let mut lb = LoadBalancer::new(LoadBalancingStrategy::Static).with_workers(3);
823        lb.prepare(6);
824        let assignments: Vec<usize> = (0..6).map(|i| lb.assign_task(i)).collect();
825
826        // Each of the 3 workers should receive exactly 2 tasks.
827        let mut counts = vec![0usize; 3];
828        for &w in &assignments {
829            counts[w] += 1;
830        }
831        assert_eq!(counts, vec![2, 2, 2], "static partition should be balanced");
832
833        // Contiguous blocks: tasks 0,1 → worker 0; 2,3 → worker 1; 4,5 → worker 2.
834        assert_eq!(
835            assignments,
836            vec![0, 0, 1, 1, 2, 2],
837            "static partition should assign contiguous blocks"
838        );
839    }
840
841    #[test]
842    fn test_work_stealing() {
843        let mut lb = LoadBalancer::new(LoadBalancingStrategy::WorkStealing).with_workers(3);
844
845        // First task: all workers have 0 pending; tie broken by lowest index → 0.
846        assert_eq!(lb.assign_task(0), 0);
847        // Worker 0 now has 1 pending; workers 1 and 2 have 0 → assign to 1.
848        assert_eq!(lb.assign_task(1), 1);
849        // Workers 0,1 have 1; worker 2 has 0 → assign to 2.
850        assert_eq!(lb.assign_task(2), 2);
851        // All have 1 pending; tie broken by lowest index → 0.
852        assert_eq!(lb.assign_task(3), 0);
853
854        // Verify the invariant directly: the next task must go to a worker with
855        // the minimum pending count.
856        let min_pending = *lb.pending_tasks.iter().min().unwrap();
857        let next = lb.assign_task(4);
858        assert_eq!(
859            lb.pending_tasks[next],
860            min_pending + 1,
861            "work-stealing should assign to the worker with the fewest pending tasks"
862        );
863    }
864
865    #[test]
866    fn test_parallel_execution_collects_results() {
867        let executor = ParallelExecutor::new(2);
868        let tasks: Vec<ParallelTask> = (0..3)
869            .map(|i| ParallelTask {
870                task_id: i,
871                operation: ParallelOperation::MatrixMultiply,
872                estimated_work: 10 + i as u64,
873                priority: TaskPriority::Normal,
874            })
875            .collect();
876
877        let results = executor
878            .execute_parallel(&tasks)
879            .expect("execution should succeed");
880
881        assert_eq!(
882            results.len(),
883            3,
884            "execute_parallel should return one result per task"
885        );
886        // Results are returned in input order with matching task ids.
887        assert_eq!(
888            results.iter().map(|r| r.task_id).collect::<Vec<_>>(),
889            vec![0, 1, 2],
890            "results should preserve input order"
891        );
892        // Every task should be marked completed.
893        assert!(
894            results.iter().all(|r| r.status == TaskStatus::Completed),
895            "all tasks should complete"
896        );
897        // Every result should be assigned to a valid worker index.
898        assert!(
899            results
900                .iter()
901                .all(|r| r.worker_index < executor.num_workers()),
902            "worker indices must be within the pool"
903        );
904    }
905
906    #[test]
907    fn test_empty_tasks() {
908        let executor = ParallelExecutor::new(4);
909        let results = executor
910            .execute_parallel(&[])
911            .expect("empty execution should succeed");
912        assert!(
913            results.is_empty(),
914            "empty task list should yield no results"
915        );
916    }
917}