neurox 0.2.0

A Rust crate providing core building blocks for numerical computing and machine learning, including tensor operations, model abstractions, and future GPU acceleration support.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! Defines the core `Tensor` struct and its associated methods.

use crate::errors::{NeuroxError, NeuroxResult};
use rand::Rng;
use std::fmt;

/// A 2D tensor representing a matrix of `f32` values, stored in row-major order.
#[derive(Clone)]
pub struct Tensor {
    pub data: Vec<f32>,
    pub rows: usize,
    pub cols: usize,
}

impl Tensor {
    /// Creates a new tensor of `rows` x `cols` initialized with zeros.
    pub fn new(rows: usize, cols: usize) -> Self {
        Self {
            data: vec![0.0; rows * cols],
            rows,
            cols,
        }
    }

    /// Creates a new tensor from an existing data vector in row-major order.
    ///
    /// # Panics
    ///
    /// Panics if `data.len()` is not equal to `rows * cols`.
    pub fn from_data(data: Vec<f32>, rows: usize, cols: usize) -> Self {
        assert_eq!(
            data.len(),
            rows * cols,
            "Data size must match tensor dimensions."
        );
        Self { data, rows, cols }
    }

    /// Creates a new tensor with random values sampled from a uniform distribution between -1.0 and 1.0.
    pub fn random(rows: usize, cols: usize) -> Self {
        let mut rng = rand::rng();
        let data = (0..rows * cols)
            .map(|_| rng.random_range(-1.0..1.0))
            .collect();
        Self { data, rows, cols }
    }

    /// Returns the shape of the tensor as `(rows, cols)`.
    pub fn shape(&self) -> (usize, usize) {
        (self.rows, self.cols)
    }

    /// Returns the value at the specified `(row, col)` index.
    ///
    /// # Panics
    ///
    /// Panics if the index is out of bounds.
    pub fn get(&self, r: usize, c: usize) -> f32 {
        self.data[r * self.cols + c]
    }

    /// Sets the `value` at the specified `(row, col)` index.
    ///
    /// # Panics
    ///
    /// Panics if the index is out of bounds.
    pub fn set(&mut self, r: usize, c: usize, v: f32) {
        self.data[r * self.cols + c] = v;
    }

    /// Applies a function element-wise to the tensor, returning a new `Tensor`.
    pub fn map<F>(&self, mut f: F) -> Tensor
    where
        F: FnMut(f32) -> f32,
    {
        let d = self.data.iter().map(|&x| f(x)).collect();
        Tensor::from_data(d, self.rows, self.cols)
    }

    /// Adds a bias row vector to each row of this tensor (broadcasts).
    ///
    /// # Errors
    ///
    /// Returns `NeuroxError::ShapeMismatch` if the bias tensor's shape is not `(1, self.cols)`.
    pub fn add_row_broadcast(&self, bias: &Tensor) -> NeuroxResult<Tensor> {
        if bias.rows != 1 || bias.cols != self.cols {
            return Err(NeuroxError::ShapeMismatch(
                "bias shape must be (1, cols)".into(),
            ));
        }
        let mut out = self.clone();
        for i in 0..self.rows {
            for j in 0..self.cols {
                let idx = i * self.cols + j;
                out.data[idx] += bias.data[j];
            }
        }
        Ok(out)
    }

    /// Creates a new tensor of `rows` x `cols` initialized with zeros. Alias for `new`.
    pub fn zeros(rows: usize, cols: usize) -> Self {
        Self::new(rows, cols)
    }

    /// Returns a new `Tensor` that is the transpose of this one.
    pub fn transpose(&self) -> Tensor {
        let mut out = vec![0.0; self.rows * self.cols];
        for i in 0..self.rows {
            for j in 0..self.cols {
                out[j * self.rows + i] = self.get(i, j);
            }
        }
        Tensor::from_data(out, self.cols, self.rows)
    }
}

/// Provides a truncated, pretty-printed format for debugging tensors.
impl fmt::Debug for Tensor {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut s = String::new();
        s.push_str(&format!("Tensor({}, {}) [", self.rows, self.cols));
        for i in 0..self.rows.min(3) {
            s.push('[');
            for j in 0..self.cols.min(6) {
                s.push_str(&format!("{:.4}", self.get(i, j)));
                if j + 1 < self.cols.min(6) {
                    s.push_str(", ");
                }
            }
            if self.cols > 6 {
                s.push_str(", ...");
            }
            s.push(']');
            if i + 1 < self.rows.min(3) {
                s.push_str(", ");
            }
        }
        if self.rows > 3 {
            s.push_str(", ...");
        }
        s.push(']');
        write!(f, "{}", s)
    }
}