lak/
lib.rs

1#![feature(portable_simd)]
2
3//! Linear algebra kernels.
4//!
5//! LAK is a personal project. Its guiding question is whether fully-safe Rust and
6//! contiguous-memory-only BLAS routines can stay minimal and elegant without 
7//! sacrificing much performance. Benchmarks can be found at
8//! <https://devald.dev/notes/linalg-kernels/lak_8.pdf> 
9//!
10//! LAK provides small lightweight BLAS-like routines over contiguous Rust slices. 
11//! Matrices are stored column-major.
12//!
13//! The main API is organized by BLAS level: 
14//!
15//! * [l1] - vector-vector routines like [l1::dot()] and [l1::axpy()] 
16//! * [l2] - matrix-vector routines like [l2::gemv()] and [l2::trsv()] 
17//! * [l3] - matrix-matrix routines like [l3::gemm()] 
18//!
19//! Currently, [l3::gemm()] is the only level-3 routine implemented. LAK only
20//! accepts real [f32]/[f64] scalars. 
21//!
22//! GEMM also provides direct [f32] [l3::sgemm()] and [f64] [l3::dgemm()] for maximum 
23//! performance. Level-1 and level-2 routines are all generic.  
24//!
25//! Example:
26//! ```
27//! use lak::l3::gemm;
28//! use lak::types::{MatMut, MatRef, Transpose};
29//!
30//! // column-major 2 x 3 matrix:
31//! // [1 3 5]
32//! // [2 4 6]
33//! let a = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
34//!
35//! // column-major 3 x 2 matrix:
36//! // [ 7 10]
37//! // [ 8 11]
38//! // [ 9 12]
39//! let b = [7.0, 8.0, 9.0, 10.0, 11.0, 12.0];
40//!
41//! let mut c = [0.0, 0.0, 0.0, 0.0];
42//!
43//! let alpha = 1.0;
44//! let beta = 0.0;
45//!
46//! let a = MatRef::new(&a, (2, 3));
47//! let b = MatRef::new(&b, (3, 2));
48//! let mut c = MatMut::new(&mut c, (2, 2));
49//! 
50//! // c.reborrow() used to allow c.as_slice() afterwards. 
51//! gemm(
52//!     Transpose::NoTranspose,
53//!     Transpose::NoTranspose,
54//!     alpha,
55//!     beta,
56//!     a,
57//!     b,
58//!     c.reborrow(),
59//! );
60//!
61//! // C = A * B 
62//! // [ 76 103] 
63//! // [100 136] 
64//! assert_eq!(c.as_slice(), &[76.0, 100.0, 103.0, 136.0]);
65//! ```
66//!
67//! Data is passed through view types: 
68//!
69//! * [types::VecRef] and [types::VecMut] for vectors 
70//! * [types::MatRef] and [types::MatMut] for column-major matrices
71//!
72//! The [blas] module provides unsafe BLAS-shaped LP64 and ILP64 wrapper functions.
73//! These wrappers keep the historical BLAS argument order, but LAK only accepts 
74//! contiguous vectors and matrices: 
75//!
76//! * vector increments must be `1` 
77//! * matrix leading dimensions must be equal to the number of rows. 
78//!
79//! This crate currently uses `rustc 1.94.0-nightly` for `portable_simd`.  
80//!
81//! Informal notes from writing LAK can be found at <https://devald.dev>. 
82
83pub mod types; 
84pub mod traits; 
85#[doc(hidden)]
86pub mod helpers;
87
88pub mod l1; 
89pub mod l2; 
90pub mod l3; 
91pub mod fused; 
92
93pub mod blas;
lak/lib.rs

lak/
lib.rs
