Shared Numerics Reference

condestJacobian(J::AbstractMatrix{<:Real}; exact::Bool = false) -> Float64

Estimate the 1-norm condition number $\kappa_1(J) = \|J\|_1 \cdot \|J^{-1}\|_1$ of a power-flow Jacobian.

• default: Hager/Higham estimator for $\|J^{-1}\|_1$ on the LU factorization, so it works on the sparse Jacobians the Newton step factors anyway. The estimate matches the exact condition number's order of magnitude; a factor of 2 to 3 spread is normal.
• exact = true: exact 2-norm condition number via dense SVD. This materializes the full matrix, so use it only for small systems.

The matrix must be real (the rectangular Newton-Raphson Jacobian is; the Hager sign-vector test below is not defined for complex entries) and square. Throws an ArgumentError otherwise, and rethrows the factorization error for a structurally singular matrix.

condestJacobian(net::Net; exact::Bool = false) -> Float64

Estimate the condition number of the rectangular Newton-Raphson Jacobian at the net's CURRENT voltage state (_vm_pu / _va_deg per node): after a solve that is the operating point, after a failed solve the last iterate, which is exactly where conditioning questions arise. Builds the same sparse PQ/PV Jacobian the solver factors (slack row fixed, PV rows as magnitude equations) and forwards to the matrix method.

De-energized buses (net.isoNodes) are excluded: they carry zero Ybus rows and no Jacobian equations, so the estimate describes the active subsystem the solver actually solves. Prefer the value stored by the last rectangular solve (see _jacobian_condest) when one exists: for nets with closed bus links the solver works on an internally contracted copy, which this standalone reconstruction cannot reproduce.

Throws an ArgumentError when the net has no slack bus among the active buses or fewer than two active buses.

reportCondition(J::AbstractMatrix{<:Real}; iter::Int = -1) -> Float64

Print the estimated condition number of a Newton-Raphson Jacobian together with the attainable relative accuracy (kappa * eps(Float64)) and a plain-language verdict, then return the estimate. Pass iter >= 0 to prefix the line with the Newton iteration number when logging inside a solver loop.

takahashi_diag(F) -> (diagZ::Vector, ok::Bool, info::String)

Compute the full diagonal of inv(A) from the UMFPACK factorization F of A via the Takahashi/Erisman-Tinney selected-inverse recurrences on the filled factor pattern: one backward pass over nnz(L) + nnz(U) entries instead of one triangular solve per column (measured 34x to 264x over the serial short-circuit sweep between n = 2000 and n = 16000, agreeing with direct solves to about 1e-15 relative). The element type follows the factorization (ComplexF64 for the short-circuit Ybus, Float64 for the SE gain matrix).

Applicability guard: requires the symmetric pivot ordering (F.p == F.q) that UMFPACK's symmetric strategy picks on structurally symmetric matrices; with an unsymmetric ordering the original-diagonal positions leave the factor pattern. Returns ok = false with the reason in info in that case (or on a zero pivot, a non-unit-lower L, or a pattern-closure violation, counted defensively); callers must fall back to direct solves.

takahashi_selected_inverse(F) -> (S::Union{Nothing,TakahashiSelectedInverse}, ok::Bool, info::String)

Same backward pass as takahashi_diag (identical guards and code path), but returns the FULL selected inverse on the factor pattern as a queryable TakahashiSelectedInverse: S[i, j] yields inv(A)[i, j] for any position inside the pattern and nothing outside. This is what the SE diagnostics need for Omega_ii: every G^-1 entry they look up sits at a structural nonzero of G itself, which is contained in the filled pattern of its factors, so no in-pattern lookup can miss.

_jacobian_condest(net::Net; warn_on_failure = true, context = "result output") -> Union{Nothing,Float64}

Jacobian condition estimate for reporting. Prefers the lazy estimate the last rectangular solve stored in its status (field jacobian_condest, a cached closure over the exact system the solver factored, including link contraction and Q-limit active-set state). Falls back to the standalone reconstruction condestJacobian(net) when no solver status carries one (e.g. APSLF or DC runs). Returns nothing when the estimate fails; the failure is logged as @warn (default) or @debug (warn_on_failure = false) with context as the message prefix, and never propagates into the report.

TakahashiSelectedInverse{T}

Queryable selected inverse from takahashi_selected_inverse: S[i, j] returns inv(A)[i, j] when the (permuted) position lies inside the filled factor pattern, and nothing outside it. Internally the entries live on the pattern of (L + U)^T in permuted coordinates; the stored permutation and row-scaling context map original indices back (inv(A)[i, j] = Z[pinv[i], pinv[j]] * Rs[j], since L*U == (Rs .* A)[p, p] scales the ROWS of A).