Crate powerio_matrix

Expand description

powerio-matrix: sparse matrices and graph views for power system case files, built on powerio (re-exported, so one use powerio_matrix::... pulls in both layers).

Signed incidence A, weighted Laplacian L = A diag(b) Aᵀ and its reference-grounded form, B’/B’’/Y_bus, PTDF/LODF, adjacency, the LACPF block, and the DC OPF instance bundle, plus a petgraph view. The builders take the dense-indexed IndexedNetwork view of a Network.

use powerio_matrix::{parse_file, IndexedNetwork, build_bprime, BuildOptions};

let net = parse_file(case, None)?.network;   // re-exported from powerio
let g = IndexedNetwork::new(&net);           // dense [0, n) analysis view
let bprime = build_bprime(&g, &BuildOptions::default())?;
assert_eq!(bprime.rows(), g.n());            // B' is n×n

§Conventions

B’ and the Laplacians use the positive (M-matrix) form: off-diagonal < 0, diagonal > 0, diag = Σ|off-diag|. Bus ids are 1-based on the model; IndexedNetwork maps them to a dense [0, n). tap == 0 means tap = 1; B’ ignores taps and shifts, B’’ keeps taps and zeros shifts, Y_bus keeps both. Branch charging susceptance is stored per unit. DC OPF is bus indexed (p_g ∈ ℝⁿ), default susceptance b = 1/x, with DcConvention::Matpower the 1/(x·τ) plus phase-shift variant. The full reference across every matrix is in docs/matrices.md.

Re-exports§

pub use matrix::BuildOptions;
pub use matrix::BusCosts;
pub use matrix::DcConvention;
pub use matrix::GenCosts;
pub use matrix::GroundedIndexMap;
pub use matrix::IncidenceParts;
pub use matrix::MatrixStats;
pub use matrix::OpfInstance;
pub use matrix::Scheme;
pub use matrix::Units;
pub use matrix::build_adjacency;
pub use matrix::build_bdoubleprime;
pub use matrix::build_bprime;
pub use matrix::build_flow_map;
pub use matrix::build_incidence;
pub use matrix::build_lacpf;
pub use matrix::build_lodf;
pub use matrix::build_opf_instance;
pub use matrix::build_ptdf;
pub use matrix::build_ptdf_lodf;
pub use matrix::build_weighted_laplacian;
pub use matrix::build_ybus;
pub use matrix::ground_at;
pub use matrix::ground_at_each;
pub use matrix::reference_indicator;
pub use matrix::sddm_check;
pub use matrix::susceptance_diag;
pub use matrix::unit_vector;
pub use opf_pipeline::DcOpfOptions;
pub use opf_pipeline::DcOpfOutputs;
pub use opf_pipeline::write_dcopf_bundle;
pub use pipeline::MatrixKind;
pub use pipeline::Pipeline;
pub use pipeline::PipelineOutputs;
pub use pipeline::RhsKind;
pub use pipeline::build_kind;
pub use io::gridfm::GridfmOptions;
pub use io::gridfm::GridfmOutputs;
pub use io::gridfm::GridfmRead;
pub use io::gridfm::GridfmSnapshot;
pub use io::gridfm::GridfmTables;
pub use io::gridfm::gridfm_base_case;
pub use io::gridfm::gridfm_record_batches;
pub use io::gridfm::gridfm_record_batches_batch;
pub use io::gridfm::gridfm_scenario_ids;
pub use io::gridfm::numbered_snapshots;
pub use io::gridfm::read_gridfm_dataset;
pub use io::gridfm::read_gridfm_network;
pub use io::gridfm::read_gridfm_scenarios;
pub use io::gridfm::write_gridfm_batch;
pub use io::gridfm::write_gridfm_dataset;
pub use io::dataset_scenario_ids;
pub use io::read_dataset_dir;

Modules§

error
format: Readers and writers for supported case formats, all meeting at Network.
indexed: IndexedNetwork: the dense-indexed analysis view over a Network.
io: File I/O: Matrix Market (.mtx) and JSON metadata, plus the gridfm-datakit Parquet export (--features gridfm).
matrix: Sparse matrix builders for MATPOWER cases.
network: Format-neutral network model: the hub every converter meets at.
opf_pipeline: Writes the static DC OPF bundle for a case: one directory of named Matrix Market files plus a JSON manifest.
pipeline: Orchestrates a single case → output directory.
synth: Synthetic MATPOWER style cases. Stress tests the matrix builders beyond the vendored matpower test set.

Structs§

Branch
Bus
BusId: A bus identifier as it appears in the source file: the external, stable id (1-based in MATPOWER, and possibly sparse; pegase has gaps in its ids). Distinct from the dense [0, n) analysis index, which only IndexedNetwork produces, via bus_index. The two are both integers and trivially confused; making the id its own type stops one being used where the other is meant (using a 1-based id to index a matrix is off-by-one on a contiguous case and pure garbage on a sparse one).
ConnectivityReport: Topological invariants the TUI Inspect screen and downstream solvers care about.
Conversion: Output of a conversion: the serialized text plus any fidelity warnings: data the target can’t represent, defaults synthesized, or blocks mapped best effort. An empty warnings means a faithful conversion. For convert_file and convert_str, warnings carries the read side (Parsed warnings) too, ahead of the write side.
ElementCounts: The element counts that define a scenario batch’s shared base shape. Named (rather than a bare (usize, usize, usize)) so the three same-typed fields can’t be transposed silently in an error message or a comparison.
GenCost: A generator cost curve (mpc.gencost row).
Generator
Hvdc: A two-terminal HVDC line (MATPOWER dcline).
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 Network.
IndexedNetwork: A Network 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 Network::expand_transformers_3w); the core is owned (IndexedNetwork::new) or borrowed from a cached IndexCore (IndexedNetwork::with_core).
Load
Network: A format-neutral power network.
Parsed: Output of a parse: the network plus the reader’s fidelity warnings, tables and columns the model cannot carry, reported instead of dropped silently. Empty for readers that don’t report read warnings (currently readers that do not need to reduce any source fields).
PwdDisplay: Decoded PowerWorld display file content.
PwdSubstation: One substation symbol from a display file: the identity row joined with its drawing record, in identity table (display) order. x and y are diagram coordinates as stored, y north positive (see the module docs).
PypsaCsvOutputs
Shunt
Storage

