t4a-faer

t4a-faer provides dense and sparse linear algebra in Rust for scientific and HPC applications. tenferro and other tensor4all libraries use it. It is not API compatible with upstream faer.

The caller owns the threadteam team and passes Par::Team for parallel work, or Par::Seq for sequential work. faer does not use an implicit global thread pool. See the migration guide.

Benchmarks: published measurements and their conditions live here. Status: Published versions follow semver; APIs can change in incompatible releases.

See the migration guides for Eigen, BLAS, LAPACK, and Julia users.

This is a tensor4all fork of faer. The GitHub repository is a mirror of upstream. The crate body stays MIT, keeping the upstream copyright and attribution, and code ported from other projects keeps its own COPYING terms (see NOTICE).

Community

Questions and discussion about this fork go to the tensor4all Matrix space: #tensor4all:matrix.org. Bug reports and feature requests go to the GitHub issues.

The upstream community is the zulip server, for questions about upstream faer itself. The fork's own channel is the Matrix space above.

faer

faer is a rust crate that implements low level linear algebra routines and a high level wrapper for ease of use, in pure rust, with a focus on portability, correctness and performance. This fork keeps upstream's API where it can and changes it where the tensor4all workload needs another shape; PATCHSET.md lists every difference.

Upstream documentation, for the same crate with an API that differs in places: the upstream website, docs.rs/faer, and the upstream zulip server.

parallelism

There is no process wide parallelism setting. Every operation that can run in parallel takes a Par: Par::Seq runs it on the calling thread, and Par::Team runs its regions on the members of a threadteam team that the caller owns. A caller with a thread budget scopes its work once:

faer::team::with_team(8, |par| {
    // every faer call in here with `par` runs its regions on 8 participants: the calling thread
    // and 7 reserved workers
    qr_in_place(a.as_mut(), h.as_mut(), par, stack, params);
});

A caller that already owns a team lends a sub-team to each call with par.reborrow(); a width of one is Par::Seq.

Each with_team call acquires a pool and team for its closure. Threadteam can reuse cached workers across calls rather than spawning and joining them each time. Code that runs parallel work repeatedly should own the threadteam Pool and Team itself and lend a Par from the team to each call:

// once: 8 participants, the calling thread and 7 reserved workers
let pool = threadteam::Pool::builder().threads(8).build()?;
let team = pool.into_team(8).ok().expect("an idle pool");

// per call: lend the team to faer for the duration of the closure
for (a, h) in work {
    let mut exec = team.exec(8);
    exec.team(|t| qr_in_place(a.as_mut(), h.as_mut(), Par::Team(t), stack, params))
        .ok()
        .expect("a team token for an idle team");
}

See the parallelism section of the crate documentation for the full picture.

minimum supported rust version

1.89.0, declared as rust-version in faer/Cargo.toml. Rust 1.89 is the first release where the AVX-512 target features are stable, which is what lets the x86-v4 kernels build without the nightly compiler. They stay opt in until that path is settled.

contributing

Upstream's contribution guide applies to this fork as well: start with the issues labelled "good first issue", and ask on the upstream zulip server or in the issue itself. Fork specific reports belong in this repository's issues, and a defect that also reproduces on the published upstream crates belongs in upstream-reports/.

benchmarks

The fork's own results are the published campaign pages, and the upstream benchmark page is at faer.veganb.tw/benchmarks. Performance lessons that carry over between changes are in PERFORMANCE_TIPS.md.