burn-msa 0.2.2

MiniMax Sparse Attention (MSA) - block-sparse attention with per-GQA-group top-k block selection for Burn
Documentation
use burn::tensor::backend::Backend;
use burn::tensor::{Int, Tensor};

/// GPU-sync-free top-K block selector. Now accepts 4D tensor directly.
#[derive(Debug)]
pub struct TopKSelector {
    pub topk: usize,
    pub block_size: usize,
    pub force_local_block: bool,
}

impl TopKSelector {
    pub fn new(topk: usize, block_size: usize, force_local_block: bool) -> Self {
        Self {
            topk,
            block_size,
            force_local_block,
        }
    }

    /// `block_scores`: [batch, n_heads_kv, seq_q, n_blocks]
    /// Returns: [batch, n_heads_kv, seq_q, topk_actual]
    pub fn select<B: Backend>(&self, block_scores: Tensor<B, 4>) -> Tensor<B, 4, Int> {
        let [batch, h, seq_q, n_blocks] = block_scores.dims();
        let topk = self.topk.min(n_blocks);
        let device = block_scores.device();

        // Flatten batch and heads for topk
        let scores_3d = block_scores
            .permute([0, 1, 3, 2]) // [B, H, Nb, Sq]
            .reshape::<3, _>([batch * h, n_blocks, seq_q])
            .permute([0, 2, 1]); // [B*H, Sq, Nb]

        let indices_3d = if self.force_local_block && seq_q > 0 && n_blocks > 0 && topk > 1 {
            let q_pos =
                Tensor::<B, 1, Int>::arange(0..seq_q as i64, &device).reshape::<2, _>([seq_q, 1]);
            let local_block = q_pos.div_scalar(self.block_size as i64);
            let block_idx = Tensor::<B, 1, Int>::arange(0..n_blocks as i64, &device)
                .reshape::<2, _>([1, n_blocks]);
            let bias = local_block
                .equal(block_idx)
                .float()
                .mul_scalar(1e4)
                .unsqueeze::<3>();
            let (_values, idx) = scores_3d.add(bias).topk_with_indices(topk, 2);
            idx
        } else {
            let (_values, idx) = scores_3d.topk_with_indices(topk, 2);
            idx
        };

        let actual_topk = indices_3d.dims()[2];
        indices_3d.reshape::<4, _>([batch, h, seq_q, actual_topk])
    }
}