Skip to main content

neco_linear_dense/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![forbid(unsafe_code)]
3#![doc = include_str!("../README.md")]
4
5extern crate alloc;
6
7use alloc::vec::Vec;
8use neco_linear_types::{ColumnIndex, LinearError, LinearOperator, RowIndex, Shape, Vector};
9
10#[derive(Clone, Debug, PartialEq)]
11pub struct DenseMatrix<T> {
12    shape: Shape,
13    values: Vec<T>,
14}
15
16impl<T> DenseMatrix<T> {
17    pub fn from_column_major(shape: Shape, values: Vec<T>) -> Result<Self, LinearError> {
18        let expected = shape.element_count()?;
19        if values.len() != expected {
20            return Err(LinearError::StorageLengthMismatch {
21                expected,
22                actual: values.len(),
23            });
24        }
25        if values.len() > isize::MAX as usize {
26            return Err(LinearError::InvalidStorage {
27                reason: "matrix length exceeds the representable allocation limit",
28            });
29        }
30        Ok(Self { shape, values })
31    }
32
33    pub fn from_row_major(shape: Shape, values: Vec<T>) -> Result<Self, LinearError>
34    where
35        T: Clone,
36    {
37        let expected = shape.element_count()?;
38        if values.len() != expected {
39            return Err(LinearError::StorageLengthMismatch {
40                expected,
41                actual: values.len(),
42            });
43        }
44        let mut column_major = Vec::new();
45        column_major
46            .try_reserve_exact(expected)
47            .map_err(|_| LinearError::AllocationFailure {
48                requested: expected,
49            })?;
50        for column in 0..shape.columns() {
51            for row in 0..shape.rows() {
52                let row_major_index = row
53                    .checked_mul(shape.columns())
54                    .and_then(|offset| offset.checked_add(column))
55                    .ok_or(LinearError::CapacityOverflow {
56                        requested: usize::MAX,
57                    })?;
58                column_major.push(values[row_major_index].clone());
59            }
60        }
61        Self::from_column_major(shape, column_major)
62    }
63
64    pub fn shape(&self) -> Shape {
65        self.shape
66    }
67
68    pub fn rows(&self) -> usize {
69        self.shape.rows()
70    }
71
72    pub fn columns(&self) -> usize {
73        self.shape.columns()
74    }
75
76    pub fn len(&self) -> usize {
77        self.values.len()
78    }
79
80    pub fn is_empty(&self) -> bool {
81        self.values.is_empty()
82    }
83
84    pub fn value(&self, row: RowIndex, column: ColumnIndex) -> Result<&T, LinearError> {
85        if row.value() >= self.shape.rows() {
86            return Err(LinearError::IndexOutOfBounds {
87                axis: "row",
88                index: row.value(),
89                bound: self.shape.rows(),
90            });
91        }
92        if column.value() >= self.shape.columns() {
93            return Err(LinearError::IndexOutOfBounds {
94                axis: "column",
95                index: column.value(),
96                bound: self.shape.columns(),
97            });
98        }
99        let position = column
100            .value()
101            .checked_mul(self.shape.rows())
102            .and_then(|offset| offset.checked_add(row.value()))
103            .ok_or(LinearError::CapacityOverflow {
104                requested: usize::MAX,
105            })?;
106        self.values
107            .get(position)
108            .ok_or(LinearError::InvalidStorage {
109                reason: "matrix storage is shorter than its declared shape",
110            })
111    }
112
113    pub fn values(&self) -> &[T] {
114        &self.values
115    }
116
117    pub fn into_values(self) -> Vec<T> {
118        self.values
119    }
120}
121
122impl<T> DenseMatrix<T>
123where
124    T: Clone,
125{
126    pub fn try_zeros(shape: Shape, value: T) -> Result<Self, LinearError> {
127        let length = shape.element_count()?;
128        let mut values = Vec::new();
129        values
130            .try_reserve_exact(length)
131            .map_err(|_| LinearError::AllocationFailure { requested: length })?;
132        values.resize(length, value);
133        Self::from_column_major(shape, values)
134    }
135}
136
137impl LinearOperator<f64> for DenseMatrix<f64> {
138    fn domain(&self) -> usize {
139        self.shape.columns()
140    }
141
142    fn codomain(&self) -> usize {
143        self.shape.rows()
144    }
145
146    fn apply(&self, input: &Vector<f64>) -> Result<Vector<f64>, LinearError> {
147        if input.len() != self.domain() {
148            return Err(LinearError::StorageLengthMismatch {
149                expected: self.domain(),
150                actual: input.len(),
151            });
152        }
153        let mut output_values = Vec::new();
154        output_values
155            .try_reserve_exact(self.codomain())
156            .map_err(|_| LinearError::AllocationFailure {
157                requested: self.codomain(),
158            })?;
159        output_values.resize(self.codomain(), 0.0);
160        for column in 0..self.domain() {
161            let input_value = *input.value(column)?;
162            let column_offset =
163                column
164                    .checked_mul(self.shape.rows())
165                    .ok_or(LinearError::CapacityOverflow {
166                        requested: usize::MAX,
167                    })?;
168            for (row, output_value) in output_values.iter_mut().enumerate() {
169                let position =
170                    column_offset
171                        .checked_add(row)
172                        .ok_or(LinearError::CapacityOverflow {
173                            requested: usize::MAX,
174                        })?;
175                let matrix_value =
176                    *self
177                        .values
178                        .get(position)
179                        .ok_or(LinearError::InvalidStorage {
180                            reason: "matrix storage is shorter than its declared shape",
181                        })?;
182                *output_value += matrix_value * input_value;
183            }
184        }
185        Vector::try_from_vec(output_values)
186    }
187}
188
189#[cfg(test)]
190mod tests {
191    use alloc::vec;
192
193    use super::DenseMatrix;
194    use neco_linear_types::{LinearError, LinearOperator, Shape, Vector};
195
196    #[test]
197    fn row_major_input_is_stored_and_observed_in_column_major_order() {
198        let shape = Shape::new(2, 3);
199        let matrix =
200            DenseMatrix::from_row_major(shape, vec![1, 2, 3, 4, 5, 6]).expect("valid matrix");
201        assert_eq!(matrix.values(), &[1, 4, 2, 5, 3, 6]);
202        assert_eq!(
203            matrix.value(
204                shape.row_index(1).expect("row"),
205                shape.column_index(2).expect("column")
206            ),
207            Ok(&6)
208        );
209    }
210
211    #[test]
212    fn storage_length_mismatch_is_reported() {
213        let result = DenseMatrix::from_column_major(Shape::new(2, 2), vec![1, 2, 3]);
214        assert!(matches!(
215            result,
216            Err(LinearError::StorageLengthMismatch {
217                expected: 4,
218                actual: 3
219            })
220        ));
221    }
222
223    #[test]
224    fn value_rejects_row_index_from_a_different_shape() {
225        let matrix_shape = Shape::new(2, 2);
226        let row = Shape::new(3, 1)
227            .row_index(2)
228            .expect("valid row in source shape");
229        let column = matrix_shape.column_index(0).expect("valid column");
230        let matrix = DenseMatrix::try_zeros(matrix_shape, 0).expect("valid matrix");
231
232        assert!(matches!(
233            matrix.value(row, column),
234            Err(LinearError::IndexOutOfBounds {
235                axis: "row",
236                index: 2,
237                bound: 2
238            })
239        ));
240    }
241
242    #[test]
243    fn value_rejects_column_index_from_a_different_shape() {
244        let matrix_shape = Shape::new(2, 2);
245        let row = matrix_shape.row_index(0).expect("valid row");
246        let column = Shape::new(1, 3)
247            .column_index(2)
248            .expect("valid column in source shape");
249        let matrix = DenseMatrix::try_zeros(matrix_shape, 0).expect("valid matrix");
250
251        assert!(matches!(
252            matrix.value(row, column),
253            Err(LinearError::IndexOutOfBounds {
254                axis: "column",
255                index: 2,
256                bound: 2
257            })
258        ));
259    }
260
261    #[test]
262    fn matrix_vector_product_preserves_values_and_dimensions() {
263        let matrix = DenseMatrix::from_row_major(Shape::new(2, 2), vec![1.0, 2.0, 3.0, 4.0])
264            .expect("valid matrix");
265        let input = Vector::try_from_vec(vec![10.0, 20.0]).expect("valid vector");
266        assert_eq!(matrix.domain(), 2);
267        assert_eq!(matrix.codomain(), 2);
268        assert_eq!(
269            matrix.apply(&input).expect("valid product").values(),
270            &[50.0, 110.0]
271        );
272    }
273
274    #[test]
275    fn matrix_vector_product_rejects_input_length_mismatch() {
276        let matrix = DenseMatrix::try_zeros(Shape::new(2, 3), 0.0).expect("valid matrix");
277        let input = Vector::try_from_vec(vec![1.0, 2.0]).expect("valid vector");
278        assert!(matches!(
279            matrix.apply(&input),
280            Err(LinearError::StorageLengthMismatch {
281                expected: 3,
282                actual: 2
283            })
284        ));
285    }
286}