PowerIO

PowerIO reads power system data into typed values, writes those values back out in the formats other tools read, and builds the sparse matrices and graph data that solvers consume. The core is Rust, and the Python package, the Julia package PowerIO.jl, and the C ABI expose the same operations under the same names.

A parse returns a PioModule, which is one typed value together with its sources, diagnostics, source map, and history. Depending on what the source declares, the value is a network, an operating point, a calculation instance, a solution, a time series, a scenario set, a geographic layer, or a PSS/E contingency analysis file.

Convert files in the browser, including mixed transmission and distribution batches. Files stay on the computer.

Install

cargo add powerio                 # parsing, emission, PowerIO IR
cargo add powerio -F matrix       # and sparse matrices, sensitivities, graph data
pip install powerio               # pip install 'powerio[all]' adds SciPy, NetworkX, Polars
julia -e 'using Pkg; Pkg.add("PowerIO")'
cargo install powerio-cli         # the powerio command

Parse and emit

The examples use case9.m, the nine-bus MATPOWER case included in this repository. Save it in your working directory first, or replace "case9.m" with the path to your own case.

Rust:

use powerio::{PioValue, emit, parse};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let module = parse("case9.m")?;
    let PioValue::BalancedNetwork(network) = module.value() else {
        panic!("expected a balanced network");
    };
    assert_eq!(network.buses().len(), 9);
    emit(&module, "matpower", "copy.m")?;   // the source bytes, unchanged
    let result = emit(&module, "psse", "case9.raw")?;
    for finding in result.diagnostics() {
        eprintln!("{}", finding.code());    // what PSS/E cannot carry
    }
    Ok(())
}

Python:

import powerio

module = powerio.parse("case9.m")
network = module.value
assert isinstance(network, powerio.BalancedNetwork)
module.diagnostics                          # the reader's findings
powerio.emit(module, "matpower", "copy.m")  # the source bytes, unchanged
result = powerio.emit(module, "psse")       # text in memory plus findings

Julia:

using PowerIO

module_ = parse("case9.m")            # PioModule{BalancedNetwork}
net = module_.value
length(net.buses)                     # 9
module_.diagnostics
emit(module_, "matpower", "copy.m")

Command line:

powerio convert case9.m --to psse -o case9.raw
powerio serialize case9.m -o case9.pio.json
powerio verify case9.m --kind bdoubleprime
powerio sensitivities case9.m -o out

If you write an unchanged module back to its own format, you get the source back byte for byte. If you write it to another format, PowerIO keeps what that format can represent and reports each loss as a diagnostic with a stable code, so you can see what the conversion dropped. serialize and deserialize write and read PowerIO IR, the JSON document that stores a complete module for another PowerIO consumer to read back. It preserves the typed data and its history; retained source bytes stay in the running process. After deserialization, emit writes fresh output from the stored value.

Upgrading from 0.10? Start with the migration guide. PowerIO 0.11.7 keeps PowerIO IR version 2 and C ABI 7; these version numbers describe separate interfaces.

Formats

The balanced transmission formats parse to BalancedNetwork, and OpenDSS, PMD, BMOPF, and distribution CIM parse to MulticonductorNetwork. SINCAL holds both kinds of network in one project, so a parse names its profile: sincal-balanced gives a BalancedNetwork and sincal-multiconductor a MulticonductorNetwork. A GO Challenge 3 problem parses to AcScucInstance, a problem with its solution to AcScucSolution, an OPFData file to AcOpfSolution, a GridFM dataset to ScenarioSet<BalancedNetwork>, a PyPSA directory with several snapshots to a TimeSeries<BalancedNetwork>, or to TimeSeries<OperatingPoint<BalancedNetwork>> when only the electrical state varies, a PowerWorld .pwd display and a .geo.json file to GeoLayer, and the PSS/E .con, .sub, and .mon files to ContingencySet, SubsystemSet, and MonitoredSet. PowerIO IR is not in the table: it moves only through serialize and deserialize, and parse refuses it.

The gridfm and sincal cargo features gate their formats. The facade leaves gridfm off and turns sincal on by default; the CLI and the Python wheel include both. The format guide says what each reader keeps, what each writer reports, and how each is checked against its reference implementation.

Packages

Start with powerio in an application. The component crates let libraries depend on just the layer they use.

powerio-tx and powerio-dist share powerio-core and nothing else, so a distribution consumer pulls in no transmission code. powerio-prob is matrix free. The powerio facade re-exports the component crates, with powerio-matrix behind its matrix feature. Native SINCAL support is the sincal feature, on by default; it brings in SQLite, so a wasm32-unknown-unknown build with it needs a C compiler with a WebAssembly backend, and default-features = false leaves it out.

Documentation

• Guide
• Core concepts
• Formats and fidelity
• Matrices and graphs
• Rust, Python, Julia, and C
• Rust API reference
• PowerIO.jl
• Contributing

License

Apache License 2.0 or MIT License, at your option.