HyBIT

HyBIT — Autonomous Hybrid Sparse Solver is a Rust-first sparse linear-solver framework for large sparse systems arising in FEM and HPC workloads.

HyBIT starts from a low-cost iterative path, observes convergence, identifies numerically difficult degrees of freedom when progress is poor, and can promote bounded local regions to direct Cholesky corrections. ABTM bitmap topology metadata is used internally to expand and organize selected regions. Applications continue to provide ordinary CSR32 matrices.

Project status: HyBIT 0.5.0 is an experimental pre-1.0 release. The current automatic solver path is restricted to real symmetric positive-definite (SPD) systems and PCG. APIs may evolve before 1.0.

日本語の説明は README.ja.md を参照してください。

Highlights

• Rust-first implementation with a stable C ABI for C, C++, and Fortran consumers.
• CSR32 public matrix input; ABTM stays an internal execution/topology backend.
• PCG with reusable Krylov workspaces.
• Automatic poor-progress probing and selective local direct escalation.
• Multiple hard regions with weighted overlapping Schwarz correction.
• Bounded dense Cholesky factors for selected SPD principal submatrices.
• analyze -> prepare -> solve-many execution with reusable workspaces and learned local factors.
• Detailed SolveReport diagnostics for convergence, timings, selected regions, factor memory, and reuse.
• MIT licensed.

Install from crates.io

cargo add hybit

or add it manually:

[dependencies]
hybit = "0.5.0"

Rust 1.73 or newer is required.

Quick start

use hybit::{Csr32Matrix, HybitSolver};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // SPD tridiagonal matrix:
    // [ 2 -1  0 ]
    // [-1  2 -1 ]
    // [ 0 -1  2 ]
    let a = Csr32Matrix::new(
        3,
        3,
        vec![0, 2, 5, 7],
        vec![0, 1, 0, 1, 2, 1, 2],
        vec![2.0, -1.0, -1.0, 2.0, -1.0, -1.0, 2.0],
    )?;

    let b = vec![1.0, 0.0, 1.0];
    let mut x = vec![0.0; 3];

    let solver = HybitSolver::new();
    let report = solver.solve_csr32(&a, &b, &mut x)?;

    println!("x = {x:?}");
    println!(
        "status={:?}, iterations={}, relative_residual={:.3e}",
        report.status, report.iterations, report.relative_residual
    );
    Ok(())
}

A convenience one-shot API is also available:

let (x, report) = hybit::solve(&a, &b)?;

Analyze, prepare, solve many

For repeated right-hand sides against an unchanged matrix, use a prepared context:

use hybit::HybitSolver;

let solver = HybitSolver::new();
let analysis = solver.analyze_csr32(&a)?;
let mut prepared = solver.prepare_csr32(&a, &analysis)?;

let mut x1 = vec![0.0; a.nrows()];
let report1 = prepared.solve(&a, &b1, &mut x1)?;

let mut x2 = vec![0.0; a.nrows()];
let report2 = prepared.solve(&a, &b2, &mut x2)?;

The first difficult RHS may trigger adaptive region detection and local Cholesky construction. Later RHS vectors reuse the learned Hybrid preconditioner and the PCG workspace while the matrix remains bitwise unchanged.

Numerical pipeline

CSR32 matrix
    |
    v
 analyze
    |-- MatrixProfile
    |-- SPD baseline checks
    |-- backend policy
    |-- structure/value signatures
    v
 prepare
    |-- Jacobi preconditioner
    |-- reusable PCG workspace
    |-- optional ABTM backend
    v
 prepared solve #1
    |-- short Jacobi-PCG probe
    |       |
    |       +-- good progress ------> continue PCG
    |       |
    |       +-- poor progress
    |             |-- residual/risk masks
    |             |-- hard-region components
    |             |-- ABTM halo expansion
    |             |-- local Cholesky factors
    |             +-- Hybrid PCG restart
    v
 cache learned local factors
    v
 prepared solve #2..N
    |-- reuse factors
    |-- reuse Krylov workspace
    +-- skip adaptive probe/factor build

Hybrid preconditioner

