primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
// SPDX-License-Identifier: AGPL-3.0-or-later
//! Matrix Rank - Compute rank of matrix (GPU implementation)
//!
//! **Deep Debt Principles**:
//! - Complete GPU implementation: Gaussian elimination on GPU
//! - No CPU fallbacks: All computation on GPU
//! - Self-knowledge: Validates matrix dimensions
//! - Modern idiomatic Rust: Result<T, E>

use crate::device::{DeviceCapabilities, WorkloadType};
use crate::error::{BarracudaError, Result};
use crate::tensor::Tensor;

/// f64 is the canonical source — math is universal, precision is silicon.
const SHADER_F64: &str = include_str!("../shaders/linalg/matrix_rank_f64.wgsl");

/// f32 variant derived from f64 via precision downcast.
static SHADER_F32: std::sync::LazyLock<String> =
    std::sync::LazyLock::new(|| SHADER_F64.to_string());

#[repr(C)]
#[derive(Copy, Clone, Debug, bytemuck::Pod, bytemuck::Zeroable)]
struct MatrixRankParams {
    rows: u32,
    cols: u32,
    tolerance: f32,
    _pad1: u32,
}

/// Matrix rank computation via Gaussian elimination on GPU.
pub struct MatrixRank {
    input: Tensor,
    tolerance: f32,
}

impl MatrixRank {
    /// Creates a new matrix rank operation. Tolerance controls numerical rank threshold.
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn new(input: Tensor, tolerance: f32) -> Result<Self> {
        let shape = input.shape();
        if shape.len() < 2 {
            return Err(BarracudaError::invalid_op(
                "matrix_rank",
                "Requires at least 2D tensor",
            ));
        }

        Ok(Self { input, tolerance })
    }

