RustedSciThe 0.4.22

# Optional SuperLU Sparse Backend

`BvpSciSparseFactorization::SuperLu` is an opt-in native sparse LU policy for
`BVP_sci`. It is not selected by default: ordinary Sparse solves continue to
use StandardFaer. The C ABI implementation is private; other Rust code should
use the checked facade in `somelinalg::superlu` rather than loading symbols or
calling FFI directly.

## Build The Bridge

The bridge is built separately for the current operating system and CPU. The
script pins SuperLU 6.0.1 and writes the generated native library under the
ignored `test_reports/` tree; no generated DLL or shared object belongs in git
or a crate release.

Windows (requires Git, CMake, Ninja and MinGW-w64 GCC):

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_superlu_bridge.ps1
$env:SUPERLU_LIBRARY = (Resolve-Path '.\test_reports\somelinalg_sparse_lu_reference\native\superlu_bridge.dll').Path
```

Linux (requires Git, CMake, Ninja and a C compiler):

```sh
bash scripts/build_superlu_bridge.sh
export SUPERLU_LIBRARY="$(pwd)/test_reports/somelinalg_sparse_lu_reference/native/libsuperlu_bridge.so"
```

Enable the Rust feature when compiling the application:

```sh
cargo run --features superlu --example bvp_sci_backends_guide
```

In application code, select the route with builder `.with_superlu()`; the
matrix layout is Sparse:

```rust,ignore
let mut solver = BvpSciSolver::builder(
    vec![Expr::parse_expression("z"), Expr::parse_expression("0")],
    vec!["y".into(), "z".into()],
)
.with_frontend(BvpSciAssembly::ExprLegacy)
.with_superlu()
.with_mesh_and_initial_state(mesh, initial_state)
.with_boundary_callback(|ya, yb, _parameters, residual| {
    residual[0] = ya[0];
    residual[1] = yb[0] - 1.0;
    Ok(())
})
.build()?;
let solution = solver.solve()?;
```

If Cargo feature `superlu` was omitted, the library
path is unset, or the bridge cannot be loaded/validated, BVP_sci prints a
warning and falls back to StandardFaer Sparse. The `superlu_fallbacks`
telemetry counter makes that route observable. A fallback is safe behavior,
but it is not SuperLU performance evidence.

The release matrix keeps these exploratory A/B stories separate from ordinary
ignored story gates. To include the three sparse-policy comparisons and the
focused full-solve benchmark on Windows:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\bvp_sci_release_matrix.ps1 `
  -SkipIgnoredStories -SkipBench -SkipScaleEvidence `
  -IncludeSparseStrategyAb -EnableSuperLu `
  -SuperLuLibraryPath $env:SUPERLU_LIBRARY
```

To add the dedicated StandardFaer-versus-SuperLU full-solve benchmark to the
runner, omit `-SkipBench` and add `-IncludeSuperLuBench`; that also runs the
other selected BVP_sci benches. For only the focused benchmark, use:

```powershell
$env:SUPERLU_LIBRARY = (Resolve-Path '.\test_reports\somelinalg_sparse_lu_reference\native\superlu_bridge.dll').Path
cargo bench --no-default-features --features superlu --bench bvp_sci_superlu_ab -- --noplot
```

The release runner records compiler output under `technical/` and compact
tables under `reports/`.

## Shared Linear Algebra API

Other solvers can opt into the same safe API without depending on BVP_sci:

```rust,ignore
use RustedSciThe::somelinalg::superlu::{CscMatrix, SolverLibrary};

let matrix = CscMatrix::try_from_usize(n, &column_pointers, &row_indices, &values)?;
let library = SolverLibrary::load(std::env::var("SUPERLU_LIBRARY")?)?;
let mut factor = library.factorize(&matrix)?;
factor.solve_in_place(&mut rhs)?; // retained LU can solve later RHS vectors
```

For a one-shot operation, `somelinalg::superlu::solve_csc(...)` loads the
configured bridge, factors the matrix and solves one RHS. Repeated systems
should retain `SolverLibrary` and `Factorization` as shown above.

## Evidence And Scope

The official 60-state BVP continuation A/B showed a substantial workload-
specific speedup over StandardFaer with matching nonlinear work counters. A
small two-state control did not show a SuperLU win. This supports offering a
selectable backend, not a claim that SuperLU is universally faster. Native
library distribution, memory accounting and Linux runtime validation remain
open before considering a default change. Reusable-faer kernels and their A/B
tests are separate experiments; they are not the StandardFaer production path.

### Release Matrix Snapshot (2026-10-12)

The broad release matrix compared the same frontend/workload axes across
Dense/Sparse/Banded and ExprLegacy/AtomViewNative, and included cached AOT,
Lambdify, continuation, and SuperLU policy runs. The clearest repeated SuperLU
result was the official 60-state sparse BVP with four prepared parameter
rebinds: nine paired repetitions gave a `428.454 ms` StandardFaer full-series
median and `80.634 ms` with SuperLU (`-81.30%`). Both used 14 factorizations,
four rebinds and four continuation solves, ended on the same 17-node mesh, and
had maximum state drift `2.339e-12`; SuperLU fallback count was zero.

This is workload-specific, not a general Sparse speed claim. In the same
release evidence, the simple two-state control favored StandardFaer, while
fixed-mesh stiff-decay and stiff-coupled cases were usually near parity or
favored StandardFaer. Keep StandardFaer as default and select SuperLU
explicitly for workloads where matched measurements justify it.

For matched ExprLegacy/AtomViewNative and AOT/Lambdify comparisons, full-solve
time was primarily determined by layout and workload. On a 32-state, 64-node
Dense case, full-solve rows clustered around `268-271 ms`; Sparse rows were
around `10-13 ms`. AtomView preparation could be several tenths of a
millisecond slower than ExprLegacy, but was negligible beside the large Dense
solve and a small fraction of the Sparse solve. Cold TCC compilation/linking
was about `20-23 ms` in the measured small AOT case, while cached AOT solves
were comparable to Lambdify. Since subsequent continuation rows were cache
hits, that table does not establish a cold-build break-even count.

The continuation lifecycle gates also confirmed that 16 parameter rebinds do
not repeat symbolic preparation; on an unchanged mesh there were no additional
workspace resizes, while a mesh change caused the expected growth. Timing
scopes for factorization and solve overlap and must not be summed. The broad
workload matrix is a one-pass diagnostic slice; use repeated paired reports for
claims about small performance differences.

Source tables:

- `test_reports/BVP_sci_release_manual/20261012T220656Z/reports/BVP_sci_new/release/sparse_kernel_official_60_state_continuation_ab.md`
- `test_reports/BVP_sci_release_manual/20261012T220656Z/reports/BVP_sci_Matched_Bench/release/matched_full_solve_continuation.md`
- `test_reports/BVP_sci_release_manual/20261012T220656Z/reports/BVP_sci_Lambdify_Bench/release/lambdify_matrix.md`