Module block_sparse 

Experimental block-per-bus sparse LU backend for symmetric power flow, mirroring power-grid-model’s approach of grouping each bus’s own unknowns (angle, voltage magnitude) into one dense 2×2 block instead of two separate scalar unknowns scattered across the Jacobian.

This is a parallel, opt-in backend (solver::JacobianBackend::Block) — the Scalar path (sparse.rs, backed by faer) and the default KluNative are untouched by this module, so a bug here cannot affect them. Scoped to symmetric power flow only. Every non-slack bus, PV or PQ, gets a uniform 2×2 block here — this module itself has no notion of bus types; solver::build_jacobian_blocks is what encodes a PV bus’s missing Q-mismatch equation, by substituting a dummy ΔVmag = 0 row instead of varying block size per bus.

Only the fill-reducing ordering is reused from faer (faer::sparse::linalg::colamd::order, which is purely structural and works identically for scalar or block payloads). The numeric block LU (symbolic elimination-graph reachability + block-pivoted factorization + block triangular solve) is hand-written here, following the classic Gilbert-Peierls left-looking sparse LU algorithm, adapted from scalar arithmetic to 2×2 block arithmetic at each step.

Structs

BlockAdjacency

The finalized, consolidated block structure of a BlockMatrix, indexed both by row and by column (see BlockMatrix::finish’s doc comment for why both are needed rather than one derived from the other on demand).

BlockLu

A numeric block LU factorization, computed against a BlockSymbolic’s known structure — either freshly analyzed (factorize) or reusing an existing BlockSymbolic across calls (refactor, the cheap path used once per Newton-Raphson iteration).

BlockMatrix

A mutable block-COO Y-bus/Jacobian accumulator: one 2×2 block per (bus, bus) slot instead of network::YBus’s one Complex<f64> per (unknown, unknown) slot. Duplicate (i, j) entries are summed once finalized, matching YBus’s accumulation semantics.

BlockSymbolic

The symbolic (structure-only) part of a block LU factorization: the colamd permutation plus which rows are nonzero in each column of L and U after fill-in. This is fixed for as long as the sparsity pattern doesn’t change — exactly the case across Newton-Raphson iterations, where the bus topology stays constant and only numeric Jacobian values change — so it’s computed once via analyze and reused by BlockLu::refactor for cheap numeric-only refactorization on every iteration, mirroring sparse::RealSparseSystem’s SymbolicLu reuse for the scalar backend.

Functions

block_abs

A 2×2 block’s Frobenius-like magnitude, used for pivot comparison.

block_add

block_inv

Inverts a 2×2 block via the explicit determinant formula. Returns None if the block is (near-)singular.

block_mul

block_sub

block_vec_mul

block_zero

vec_sub

Type Aliases

Block2

A 2×2 real block, row-major: [[a, b], [c, d]].