Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Matrices and graphs

powerio-matrix calculates sparse matrices and graph data from parsed networks. Source bus identifiers are not dense indices, so each result comes with the element mapping you need to read its rows and columns, and the dense [0, n) index space exists only inside a result that says which bus each index is.

powerio-prob owns the calculation instances and builds no matrices itself; the matrix crate turns those instances into sparse operators. The files of the DC OPF bundle are defined in DC OPF bundle, and the Rust API is documented in the crate reference.

Capabilities

matrixshapecalculationnotes
MATPOWER Bp (FDPF)\(n \times n\)calc_bprime_matrix-Im(Y_bus) after the makeB Bp edits
MATPOWER Bpp (FDPF)\(n \times n\)calc_bdoubleprime_matrix-Im(Y_bus) after the makeB Bpp edits
\(\Re(Y_{\mathrm{bus}})\), \(-\Im(Y_{\mathrm{bus}})\)\(n \times n\)calc_admittance_matrixfull admittance, keeps taps and shifts
LACPF (linear AC power flow) block\(2n \times 2n\)calc_lacpf_matrix\(\begin{bmatrix}G & -B \\ -B & -G\end{bmatrix}\), flat start, indefinite
PowerModels DC incidence \(A\)\(m \times n\)DcOperators::calc_incidence_matrixrow \(e\) has \(+1\) at the from bus, \(-1\) at the to bus
DC branch susceptances \(b\)\(m\)DcOperators::calc_branch_susceptancesone signed susceptance per in service branch
DC branch flow matrix \(B_f\)\(m \times n\)DcOperators::calc_branch_flow_matrix\(B_f = \operatorname{diag}(b)A\)
DC bus susceptance \(B\)\(n \times n\)DcOperators::calc_bus_susceptance_matrix\(B = A^\mathsf{T}\operatorname{diag}(b)A\)
DC branch phase shift injection\(m\)DcOperators::calc_branch_phase_shift_injection\(b .* shift\)
DC bus phase shift injection \(p_{shift}\)\(n\)DcOperators::calc_bus_phase_shift_injection\(p_{shift} = A^\mathsf{T}(b .* shift)\)
DC bus injection \(p_{bus}\)\(n\)DcOperators::calc_bus_injection_dc\(p_{bus} = -Bv_a + p_{shift}\)
weighted bus factor \(L\)\(n \times n\)calc_weighted_laplacian\(L = C \operatorname{diag}(w) C^\mathsf{T}\); internal solver data
solver branch flow matrix\(m \times n\)calc_solver_branch_flow_matrixpositive solver susceptance magnitudes times \(C^\mathsf{T}\); internal solver data
Per-island PTDFone matrix per componentcalc_ptdf_by_islandpartitions one global PTDF solve and returns source bus/branch index mappings
PTDF\(m \times n\)calc_ptdfroutes through Auto solver selection; calc_ptdf_lodf_with_options exposes the choice
LODF\(m \times m\)calc_lodfroutes through Auto solver selection; option based builds can prune small output entries
selected PTDF rows, PTDF columns, LODF columns\(k \times n\), \(m \times k\), \(m \times k\)calc_ptdf_rows, calc_ptdf_columns, calc_lodf_columnsone solve per requested row or column, in the order requested; the full matrices are never formed
AC power flow Jacobian\(2n \times 2n\)calc_power_flow_jacobianpolar or rectangular voltage coordinates
multiconductor admittanceconductor by conductorcalc_multiconductor_admittance_matrixfrom a MulticonductorNetwork; Rust only in 0.11
adjacency\(n \times n\)calc_adjacency_matrixsparse graph adjacency
graph edgesone per in-service branchIndexedNetwork::branch_edges(branch, from, to) over dense bus indices

PTDF and LODF need a linear solve, and calc_ptdf, calc_lodf, calc_ptdf_lodf, and the option based calc_ptdf_lodf_with_options all go through the same solver selection. You pick the path with SensitivitySolver, the solver field on SensitivityOptions. Dense forces the dense grounded factorization. Sparse factors the grounded DC bus susceptance matrix once and reuses that factorization for every right hand side. Auto picks dense up to a reduced dimension of 512 (with a memory ceiling) and sparse above it. The sparse path avoids forming the \((n-r) \times (n-r)\) dense inverse, though the PTDF and LODF outputs themselves can still be large. With positive internal factor weights w = -b the grounded matrix L = -B is positive definite and the sparse path uses a Cholesky factorization. A negative weight, a series capacitor’s, can make it indefinite; the sparse path then uses LDLᵀ, and LU with partial pivoting when that fails, reported as the sparse_ldlt and sparse_lu solver paths. Each factorization must solve a probe right hand side with a normwise backward error below 1e-10 and a relative forward error below 1e-4; a matrix every factorization fails is refused as singular. Every connected component must contain at least one reference bus.

