# RLST — Rust Linear Solver Toolbox A dual-licensed (MIT OR Apache-2.0) Rust library for **high-performance dense and sparse linear algebra**, designed for solving partial differential equations and related computational problems. It originated from the merger of two experimental projects — [Householder](https://github.com/UCL-ARC/householder) and [sandbox](https://github.com/linalg-rs/sandbox). ## Architecture The workspace has **two members**: | Crate | Purpose | |---|---| | `rlst/` | The core library — all linear algebra, arrays, operators, sparse/distributed types, I/O, SIMD, interpolation | | `rlst-suitesparse/` | Bindings between RLST sparse matrices and native SuiteSparse libraries (e.g. UMFPACK) | | `proc-macro/` | Procedural macro crate (`rlst-proc-macro`) providing array-construction & tracing macros like `@rlst_dynamic_array!`, `measure_duration!` etc. | ## Core Feature Modules (`rlst/src/lib.rs`) - **`base_types`** — RLST's numeric type system (custom trait hierarchy for generic math). - **`dense`** — n-dimensional arrays (stack/heap allocation) with BLAS GEMM and a full LAPACK-backed decomposition suite (LU, SVD, QR, Cholesky, eigendecomposition, etc.). - **`sparse`** — CSR matrices; MPI-gated distributed CSR variants. - **`operator`** — Abstract linear operator / vector-space abstraction, plus iterative solvers (e.g., conjugate gradients). - **`traits`** — Shared generic traits for arrays, numerics, sparse types, I/O, and distributed operations. Re-exported from the crate root. - **`distributed_tools`** — MPI-only: distributed arrays, ghost-cell communication, index layouts, parallel sort. - **`fftw`** / **`chebychev`** — FFTW-gated transforms and Chebyshev polynomial tools. - **`interpolation`** — Interpolation utilities. - **`interface`** — Optional integrations (e.g. Burn framework via `burn` feature). - **`io`** — Matrix Market format I/O. - **`simd`** — SIMD-accelerated operations. - **`doc`** — Crate-level user documentation (getting started, dense LA, decompositions, sparse ops, abstract linear algebra, MPI distributed computations). ## Key Re-exports ```rust pub use rlst_proc_macro::measure_duration; pub use rlst_proc_macro::rlst_dynamic_array; pub use rlst_proc_macro::rlst_static_array; pub use rlst_proc_macro::rlst_static_type; pub use crate::dense::array::Array; pub use traits::*; // all traits re-exported pub use base_types::*; // all base types ``` Plus convenience constants for memory alignment: `CACHE_ALIGNED`, `FFTW_ALIGNED` (16-byte), `PAGE_ALIGNED`. ## Feature Flags | Flag | Effect | |---|---| | *(none)* | No optional deps — defaults to zero optional dependencies | | `strict` | Denies all warnings + unused crate dependencies | | `mpi` | Enables distributed APIs (`mpi`, `mpi-sys`) | | `fftw` | FFTW support; pair with exactly one: `fftw_system`, `fftw_source`, or `fftw_mkl` | | `burn` | Optional Burn (Rust ML framework) integration | | `enable_tracing` | Tracing macros + `log` crate | ## Dependencies & Native Linkage - **BLAS/LAPACK**: Platform-native — Accelerate on macOS, OpenBLAS on Linux. Test fixtures link via `blas_src`/`lapack_src`. - **FFTW**: GPL-licensed backends (`fftw_system`, `fftw_source`) require adhering to the FFTW license; `fftw_mkl` uses Intel MKL. - **SuiteSparse**: Required for `rlst-suitesparse`; set `SUITESPARSE_PATH` for non-standard installations. ## Workflow / Conventions - Rust 2024 edition for `rlst`, Rust 2021 for the proc-macro crate. - Full trait-oriented design — every implementation follows existing traits in `rlst/src/traits/`. - `#![warn(missing_docs)]` on the crate root; public API must be documented. - Minimal `unsafe`; explicit imports (no wildcard glob imports via Clippy). - Tests use `approx` for floating-point comparisons. ## Quick Validation ```bash cargo fmt -- --check cargo clippy -- -D warnings cargo test ``` Full CI feature matrix: `--features "mpi,fftw,fftw_system,strict"` (requires all native deps).