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;

Modules§

error
format: The format hub: readers and writers for every supported file format, all meeting at the shared 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. Borrows the network; the core is either owned (the one-shot 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 every format except pandapower JSON and PyPSA CSV; the PSS/E and PowerWorld reductions are documented in docs/format-fidelity.md, not reported here yet).
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 and pwb) 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), case-insensitively (issue #97: .RAW is as common as .raw in the wild). A .json file is sniffed three ways: pandapower ("_class": "pandapowerNet"), egret (top level elements and system), else PowerModels. Pass from to force one. .pwb binaries are read only and carry no retained source. 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_psse: Parse a PSS/E v33 .raw into a Network. Reads bus/load/fixed-shunt/ generator/branch/2-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. 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
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