Skip to main content

Crate powerio_matrix

Crate powerio_matrix 

Source
Expand description

Sparse matrix and graph projections from PowerIO networks.

Outputs include signed incidence, weighted bus Laplacian, MATPOWER Bp/Bpp, Y bus, PTDF, LODF, adjacency, and LACPF views. Calculations take the dense IndexedNetwork view of a BalancedNetwork. Parsing and emitting belong to the top level powerio facade; this crate owns derived matrix and graph calculations.

use powerio_core::Source;
use powerio_matrix::{BuildOptions, IndexedNetwork, calc_bprime_matrix};
use powerio_tx::parse;

let net = parse(Source::open(case)?)?.into_value();
let g = IndexedNetwork::new(&net);           // dense [0, n) analysis view
let bprime = calc_bprime_matrix(&g, &BuildOptions::default())?;
assert_eq!(bprime.rows(), g.n());            // Bp is n×n

§Conventions

Public DC operators follow PowerModels: an inductive branch has negative b. Their branch by bus incidence matrix A_pm gives B = A_pmᵀ diag(b) A_pm, with nonpositive diagonals and nonnegative off-diagonals. Solver preparation retains its bus by branch factor A_s = A_pmᵀ and uses w = -b, so the sparse factor is the positive M-matrix L = A_s diag(w) A_sᵀ = -B. Source bus IDs remain on the model; IndexedNetwork maps them to dense indices in [0, n). tap == 0 means tap = 1. calc_bprime_matrix and calc_bdoubleprime_matrix follow MATPOWER makeB; Y_bus keeps tap magnitudes and phase shifts. Branch terminal admittance is stored per unit. The default public DC formula is b = -x/(r² + x²). BranchSusceptanceFormula::TapAdjustedReactance uses b = -1/(x·τ); both carry phase shift injection. BranchSusceptanceFormula::TapAdjustedSeriesSusceptance divides the series coefficient by the tap; BranchSusceptanceFormula::SeriesSusceptanceNoPhaseShift ignores taps and shifts to match PowerModels DCP. The full reference is in the matrix guide.

Re-exports§

pub use error::ElementCounts;
pub use error::Error;
pub use error::PiecewiseCostInvalidity;
pub use error::Result;
pub use error::ScenarioMismatch;
pub use matrix::multiconductor::AugmentedSystem;
pub use matrix::multiconductor::DistNode;
pub use matrix::multiconductor::GroundedNeutral;
pub use matrix::multiconductor::MulticonductorAdmittance;
pub use matrix::multiconductor::MulticonductorNodeIndex;
pub use matrix::multiconductor::NetworkPrimitives;
pub use matrix::multiconductor::NodeRef;
pub use matrix::multiconductor::PassiveFamily;
pub use matrix::multiconductor::PassivePrimitive;
pub use matrix::multiconductor::assemble_multiconductor_admittance;
pub use matrix::multiconductor::calc_capacitor_primitive_admittance;
pub use matrix::multiconductor::calc_line_primitive_admittance;
pub use matrix::multiconductor::calc_multiconductor_admittance_matrix;
pub use matrix::multiconductor::calc_passive_primitives;
pub use matrix::multiconductor::calc_shunt_primitive_admittance;
pub use matrix::multiconductor::scatter_primitive_admittance;
pub use matrix::BuildOptions;
pub use matrix::GroundedIndexMap;
pub use matrix::GroundedLaplacianFactor;
pub use matrix::Grounding;
pub use matrix::IslandPtdf;
pub use matrix::MatrixStats;
pub use matrix::Scheme;
pub use matrix::SensitivityMatrices;
pub use matrix::SensitivityMatrixMetadata;
pub use matrix::SensitivityMetadata;
pub use matrix::SensitivityOptions;
pub use matrix::SensitivitySolver;
pub use matrix::SensitivitySolverPath;
pub use matrix::ZeroImpedanceRule;
pub use matrix::ZeroImpedanceSkips;
pub use matrix::calc_adjacency_matrix;
pub use matrix::calc_admittance_matrix;
pub use matrix::calc_bdoubleprime_matrix;
pub use matrix::calc_bprime_matrix;
pub use matrix::calc_diagonal;
pub use matrix::calc_edge_flows;
pub use matrix::calc_edge_laplacian_product;
pub use matrix::calc_lacpf_matrix;
pub use matrix::calc_lodf;
pub use matrix::calc_lodf_columns;
pub use matrix::calc_ptdf;
pub use matrix::calc_ptdf_by_island;
pub use matrix::calc_ptdf_columns;
pub use matrix::calc_ptdf_lodf;
pub use matrix::calc_ptdf_lodf_with_options;
pub use matrix::calc_ptdf_rows;
pub use matrix::calc_reference_indicator;
pub use matrix::calc_solver_branch_flow_matrix;
pub use matrix::calc_susceptance_diagonal;
pub use matrix::calc_unit_vector;
pub use matrix::calc_weighted_laplacian;
pub use matrix::calc_zero_impedance_skips;
pub use matrix::check_sddm;
pub use matrix::ground_at;
pub use matrix::ground_at_each;
pub use pipeline::MatrixKind;
pub use pipeline::Pipeline;
pub use pipeline::PipelineOutputs;
pub use pipeline::RhsKind;
pub use pipeline::calc_matrix;
pub use pipeline::calc_matrix_stats_for_kind;
pub use pipeline::calc_zero_impedance_skips_for_kind;
pub use pipeline::sanitize_stem;
pub use pipeline::select_zero_impedance_rule_for_kind;
pub use io::gridfm::GridfmDataset;
pub use io::gridfm::GridfmOptions;
pub use io::gridfm::GridfmOutputs;
pub use io::gridfm::GridfmSnapshot;
pub use io::gridfm::GridfmTables;
pub use io::gridfm::build_gridfm_batch;
pub use io::gridfm::build_gridfm_dataset;
pub use io::gridfm::emit_gridfm_batch;
pub use io::gridfm::emit_gridfm_dataset;
pub use io::gridfm::number_snapshots;
pub use io::gridfm::to_gridfm_record_batches;
pub use io::gridfm::to_gridfm_record_batches_single;

