rlumod

rlumod is a safe, no_std Rust adaptation of LUmod, Michael A. Saunders' software for incrementally updating a dense square matrix and solving systems with the updated matrix. It maintains the LUmod representation L A = U; it does not compute a conventional A = LU decomposition of an arbitrary completed matrix.

The crate provides:

row-and-column insertion, row replacement, column replacement, and row-and-column removal;
in-place solution of A x = b and A^T x = b;
safe, zero-based APIs for both f32 and f64;
caller-owned factor and workspace storage, with no heap allocation during updates or solves; and
an optional lumod-c feature exposing a lower-level Rust slice API with the original LUmod names and mode arguments; and
an optional c-ffi-one-based feature exposing one-based C entry points for LUmod, Lprod, and Usolve.

rlumod supports dense square matrices only. It does not provide sparse matrix storage or a one-shot factorization API.

Installation

cargo add rlumod

C FFI

The optional c-ffi-one-based feature includes dense, one-based C entry points for LUmod, Lprod, and Usolve, as declared by lumod-c/lumod_dense.h. It automatically enables the lower-level lumod-c Rust API. rlumod remains an rlib; the final no_std crate is responsible for its panic handler and for selecting staticlib when a C-linkable archive is needed. The header is include/lumod-c/lumod_dense.h.

The final crate must also reference rlumod so the linker retains the C ABI:

[lib]
crate-type = ["staticlib"]

[dependencies]
rlumod = { version = "0.2.0", features = ["c-ffi-one-based"] }

[profile.dev]
panic = "abort"

[profile.release]
panic = "abort"

#![no_std]

extern crate rlumod; // Force-link the exported C ABI.

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo<'_>) -> ! {
    loop {
        core::hint::spin_loop();
    }
}

// Stock core may retain this reference even when the final crate aborts on panic.
#[cfg(not(target_env = "msvc"))]
#[unsafe(no_mangle)]
extern "C" fn rust_eh_personality(
    _version: i32,
    _actions: i32,
    _exception_class: u64,
    _exception_object: *mut (),
    _context: *mut (),
) -> i32 {
    loop {
        core::hint::spin_loop();
    }
}

This compatibility ABI uses caller-owned, one-based buffers. Element zero is an unused dummy; L needs maxmod * maxmod + 1 doubles and U needs maxmod * (maxmod + 1) / 2 + 1 doubles. Callers must provide initialized, aligned, writable, sufficiently large, non-overlapping buffers. The ABI cannot verify those C pointer properties. Sparse storage, a dynamic library, and a checked length-and-status C API are not provided.

Documentation and examples

The crate documentation is the main user guide. It covers matrix construction, storage lifetime, update and removal semantics, numerical behavior, and migration from the C LUmod API.

Small runnable programs and the larger validation drivers are listed in the examples guide.

Build and open the documentation locally with:

cargo doc --all-features --open

About LUmod and SOL

The original LUmod was written by Michael A. Saunders at Stanford University's Systems Optimization Laboratory (SOL). It maintains the factorization L A = U, where L is a product of stabilized elementary transformations and U is upper triangular.

See the official LUmod page at SOL for the algorithm's provenance, original distributions, and references.

The rlumod project is an independent Rust adaptation and is not affiliated with, endorsed by, or maintained by Michael A. Saunders or SOL.

License