Module sparse 

Thin internal wrapper around faer’s sparse LU, isolating gridoxide’s power-flow math from the specific sparse-solver backend. Both a general (non-symmetric, since phase-shifting transformers make the admittance matrix non-Hermitian) complex solve and a real solve are provided, since Newton-Raphson needs the latter for its Jacobian and the linear initial-guess warm start needs the former for the Y-bus.

Each of the two arithmetics comes in a pattern-fixed flavour, which recomputes numeric values on every solve (RealSparseSystem), and a fully-fixed flavour, which factorizes once and then only moves the right-hand side (ComplexSparseSystem, RealFactorization). Which one a caller wants is decided by whether its matrix changes between solves, not by how often it solves.

No faer type appears in any signature here: keeping the backend behind this module is what lets it be swapped without touching the power-flow math.

Structs

ComplexSparseSystem

A complex sparse system whose sparsity pattern and values are both fixed across repeated solves, so the whole factorization — not merely the symbolic half — is computed once and reused.

RealFactorization

A real sparse system whose sparsity pattern and values are both fixed across repeated solves, so the whole factorization — not merely the symbolic half — is computed once and reused.

RealSparseSystem

A real sparse system whose sparsity pattern is fixed across repeated solves (Newton-Raphson’s Jacobian: same bus topology every iteration, only numeric values change) — caches both the LU symbolic factorization (ordering + fill-in) and the triplet argsort (which sparse-matrix slot each triplet’s value lands in) once, and reuses both on each call.

SparseMatrix

A sparse matrix built once from a fixed set of (row, col, value) triplets (duplicates summed), kept around for repeated matrix-vector products — power_injections needs one every Newton-Raphson iteration, but the Y-bus itself never changes across iterations, so the conversion from triplets happens once at construction, not on every call.

Traits

LinearSolver

The one operation the Newton loop needs from a sparse-LU backend: build a reusable symbolic factorization from a sparsity pattern once, then numerically refactorize and solve against that same pattern every iteration.

Functions

solve_complex

Solves a one-shot general complex sparse linear system A x = b. Returns None if the matrix is singular. Used by linear_initial_guess, which only solves once per power-flow run.

solve_dense

Solves a small dense A x = b by Gaussian elimination with partial pivoting. Returns None if A is singular — no pivot clears a small absolute threshold.