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
//! GPU compute operations for Local Attention
//!
//! This module contains the 3-pass GPU execution:
//! 1. Pass 1: Compute QK^T scores (matmul)
//! 2. Pass 2: Apply softmax with local window mask
//! 3. Pass 3: Apply weights to values

use super::{LocalAttention, LocalAttentionParams};
use crate::device::compute_pipeline::ComputeDispatch;
use crate::device::{DeviceCapabilities, WorkloadType};
use crate::error::Result;
use crate::tensor::Tensor;

impl LocalAttention {
    /// Execute local attention (3 GPU passes)
    /// **Deep Debt**: Reuses 2/3 shaders from validated attention!
    /// # 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<Tensor> {
        let device = self.query().device();

        // Extract dimensions
        let shape = self.query().shape();
        let batch_size = shape[0];
        let num_heads = shape[1];
        let seq_len = shape[2];
        let head_dim = shape[3];

        // Create parameters
        let params = LocalAttentionParams {
            batch_size: batch_size as u32,
            num_heads: num_heads as u32,
            seq_len: seq_len as u32,
            head_dim: head_dim as u32,
            window_size: self.window_size() as u32,
            _padding: [0, 0, 0],
        };

        let params_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Local Attention Params"),
            size: std::mem::size_of::<LocalAttentionParams>() as u64,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        device
            .queue
            .write_buffer(&params_buffer, 0, bytemuck::bytes_of(&params));

        // Intermediate buffers
        let scores_size = batch_size * num_heads * seq_len * seq_len;
        let scores_buffer = device.create_buffer_f32(scores_size)?;
        let weights_buffer = device.create_buffer_f32(scores_size)?;

        // Output buffer
        let output_size = batch_size * num_heads * seq_len * head_dim;
        let output_buffer = device.create_buffer_f32(output_size)?;

        // Deep Debt Evolution: Capability-based dispatch
        let caps = DeviceCapabilities::from_device(device);

        // ═══════════════════════════════════════════════════════════
        // PASS 1: Compute QK^T scores (REUSED from attention ✅)
        // ═══════════════════════════════════════════════════════════
        let matmul_workgroups = ((batch_size * num_heads * seq_len * seq_len) as u32)
            .div_ceil(caps.optimal_workgroup_size(WorkloadType::MatMul));

        ComputeDispatch::new(device, "local_attn_matmul")
            .shader(Self::shader_matmul(), "main")
            .storage_read(0, self.query().buffer())
            .storage_read(1, self.key().buffer())
            .storage_rw(2, &scores_buffer)
            .uniform(3, &params_buffer)
            .dispatch(matmul_workgroups.max(1), 1, 1)
            .submit()?;

        // ═══════════════════════════════════════════════════════════
        // PASS 2: Apply softmax with local window mask (NEW shader!)
        // ═══════════════════════════════════════════════════════════
        let softmax_workgroups = ((batch_size * num_heads * seq_len) as u32)
            .div_ceil(caps.optimal_workgroup_size(WorkloadType::ElementWise));

        ComputeDispatch::new(device, "local_attn_softmax")
            .shader(Self::shader_local_softmax(), "main")
            .storage_read(0, &scores_buffer)
            .storage_rw(1, &weights_buffer)
            .uniform(2, &params_buffer)
            .dispatch(softmax_workgroups.max(1), 1, 1)
            .submit()?;

        // ═══════════════════════════════════════════════════════════
        // PASS 3: Apply weights to values (REUSED from attention ✅)
        // ═══════════════════════════════════════════════════════════
        let apply_workgroups = ((batch_size * num_heads * seq_len * head_dim) as u32)
            .div_ceil(caps.optimal_workgroup_size(WorkloadType::ElementWise));

        ComputeDispatch::new(device, "local_attn_apply")
            .shader(Self::shader_apply(), "main")
            .storage_read(0, &weights_buffer)
            .storage_read(1, self.value().buffer())
            .storage_rw(2, &output_buffer)
            .uniform(3, &params_buffer)
            .dispatch(apply_workgroups.max(1), 1, 1)
            .submit()?;

        // Return output tensor
        Ok(Tensor::from_buffer(
            output_buffer,
            vec![batch_size, num_heads, seq_len, head_dim],
            device.clone(),
        ))
    }
}