Crate powerio_matrix 

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