faier 0.25.2

linear algebra library — maintained fork of faer with AI-assisted fixes
Documentation

faier

faier on crates.io faier documentation

faier is a maintained fork of faer, Sarah Quiñones's pure-Rust linear algebra library, carrying fixes that upstream can't take. It is used by geode-fem and related projects.

Upstream doesn't accept contributions written with AI assistance. Our development uses AI tools, so the fixes we need are kept here instead. The library is still called faer, so code keeps use faer::....

Using faier

Rename the package in your Cargo.toml and keep faer as the dependency key:

[dependencies]
faer = { package = "faier", version = "0.25" }
use faer::Mat;

For fixes that are on main but not yet released, use the git form:

[dependencies]
faer = { package = "faier", git = "https://github.com/rjwalters/faier" }
# or pin it: add `rev = "<commit>"` (or `branch = "main"`)

If you depend on faer-traits directly, rename that too; its library name is still faer_traits:

faer-traits = { package = "faier-traits", version = "0.24" }
# with the git form of faier, take faier-traits from git as well, or cargo
# builds two copies of the traits crate:
# faer-traits = { package = "faier-traits", git = "https://github.com/rjwalters/faier" }

What's different from faer

faier 0.25 is based on faer 0.24.4. It adds:

  • Generalized eigenvalues (gevd, QZ). Fixes for an index-overflow panic, wrong (mostly zero) eigenvalues from eigenvalues-only solves above 32 rows, loss of accuracy in the real double-shift bulge chase, and the deflation window spinning on larger problems. Non-finite input and running out of iterations are now reported as GevdError::NoConvergence instead of returning meaningless eigenvalues.
  • Givens rotations in the generalized Hessenberg reduction. The internal rotation routine used by gevd now applies LAPACK's safe scaling (zlartg/dlartg), so subnormal and extreme-magnitude inputs no longer overflow or lose the complex phase. The public JacobiRotation::make_givens is unchanged.
  • Upstream's unreleased fix.gevd-313, cherry-picked. gevd_scratch no longer under-allocates for n = 2 with eigenvectors, and the eigenvalues-only real QZ writes both slots of a conjugate pair.
  • Tridiagonal divide and conquer. The matrix is scaled to unit norm first, so small-norm matrices no longer merge distinct eigenvalues.
  • Sparse LU column ordering. LuColOrdering::{Colamd, Identity, Custom} lets you supply your own fill-reducing ordering.

Two API differences come with the LU change:

  • factorize_symbolic_lu takes a column-ordering argument. Pass LuColOrdering::Colamd for faer's behaviour.
  • Sparse QR's column_counts_ata takes the matrix A instead of its transpose.

Apart from these, the library's behaviour and API match faer 0.24.4. FORK.md lists every change with its regression test and the issue it resolves.

Versions and releases

faier follows upstream's minor version and makes patch releases for fork fixes. The 0.25 line is a one-time exception, a minor ahead of faer 0.24 because of the LU API change, and faier returns to upstream's numbering from faer 0.26. Releases are published to crates.io by release-plz through crates.io Trusted Publishing. The details are in FORK.md; per-release notes are in faer/CHANGELOG.md.

The minimum supported Rust version is 1.84.0.

Documentation

API documentation for this fork is on docs.rs/faier. For guides, examples and benchmarks, see upstream's website and benchmark page. They describe faer, which faier matches apart from the differences above.

Contributing

Report bugs and send pull requests to rjwalters/faier, not upstream, including bugs that also exist in faer. AI-assisted contributions are welcome here. Each fix should come with a regression test and a row in FORK.md.

License and credit

faier is MIT-licensed, like faer. The original copyright, license and third-party notices (Eigen, LAPACK, SuiteSparse) are kept, and all credit for faer itself belongs to its author. To cite the library, cite upstream faer-rs: CITATION.cff and paper.md describe it. This fork is a derivative work.