Modules§

diagnostics
The codes this crate emits.
error
Failures the matrix and dataset builders raise.
io
File I/O: Matrix Market (.mtx) and JSON metadata, plus the gridfm-datakit Parquet export (--features gridfm).
matrix
Sparse matrix calculations for power system cases.
pipeline
Orchestrates a single case → output directory.
synth
Deterministic synthetic network generators.

Structs§

AcBranchData
Branch data in active branch column order.
AcBranchFlows
Terminal branch flows in active branch column order, in the preparation’s power unit: S_f = pf + j qf enters the branch at its from bus and S_t = pt + j qt at its to bus.
AcBusData
Bus data in dense bus order.
AcGeneratorData
Generator data in generator column order.
AcOpfAssemblyOptions
Assembly choices that select the numerical content derived from an AC instance without changing the instance itself. There is no convention field: the branch pi model always carries taps, shifts, and charging.
AcOpfPreparation
Matrix free AC OPF input data on the branch pi model.
AcPfAssemblyOptions
Assembly choices for an AC power flow instance.
AcPfBusData
Bus values needed to start and evaluate an AC power flow.
AcPfGeneratorData
Generator data used by PV to PQ reactive limit handling.
AcPfPreparation
Matrix free AC power flow input on the branch pi model.
AcStorageData
Storage data in active storage column order.
AffineScalarCoefficients
Real affine scalar constant + coefficients' * w.
BalancedNetwork
A balanced network with stable source bus IDs and separate element tables: an immutable cheap to clone owning handle over private shared tables.
Branch
Bus
BusId
A source bus ID, preserved from the input format.
BusPowerInjection
The bus power injection S = diag(V) conj(Y V) at one voltage point: p and q in bus row order, per unit on the admittance’s base. It also keeps the voltages, per bus angle cosines and sines, and currents I = Y V it was formed from, so PowerFlowJacobian::update_from_injection refreshes the Jacobian at the same point without recomputing them.
ClosureInjection
An injection that closes one bus’s stated-state mismatch.
ConnectionPowerMap
Reference-frozen map from physical channel powers to terminal powers.
ConnectivityReport
Topological invariants the TUI Inspect screen and downstream solvers care about.
CrossVoltageCoefficients
Affine closure c + a w_phi + b w_psi for one cross-voltage product.
DcBranchParameters
Branch parameters in active branch column order.
DcGeneratorParameters
Generator parameters in generator column order.
DcOperatorOptions
Build options for DcOperators.
DcOperators
DC matrix operations built once from an instance.
DcOpfAssemblyOptions
Assembly choices that select the numerical content derived from an instance without changing the instance itself.
DcOpfBundleMetadata
Cost policy information recorded in a bundle manifest.
DcOpfBundleOptions
Options that affect bundle output without changing the instance.
DcOpfMatrices
Sparse matrices for a DC OPF instance.
DcOpfOutputs
DcOpfPreparation
Matrix free DC OPF input data.
GenCost
A generator cost curve (mpc.gencost row).
Generator
Hvdc
IndexCore
The owned, network-independent derivation behind IndexedNetwork: the dense bus-id map plus the per-bus demand/shunt aggregates. Build it once with IndexCore::build and reuse it across many IndexedNetwork::with_core views of the same BalancedNetwork.
IndexedNetwork
A BalancedNetwork paired with its derived IndexCore. The network is borrowed for the common case, but owned when it had to be star-lowered (a 3-winding transformer expanded into a star bus plus three branches via BalancedNetwork::expand_transformers_3w); the core is owned (IndexedNetwork::new) or borrowed from a cached IndexCore (IndexedNetwork::with_core).
LinDist3FlowAffineExpression
An affine scalar over the prepared squared-voltage variables.
LinDist3FlowBalanceEquation
One equality expression constrained to zero.
LinDist3FlowBalanceRow
Active and reactive KCL at one retained bus terminal.
LinDist3FlowBalanceTerm
One coefficient on a semantic decision variable.
LinDist3FlowComplexAffinePower
Active and reactive affine power expressions.
LinDist3FlowConicProblem
Complete conic program structure in stable PowerIO variable order.
LinDist3FlowDeviceData
All device rows and the fully expanded nodal balances.
LinDist3FlowDispatchChannel
Bounds, objective coefficient, and SOC data for one dispatch channel.
LinDist3FlowEquality
One affine equality expression == 0.
LinDist3FlowGeneratorData
One dispatchable generator and its terminal allocation.
LinDist3FlowLineData
One coupled line block in the solver-neutral network data.
LinDist3FlowLinearExpression
constant + terms' * x in canonical variable order.
LinDist3FlowLinearTerm
One coefficient in a canonical affine expression.
LinDist3FlowLoadData
One physical load and its reference-frozen terminal allocation.
LinDist3FlowNetworkData
Numerical rows for the voltage, line-drop, and line SOC portion of L3F.
LinDist3FlowNodeData
One squared-voltage variable row in the solver-neutral network data.
LinDist3FlowPreparation
Complete solver-neutral preparation for the currently supported L3F slice.
LinDist3FlowScaling
Diagonal coordinate maps applied to the canonical SI program.
LinDist3FlowShuntData
One affine terminal shunt-power row.
LinDist3FlowSourceData
One voltage source. Its channel powers inject directly at corresponding terminals; the squared voltages are fixed in LinDist3FlowNetworkData.
LinDist3FlowStandardForm
Clarabel-compatible sparse conic data plus its semantic source model.
LinDist3FlowStandardFormOptions
Numerical coordinate choices for the sparse solver program.
LinDist3FlowVariableData
One variable column, including its native bound and objective data.
LinDist3FlowVoltageTerm
One coefficient on a squared-voltage variable.
LineDropCoefficients
Real coefficient blocks in w_child = w_parent - M p - N q.
Load
McAcOpfAssemblyOptions
Explicit system bases; no physical bound is inferred from these values.
McAcOpfPreparation
Canonical IVR coefficients. These contain no optimizer or expression types.
McOpfAngleLimit
Centered angle of V[first] * conj(V[second]), in radians.
McOpfBranch
A line or ideal switch, with dense local conductor matrices.
McOpfCoil
One two-terminal coil; a missing negative terminal means physical ground.
McOpfComplexRow
Complex affine expression with no constant term. Coefficients are [real, imaginary]. Voltage indices address preparation.terminals; current indices address the owning transformer’s coils. Rows of equations are constrained to zero.
McOpfDevice
McOpfDroop
Smooth clipped piecewise-linear controller, with SI-derived per-unit knots.
McOpfDroopHinge
One softplus corner of a droop curve: it adds coefficient · width · softplus((v − knot) / width) to the control power at the monitored voltage v (McOpfDroopTerms).
McOpfDroopTerms
A droop curve as a sum: constant + Σ hinges (McOpfDroop::calc_terms). A segment of zero slope adds no hinge.
McOpfDroopValue
The value and slope of a smoothed droop curve, and the response of both to a parameter direction (McOpfDroop::calc_parameter_derivative).
McOpfLoadLaw
A sum of voltage power laws: coefficient times (|U|/nominal)^exponent. Coefficients are per-unit power; exponents are dimensionless.
McOpfLoadLawProjection
One load whose voltage-bounded law was replaced by its nominal law.
McOpfShunt
McOpfTerminal
A source terminal in canonical bus/terminal order.
McOpfTransformer
Winding-current equations, ports and optional continuous tap parameter. Each row is equations[k] + t * tap_equations[k] = 0, where t is a dimensionless multiplier with nominal value one. The physical tap is tap_nominal * t, or tap_nominal / t when tap_inverse is true. An empty tap_equations vector means the descriptor is fixed.
McOpfTransformerCoil
A winding coil oriented from positive to negative, with a retained current unknown.
McOpfTransformerPort
A rated physical terminal/coil port reconstructed from winding currents.
McOpfVoltageLimit
A magnitude bound on a difference of terminal voltages, in per unit.
NodalAcGeneratorData
Generator data in dense bus order, aggregated over the generators at each bus. See AcOpfPreparation::calc_nodal_generator_data.
NodalGeneratorParameters
Generator parameters in dense bus order, aggregated over the generators at each bus. See DcOpfPreparation::calc_nodal_generator_data.
PiecewiseLinearCost
One convex piecewise linear generator cost in preparation units.
PowerFlowJacobian
The assembled sparse physical Jacobian, with its bus mappings and the machinery to update values in place.
ReferenceConstrainedSystem
The reference constrained linear system: the positive definite matrix a sparse solver factors, its right hand side, and the mapping from reduced rows back to bus rows.
Shunt
StatedBranchFlows
Active and reactive power entering every analysis branch at both ends, at the stored voltages, from calc_stated_branch_flows.
StatedBusFlags
Equipment at a bus that a stated-state residual is commonly traced to.
StatedBusMismatch
The balance at one bus.
StatedIslandMismatch
The balance summed over one island of the in service topology.
StatedStateMismatch
The AC bus balance at the stored voltages, from calc_stated_state_mismatch.
StatedStateOptions
Options for calc_stated_state_mismatch.
Storage
TransformerPrimitive
A finite leakage transformer’s primitive admittance, siemens, over its physical terminals.

