rustebra

Linear algebra for embedded systems, microcontrollers, and real-time applications.
A hybrid no_std/alloc library. Stack-first by default. Scales to sparse matrices and Krylov subspace solvers when a heap is available.

Documentation · API Reference · Design Decisions · Contributing

Status

Early development (v0.4.0). Core features implemented: static/dynamic vectors and matrices, matrix decompositions (LU, QR, SVD, Cholesky), sparse matrix support (COO, CSR, CSC), and Krylov eigenvalue solvers (power iteration, inverse power iteration). See design decisions for architecture details.

Why this exists

Embedded systems, microcontrollers, and real-time applications need linear algebra without assuming a heap. Rust currently lacks a library that is simultaneously serious about no_std support and complete enough to cover sparse matrices and iterative solvers. Existing options either assume a heap is always available or only provide a partial set of operations for constrained environments. rustebra aims to close that gap.

Design principles

• No allocator required by default. The core of the library works entirely on the stack, using const generics to fix sizes at compile time.
• Allocation is opt-in. Dynamic, heap-backed data structures and algorithms are available behind the alloc feature flag, for use in environments with an operating system.
• Generic over numeric precision. Operations are written to work with different floating-point types, reflecting the range of hardware this library targets — from microcontrollers without double-precision floating-point units to desktop and server systems.
• Explicit error handling. Recoverable failures are reported through Result, not panics, since an uncontrolled abort is often unacceptable in embedded contexts.

When to use rustebra

• Embedded systems (ARM Cortex-M, RISC-V) where allocation is unavailable
• Real-time systems that need predictable stack-only memory
• Microcontrollers with tight RAM (STM32, nRF, etc.)
• Edge devices (Raspberry Pi Zero)
• Any system needing linear algebra without dynamic allocators

When NOT to use rustebra

• Desktop/server apps with heap → use ndarray
• Graphics/game engines → use nalgebra
• Systems where allocation is not a constraint
• Need LAPACK-level routines → ndarray

How rustebra compares

When to use each

rustebra — Use if:

• You need linear algebra without dynamic allocation (embedded, real-time, microcontroller)
• You're working with sparse matrices in an embedded context
• You want no_std + optional alloc (best of both worlds for OS environments)
• Predictable stack-only memory is a requirement

ndarray — Use if:

• You need production-strength BLAS/LAPACK routines (scientific computing, data science)
• You're comfortable with heap allocation and want optimal performance
• You need large matrices with sophisticated solvers and decompositions
• Building NumPy-like workflows in Rust

nalgebra — Use if:

• You need 3D graphics, robotics, or game engine math (Points, Isometries, Rotations)
• You want optional no_std support with fixed-size matrices
• Building low-level geometric transformations
• Working with transformation matrices up to ~6×6

Usage

[dependencies]
rustebra = "0.4.0"

# Optional: heap-backed structures and Krylov solvers
rustebra = { version = "0.4.0", features = ["alloc"] }

Build and test locally:

# no_std build (default)
cargo build
cargo test

# with alloc feature
cargo build --features alloc
cargo test --features alloc

Running Examples

Host Examples

Run any of the host examples with:

cargo run --example vector
cargo run --example matrix
cargo run --example storage
cargo run --example scalar
cargo run --example algorithm

# Requires alloc feature (uses dynamic sparse matrices)
cargo run --example sparse --features alloc

Firmware Examples

For bare-metal embedded targets, see the tests/firmware/ workspace. This keeps device-specific dependencies isolated from the main library.

ARM Cortex-M3 (via QEMU):

cd tests/firmware
cargo build -p cortex-m3-lm3s6965evb --target thumbv7m-none-eabi --release

The binary will be at target/thumbv7m-none-eabi/release/cortex-m3-lm3s6965evb.

To run in QEMU, you need qemu-system-arm installed and in your PATH:

qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic \
  -semihosting -kernel target/thumbv7m-none-eabi/release/cortex-m3-lm3s6965evb

The firmware workspace includes:

• Linker scripts for memory layout
• Panic handlers for no_std environments
• Semihosting I/O for debugging
• Stack-only operation (no heap allocation)

Documentation

• API reference — generated from cargo doc, hosted on GitHub Pages.
• Design decisions — records of the key design choices made during development.
• GitHub Pages site — full project documentation.

To generate and browse the API docs locally:

cargo doc --open

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Contributors

Want to appear here? See CONTRIBUTING.md.

License

Licensed under the Apache License 2.0.