numr 0.5.1

High-performance numerical computing with multi-backend GPU acceleration (CPU/CUDA/WebGPU)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

//! Sparse Linear Algebra Algorithm Contracts
//!
//! This module defines traits for sparse linear algebra algorithms that are
//! essential for iterative solvers. All backends must implement the same
//! algorithms to ensure numerical parity.
//!
//! # Algorithms
//!
//! ## Preprocessing (CPU-only, structure-based)
//!
//! - **COLAMD**: Column Approximate Minimum Degree ordering to minimize fill-in
//! - **Maximum Transversal**: Hopcroft-Karp algorithm for row permutation
//!
//! ## Factorization (multi-backend, value-based)
//!
//! - **Sparse LU**: Direct LU factorization with partial pivoting (Gilbert-Peierls)
//! - **ILU(0)**: Incomplete LU factorization with zero fill-in
//! - **ILU(k)**: Incomplete LU factorization with level-k fill-in
//! - **IC(0)**: Incomplete Cholesky factorization with zero fill-in
//! - **Sparse Triangular Solve**: Forward/backward substitution for sparse triangular matrices
//!
//! # Use Cases
//!
//! - **COLAMD** → Reduce fill-in before LU/QR factorization
//! - **Maximum Transversal** → Row permutation for diagonal nonzeros, BTF preprocessing
//! - **Sparse LU** → Direct solver for sparse linear systems
//! - **ILU(0)** → Preconditioner for GMRES, BiCGSTAB (non-symmetric systems)
//! - **ILU(k)** → Stronger preconditioner with more fill-in for difficult systems
//! - **IC(0)** → Preconditioner for CG (symmetric positive definite systems)
//! - **Sparse Triangular Solve** → Application of the preconditioner (L⁻¹ or U⁻¹)
//!
//! # Symbolic/Numeric Split
//!
//! For repeated solves with the same sparsity pattern (e.g., Newton iterations
//! in ODE solvers), the factorization can be split into:
//!
//! 1. **Ordering phase**: COLAMD/maximum transversal (once per pattern)
//! 2. **Symbolic phase**: Compute fill pattern based on sparsity structure
//! 3. **Numeric phase**: Compute actual values using precomputed pattern
//!
//! This gives ~10-50x speedup for repeated solves since the expensive symbolic
//! analysis is only done once.
//!
//! # Algorithm Guarantees
//!
//! All backends produce identical results (within floating-point tolerance):
//! - Same sparsity pattern in output
//! - Same numerical values (order of operations matches)
//! - Same handling of near-zero pivots

pub mod cpu;
pub mod levels;
pub mod lu;
pub mod matching;
pub mod ordering;
pub mod qr;
pub mod symbolic;
pub mod traits;
pub mod types;

// Re-export types
pub use types::{
    IcDecomposition, IcOptions, IluDecomposition, IluFillLevel, IluMetrics, IluOptions,
    IlukDecomposition, IlukOptions, IlukSymbolic, SymbolicIlu0,
};

// Re-export trait and validation helpers
pub use traits::{SparseLinAlgAlgorithms, validate_square_sparse, validate_triangular_solve_dims};

// Re-export level scheduling
pub use levels::{
    LevelSchedule, compute_levels_csc_lower, compute_levels_csc_upper, compute_levels_ilu,
    compute_levels_lower, compute_levels_upper, flatten_levels,
};

// Re-export shared symbolic implementations
pub use symbolic::{ilu0_symbolic_impl, iluk_symbolic_impl};

// Re-export CPU implementations
pub use cpu::{
    ic0_cpu, ilu0_cpu, ilu0_numeric_cpu, ilu0_symbolic_cpu, iluk_cpu, iluk_numeric_cpu,
    iluk_symbolic_cpu, sparse_solve_triangular_cpu,
};

// Re-export sparse LU types and functions
pub use lu::{
    LuFactors, LuMetrics, LuOptions, LuSymbolic, LuSymbolicSimple, LuWorkspace, SparseLuKernels,
    SparseLuOps, sparse_lu_cpu, sparse_lu_cpu_with_metrics, sparse_lu_cpu_with_workspace,
    sparse_lu_cpu_with_workspace_and_metrics, sparse_lu_simple_cpu, sparse_lu_solve_cpu,
};

// Re-export ordering algorithms
pub use ordering::{ColamdOptions, ColamdStats, SparseOrdering, colamd};

// Re-export matching algorithms
pub use matching::{BipartiteMatching, MatchingResult, hopcroft_karp, maximum_transversal};

// Re-export sparse QR types and functions
pub use qr::{
    QrFactors, QrMetrics, QrOptions, QrOrdering, QrSymbolic, sparse_qr_cpu,
    sparse_qr_cpu_with_metrics, sparse_qr_least_squares_cpu, sparse_qr_simple_cpu,
    sparse_qr_solve_cpu, sparse_qr_symbolic,
};

// Re-export CUDA QR implementations
#[cfg(feature = "cuda")]
pub use qr::{sparse_qr_cuda, sparse_qr_simple_cuda, sparse_qr_solve_cuda};

// Re-export WebGPU QR implementations
#[cfg(feature = "wgpu")]
pub use qr::{sparse_qr_simple_wgpu, sparse_qr_solve_wgpu, sparse_qr_wgpu};