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}