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
| matrix | shape | calculation | notes |
|---|---|---|---|
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_matrix | full 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_matrix | row \(e\) has \(+1\) at the from bus, \(-1\) at the to bus |
| DC branch susceptances \(b\) | \(m\) | DcOperators::calc_branch_susceptances | one 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_matrix | positive solver susceptance magnitudes times \(C^\mathsf{T}\); internal solver data |
| Per-island PTDF | one matrix per component | calc_ptdf_by_island | partitions one global PTDF solve and returns source bus/branch index mappings |
| PTDF | \(m \times n\) | calc_ptdf | routes through Auto solver selection; calc_ptdf_lodf_with_options exposes the choice |
| LODF | \(m \times m\) | calc_lodf | routes 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_columns | one 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_jacobian | polar or rectangular voltage coordinates |
| multiconductor admittance | conductor by conductor | calc_multiconductor_admittance_matrix | from a MulticonductorNetwork; Rust only in 0.11 |
| adjacency | \(n \times n\) | calc_adjacency_matrix | sparse graph adjacency |
| graph edges | one per in-service branch | IndexedNetwork::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
pgandqg, 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 unlessHvdcTreatment::Ignoreis 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), unlessLccReactivePower::Statedkeeps 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 aBUILD.STATED_STATE.LCC_MODEL_UNAVAILABLEwarning. The active powers stay the reader’spfandpt, which price the DC current differently from the bridge model (seepowerio_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
newtonpfdrives to zero. An injection equal to it closes the bus, andclosure_injections(mask)returns that injection at every bus carrying a flag inmask. - Flags. Each bus carries
StatedBusFlagsnaming 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, andlow_impedance_branch(a branch belowlow_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_klargest 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 withBUILD.SWITCH.CLOSED, as the PTDF and LODF builders refuse it. Merge the buses either joins first:BalancedNetwork::merge_busesin Rust, or--merge-buses switches(closed switches) or--merge-buses exact(and zero impedance branches) withpowerio 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)\), returningNonefor an unknown source ID. The matrix builders turn that intoError::UnknownBusat 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). MATPOWERBpclears bus shunts and line charging, sets tap magnitudes to one, and keeps phase shifts. MATPOWERBppkeeps 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::chargingis the stored per terminal admittance when present:g_fr,b_fr,g_to, andb_toare already per unit on the system base.Branch::bis the legacy MATPOWERBR_Btotal projection for formats that carry only one charging value. Matrix builders useBranch::calc_terminal_charging(), so terminal values feed \(Y_{\mathrm{bus}}\) even when the legacy total is zero or stale. -
FDPF scheme.
Schemeselects between the two MATPOWER fast decoupled forms.Xbclears resistance forBp;Bxclears resistance forBpp. The default isBx. -
Zero impedance branches.
BuildOptions::skip_zero_impedancecontrols the builders whose branch denominator can be zero. The defaultfalsereturnsError::ZeroImpedance;trueskips the branch and records the skipped source branch rows inMatrixStatsasskipped_zero_impedanceandskipped_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 recordsdropped_zero_impedanceingridfm_meta.json.BalancedNetwork::merge_busesresolves them explicitly instead, together with closed switches (see Merging buses). -
Reference coverage.
IndexedNetwork::check_reference_coverageverifies 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 (
ClosedSwitchPolicyonNormalizeSettingskeeps or refuses them instead), andmerge_busesmerges them on request (see Merging buses).IndexedNetwork::check_closed_switchesrefuses a network that skipped both withBUILD.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. ExplicitKeepremains for consumers that model switches themselves. -
Branch susceptance formulas.
BranchSusceptanceFormulaselects the branch susceptance vector \(b\) and, for formulas that include phase shifts, the phase shift injection. In the PowerModels form,DcOperators::calc_incidence_matrixreturns 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
SeriesSusceptanceuses \(b = -x/(r^2 + x^2)\), which takes the whole series impedance into account, plus the phase shift injection vectorp_shift. A tap does not scale it. It reduces to \(b = -1/x\) when the branch has no resistance.SeriesSusceptanceNoPhaseShiftuses 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.TapAdjustedSeriesSusceptancedivides that series coefficient by the effective transformer tap and includes phase shifts. It is the ignore-conductance convention; see the formula table.TapAdjustedReactancereproduces MATPOWER’smakeBdc: \(b = -1/(x\tau)\) for a transformer with tap ratio \(\tau\), plusp_shift.ReactanceOnlyis the textbook \(b = -1/x\) with resistance, taps, and shifts ignored. The resulting \(-B\) matches MATPOWERBpunderScheme::Xbwhen 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.