Enums§

BusType: Bus type per MATPOWER convention: 1=PQ, 2=PV, 3=ref/slack, 4=isolated.
DisplayData: Output of a display parse. v0.2.2 supports PowerWorld .pwd; future display formats can add variants without changing the parse entry point.
DisplayFormat: A display artifact format. These files are not power network cases and do not parse to Network.
Error
ErrorCategory: Coarse classification of an Error, for callers that map onto their own taxonomy (the Python layer’s exception subclasses, C ABI status codes, a CLI exit code). Distinguishing “the input file is bad” from “the operation can’t run on this otherwise-valid case” is the split callers actually branch on, and it’s a property of the error, not of the binding that surfaces it.
ScenarioMismatch: Why a gridfm scenario snapshot doesn’t line up with the first snapshot’s base element set (the row-stack keeps every table schema-consistent by requiring the same element counts and bus-id ordering across snapshots).
SourceFormat: Which format a Network was read from. Drives the same format byte exact echo on write.
TargetFormat: A target interchange format. See write_as.

Functions§

convert_file: Convert a case file to to, optionally forcing the source format with from.
convert_str: Convert in-memory case text of the named format (see target_format_from_name) to to.
display_format_from_name: Map a display format name to a DisplayFormat, or None if unrecognized. Accepts pwd, powerworld-pwd, and powerworld-display.
parse_display_bytes: Parse display bytes in the named display format.
parse_display_file: Parse the display file at path, choosing the reader from from or, when None, from the extension. v0.2.2 infers PowerWorld .pwd.
parse_file: Parse the case file at path, choosing the reader from from (the target_format_from_name names plus pypsa-csv/pypsa, pwb, pslf, and epc) or, when None, from the path: a directory containing network.csv parses as a PyPSA CSV folder (any other directory fails: Error::UnknownFormat when its name maps to no extension, the I/O error otherwise), and a file maps by extension (m/json/raw/aux/pwb/epc), case insensitively (issue #97: .RAW is as common as .raw in the wild). A .json file is sniffed four ways: pandapower ("_class": "pandapowerNet"), egret (top level elements and system), the powerio-json snapshot (top level buses), else PowerModels. Pass from to force one. PowerWorld .pwb is a binary read only format with no retained source; PSLF .epc is text and has a writer. Returns Parsed: the network plus the reader’s fidelity warnings.
parse_matpower: Parse the MATPOWER case in content into a Network.
parse_matpower_file: Parse the MATPOWER case at path, using the file stem as the network name.
parse_pandapower_json: Parse pandapower pandapowerNet JSON content. Returns Parsed: the network plus the reader’s fidelity warnings.
parse_powermodels_json: Parse PowerModels.jl network data JSON into a Network. Loads and shunts are read as first-class elements and the raw text is retained, so writing back to PowerModels JSON is a byte-exact echo. per_unit = true input (powerio’s own output, and PowerModels’ own export) is converted to the neutral MW/degree convention (powers ×baseMVA, angles to degrees, cost coefficients un-scaled), following PowerModels’ own exceptions (storage ps/qs stay raw, dcline pt/qf/qt flip sign); per_unit = false is read as-is.
parse_powerworld: Parse a PowerWorld .aux into a Network, reading the Bus/Load/Shunt/ Gen/Branch DATA blocks by their declared field lists.
parse_pslf: Parse a PSLF .epc case into a Network.
parse_psse: Parse a PSS/E .raw (revisions 33-35) into a Network. Reads bus/load/ fixed-shunt/generator/branch/2- and 3-winding transformer; skips the advanced sections.
parse_str: Parse in-memory case text of the named format (see target_format_from_name). Returns Parsed: the network plus the reader’s fidelity warnings.
read_pypsa_csv_folder: Read a PyPSA CSV folder at path. Returns Parsed: the network plus the reader’s fidelity warnings.
target_format_from_name: Map a format name (with the common aliases) to a TargetFormat, or None if unrecognized. Accepts matpower/m, powermodels-json/powermodels/pm, egret-json/egret, pandapower-json/pandapower/pp, psse/raw, powerworld/aux, powerio-json/powerio/json (the canonical snapshot; plain json means this one, the foreign JSON dialects are namespaced). Case-insensitive. The one place the bindings (Python, C ABI) share, so a new text format means one new arm here, not three. PyPSA CSV folders are directory inputs with no text target; their aliases are matched by the private is_pypsa_csv_name next to this.
write_as: Convert a Network to format. Writing back to the source format returns the retained source text; otherwise the network is serialized into the target.
write_egret_json
write_matpower: Serialize net to MATPOWER .m text. Echoes the retained source verbatim when net came from MATPOWER; otherwise emits canonical .m.
write_pandapower_json
write_powermodels_json
write_powerworld
write_psse: Serialize net to PSS/E .raw at the default revision (33).
write_pypsa_csv_folder

Type Aliases§

Extras: Source-format fields the neutral model doesn’t name, kept for round-trip and cross-format passthrough. Keys are the field names; values are JSON scalars.
Result