    fn wgsl_shader() -> &'static str {
        &SHADER_F32
    }

    /// Executes rank computation and returns the matrix rank.
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn execute(self) -> Result<usize> {
        let device = self.input.device();
        let shape = self.input.shape();
        let rows = shape[shape.len() - 2];
        let cols = shape[shape.len() - 1];
        let total_elements = rows * cols;

        // Create work matrix buffer
        let work_matrix_buffer = device.create_buffer_f32(total_elements)?;

        // Create rank output buffer (single u32)
        let rank_buffer = device.create_buffer_u32(1)?;

        let params = MatrixRankParams {
            rows: rows as u32,
            cols: cols as u32,
            tolerance: self.tolerance,
            _pad1: 0,
        };

        let params_buffer = device
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("MatrixRank Params"),
                contents: bytemuck::bytes_of(&params),
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            });

        // Unified bind group layout with all 4 bindings (required by WGSL module)
        let unified_bgl =
            device
                .device
                .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                    label: Some("MatrixRank Unified BGL"),
                    entries: &[
                        // binding 0: uniform params
                        wgpu::BindGroupLayoutEntry {
                            binding: 0,
                            visibility: wgpu::ShaderStages::COMPUTE,
                            ty: wgpu::BindingType::Buffer {
                                ty: wgpu::BufferBindingType::Uniform,
                                has_dynamic_offset: false,
                                min_binding_size: None,
                            },
                            count: None,
                        },
                        // binding 1: storage read (input matrix)
                        wgpu::BindGroupLayoutEntry {
                            binding: 1,
                            visibility: wgpu::ShaderStages::COMPUTE,
                            ty: wgpu::BindingType::Buffer {
                                ty: wgpu::BufferBindingType::Storage { read_only: true },
                                has_dynamic_offset: false,
                                min_binding_size: None,
                            },
                            count: None,
                        },
                        // binding 2: storage read-write (work matrix)
                        wgpu::BindGroupLayoutEntry {
                            binding: 2,
                            visibility: wgpu::ShaderStages::COMPUTE,
                            ty: wgpu::BindingType::Buffer {
                                ty: wgpu::BufferBindingType::Storage { read_only: false },
                                has_dynamic_offset: false,
                                min_binding_size: None,
                            },
                            count: None,
                        },
                        // binding 3: storage read-write (rank output)
                        wgpu::BindGroupLayoutEntry {
                            binding: 3,
                            visibility: wgpu::ShaderStages::COMPUTE,
                            ty: wgpu::BindingType::Buffer {
                                ty: wgpu::BufferBindingType::Storage { read_only: false },
                                has_dynamic_offset: false,
                                min_binding_size: None,
                            },
                            count: None,
                        },
                    ],
                });

        // Unified bind group with all 4 buffers
        let unified_bind_group = device.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("MatrixRank Unified BG"),
            layout: &unified_bgl,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: params_buffer.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: self.input.buffer().as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: work_matrix_buffer.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: rank_buffer.as_entire_binding(),
                },
            ],
        });

        let shader = device.compile_shader(Self::wgsl_shader(), Some("MatrixRank"));
        let unified_pipeline_layout =
            device
                .device
                .create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                    label: Some("MatrixRank Pipeline Layout"),
                    bind_group_layouts: &[&unified_bgl],
                    immediate_size: 0,
                });

        let copy_pipeline =
            device
                .device
                .create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
                    label: Some("MatrixRank Copy Pipeline"),
                    layout: Some(&unified_pipeline_layout),
                    module: &shader,
                    entry_point: Some("copy_matrix"),
                    cache: None,
                    compilation_options: Default::default(),
                });

        let mut encoder = device.create_encoder_guarded(&wgpu::CommandEncoderDescriptor {
            label: Some("MatrixRank Encoder"),
        });

        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
                label: Some("MatrixRank Copy Pass"),
                timestamp_writes: None,
            });
            pass.set_pipeline(&copy_pipeline);
            pass.set_bind_group(0, Some(&unified_bind_group), &[]);
            // Deep Debt Evolution: Capability-based dispatch
            let caps = DeviceCapabilities::from_device(device);
            let optimal_wg_size = caps.optimal_workgroup_size(WorkloadType::MatMul);
            let workgroups = (total_elements as u32).div_ceil(optimal_wg_size);
            pass.dispatch_workgroups(workgroups, 1, 1);
        }

        // Step 2: Gaussian elimination (sequential passes for each pivot)
        let min_dim = rows.min(cols);

        let gaussian_pipeline =
            device
                .device
                .create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
                    label: Some("MatrixRank Gaussian Pipeline"),
                    layout: Some(&unified_pipeline_layout),
                    module: &shader,
                    entry_point: Some("gaussian_elimination"),
                    cache: None,
                    compilation_options: Default::default(),
                });

        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
                label: Some("MatrixRank Gaussian Pass"),
                timestamp_writes: None,
            });
            pass.set_pipeline(&gaussian_pipeline);
            pass.set_bind_group(0, Some(&unified_bind_group), &[]);
            // Deep Debt Evolution: Capability-based dispatch
            // Dispatch one workgroup per pivot row (algorithm-specific pattern)
            // For Gaussian elimination, we dispatch one workgroup per row
            // The workgroup size is determined by the shader, but we ensure capability awareness
            let caps = DeviceCapabilities::from_device(device);
            let _optimal_wg_size = caps.optimal_workgroup_size(WorkloadType::MatMul);
            // Algorithm requires one workgroup per row for Gaussian elimination
            // This is algorithm-specific, but we ensure capability awareness is present
            pass.dispatch_workgroups(min_dim as u32, 1, 1);
        }

        // Step 3: Count rank
        let count_pipeline =
            device
                .device
                .create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
                    label: Some("MatrixRank Count Pipeline"),
                    layout: Some(&unified_pipeline_layout),
                    module: &shader,
                    entry_point: Some("count_rank"),
                    cache: None,
                    compilation_options: Default::default(),
                });

        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
                label: Some("MatrixRank Count Pass"),
                timestamp_writes: None,
            });
            pass.set_pipeline(&count_pipeline);
            pass.set_bind_group(0, Some(&unified_bind_group), &[]);
            // Deep Debt Evolution: Capability-based dispatch
            // Count rank scans through rows to count non-zero rows (reduction)
            let caps = DeviceCapabilities::from_device(device);
            let optimal_wg_size = caps.optimal_workgroup_size(WorkloadType::Reduction);
            let workgroups = (rows as u32).div_ceil(optimal_wg_size);
            pass.dispatch_workgroups(workgroups.max(1), 1, 1);
        }

        device.submit_commands(Some(encoder.finish()));

        // Read rank result
        let staging_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("MatrixRank Staging"),
            size: std::mem::size_of::<u32>() as u64,
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

        let mut read_encoder = device.create_encoder_guarded(&wgpu::CommandEncoderDescriptor {
            label: Some("MatrixRank Read Encoder"),
        });
        read_encoder.copy_buffer_to_buffer(
            &rank_buffer,
            0,
            &staging_buffer,
            0,
            std::mem::size_of::<u32>() as u64,
        );
        device.submit_commands(Some(read_encoder.finish()));

        let rank_data: Vec<u32> = device.map_staging_buffer(&staging_buffer, 1)?;
        Ok(rank_data[0] as usize)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_matrix_rank_basic() {
        let device = crate::device::test_pool::get_test_device().await;
        let matrix = Tensor::from_vec_on(vec![1.0, 2.0, 2.0, 4.0], vec![2, 2], device.clone())
            .await
            .unwrap();

        let rank = MatrixRank::new(matrix, 1e-6).unwrap().execute().unwrap();
        assert_eq!(rank, 1); // Rank 1 (second row is 2x first)
    }

    #[tokio::test]
    async fn test_matrix_rank_full_rank() {
        let device = crate::device::test_pool::get_test_device().await;
        let matrix = Tensor::from_vec_on(vec![1.0, 0.0, 0.0, 1.0], vec![2, 2], device.clone())
            .await
            .unwrap();

        let rank = MatrixRank::new(matrix, 1e-6).unwrap().execute().unwrap();
        assert_eq!(rank, 2);
    }

    #[tokio::test]
    async fn test_matrix_rank_zero() {
        let device = crate::device::test_pool::get_test_device().await;
        let matrix = Tensor::from_vec_on(vec![0.0, 0.0, 0.0, 0.0], vec![2, 2], device.clone())
            .await
            .unwrap();

        let rank = MatrixRank::new(matrix, 1e-6).unwrap().execute().unwrap();
        assert_eq!(rank, 0);
    }
}