Expand description
§expm_rust
expm_rust is a high-performance, backend-agnostic Rust library for computing the matrix exponential
($\exp(A) = e^A$) using the scaling and squaring method with diagonal $[p/p]$ Padé rational approximants.
§Key Features
- Generic Backend Architecture: Designed around the
MatrixOpstrait. Bring your own matrix library (such asnalgebra,faer,ndarray, custom SIMD buffers, or fixed arrays) by simply implementing the trait. - Built-in
oxiblasBackend: Ready-to-use, high-performance BLAS/SIMD implementation foroxiblas::prelude::Mat<f64>under theoxiblas-backendfeature flag (enabled by default). - Optimized Polynomial Evaluations: Supports Padé degrees $p \in {3, 4, 5, 6, 7, 9, 13}$ using Paterson-Stockmeyer and Horner matrix evaluation schemes that minimize matrix-matrix multiplications.
- Compile-Time Exact Rational Coefficients: Padé coefficients are computed at compile time as exact fractions
using 128-bit integer arithmetic (
pade_coef::Rational), completely avoiding floating-point error in coefficient definitions. - Extensible to
f128,f32, and Custom Precision: Easily compute exact Padé coefficients for 128-bit floats or arbitrary precision scalars usingpade_coef::compute_pade_array. - Minimal Allocations: Reuses matrix buffers in-place during scaling, polynomial accumulation, and squaring stages.
§Mathematical Method
For a square matrix $A \in \mathbb{R}^{n \times n}$ (or $\mathbb{C}^{n \times n}$):
-
Scaling: Choose a non-negative integer $s$ such that $|2^{-s} A|$ is sufficiently small, and scale: $$A_s = 2^{-s} A$$
-
Padé Approximation: Approximate $e^{A_s} \approx R_{p,p}(A_s) = [V_p(A_s)]^{-1} U_p(A_s)$, where: $$U_p(X) = \sum_{k=0}^p c_k X^k, \quad V_p(X) = \sum_{k=0}^p c_k (-X)^k$$ and coefficients satisfy $c_k = c_{k-1} \frac{p - k + 1}{k(2p - k + 1)}$.
(Note: $c_0 = 1$ and $c_1 = 0.5$ are embedded directly into the base identity/diagonal matrices; the coefficient arrays passed to
pade_ppomit these two and provide $[c_2, \dots, c_p]$). -
Linear System Solve: Overwrite $U_p(A_s)$ by solving: $$V_p(A_s) \cdot X = U_p(A_s)$$
-
Repeated Squaring: Recover $e^A$ through $s$ successive matrix squarings: $$e^A = \left(R_{p,p}(A_s)\right)^{2^s}$$
§Quick Start
Add expm_rust to your Cargo.toml:
[dependencies]
expm_rust = "0.1"Compute the matrix exponential using the default oxiblas backend:
use expm_rust::pade_pp_f64;
use oxiblas::prelude::*;
// Create a 2x2 matrix:
// [ 0.0 1.0 ]
// [ 0.0 0.0 ]
let mut a = MatBuilder::<f64>::zeros(2, 2);
a[(0, 1)] = 1.0;
// exp(A) for a nilpotent matrix [[0, 1], [0, 0]] is [[1, 1], [0, 1]]
let exp_a = pade_pp_f64(&mut a, 6, 0).expect("Exponential computation failed");
assert!((exp_a[(0, 0)] - 1.0).abs() < 1e-14);
assert!((exp_a[(0, 1)] - 1.0).abs() < 1e-14);
assert!((exp_a[(1, 0)] - 0.0).abs() < 1e-14);
assert!((exp_a[(1, 1)] - 1.0).abs() < 1e-14);§Implementing a Custom Backend
To use your own matrix data structures, implement MatrixOps for your matrix type:
use expm_rust::{MatrixOps, MathError};
#[derive(Clone)]
struct SimpleMat2x2 {
data: [f64; 4], // row-major: [m00, m01, m10, m11]
}
impl MatrixOps for SimpleMat2x2 {
type Scalar = f64;
fn shape(&self) -> (usize, usize) { (2, 2) }
fn zeros(_size: usize) -> Self {
Self { data: [0.0; 4] }
}
fn identity(_size: usize) -> Self {
Self { data: [1.0, 0.0, 0.0, 1.0] }
}
fn diag(_size: usize, val: f64) -> Self {
Self { data: [val, 0.0, 0.0, val] }
}
fn scale_assign(&mut self, alpha: f64) {
for x in &mut self.data { *x *= alpha; }
}
fn axpy(&mut self, alpha: f64, x: &Self) {
for (y, &xi) in self.data.iter_mut().zip(x.data.iter()) {
*y += alpha * xi;
}
}
fn from_axpy(&mut self, alpha: f64, x: &Self, y: &Self) {
for (res, (&xi, &yi)) in self.data.iter_mut().zip(x.data.iter().zip(y.data.iter())) {
*res = alpha * xi + yi;
}
}
fn gemm(&mut self, alpha: f64, a: &Self, b: &Self, beta: f64) {
let (a00, a01, a10, a11) = (a.data[0], a.data[1], a.data[2], a.data[3]);
let (b00, b01, b10, b11) = (b.data[0], b.data[1], b.data[2], b.data[3]);
let prod = [
a00 * b00 + a01 * b10,
a00 * b01 + a01 * b11,
a10 * b00 + a11 * b10,
a10 * b01 + a11 * b11,
];
for (c, &p) in self.data.iter_mut().zip(prod.iter()) {
*c = alpha * p + beta * *c;
}
}
fn solve_in_place(&self, b: &mut Self) -> Result<(), MathError> {
// Direct 2x2 solve: X = A^(-1) * B
let det = self.data[0] * self.data[3] - self.data[1] * self.data[2];
if det.abs() < 1e-15 { return Err(MathError::SingularMatrix); }
let inv = [
self.data[3] / det, -self.data[1] / det,
-self.data[2] / det, self.data[0] / det,
];
let (b00, b01, b10, b11) = (b.data[0], b.data[1], b.data[2], b.data[3]);
b.data = [
inv[0] * b00 + inv[1] * b10,
inv[0] * b01 + inv[1] * b11,
inv[2] * b00 + inv[3] * b10,
inv[2] * b01 + inv[3] * b11,
];
Ok(())
}
fn copy_from(&mut self, x: &Self) {
self.data = x.data;
}
}§Feature Flags
Modules§
- backends
- Built-in matrix backend implementations.
- pade_
coef - Compile-time Padé approximant coefficient generation.
Enums§
- Math
Error - Errors that can occur during matrix operations and Padé matrix exponential computations.
Traits§
- Matrix
Ops - Core abstraction trait defining the fundamental linear algebra primitives required for Padé matrix exponential evaluation.
Functions§
- pade_pp
- Computes the matrix exponential $e^A$ using a $[p/p]$ Padé approximant and scaling and squaring.
- pade_
pp_ f64 - Computes the matrix exponential $e^A$ for
f64scalar matrix types using standard precomputed Padé coefficients.