When only some branches or buses matter, calc_ptdf_rows(case, options, branches), calc_ptdf_columns(case, options, buses), and calc_lodf_columns(case, options, outaged) return just those rows or columns, indexed by dense branch and bus index in the order requested. They factor once and solve one right hand side per requested row or column, so a 100k bus case never forms its \(m \times n\) PTDF or \(m \times m\) LODF. The DC OPF bundle (\(A\), \(b\), \(L\), costs, bounds, thermal limits, \(C_g\)) is prepared from a DcOpfInstance and documented in DC OPF bundle.

Bp and Bpp are the fast decoupled power flow matrices from MATPOWER makeB. Solvers reduce Bp to PV+PQ buses for active power mismatch to voltage angle updates, and reduce Bpp to PQ buses for reactive power mismatch to voltage magnitude updates. PowerIO exports the full \(n \times n\) matrices so you can apply your own bus type reduction.

The public DC calculations live on DcOperators: calc_incidence_matrix, calc_branch_susceptances, calc_bus_susceptance_matrix, calc_branch_flow_matrix, calc_branch_phase_shift_injection, calc_bus_phase_shift_injection, calc_bus_injection_dc, and calc_branch_flow_dc. A calc_* name means the call computes a new result; a plain noun is a stored field or a borrowed accessor. The incidence matrix follows PowerModels, branches by buses, with \(+1\) at the from bus and \(-1\) at the to bus, and the phase shift injection is a separate result. The sensitivity and DC OPF builders use a transposed incidence factor internally, and that factor stays internal rather than becoming a second public incidence API.

Stated-state balance

A case saved from a converged power flow stores bus voltages that balance its injections. calc_stated_state_mismatch evaluates every bus’s AC balance at those stored voltages, with each device at its stated output, so a residual points at equipment PowerIO reads differently from the program that solved the case.

  • Network side. Every in service branch and three winding transformer winding at its stated tap and shift, and every in service fixed and switched shunt at its stated admittance, through the same branch admittances as calc_admittance_matrix.
  • Device side. Generators at their stated pg and qg, loads through their voltage model at the stored magnitude, static VAR compensators and storage at their stated terminal power, and HVDC lines as fixed injections unless HvdcTreatment::Ignore is selected. Each converter of a line read from a PSS/E two-terminal record draws the reactive power its bridge equations give at the stored AC voltages (Hvdc::calc_lcc_operating_point: firing and extinction angles, overlap, and the fundamental power factor), unless LccReactivePower::Stated keeps the line’s stated reactive powers. A record that reaches no operating point at a positive power factor keeps the stated reactive powers too, with a BUILD.STATED_STATE.LCC_MODEL_UNAVAILABLE warning. The active powers stay the reader’s pf and pt, which price the DC current differently from the bridge model (see powerio_tx::lcc).
  • Sign. A bus mismatch is the power the network draws at the stored voltages minus the stated injection, MW and MVAr, the mismatch MATPOWER’s newtonpf drives to zero. An injection equal to it closes the bus, and closure_injections(mask) returns that injection at every bus carrying a flag in mask.
  • Flags. Each bus carries StatedBusFlags naming the attached equipment a residual is commonly traced to: hvdc, vsc, facts, generator_on_pq_bus, star_bus, merged_group, voltage_dependent_load, switched_shunt, reference, storage, and low_impedance_branch (a branch below low_impedance_threshold, default (10^{-3}) per unit, whose flow the rounding of the stored voltages can move).
  • Totals. The result sums each island of the in service topology, largest first, and ranks the top_k largest bus mismatches. A bus typed isolated has no balance and belongs to no island.
  • Refusal. The stored voltages do not determine the flow through a branch with zero series impedance, so such a branch is refused with Error::UnmergedZeroImpedance. The balance stamps branches only, so a closed switch joining two buses is refused with BUILD.SWITCH.CLOSED, as the PTDF and LODF builders refuse it. Merge the buses either joins first: BalancedNetwork::merge_buses in Rust, or --merge-buses switches (closed switches) or --merge-buses exact (and zero impedance branches) with powerio verify --stated-state.

calc_stated_branch_flows returns the active and reactive power entering both ends of every branch and winding at the stored voltages. From the command line, powerio verify case.raw --stated-state prints the island totals and the largest bus mismatches with their flags, and Python exposes both calculations on BalancedNetwork.

GridFM datasets