For local restriction operators R_k, local SPD principal matrices A_k, and symmetric overlap weights W_k, HyBIT uses the conceptual form

M^-1 = J_uncovered + sum_k R_k^T W_k A_k^-1 W_k R_k

For a DOF contained in m_i local regions, each local term uses weight 1/sqrt(m_i). Jacobi acts on DOFs not covered by any local direct factor. When the preconditioner changes, HyBIT restarts PCG rather than mutating the preconditioner inside an active PCG recurrence.

See docs/HYBRID_MATH.md for details.

C, C++, and Fortran

The repository contains a C ABI and thin language bindings under include/ and fortran/. On Windows the Rust core builds hybit.dll; MinGW consumers use a generated GNU import library.

.\build.ps1
.\build-examples.ps1

.\build\hybit_c.exe
.\build\hybit_cpp.exe
.\build\hybit_fortran.exe

Prepared execution is available through the C ABI functions hybit_prepare, hybit_solve_prepared, and hybit_prepared_destroy. The C++ wrapper provides an RAII Prepared object and the Fortran module exposes matching ISO_C_BINDING declarations.

Release-gate validation

The public 0.5.0 release keeps the numerical and ABI implementation validated by the 0.4.1 release gate; 0.5.0 changes are release packaging, metadata, documentation, and publication tooling.

The Windows release gate passed Rust tests, the C ABI test, Rust examples, and C/C++/Fortran runtime examples. The adaptive synthetic validation produced the following iteration counts:

The prepared solve-many validation reported 13 iterations on the first difficult RHS and 1 iteration on the second RHS, with cached local factors reused and no second factorization.

These are deliberately small synthetic regression problems used to validate control flow and numerical behavior. They are not representative application benchmarks and do not imply a general speedup. Large real FEM/HPC systems still need dedicated validation.

Current scope and limitations

HyBIT 0.5.0 intentionally has a narrow numerical scope:

• real f64 matrices;
• square SPD systems on the automatic path;
• PCG as the automatic Krylov method;
• CSR32 public storage and an internal ABTM backend;
• dense local Cholesky factors with bounded region sizes;
• up to 8 local regions by default, each limited to 128 DOFs by default;
• prepared-factor reuse only when matrix structure and coefficient bits are unchanged;
• prepared contexts are intended for single-threaded use;
• no MINRES, GMRES, BiCGStab, coarse-grid correction, distributed memory, GPU, or out-of-core execution yet;
• adaptive region selection is currently heuristic rather than spectral.

The project should therefore be treated as experimental numerical software. Validate residuals and physical results independently before using it in engineering decisions.

Repository layout

crates/
  hybit-core      common traits, errors, options, reports
  hybit-matrix    CSR32, ABTM, matrix analysis, masks
  hybit-krylov    PCG and reusable Krylov workspace
  hybit-precond   Jacobi, local Cholesky, weighted Schwarz
  hybit-auto      adaptive solver policy and prepared contexts
  hybit           public Rust facade crate
  hybit-ffi       C ABI DLL layer (repository build, not published to crates.io)
include/          C and C++ headers / Windows .def file
fortran/          Fortran ISO_C_BINDING module
docs/             architecture and numerical notes
examples/         C/C++/Fortran build examples

Build and test from source

git clone https://github.com/michioga/hybit.git
cd hybit
.\public-release-gate.ps1

The public release gate includes runtime/ABI validation and crates.io packaging checks. See docs/PUBLISHING.md before uploading immutable crate versions.

For Cargo-only development:

cargo test --workspace --release
cargo run --release -p hybit --example hybrid
cargo run --release -p hybit --example multiregion
cargo run --release -p hybit --example prepared

Roadmap

Near-term work is focused on real FEM validation, separation of symbolic reuse from numerical refactorization, broader Krylov coverage, stronger diagnostics, and scalable local/coarse corrections. Parallel CPU, GPU, and distributed-memory backends are longer-term directions.

See docs/ROADMAP.md.

Contributing

Bug reports, numerical counterexamples, reproducible matrices, API feedback, and performance measurements are welcome. See CONTRIBUTING.md.

License

HyBIT is licensed under the MIT License.

Repository: https://github.com/michioga/hybit