Enums§

AnalysisBranchSource
The source component represented by one branch row in a lowered analysis network.
AngleDifferenceBounds
Which angle difference bounds an OPF or power flow preparation carries.
BoundedLoadLawPolicy
What preparation does with a voltage-bounded load law.
BranchSusceptanceFormula
Rule for the DC branch susceptance b.
BusType
Bus type per MATPOWER convention: 1=PQ, 2=PV, 3=ref/slack, 4=isolated.
LccReactivePower
Where a line-commutated (LCC) converter’s reactive demand comes from in calc_stated_state_mismatch.
LinDist3FlowCone
A standard or rotated second-order cone over affine arguments.
LinDist3FlowConeOrigin
Physical origin and meaning of one cone row block.
LinDist3FlowDecisionVariable
Stable semantic identity of one scalar decision variable.
LinDist3FlowEqualityOrigin
Physical origin of one equality constrained to zero.
LinDist3FlowStandardCone
One contiguous cone block in standard-form row order.
LinDist3FlowStandardRowOrigin
Semantic provenance for one row of A and b.
LinDist3FlowVariable
Semantic scalar variables used by nodal-balance rows.
McOpfDeviceKind
Distinguishes demand (positive consumption) from injection device tables.
PreparedAcBusSpecification
One AC power flow bus specification in preparation units.
PreparedObjective
The objective compiled into a balanced OPF preparation.
SourceFormat
Which format a BalancedNetwork was read from. Drives the same format byte exact echo on write.
SynthesizedLimitWindow
Which angle difference interval a synthesized thermal limit (Branch::synthesize_rate_a) spans for a branch the source left unrated.
TransformerLeakageBase
The unit system a transformer states its leakage in, which calc_transformer_leakage_impedances reads.
Units
Unit system for power and generator cost data.
VoltageCoordinates
The voltage coordinate selection, the one option of the calculation.