Reading and writing GridFM needs the gridfm cargo feature; the CLI and the Python wheel are built with it. The export is a Parquet dataset under <case>/raw/ with bus_data, gen_data, branch_data, and y_bus_data. A single parsed case writes one scenario. A scenario batch stacks the rows of snapshots that share the same element set, with the scenario column as the key; to build one you need unique scenario ids, one system base, and bus, branch, and generator row IDs that match across the snapshots. Column names and units follow the GridFM data kit output schema.

Reading a GridFM dataset recovers everything its balanced tables hold: bus types, voltages and limits; nodal load and shunt totals; generator dispatch, bounds, and quadratic costs; branch parameters and terminal flows; and base_mva. Dense bus indices, nodal demand, and a fixed quadratic cost triple are how the GridFM tables are laid out, so reading them reports no conversion loss.

Writing a richer network into GridFM reports each projection the format forces: bus renumbering, several load or shunt records aggregated into one, equipment and metadata left out, costs that do not fit the fixed quadratic columns, and terminal flows evaluated from bus voltages when the source has no branch solution. A GridFM dataset read and written back without an edit in between produces none of these findings.

Conventions

  • Weighted bus solver factors. Stored nonzero off-diagonal entries are negative; diagonals are nonnegative and positive for buses incident to a positive weight branch. For \(L = C \operatorname{diag}(w) C^\mathsf{T}\) with nonnegative branch weights \(w\), \(L_{ii} = \sum_j \lvert L_{ij} \rvert\). This is the M-matrix form an SDDM (symmetric diagonally dominant M-matrix) or Cholesky solver expects once the grounded matrix is positive definite; a consumer can recover an edge weight as \(-L_{ij} > 0\).

  • Bus indexing. Source bus IDs are preserved on the model as a newtype and need not be contiguous. IndexedNetwork::bus_index(id) maps them into dense zero based indices in \([0,n)\), returning None for an unknown source ID. The matrix builders turn that into Error::UnknownBus at the point they need a bus that is not in the network.

  • Taps and shifts. \(\mathrm{tap} = 0\) means \(\mathrm{tap} = 1\) (Branch::calc_effective_tap). MATPOWER Bp clears bus shunts and line charging, sets tap magnitudes to one, and keeps phase shifts. MATPOWER Bpp keeps bus shunts, line charging, and tap magnitudes while clearing phase shifts. \(Y_{\mathrm{bus}}\) keeps both tap magnitudes and phase shifts.

  • Branch shunt admittance is stored per unit. Branch::charging is the stored per terminal admittance when present: g_fr, b_fr, g_to, and b_to are already per unit on the system base. Branch::b is the legacy MATPOWER BR_B total projection for formats that carry only one charging value. Matrix builders use Branch::calc_terminal_charging(), so terminal values feed \(Y_{\mathrm{bus}}\) even when the legacy total is zero or stale.

  • FDPF scheme. Scheme selects between the two MATPOWER fast decoupled forms. Xb clears resistance for Bp; Bx clears resistance for Bpp. The default is Bx.

  • Zero impedance branches. BuildOptions::skip_zero_impedance controls the builders whose branch denominator can be zero. The default false returns Error::ZeroImpedance; true skips the branch and records the skipped source branch rows in MatrixStats as skipped_zero_impedance and skipped_zero_impedance_branches. Full AC admittance builders use \(r^2 + x^2\). DC incidence and the DC OPF use \(r^2 + x^2\) under the formulas that read resistance (series_susceptance, tap_adjusted_series_susceptance, series_susceptance_no_phase_shift) and \(x\) under the reactance formulas; reactance only FDPF forms use \(x\). The gridfm export still zeros its admittance and flow columns for these rows and records dropped_zero_impedance in gridfm_meta.json. BalancedNetwork::merge_buses resolves them explicitly instead, together with closed switches (see Merging buses).

  • Reference coverage. IndexedNetwork::check_reference_coverage verifies that every in service island has a reference bus. Islands are joined by in service branches and closed switches.

  • Closed switches. The builders stamp branches only, so on a network that still carries a closed switch they leave its two buses apart. Normalization merges closed switches by default (ClosedSwitchPolicy on NormalizeSettings keeps or refuses them instead), and merge_buses merges them on request (see Merging buses). IndexedNetwork::check_closed_switches refuses a network that skipped both with BUILD.SWITCH.CLOSED, counting the closed switches. Default merging also fails with that code if it cannot eliminate an eligible closed switch, such as a connection between two windings of one three winding transformer. It reports original source rows and returns no partial normalized network. Explicit Keep remains for consumers that model switches themselves.

  • Branch susceptance formulas. BranchSusceptanceFormula selects the branch susceptance vector \(b\) and, for formulas that include phase shifts, the phase shift injection. In the PowerModels form, DcOperators::calc_incidence_matrix returns the \(m \times n\) branch by bus matrix \(A_{pm}\). Each branch row has \(+1\) at the from bus and \(-1\) at the to bus. The signed matrix combines with \(b\) to form the direct PowerModels operators \(B = A_{pm}^\mathsf{T} \operatorname{diag}(b) A_{pm}\) and \(B_f = \operatorname{diag}(b) A_{pm}\). The phase shift injection is \(p_{shift} = A_{pm}^\mathsf{T}(b \circ shift)\), so \(p_{bus}=-B\theta+p_{shift}\). \(b\) is negative for an inductive branch, the PowerModels series susceptance sign.

    Solver preparation retains the \(n \times m\) bus by branch factor \(A_s=A_{pm}^\mathsf{T}\). It uses the positive factor weight \(w=-b\), so its sparse matrix is \(L=A_s \operatorname{diag}(w) A_s^\mathsf{T}=-B\). The two orientations have separate names so that a transposition cannot slip across a language boundary unnoticed.

    The default SeriesSusceptance uses \(b = -x/(r^2 + x^2)\), which takes the whole series impedance into account, plus the phase shift injection vector p_shift. A tap does not scale it. It reduces to \(b = -1/x\) when the branch has no resistance.

    SeriesSusceptanceNoPhaseShift uses the same series coefficient but drops phase shifts as well as taps, matching PowerModels DCP on the same branch orientation and impedance reference side. PowerModels’ parsing can reverse antiparallel transformers and rescale their impedances, changing this tap-ignoring coefficient; see the orientation caveat. The unchanged default is also not identical to DCP on phase-shifting branches.

    TapAdjustedSeriesSusceptance divides that series coefficient by the effective transformer tap and includes phase shifts. It is the ignore-conductance convention; see the formula table.

    TapAdjustedReactance reproduces MATPOWER’s makeBdc: \(b = -1/(x\tau)\) for a transformer with tap ratio \(\tau\), plus p_shift.

    ReactanceOnly is the textbook \(b = -1/x\) with resistance, taps, and shifts ignored. The resulting \(-B\) matches MATPOWER Bp under Scheme::Xb when phase shifts are zero.

