Rectangular Power Flow Reference

Map every bus to the representative of its closed-link cluster.

Links (busbar couplers, retained CGMES switches) are impedance-less: their two buses are one electrical node. The solver cannot represent a zero-impedance branch – it would make the Ybus singular – so such clusters are contracted onto a single representative bus before the Ybus is built.

Returns a vector reps with reps[bus] = representative bus. Buses without a closed link map to themselves, so reps == 1:n means "nothing to merge".

Return a working net in which all closed-link clusters are contracted.

Yields (wnet, reps, has_merges). When nothing has to be merged the ORIGINAL net is returned unchanged (has_merges == false) – callers must therefore not assume they own a private copy, and must consult has_merges before syncing results back through reps.

The contraction moves every cluster's injections onto its representative and marks the remaining cluster members Isolated. Bus indices deliberately stay untouched, so the caller can map results back one-to-one via reps.

Ordered rescue strategies for a non-converged AC solve. Each entry is a (name, config) pair derived from the failed run's configuration:

1. :alternate_start — toggle the flat-start flag: a stalled imported start often solves from flat, and a failed flat start may solve from the imported voltages.
2. :autodamp — adaptive damping with the default floor (skipped when the failed run already used autodamp; the competing trust-region step control is disabled for this attempt).
3. :dc_seed — flat voltage magnitudes with DC-projected start angles via the existing start-projection machinery.
4. :settled_qlimits — the globalization package for large, Q-limit-noisy systems: Armijo merit line search, a low damping floor, and Q-limit switching held back until the reactive requests have settled (qlimits.start_mode = :auto). Measured on an 82000-bus case whose Q limits are not even binding at the solution: the shipped early switching produced 8445 PV/PQ flips and diverged, this combination converges in ~60 iterations with the limits fully enforced.

runpf!(net, maxIte, tolerance=1e-6, verbose=0; method=:rectangular)

Unified AC power flow interface.

Arguments:

• net::Net: network
• maxIte::Int: maximum iterations
• tolerance::Float64: mismatch tolerance
• verbose::Int: verbosity level
• method::Symbol: must be :rectangular
• autodamp::Bool: enable residual-based backtracking for rectangular Newton steps
• autodamp_min::Float64: minimum automatic damping factor when autodamp = true
• linear_solver::Symbol: sparse linear-algebra backend for the Newton step, :umfpack (default) or :umfpack_reuse (symbolic-analysis reuse across iterations via lu!)
• qlimit_start_iter::Int: first Newton iteration where PV→PQ Q-limit switching may run in :iteration mode
• qlimit_start_mode::Symbol: :iteration, :auto, or :iteration_or_auto start criterion for PV→PQ switching
• qlimit_auto_q_delta_pu::Float64: PV reactive-power request change threshold for automatic switching start

Notes:

• Link-flow recovery (calcLinkFlowsKCL!) is method-agnostic and uses solved PF results.
• If active-link merges create internal isolated buses, the rectangular sparse solver remains the only supported PF path; there is no polar fallback.

Returns: (iterations::Int, status::Int) where status == 0 indicates convergence.