oxiblas

Unified API for OxiBLAS - Pure Rust BLAS/LAPACK implementation

Overview

oxiblas is the meta-crate that re-exports all OxiBLAS functionality through a unified, convenient API. This is the recommended way to use OxiBLAS for most users.

Features

• Complete BLAS - Level 1, 2, 3 operations
• Extensive LAPACK - LU, QR, SVD, Cholesky, EVD, and more
• Sparse matrices - 9 formats with iterative solvers
• Tensor operations - Einstein summation, batched operations
• Extended precision - f16, f128 support
• High performance - Competitive with OpenBLAS for typical workloads; see oxiblas-benchmarks for reproducible numbers on your own hardware
• Pure Rust - No C dependencies, easy cross-compilation

Quick Start

[dependencies]
oxiblas = "0.2"

# With all features
oxiblas = { version = "0.2", features = ["full"] }

Usage

Matrix Operations

use oxiblas::prelude::*;

// Create matrices
let a = Mat::from_rows(&[
    &[1.0, 2.0, 3.0],
    &[4.0, 5.0, 6.0],
]);

let b = Mat::from_rows(&[
    &[7.0, 8.0],
    &[9.0, 10.0],
    &[11.0, 12.0],
]);

// Matrix multiplication
let mut c = Mat::zeros(2, 2);
gemm(1.0, a.as_ref(), b.as_ref(), 0.0, c.as_mut());
// c = [[58, 64], [139, 154]]

Linear Algebra

use oxiblas::prelude::*;

let a = Mat::from_rows(&[
    &[2.0, 1.0, 1.0],
    &[4.0, 3.0, 3.0],
    &[8.0, 7.0, 9.0],
]);

// LU decomposition
let lu = Lu::compute(a.as_ref())?;
let det = lu.determinant();
let inv = lu.inverse()?;

// QR decomposition
let qr = Qr::compute(a.as_ref())?;
let q = qr.q();
let r = qr.r();

// SVD
let svd = Svd::compute(a.as_ref())?;
let singular_values = svd.singular_values();

// Solve Ax = b (b is an n x 1 matrix, i.e. a column vector)
let b = Mat::from_rows(&[&[4.0], &[10.0], &[24.0]]);
let x = lu.solve(b.as_ref())?;

Sparse Matrices

use oxiblas::prelude::*;

// Create sparse matrix
let mut coo = CooMatrix::<f64>::new_empty(1000, 1000);
coo.push(0, 0, 4.0);
coo.push(0, 1, -1.0);
// ... add more elements

let csr = coo.to_csr();

// Solve sparse system with GMRES
let b = vec![/*...*/];
let x0 = vec![0.0; 1000]; // initial guess
let result = gmres(&csr, &b, &x0, 30, 1e-10, 100)?;
let x = result.x;

Tensor Operations

// Tensor operations live in `oxiblas-blas`'s `tensor` module and are not
// part of `oxiblas::prelude` - import them from `oxiblas::blas::tensor`.
use oxiblas::blas::tensor::{Tensor3, batched_matmul, einsum};

// Einstein summation: matrix multiplication (A: 2x3, B: 3x2)
let a = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
let b = vec![7.0, 8.0, 9.0, 10.0, 11.0, 12.0];
let c = einsum("ij,jk->ik", &a, &[2, 3], Some((&b, &[3, 2])))?;

// Batched matrix multiplication
let (batch, m, k, n) = (4, 2, 3, 2);
let data_a = vec![1.0; batch * m * k];
let data_b = vec![1.0; batch * k * n];
let a_batch = Tensor3::from_data(data_a, batch, m, k);
let b_batch = Tensor3::from_data(data_b, batch, k, n);
let c_batch = batched_matmul(&a_batch, &b_batch)?;

Module Structure

The oxiblas crate re-exports from these sub-crates:

Prelude

The oxiblas::prelude module provides convenient imports:

use oxiblas::prelude::*;

// Now you have access to:
// - Mat, MatRef, MatMut (matrix types)
// - gemm, gemv, dot, axpy, etc. (BLAS operations)
// - Lu, Qr, Svd, Cholesky, etc. (LAPACK decompositions)
// - CsrMatrix, CooMatrix, etc. (sparse matrices)
// - gmres, cg, bicgstab, etc. (sparse solvers)

Feature Flags

Note: oxiblas-ffi (C FFI bindings) was retired in v0.2.0 and is no longer a feature of this crate - see the Module Structure table above.

Examples

# Minimal (dense matrices only)
oxiblas = "0.2"

# With parallelization
oxiblas = { version = "0.2", features = ["parallel"] }

# With extended precision
oxiblas = { version = "0.2", features = ["f16", "f128"] }

# With ndarray support
oxiblas = { version = "0.2", features = ["ndarray"] }

# All features
oxiblas = { version = "0.2", features = ["full"] }

Examples

The repository includes comprehensive examples:

# Basic BLAS operations
cargo run --example basic_blas

# LAPACK decompositions
cargo run --example lapack_decompositions

# Extended precision
cargo run --example extended_precision --features f128

# Tensor operations
cargo run --example tensor_operations

# Sparse matrices
cargo run --example sparse_matrices --features parallel

Performance

OxiBLAS is competitive with OpenBLAS for typical workloads (dense GEMM, BLAS Level 1-3, LAPACK decompositions), thanks to BLIS-style blocked algorithms and hand-tuned SIMD micro-kernels. Actual performance depends heavily on operation, matrix size, and hardware (SIMD width, cache hierarchy, core count), so no single ratio is representative.

Run the benchmark suite yourself for numbers reproducible on your own hardware:

# OxiBLAS-only benchmarks
cargo bench --package oxiblas-benchmarks

# Direct comparison against OpenBLAS (requires OpenBLAS installed)
cargo bench --package oxiblas-benchmarks --bench comparison --features compare-openblas

See the oxiblas-benchmarks README for details on the available benchmark suites.

Documentation

• Main README - Project overview and features
• API Documentation - Complete API reference
• Examples - Usage examples
• Benchmarks README - Performance benchmarking guide

Sub-Crate Documentation

For more detailed documentation on specific components:

• oxiblas-core - Core traits and SIMD
• oxiblas-matrix - Matrix types
• oxiblas-blas - BLAS operations
• oxiblas-lapack - LAPACK decompositions
• oxiblas-sparse - Sparse matrices
• oxiblas-ndarray - ndarray integration
• oxiblas-benchmarks - Benchmarking suite

Ecosystem

OxiBLAS is part of the SciRS2 scientific computing ecosystem:

• SciRS2 - Scientific computing library
• NumRS2 - Numerical computing
• SkleaRS - Machine learning
• ToRSh - Tensor operations
• TrustformeRS - Transformers
• QuantRS2 - Quantum computing framework
• OxiRS - Semantic Web platform

Requirements

• Rust: 1.85+ (Edition 2024)
• No external C dependencies
• Supported platforms: x86_64, AArch64 (Linux, macOS, Windows)

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Citation

If you use OxiBLAS in your research, please cite:

@software{oxiblas2026,
  author = {OxiBLAS Contributors},
  title = {OxiBLAS: Pure Rust BLAS/LAPACK Implementation},
  year = {2026},
  url = {https://github.com/cool-japan/oxiblas}
}