Output

Matrices are written as Matrix Market files or kept in memory. A symmetric matrix is stored as its lower triangle with the symmetric header and 1-based indices (io::mtx::emit_mtx). The sensitivities command writes <case>_ptdf.mtx, <case>_lodf.mtx, and <case>_sensitivity_meta.json. Pick the branch susceptance formula with --formula series-susceptance|tap-adjusted-reactance|reactance-only|tap-adjusted-series-susceptance|series-susceptance-no-phase-shift, the PTDF/LODF solve path with --solver dense|sparse|auto, and drop entries whose absolute value is at or below a threshold with --drop-tolerance <value>. On the sparse path the CLI writes the retained Matrix Market coordinates through temp files rather than holding the full sparse output in memory; the Rust calc_ptdf_lodf_with_options API still returns CsMat values and is meant for outputs that fit in memory. The metadata file lists the requested solver, the solver path used, matrix dimensions, nonzero counts, the tolerance, and how many entries were dropped. The dcopf subcommand writes its matrix family together with a JSON manifest.

The standard case solver property fixture lives at powerio-matrix/tests/fixtures/solver_matrix_stats.json. It holds bprime, bdoubleprime, and ybus_imag stats for case9, case14, case30, case57, and case118: n, nnz, min diagonal, M-matrix sign pattern, diagonal dominance margin, zero impedance skips, row sum checks, SPD checks, and a condition estimate when the solver input is SPD.

IndexedNetwork::branch_edges yields in-service branches as undirected edges (branch, from, to), with branch an index into the branch table and from and to dense bus indices. Parallel branches stay separate edges. Build a graph by adding view.n() nodes, including buses with no in-service branch, then one edge per item. The iterator does not include closed switches. The connectivity report and radial check also account for closed switches from IndexedNetwork::closed_switches. To build an equivalent graph, add those switch edges after mapping their bus IDs through bus_index, or merge closed switches before building the graph.

calc_ptdf_by_island returns one sparse PTDF per connected component. It uses the same single factorization and global solve as the ordinary PTDF builder, then scatters stored entries into component-local matrices in one pass. Each result carries dense source bus indices and source branch indices so callers can relate local matrix rows and columns back to the network. Closed switches must be merged before this call; the DC incidence matrix models branches, not unmerged switch connections.