expm_rust
High-performance, generic matrix exponential ($\exp(A) = e^A$) implementation in pure Rust using diagonal $[p/p]$ Padé rational approximation with the scaling and squaring method.
Features
- Generic Matrix Backend: Decoupled from any single linear algebra framework via the
MatrixOpstrait. Bring your own matrix type (nalgebra,faer,ndarray, custom SIMD arrays, or embedded fixed-size matrices). - Built-in
oxiblasSupport: Includes a ready-to-use backend foroxiblas::prelude::Mat<f64>featuring fast BLAS/SIMD operations. - Optimized Polynomial Evaluation: Implements Paterson-Stockmeyer and Horner evaluation schemes for degrees $p \in {3, 4, 5, 6, 7, 9, 13}$ to minimize matrix multiplications.
- Compile-Time Exact Rational Coefficients: Coefficients are generated at compile time as exact irreducible fractions using 128-bit unsigned integers (
u128), avoiding floating-point rounding errors. f128,f32, and Custom Precision Ready: Exact fractions can be evaluated at compile time or runtime for custom scalar types (e.g. 128-bit quadruple precision floats or arbitrary-precision arithmetic).- In-Place Buffer Reuse: Designed for minimal memory allocations during scaling, polynomial accumulation, and squaring stages.
Mathematical Background
Given a square matrix $A \in \mathbb{R}{n \times n}$ (or $\mathbb{C}{n \times n}$), the matrix exponential is defined by the power series:
$$eA = \sum_{k=0}{\infty} \frac{1}{k!} Ak = I + A + \frac{1}{2} A2 + \frac{1}{6} A^3 + \dots$$
Scaling & Squaring Algorithm
Directly truncating the Taylor series for large $|A|$ is numerically unstable. Instead, expm_rust uses the scaling and squaring method with Padé approximants:
- Scaling: Compute an integer scale parameter $s \ge 0$ such that the scaled matrix $A_s = 2^{-s} A$ has a sufficiently small matrix norm $|A_s|$.
- Diagonal $[p/p]$ Padé Approximation: $$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 Xk, \quad V_p(X) = \sum_{k=0}^p c_k (-X)^k$$ and the recurrence for coefficients is: $$c_0 = 1, \quad c_k = c_{k-1} \frac{p - k + 1}{k(2p - k + 1)}$$
- Linear System Solve: Rather than inverting $V_p(A_s)$, solve the linear matrix equation $V_p(A_s) X = U_p(A_s)$ in-place for $X$.
- Squaring: Recover $eA$ through $s$ repeated matrix squarings: $$eA = (e{A_s}){2^s} = \underbrace{\left(\left(R_{p,p}(A_s)\right)^2\right)^2 \dots}_{s \text{ times}}$$
Coefficient Conventions & Precision
Coefficient Array Structure
In expm_rust, the first two Padé coefficients:
- $c_0 = 1.0$ (corresponds to identity matrix $I$)
- $c_1 = 0.5$ (corresponds to diagonal scaling $0.5 I$)
are structurally embedded in the base initialization of polynomial matrices $U$ and $V$. Therefore, the coefficient slices in PADE_COEFFS omit $c_0$ and $c_1$, and contain $[c_2, c_3, \dots, c_p]$ (length $p - 1$).
Higher-Precision (f128 / Custom Float Types)
The pade_coef::Rational struct stores exact numerator and denominator as u128 integers. You can compute exact Padé coefficients for custom scalar types using compute_pade_array:
use ;
// Exact rational coefficients for degree 7 (omits c0 and c1, length = 6)
const RATIONALS_7: = ;
// If using f128 or custom precision:
// let c2 = RATIONALS_7[0].num as f128 / RATIONALS_7[0].den as f128;
Installation
Add to your Cargo.toml:
[]
= "0.1"
To use only the generic traits without the default oxiblas backend:
[]
= { = "0.1", = false }
Quickstart
Using the Built-In oxiblas Backend
use pade_pp_f64;
use *;
Implementing a Custom Backend
To integrate expm_rust with any third-party or custom matrix type, implement the MatrixOps trait:
use ;
Examples
Run the provided examples:
# Run the basic exponential example
# Run the custom backend example
Supported Padé Degrees
The following polynomial degrees are supported:
- Degree 3: 2 coefficients ($c_2, c_3$)
- Degree 4: 3 coefficients ($c_2, c_3, c_4$)
- Degree 5: 4 coefficients ($c_2, \dots, c_5$)
- Degree 6: 5 coefficients ($c_2, \dots, c_6$)
- Degree 7: 6 coefficients ($c_2, \dots, c_7$)
- Degree 9: 8 coefficients ($c_2, \dots, c_9$)
- Degree 13: 12 coefficients ($c_2, \dots, c_{13}$)
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- BSD 3-Clause License (LICENSE-BSD-C-3 or https://opensource.org/licenses/BSD-3-Clause)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.