ruSOLVER

English | 简体中文

Numerical linear solvers and matrix factorizations for Ruda.

• Cargo package: ruda-solver
• Rust crate: rusolver

This crate is part of the RUDA workspace. Build from the RUDA workspace, which provides shared configuration and optional dependencies.

Features

The library is experimental. Host, device, sparse, and distributed interfaces have separate execution contracts; enabling a feature does not move host algorithms onto the GPU.

Quick Start

Build and run from the RUDA workspace:

git clone https://github.com/shuqi2077/RUDA.git
cd RUDA
cargo build --locked -p ruda-solver
cargo run --locked -p ruda-solver --example solver-demo

Documentation

• User guide
• Extended numerical science
• Environment setup
• Cargo features · Module exports

ruSOLVER User Guide

Compute libraries · 中文

1. Host operations

Matrix owns nonempty, finite, row-major FP64 data. MatrixView supports immutable positive-stride views and explicit transposition. Complex64 stores two FP64 components. Inputs are not implicitly downloaded from devices.

2. Solve a linear system

Factor A once and reuse the factor for subsequent right-hand sides. This example solves A x = b for x = [1, 2]:

use rusolver::{Lu, Matrix, relative_residual};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let a = Matrix::new(2, 2, vec![4.0, 1.0, 1.0, 3.0])?;
    let b = Matrix::new(2, 1, vec![6.0, 7.0])?;
    let factor = Lu::factor(a.view(), Default::default())?;
    let x = factor.solve(b.view())?;
    println!("x = {:?}", x.values());
    println!("relative residual = {}",
        relative_residual(a.view(), x.values(), b.values())?);
    Ok(())
}

LU uses P A = L U; pivot entries record sequential row swaps. QR uses A[:, permutation] = Q R. Put multiple right-hand sides in the columns of B instead of forming an inverse to solve each system.

Tolerances control numerical pivot and rank decisions; they are not condition-number estimates. QR rejects rank-deficient least squares. SVD supports rank truncation, so its pseudoinverse and minimum-norm solve use the retained singular values. CG requires a fixed symmetric positive-definite operator and positive-definite preconditioner; check report.converged() before treating its output as a solution.

Source: LU, QR, SVD, and CG.

3. Complex and sparse systems

The advanced example covers SVD, complex LU, sparse LU, and a solve pullback. The CSR example uses the optional ruSPARSE adapter:

cargo run --locked -p ruda-solver --example advanced-solver
cargo run --locked -p ruda-solver --features sparse --example sparse-poisson

SparseLu::factor_csr accepts zero-based CSR arrays, including duplicate entries that are summed. Factors stay in sparse row storage rather than a dense matrix. max_factor_nonzeros limits factor entries, not total process memory. Feature sparse enables SparseLu::from_rusparse and sparse::CsrF32Operator for existing ruSPARSE structures.

4. Device tensors

Enable tensor for runtime-generic interfaces or cuda for NVIDIA examples:

cargo run --locked -p ruda-solver --features cuda --example solver-cuda
cargo run --locked -p ruda-solver --features cuda --example solver-cuda-advanced

Inputs must be unquantized, contiguous, row-major FP32 tensors on the same device and execution queue. Default paths use one device thread per system. Explicit *_batched_warp LU and Cholesky paths cooperate within a 32-thread block using shared memory. They require the opt-in warp-solvers feature and are experimental, not enabled by default. This is not a blocked, warp-cooperative large-matrix implementation or a cuSOLVER performance claim. Inputs are unchanged, and outputs/workspace use new device allocations.

Warp-kernel optimization and A/B benchmark · 优化说明与验证范围

Call check_status_sync() before using results. It synchronizes and reads each system's status; successful submission alone does not establish numerical success. There is no implicit host numerical fallback or LAPACK/cuSOLVER ABI compatibility.

Source: Device Cholesky and additional device solvers.

5. Distributed computation and autodiff

distributed::distributed_cg keeps CSR matrix rows local while gathering search vectors and reducing scalar quantities. Feature collective provides RucclCommunicator over existing ruCCL TCP. This is host FP64 CG, not multi-GPU/RDMA or distributed sparse-direct factorization. Use a dedicated communication session; failed sessions must be replaced before retrying.

adjoint provides analytic pullbacks for solve, Cholesky, SVD, symmetric eigen, and fixed-pivot QR. Spectral derivatives require separated spectra; SVD derivatives also require full rank. The optional ruda-autodiff/solver-host feature connects solve, Cholesky, singular values, and symmetric eigenvalues to the existing first-order FP64 Host graph. It does not provide complex, sparse, distributed, GPU, or higher-order graph derivatives.

Source: Distributed CG and pullbacks.