Crate powerio_matrix

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, LACPF, and petgraph 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. 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::MulticonductorAdmittance;
pub use matrix::multiconductor::MulticonductorNodeIndex;
pub use matrix::multiconductor::NodeRef;
pub use matrix::multiconductor::calc_multiconductor_admittance_matrix;
pub use matrix::BuildOptions;
pub use matrix::GroundedIndexMap;
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_lacpf_matrix;
pub use matrix::calc_lodf;
pub use matrix::calc_ptdf;
pub use matrix::calc_ptdf_lodf;
pub use matrix::calc_ptdf_lodf_with_options;
pub use matrix::calc_reference_indicator;
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: Synthetic MATPOWER style cases. Stress tests the matrix builders beyond the vendored matpower test set.

Structs§

AcBranchData: Branch data in active branch column order.
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.
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
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
Storage

Enums§

AnalysisBranchSource: The source component represented by one branch row in a lowered analysis network.
BranchSusceptanceFormula: Rule for the DC branch susceptance b.
BusType: Bus type per MATPOWER convention: 1=PQ, 2=PV, 3=ref/slack, 4=isolated.
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.
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.
Units: Unit system for power and generator cost data.
VoltageCoordinates: The voltage coordinate selection, the one option of the calculation.

Constants§

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, and phase shift 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_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.
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.
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.
lindist3flow_connection_incidence: Build the physical-channel incidence matrix for a typed connection.
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.