PowerIO guide
Readers parse power system source formats into typed models. Explicit passes
normalize, validate, and lower them, and writers emit supported target formats.
The .pio.json document records how a source was interpreted: model kind,
provenance, source maps,
structured diagnostics, validation, and lowering history. Sparse matrices and
graph views are built from the same models for solver and analysis code.
Rustdoc covers API detail.
Public conventions:
- writing a case back to the format it was read from returns the original bytes when the reader kept them;
- cross format conversion keeps the electrical core and reports losses as warnings;
- lowering between model families is always an explicit, recorded pass;
- matrix builders state sign, tap, shift, shunt, and reference bus conventions;
- C, Python, and Julia bindings share the same Rust core.
Transmission readers cover MATPOWER, PSS/E revisions 33 through 35,
PowerWorld AUX and PWB, PSLF EPC, PowerModels JSON, egret JSON, pandapower JSON,
PyPSA CSV folders, GO Challenge 3 JSON, Surge JSON, DeepMind OPFData FullTop
and N-1 dataset JSON, and GridFM Parquet
datasets. PowerWorld PWD is a display artifact and uses the display API.
Distribution readers and writers live in powerio-dist for OpenDSS,
PowerModelsDistribution ENGINEERING JSON, and BMOPF JSON.
Where to look:
- Compiler model layers: the
BalancedNetworkandMulticonductorNetworkmodel families and the.pio.jsondocument. - PIO JSON schema: the
.pio.jsonfield reference, metadata and model JSON versioning, and row identity. - Format fidelity: numeric conventions, the validation oracles, known limits per format, and the missing generator cost policy.
- Matrix outputs and the DC OPF bundle.
- Language APIs and Python.
- Performance and testing and release checks.
- Julia bindings: https://github.com/eigenergy/PowerIO.jl.
Rendered API docs (rustdoc) for all crates: https://powerio.dev.
Crates
| crate | responsibility |
|---|---|
powerio | parsers, writers, BalancedNetwork, IndexedNetwork, normalization, format routing |
powerio-matrix | generic sparse matrices, graph views, and GridFM datasets |
powerio-prob | complete problem instances and optional matrix projections |
powerio-dist | multiconductor distribution model and converters |
powerio-pkg | .pio.json document metadata and model JSON |
powerio-cli | command line interface and TUI |
powerio-py | PyO3 extension for the Python package |
powerio-capi | C ABI for C, C++, Julia, and other foreign function interfaces |
Adding a format means adding one reader or writer at the hub rather than
pairwise converters. IndexedNetwork is the dense \([0,n)\) analysis view derived from
a balanced BalancedNetwork; matrix builders work from that view. Code that maps
source bus IDs to dense rows must use IndexedNetwork::bus_index; it must not
clamp IDs or assume 1-based contiguous IDs.