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.
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.
ConnectivityReport: Topological invariants the TUI Inspect screen and downstream solvers care about.
DcBranchParameters: Branch parameters in active branch column order.
DcGeneratorParameters: Generator parameters in generator column order.
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).
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.
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.
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.
emit_dcopf_bundle: Write matrix projections for a DC OPF instance.

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.