Constants§

MC_OPF_DROOP_SMOOTHING
The softplus width of a prepared droop curve as a share of its mean knot voltage: epsilon = MC_OPF_DROOP_SMOOTHING · mean(knots), so a knot moved by dk widens every corner by MC_OPF_DROOP_SMOOTHING · dk / n. The one smoothing rule: the preparation sets it and the curve’s parameter sensitivities differentiate it.
POWER_MODELS_ANGLE_BOUND_PAD
Default branch angle difference bound used by PowerModels parse time repair.

Functions§

build_ac_opf_preparation
Derive the complete matrix free AC OPF arrays from the instance: demand, shunt, and voltage columns per bus, the full pi model per active branch, and generator costs, bounds, and schedules with their source row mapping. The AC counterpart of build_dc_opf_preparation.
build_ac_pf_preparation
Derive the complete matrix free AC power flow arrays from an instance. The caller’s bus specifications remain authoritative. Network bus types are used only by AcPfInstance::from_network when it creates those specifications; this function does not infer them again.
build_dc_opf_preparation
Derive the complete matrix free DC OPF arrays from the instance: demand, shunt, phase shift, and HVDC withdrawals, generator costs and bounds with their source row mapping, branch susceptances as positive solver edge weights, thermal limits, angle bounds, and the reference bus set. This is the one numerical assembly the matrix builders, the bundle writer, and external solvers read, published so each consumer formulates over the same arrays instead of re-deriving them from the network. DcOpfPreparation documents each field’s unit and sign.
build_lindist3flow_conic_problem
Assemble the complete supported LinDist3Flow slice as a canonical conic program.
build_lindist3flow_device_data
Prepare load, shunt, generator, source, objective, and KCL rows against an already prepared L3F node/line axis.
build_lindist3flow_network_data
Prepare the voltage, coupled line-drop, and line-limit rows of an L3F instance in SI units.
build_lindist3flow_pf_conic_problem
Compile the fixed-dispatch electrical equations. The instance constructor has already removed conductor limits from the enforced constraint set and replaced the objective with zero.
build_lindist3flow_pf_standard_form
Compile the fixed-dispatch problem in the default scaled standard form.
build_lindist3flow_pf_standard_form_with_options
Compile the fixed-dispatch problem with explicit numerical scaling.
build_lindist3flow_preparation
Build the complete solver-neutral preparation for the supported L3F slice.
build_lindist3flow_standard_form
Compile a LinDist3Flow instance in the default per-unit coordinates using a 1 MVA system power base. Input, canonical data, and decoded results remain SI.
build_lindist3flow_standard_form_with_options
Compile sparse standard form using explicit SI or per-unit solver coordinates.
build_mc_ac_opf_preparation
Prepare the AC multiconductor IVR profile without creating solver expressions.
calc_bus_hosts
Which of n_buses buses host at least one element of bus_of.
calc_bus_power_injection
The complex power injection S = diag(V) conj(Y V) at every bus, split into active and reactive parts (p, q), at the voltages vm (per unit) and va (radians) in the admittance matrix’s bus order. The injections are the ones the Jacobian of PowerFlowJacobian::from_admittance differentiates, formed by the same calculation as PowerFlowJacobian::calc_bus_power_injection; a solver that holds a Jacobian calls that method instead, which reuses its merged admittance.
calc_bus_totals
The per bus totals of an element column: values[e] added to bus bus_of[e] for each element, in element order, over n_buses buses. The one sum of a generator (or any element) column onto buses: the nodal generator data of the DC and AC preparations reads it, and a caller summing scheduled outputs or reactive limits by bus calls it.
calc_dc_opf_matrices
Derive the sparse DC OPF matrices from the instance. The instance keeps the typed network; an external solver that needs the contiguous arrays behind these matrices calls build_dc_opf_preparation instead.
calc_power_flow_jacobian
Compute the sparse physical AC power flow Jacobian for instance at point.
calc_prepared_bus_specifications
The instance’s bus specifications in preparation units, one per source bus row: power scaled by units over the network’s per unit base (one for a normalized network), reference angles in radians. This is the conversion build_ac_pf_preparation applies; a caller that keeps its own bus index reads the same values here without building the preparation.
calc_reference_constrained_system
The reference constrained linear system of a DC power flow over a bus Laplacian L with positive branch weights: L with the reference rows and columns removed, and at each retained row the right hand side injection - (L va_ref), where va_ref holds each reference row’s angle, radians, and zero elsewhere. injection is the full length nodal power the angles must carry (net injection less every fixed withdrawal), per unit; reference_va is aligned with reference_rows. Solving matrix · va = rhs gives the retained angles with each reference fixed at its stated angle. DcOperators::calc_reference_constrained_system is this over the instance’s operators.
calc_stated_branch_flows
Calculate the active and reactive power entering every analysis branch at both ends, at the voltages net stores.
calc_stated_state_mismatch
Calculate the AC bus balance at the voltages net stores, with every device at its stated output.
calc_transformer_leakage_impedances
The pairwise leakage impedances of a multiwinding transformer, referred to the first winding: for windings a and b, on a per winding base B_a and a reference base B_ref,
calc_transformer_primitive_admittance
The primitive admittance of a finite leakage transformer, siemens, over its physical terminals, following the OpenDSS CalcY_Terminal path: the winding domain Y_1Volt (calc_transformer_winding_admittance, the inverse of the reduced pairwise leakage of calc_transformer_leakage_impedances) is referred to each phase’s coils through the turns and base factors,
calc_transformer_winding_admittance
The winding domain admittance Y_1Volt of a multiwinding transformer, siemens at a one volt winding base (OpenDSS CalcY_Terminal): the pairwise nameplate leakage impedances of calc_transformer_leakage_impedances scaled by phases / S_1, reduced against the last winding (calc_reduced_leakage), inverted, and lifted back through the winding difference incidence A (row i is u_i - u_n): Y_1Volt = Aᵀ ZB⁻¹ A. A two winding unit reduces to y · [[1, -1], [-1, 1]]. None when the reduced matrix is exactly singular or not finite: one volt base impedances of high rating units sit far below any fixed pivot threshold, so only exact singularity is refused.
connection_power_map
Construct H = diag(vbar) D' diag(D vbar)^-1.
cross_voltage_coefficients
Form the fixed-angle first-order closure of v_phi * conj(v_psi).
emit_dcopf_bundle
Write matrix projections for a DC OPF instance.
evaluate_affine
Evaluate a real affine scalar.
evaluate_cross_voltage
Evaluate a cross-voltage affine closure at two squared magnitudes.
evaluate_lindist3flow_pf_limits
Evaluate every supported line thermal limit at a fixed-dispatch point. Values and limits are returned in SI units: volt amperes and amperes. Current is evaluated independently at both physical line endpoints as hypot(P,Q) / |V|. Parallel switch contacts remain separate prepared lines, so crossed ratings cannot be relaxed by aggregation.
lindist3flow_connection_incidence
Build the physical-channel incidence matrix for a typed connection.
lindist3flow_pf_values_from_primal
Decode a canonical SI primal for a fixed-dispatch instance.
lindist3flow_pf_values_from_standard_primal
Decode a scaled standard-form primal for a fixed-dispatch instance.
lindist3flow_values_from_primal
Translate a canonical primal vector back to formulation-ordered physical values suitable for powerio_prob::LinDist3FlowOpfSolution.
lindist3flow_values_from_standard_primal
Decode a solver-coordinate primal vector into physical SI values.
line_drop_coefficients
Construct the line voltage-drop blocks for a complex series impedance.
winding_voltage_coefficients
Form real affine coefficients for the squared winding voltage |d v|^2.

Type Aliases§

Extras
Source format fields the neutral model does not name, kept for round trips and cross format conversion. Keys are field names; values are JSON scalars.
SparseMatrix
Compressed sparse row matrix used by the projection calculations.