rusting_brain 1.0.0

A Rust neural-network library for learning, training, and inference from small models to small size LLM.
Documentation
use crate::tensor::Tensor;
use rand::Rng;
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct Matrix {
    pub rows: usize,
    pub cols: usize,
    pub data: Vec<f32>,
}

impl Tensor for Matrix {
    fn rows(&self) -> usize {
        self.rows
    }
    fn cols(&self) -> usize {
        self.cols
    }

    fn new(rows: usize, cols: usize) -> Self {
        Matrix::new(rows, cols)
    }

    fn random(rows: usize, cols: usize) -> Self {
        Matrix::random(rows, cols)
    }

    fn zeros(&mut self) {
        self.zeros()
    }

    fn dot(&self, other: &Self, target: &mut Self) {
        self.dot(other, target)
    }

    fn dot_rhs_transposed(&self, other: &Self, target: &mut Self) {
        self.dot_rhs_transposed(other, target)
    }

    fn dot_self_transposed(&self, other: &Self, target: &mut Self) {
        self.dot_self_transposed(other, target)
    }

    fn outer_product(&self, input: &Self, target: &mut Self) {
        self.outer_product(input, target)
    }

    fn dot_transpose_self(&self, error: &Self, target: &mut Self) {
        self.dot_transpose_self(error, target)
    }

    fn data(&self) -> &[f32] {
        &self.data
    }

    fn data_mut(&mut self) -> &mut [f32] {
        &mut self.data
    }

    fn copy_from_slice(&mut self, source: &[f32]) {
        self.copy_from_slice(source)
    }
}

impl Matrix {
    pub fn new(rows: usize, cols: usize) -> Self {
        Matrix {
            rows,
            cols,
            data: vec![0.0; rows * cols],
        }
    }

    pub fn random(rows: usize, cols: usize) -> Self {
        let mut rng = rand::thread_rng();
        let data: Vec<f32> = (0..rows * cols).map(|_| rng.gen_range(0.0..1.0)).collect();
        Self { rows, cols, data }
    }

    pub fn from_vec(rows: usize, cols: usize, data: Vec<f32>) -> Self {
        assert_eq!(data.len(), rows * cols);
        Self { rows, cols, data }
    }

    pub fn zeros(&mut self) {
        self.data.fill(0.0);
    }

    pub fn dot(&self, other: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(self.cols, other.rows);
        debug_assert_eq!(target.rows, self.rows);
        debug_assert_eq!(target.cols, other.cols);

        unsafe {
            matrixmultiply::sgemm(
                self.rows,
                self.cols,
                other.cols,
                1.0,
                self.data.as_ptr(),
                self.cols as isize,
                1,
                other.data.as_ptr(),
                other.cols as isize,
                1,
                0.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }

    pub fn dot_rhs_transposed(&self, other: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(self.cols, other.cols);
        debug_assert_eq!(target.rows, self.rows);
        debug_assert_eq!(target.cols, other.rows);

        // A cached decode step feeds one token at a time, and `sgemm` with
        // `m == 1` spends all its time packing panels for a blocked kernel that
        // never gets a second row. A plain row-times-row dot product over
        // contiguous memory beats it by a wide margin, and the compiler
        // vectorizes it.
        if self.rows == 1 {
            let k = self.cols;
            for (slot, weight) in target.data.iter_mut().zip(other.data.chunks_exact(k)) {
                *slot = self
                    .data
                    .iter()
                    .zip(weight)
                    .map(|(a, b)| a * b)
                    .sum::<f32>();
            }
            return;
        }

        unsafe {
            matrixmultiply::sgemm(
                self.rows,
                self.cols,
                other.rows,
                1.0,
                self.data.as_ptr(),
                self.cols as isize,
                1,
                other.data.as_ptr(),
                1,
                other.cols as isize,
                0.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }

    pub fn dot_self_transposed(&self, other: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(self.rows, other.rows);
        debug_assert_eq!(target.rows, self.cols);
        debug_assert_eq!(target.cols, other.cols);

        unsafe {
            matrixmultiply::sgemm(
                self.cols,
                self.rows,
                other.cols,
                1.0,
                self.data.as_ptr(),
                1,
                self.cols as isize,
                other.data.as_ptr(),
                other.cols as isize,
                1,
                0.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }

    pub fn outer_product(&self, input: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(input.cols, 1);
        debug_assert_eq!(target.rows, self.rows);
        debug_assert_eq!(target.cols, input.rows);

        unsafe {
            matrixmultiply::sgemm(
                self.rows,
                1,
                input.rows,
                1.0,
                self.data.as_ptr(),
                self.cols as isize,
                1,
                input.data.as_ptr(),
                1,
                input.cols as isize,
                0.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }

    pub fn dot_transpose_self(&self, error: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(self.rows, error.rows);
        debug_assert_eq!(target.rows, self.cols);
        debug_assert_eq!(target.cols, 1);

        unsafe {
            matrixmultiply::sgemm(
                self.cols,
                self.rows,
                1,
                1.0,
                self.data.as_ptr(),
                1,
                self.cols as isize,
                error.data.as_ptr(),
                error.cols as isize,
                1,
                0.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }

    pub fn copy_from_slice(&mut self, source: &[f32]) {
        self.data.copy_from_slice(source);
    }

    /// Row `index` as a contiguous slice. The transformer layers keep one token
    /// per row, so this is the natural unit of work for them.
    pub fn row(&self, index: usize) -> &[f32] {
        debug_assert!(index < self.rows);
        &self.data[index * self.cols..(index + 1) * self.cols]
    }

    pub fn row_mut(&mut self, index: usize) -> &mut [f32] {
        debug_assert!(index < self.rows);
        &mut self.data[index * self.cols..(index + 1) * self.cols]
    }

    /// `target += self^T * other`, the accumulating form of
    /// [`Matrix::dot_self_transposed`].
    ///
    /// Weight gradients are summed over a whole batch and often over several
    /// call sites (a shared embedding matrix is written by both the gather and
    /// the unembedding), so the accumulating form avoids a full-size scratch
    /// matrix and an extra pass per call.
    pub fn dot_self_transposed_accumulate(&self, other: &Matrix, target: &mut Matrix) {
        debug_assert_eq!(self.rows, other.rows);
        debug_assert_eq!(target.rows, self.cols);
        debug_assert_eq!(target.cols, other.cols);

        unsafe {
            matrixmultiply::sgemm(
                self.cols,
                self.rows,
                other.cols,
                1.0,
                self.data.as_ptr(),
                1,
                self.cols as isize,
                other.data.as_ptr(),
                other.cols as isize,
                1,
                1.0,
                target.data.as_mut_ptr(),
                target.cols as isize,
                1,
            );
        }
    }
}

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

    #[test]
    fn dot_multiplies_row_major_matrices() {
        let left = Matrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
        let right = Matrix::from_vec(3, 2, vec![7.0, 8.0, 9.0, 10.0, 11.0, 12.0]);
        let mut output = Matrix::new(2, 2);

        left.dot(&right, &mut output);

        assert_eq!(output.data, vec![58.0, 64.0, 139.0, 154.0]);
    }
}