PowerIO guide

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

use powerio::{PioValue, parse};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let module = parse("case9.m")?;         // PioModule<PioValue>
    match module.value() {
        PioValue::BalancedNetwork(network) => {
            println!("{} buses", network.buses().len());
        }
        other => println!("{}", other.type_name()),
    }
    Ok(())
}

import powerio
module = powerio.parse("case9.m")                 # PioModule[BalancedNetwork]

using PowerIO
module_ = parse("case9.m")                        # PioModule{BalancedNetwork}
feeder = parse("IEEE13Nodeckt.dss")               # PioModule{MulticonductorNetwork}

A parse returns a module, which is one typed value together with the data that explains it: the source descriptions, the source map, the reader’s diagnostics, the derivation history, and, while the process runs, the source bytes themselves. Which value you get depends on what the source declares:

parse reads a grid exchange format into a module, and emit writes a module out in one. The other two operations, serialize and deserialize, write and read PowerIO IR, the JSON document that stores a complete module for another PowerIO consumer to read back. PowerIO IR is not a grid exchange format, so parse does not accept it; deserialize does.

Whichever format you use, writing an unchanged module back to its own format reproduces the source bytes byte for byte, and writing to another format keeps what that format can represent and reports each loss as a diagnostic with a stable code. Converting from one kind of value to another is an explicit operation that adds an entry to the module history; nothing converts as a side effect.

To install PowerIO and run a first conversion, start with Getting started. Core concepts defines the module, the value types, diagnostics, and sources. Formats and fidelity says what each reader keeps and each writer reports, and Rust, Python, Julia, and C shows each operation in all four languages.

Getting started

Install

Rust:

cargo add powerio             # parsing, emission, PowerIO IR
cargo add powerio -F matrix   # and sparse matrices, sensitivities, graph data

Use Rust 1.88 or newer. Add the gridfm feature when your application reads or writes GridFM Parquet directories: cargo add powerio -F gridfm.

Python:

pip install powerio           # parsing, emission, PowerIO IR
pip install 'powerio[all]'    # and SciPy matrices, NetworkX graphs, Polars for GridFM

Julia:

using Pkg; Pkg.add("PowerIO")

The powerio command:

cargo install powerio-cli

For C and C++, build the shared library from a checkout and include the checked in header.

git clone https://github.com/eigenergy/powerio
cd powerio
cargo build -p powerio-capi --release --features arrow,matrix,gridfm,dist,prob
# target/release/libpowerio_capi.{so,dylib,dll}; header powerio-capi/include/powerio.h

Parse, inspect, emit

Download case9.m to your working directory for these examples. In a repository checkout, the same file is tests/data/case9.m; pass that path when running from the root.

Rust. The example is a complete program; it imports only parse, emit, and the PioValue enum, and ? hands any failure to main.

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");
    };
    println!("{} buses", network.buses().len());
    for finding in module.diagnostics() {
        eprintln!("{}: {}", finding.code(), finding.message());
    }
    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                       # BalancedNetwork
for finding in module.diagnostics:
    print(finding.code, finding.message)
powerio.emit(module, "matpower", "copy.m")   # the source bytes, unchanged
result = powerio.emit(module, "psse")        # text in memory
result.text
result.diagnostics

Julia:

using PowerIO

module_ = parse("case9.m")
net = module_.value                          # BalancedNetwork
length(net.buses)                            # 9
module_.diagnostics
emit(module_, "matpower", "copy.m")          # the source bytes, unchanged
result = emit(module_, "psse")               # text in memory
result.diagnostics

Command line:

powerio convert case9.m --to psse -o case9.raw   # findings on stderr
powerio summary case9.m                          # counts, bases, and findings as JSON

Keep a module for later

Use serialize to save the value with its diagnostics and history, then deserialize to restore it in any PowerIO binding:

powerio::serialize(&module, "case9.pio.json")?;
let restored = powerio::deserialize("case9.pio.json")?;

powerio.serialize(module, "case9.pio.json")
restored = powerio.deserialize("case9.pio.json")

serialize(module_, "case9.pio.json")
restored = deserialize("case9.pio.json")

PowerIO IR stores the typed data and source metadata. Original input bytes stay in memory, so an unchanged parsed module can echo them, while a restored module produces fresh output. Inspect the returned emission diagnostics when exporting to another tool.

Where next

• What each source parses to and what a module contains: Core concepts.
• Balanced transmission cases: Transmission networks.
• Conductor level distribution cases: Distribution networks.
• Matrices, signs, units, and index mappings: Matrices and graphs.
• What each reader keeps and each writer reports: Formats and fidelity.
• The same operations in each language: Rust, Python, Julia, and C.

Core concepts

PowerIO borrows its structure from compiler infrastructure. Source text and the data a program computes with are different representations, and you move between them through a small set of explicit, checked operations. The electrical content is described in ordinary power system terms, and the same types and operations appear in Rust, C, Python, Julia, PowerIO IR, and the MCP server.

The module

PioModule<T> contains one typed value and the data that explains it:

PioModule<T>
├── value: T
├── diagnostics
├── producer
├── sources and source map
├── history
└── extensions

In Rust you reach the value through module.value() and the diagnostics through module.diagnostics(). Python and Julia expose both as properties, value and diagnostics, and C exposes borrowed accessors because its values are opaque. Diagnostics belong to the module rather than to the network or solution inside it.

While the process runs, a module can keep the bytes it was parsed from, which is how writing it back to its own format reproduces them byte for byte. Those bytes are not part of serialized PowerIO IR, and editing the value drops them, so the next same format write serializes the edited value instead of the old bytes.

Values

PioValue is the closed set of types a module can contain at the dynamic boundary, meaning automatic parsing, PowerIO IR, the C, Python, and Julia bindings, and the MCP server.

BalancedNetwork
MulticonductorNetwork
OperatingPoint<BalancedNetwork>
OperatingPoint<MulticonductorNetwork>
TimeSeries<T>
ScenarioSet<T>
DcPfInstance, AcPfInstance, DcOpfInstance, AcOpfInstance,
McAcPfInstance, McAcOpfInstance, AcScucInstance
DcPfSolution, AcPfSolution, DcOpfSolution, AcOpfSolution, SocwrOpfSolution,
McAcPfSolution, McAcOpfSolution, AcScucSolution
GeoLayer

The two network types are peers, and neither is a subtype of the other. BalancedNetwork is where MATPOWER, PSS/E, XIIDM, CGMES, and the other balanced formats meet; MulticonductorNetwork is where OpenDSS, PowerModelsDistribution JSON, and BMOPF meet. To get a balanced positive sequence equivalent from a multiconductor network you call an explicit transformation, which reports each assumption it made and each thing it lost.

A BalancedNetwork parsed from PSS/E and one parsed from MATPOWER are the same type with the same meanings. Each format has a documented profile, and data outside that profile is reported and stays in the retained source; it is not folded into the model. There is no universal network format. The balanced model does not absorb multiconductor data, other energy carriers, or calculation data.

A Rust application can put its own type in a module, PioModule<MyType>, and get the same source, diagnostic, and history behavior. That type stays outside the dynamic boundary until PowerIO adds it to PioValue, the IR schema, and the bindings, so until then it cannot pass through PowerIO IR or reach the other languages.

Operating points

An operating point can override demand, setpoints, dispatch, voltages, injections, equipment service status, switch positions, transformer taps, phase shifts, and the corresponding multiconductor controls. Any quantity it leaves out resolves to the network’s own assignment, which is why an operating point can be partial.

It cannot change equipment identities or terminals, physical parameters, ratings, costs, commitment or reserve structure, the horizon, or the equipment set. If your scenario changes any of those, it contains a network or a calculation instance instead of an operating point.

Topology is calculated from the declared terminals, equipment service status, and switch positions, which together give the energized connectivity. Tap and phase shift changes affect the equations and leave the connectivity alone.

Collections

TimeSeries<T> and ScenarioSet<T> nest without flattened names, so TimeSeries<OperatingPoint<BalancedNetwork>>, ScenarioSet<TimeSeries<BalancedNetwork>>, and the other combinations keep their structural type. An operating point entry refers to the shared base network instead of copying its tables, so a series of operating points contains one network and one sparse set of overrides per point. A series of networks or instances contains complete values when their physical or calculation data differs.

Indexing a collection returns the contained value or a view rooted in the owning module; nothing reparses and no complete network is copied.

Calculation instances and solutions

Network data, calculation inputs, and results are separate types. A MATPOWER case parses to a BalancedNetwork, and you construct a DcPfInstance, AcPfInstance, DcOpfInstance, or AcOpfInstance from it. A solver takes the instance and returns the corresponding solution; PowerIO itself never solves.

SocwrOpfSolution is a PowerModels SOCWR relaxation together with its objective lower bound. It is not an AcOpfSolution unless voltage recovery and AC residual checks support that claim.

Diagnostics

Every operation reports diagnostics. Each Diagnostic has a stable dotted code, a severity (error, warning, remark, or note), a message, and, where available, a target, source byte spans, related diagnostics, and a suggested action. Branch on the code rather than on the rendered message; the code is the part that stays stable.

A successful operation keeps its diagnostics on the returned module or result. A failed operation returns or raises the language’s PowerIO error, which contains the same diagnostics.

Sources, formats, and destinations

A Source owns one or more named immutable byte buffers read from a file, a directory, or memory. In Rust and C you build it yourself, since those languages need an explicit owner for the bytes. Python and Julia take a path, an open file, or a bytes value directly, because the interpreter already owns them; Rust, Python, Julia, and C explains the split. parse detects the format from the source name and content unless you declare one.

emit writes one format and returns an EmitResult. The result contains one artifact per file produced, each with its name and either its bytes (for a memory destination) or its path after a write; the layout, which is one file or a directory; the fidelity, which is either an exact echo of retained source bytes or fresh canonical output; and the emission diagnostics, which report each loss. A single file format produces one artifact, and a directory format such as PyPSA CSV, GridFM, or CGMES produces one per file.

resolve_format maps an accepted spelling of a format to its canonical token and reports the conventional file suffix, the output layout, and whether a fresh writer exists. It describes formats only; values are named by PioValue and its counterparts in each language.

PowerIO IR

serialize writes a module as PowerIO IR and deserialize reads it back with its types, diagnostics, sources, history, and extensions intact. The document has an integer generation that changes only when the serialized representation changes. PowerIO IR is absent from grid exchange format discovery, so parse does not accept it. PowerIO IR defines the document and its generation rule.

Derived data

Sparse matrices, dense solver rows, factorizations, and caches are analysis data computed from a value. They keep element mappings back into that value, they are not stored in a module, and their representation can change without changing any public meaning.

Every transformation declares its input and output types and returns diagnostics. Multiconductor to balanced conversion moves to a less detailed representation under stated assumptions, while constructing an instance from a network moves to a more specific one. Format conversion is parse followed by emit at the same level. LLVM and MLIR lessons lists the decisions PowerIO shares with LLVM and MLIR and the ones it does not.

Transmission networks

A balanced network is the positive sequence transmission model. All of the balanced formats in the format table parse to it, so one reader and one writer per format cover all the conversions between them.

using PowerIO
module_ = parse("case118.m")       # PioModule{BalancedNetwork}
net = module_.value
length(net.buses)                  # 118
net.branches[1]                    # buses, branches, generators, loads, and the other tables

The network keeps what the source says: the element inventory, terminal connections, impedances, ratings, generator capability bounds and cost curves, and the source’s operating assignment. Ratings and costs stay on the network as reusable data, and which bounds a calculation enforces is decided when you construct an instance, so one parsed case serves power flow, DC OPF, and AC OPF without reparsing (see Calculation instances and solutions).

A few conventions hold across the accessors. Bus identifiers are the source’s own; dense zero based indices exist only in matrix results, which include the mapping. Powers are MW and MVAr as the source gives them, and angles are degrees; to_normalized derives a per unit, radian, in service only copy when a solver wants one. A branch tap of 0 means 1, and a rate_a of 0 means unrated.

Sources that describe more than the balanced calculation view, such as XIIDM, CGMES, and PSS/E RAW 35, also fill in the detailed connectivity: substations, voltage levels, connectivity nodes, terminals, switches, operational limit groups, and tap changer controls. A writer whose format can represent those writes them, and one whose format cannot reports what it left out.

emit(module_, "matpower", "copy.m")            # the source bytes, unchanged
result = emit(module_, "psse")                 # fresh PSS/E text
for finding in result.diagnostics
    println(finding.code, ": ", finding.message)
end

From a library you call parse, keep the module, and call emit; on the command line, powerio convert does both in one call.

Building matrices from a balanced network has its own chapter, Matrices and graphs.

Distribution networks

A multiconductor network is the conductor level distribution model, and OpenDSS, PowerModelsDistribution engineering JSON, and BMOPF JSON all parse to it. When you need a calculation, construct an McAcPfInstance or McAcOpfInstance from it explicitly (see Calculation instances and solutions).

using PowerIO
feeder = parse("IEEE13Nodeckt.dss")        # PioModule{MulticonductorNetwork}
net = feeder.value
net.lines[1]                               # terminal maps and the line code reference
net.linecodes[1]                           # per length impedance matrices, SI units
feeder.diagnostics                         # what the reader kept, assumed, or refused

The model identifies individual conductors throughout. Buses have ordered terminals and explicit grounding, lines and switches map conductors between terminal sets, transformers list their windings with connection kinds, and loads and generators attach per terminal. Impedance and shunt matrices are in SI units, per unit length, on line codes. An element the reader has no typed slot for stays verbatim in the untyped table and is reported.

The OpenDSS profile is the static circuit, meaning the element definitions and their electrical data. Load shapes, solve commands, monitors, and other calculation instructions are outside it; they stay in the retained source, are reported as uninterpreted, and survive a same format write byte for byte.

emit(feeder, "dss", "copy.dss")            # the source bytes, sidecars included
result = emit(feeder, "pmd")               # fresh PMD JSON
result.text
result.diagnostics

Nothing converts between the multiconductor and balanced models implicitly. The balanced positive sequence equivalent is an explicit transformation that reports its assumptions, such as voltage bases per zone, phase aggregation, and switch merging, and refuses what it cannot represent:

use powerio::transform::{to_balanced, to_balanced_report};

let report = to_balanced_report(&feeder)?;   // readiness, assumptions, losses, diagnostics
let balanced = to_balanced(&feeder)?;        // PioModule<BalancedNetwork>

Python exposes the same pair as module.to_balanced_report() and module.to_balanced(). The transformation has no C entry point in 0.11, so PowerIO.jl does not bind it.

Multiconductor admittance matrices build directly from the multiconductor network through powerio_matrix::calc_multiconductor_admittance_matrix, which is Rust only in 0.11.

BMOPF schema versions

PowerIO v0.11.0 supports draft BMOPF 0.2, subject to Task Force review. The schema version is separate from the PowerIO release and from PowerIO IR generation 2. Producer provenance records the proposal revision and schema digest. Previously emitted schema identifiers remain readable aliases.

An unqualified bmopf-json emission preserves an unchanged source byte for byte. An explicit schema version always re-encodes the selected version:

powerio convert feeder.json --to bmopf-json@0.1.0 -o legacy.json
powerio convert feeder.json --to bmopf-json@0.2.0 -o proposal.json

The same format strings work with Rust powerio::emit, Python powerio.emit, C pio_emit, Julia emit and the PowerIO MCP emission tool. Rust also exposes BmopfSchemaVersion and BmopfEmitOptions for the distribution writer.

Legacy output relocates proposed-only equipment and transformer fields into extras, with diagnostics. A consumer that ignores those extensions cannot be assumed to calculate the same network. Proposal output uses the declared tables and preserves winding ratings, taps, neutral impedances and current-limit data.

Unequal bus phase bounds remain individual values through parsing, generation-2 IR and explicit BMOPF output. Uniform values use v_min/v_max; unequal values use v_min_phase/v_max_phase in the typed Rust model. A present scalar takes precedence over the corresponding vector. PMD voltage arrays instead follow terminal order and use engineering voltage units.

The C and Julia bus views expose unequal limits as phase_to_ground_voltage_min_v and phase_to_ground_voltage_max_v, while voltage_min_v and voltage_max_v represent uniform bounds. C spans borrow from the network’s owner and remain valid for the lifetime of that handle. The unreleased ABI 7 layout and Julia definitions are updated together.

Parsing, structural schema validity, semantic consistency and computational support are separate checks. Contradictory versions, invalid dimensions, unknown electrical references and inconsistent bounds produce error diagnostics. The native multiconductor admittance builder supports ideal grounded-WYE transformer coupling and rejects leakage, other winding connections, floating neutrals, core shunts or tap decisions that need a different formulation.

The BMOPF proposal schema is pinned to fe8671a, with SHA-256 74d6c6de3637d52e42a26c4cb0584f51df70d69f360b236cf5e23afaf7669462. Fresh 0.2.0 output places the immutable retrieval URL in meta.$schema and records the canonical identity, proposal status, digest and revision under meta.provenance.powerio_bmopf. Existing provenance is preserved; a name collision uses a numbered producer entry. Reading the former canonical or version-directory identifiers remains supported without fetching remote data.

Energy prices

Draft BMOPF 0.2 uses energy_cost_rate in $/kWh. Generator entries follow phase order, as do voltage-source entries. Neutral terminals have no price entry. PowerIO retains source prices in VoltageSource.energy_cost_rate and in generation-2 IR. C and Julia expose energy_cost_rate_per_kwh; Python’s voltage-source records expose energy_cost_rate.

The reader also accepts the deprecated per-phase cost spelling. Explicit 0.1.0 output keeps generator cost and relocates source prices to extras.voltage_source, with a diagnostic. Only a consumer that reads that overlay can use the retained source prices. PowerIO stores the coefficients; the selected solver determines whether and how they enter its objective.

Time series and scenarios

Some sources declare more than one value, and PowerIO keeps the structure they declare. An ordered sequence of values is a time series, a set of named alternatives is a scenario set, and the element type says what varies from one entry to the next.

A time point keeps the source’s exact label and, when the source gives one, an interval duration; PowerIO imposes no calendar meaning on labels. Scenario identifiers are the source’s own strings, and you look scenarios up by identifier rather than by position. An operating point entry refers to its shared base network instead of copying the network tables. Core concepts says what an operating point can and cannot change.

using PowerIO
dataset = parse("gridfm_case14/")          # PioModule{ScenarioSet{BalancedNetwork}}
scenarios = dataset.value
keys(scenarios)                            # the scenario identifiers
one = scenarios["7"]                       # BalancedNetwork

series_module = parse("pypsa_folder/")     # PioModule{TimeSeries{BalancedNetwork}}
series = series_module.value
length(series)                             # the number of declared time points
first_hour = series[1]                     # one based, like every Julia axis

Indexing returns the contained entry or a view rooted in the owning module; nothing reparses and no complete network is copied. If an entry needs diagnostics, history, emission, or serialization of its own, wrap it in a module.

Only the facade reads the Egret time series. powerio::parse returns the series, while the component crate’s powerio_tx::parse reads only the static profile and refuses a document with system.time_keys.

Data outside a source’s profile, such as PyPSA investment periods, stochastic scenarios, and unit commitment coupling, or Egret reserve and contingency data, stays in the retained source, is reported as uninterpreted, and survives a same format emission. Formats and fidelity says where each profile ends.

Calculation instances and solutions

An instance is the complete input for one named calculation, and a solution is the result of one; the solution shares the instance it solves. PowerIO has seven instance types, from DC power flow through multiconductor AC OPF to AC security constrained unit commitment, and eight solution types, because SocwrOpfSolution is an SOCWR relaxation of an AcOpfInstance and is not labeled an AC OPF solution.

DcPfInstance       DcPfSolution
AcPfInstance       AcPfSolution      SocwrOpfSolution
DcOpfInstance      DcOpfSolution
AcOpfInstance      AcOpfSolution
McAcPfInstance     McAcPfSolution
McAcOpfInstance    McAcOpfSolution
AcScucInstance     AcScucSolution

A source parses to an instance or a solution only when it declares that calculation:

A MATPOWER case or a PowerModels file stays a network, because it has ratings and costs that power flow, DC OPF, and AC OPF can all use and nothing in the file commits you to one calculation. The GO Challenge 3 data format also serves later challenges, but only its Challenge 3 problem file defines a calculation PowerIO has a type for; optional fields outside that formulation are retained in the source and reported.

GO Challenge 3 splits its problem and solution across two files. Put both in one directory and parse the directory:

solution = powerio.parse("scenario_002")

A directory with only the problem file returns an AcScucInstance. A solution file on its own is refused, because it contains neither the component definitions nor the time axis. The returned module retains both files and its diagnostics.

A DC instance says which branch susceptance formula it uses. In Rust you select it with with_branch_susceptance_formula(formula) and read it with branch_susceptance_formula(); the PowerIO IR document stores it in the approximation field as one of series_susceptance, tap_adjusted_reactance, or reactance_only. Matrices and graphs defines the three.

An instance contains or shares its network. emit writes that network in a grid exchange format and reports the calculation fields the format has no place for, while serialize preserves the complete instance:

using PowerIO
scuc = parse("scenario_002")             # PioModule{AcScucInstance}
emit(scuc, "matpower", "scenario_002.m") # diagnostic: scheduling data omitted
serialize(scuc, "scenario_002.pio.json")

Solvers consume instances; PowerIO never solves. The instance is the mathematical input only. The choice of equations, B-theta or PTDF for DC OPF and polar or SOC for AC OPF, belongs to the solver and does not create another instance type.

A solution lists its values by stable element identifier, along with the termination claim and residuals that PowerIO computes itself rather than taking on trust. An OPFData solution exposes the instance it solves, and residual checks run against that instance’s network. Emitting a solution writes the bus voltages, generator dispatch, and branch terminal flows the target format supports and reports the objectives, multipliers, termination data, and residuals it left out. An SOCWR result is never written as an AC power flow solution; emit writes only its instance network and reports that the W-space values and the objective lower bound were omitted.

Matrices and graphs

powerio-matrix calculates sparse matrices and graph data from parsed networks. Source bus identifiers are not dense indices, so each result comes with the element mapping you need to read its rows and columns, and the dense [0, n) index space exists only inside a result that says which bus each index is.

powerio-prob owns the calculation instances and builds no matrices itself; the matrix crate turns those instances into sparse operators. The files of the DC OPF bundle are defined in DC OPF bundle, and the Rust API is documented in the crate reference.

Capabilities

PTDF and LODF need a linear solve, and calc_ptdf, calc_lodf, calc_ptdf_lodf, and the option based calc_ptdf_lodf_with_options all go through the same solver selection. You pick the path with SensitivitySolver, the solver field on SensitivityOptions. Dense forces the dense grounded factorization. Sparse factors the grounded DC bus susceptance matrix once with a sparse Cholesky and reuses that factorization for every right hand side. Auto picks dense up to a reduced dimension of 512 (with a memory ceiling) and sparse above it. The sparse path avoids forming the \((n-r) \times (n-r)\) dense inverse, though the PTDF and LODF outputs themselves can still be large. It also needs positive finite internal factor weights w = -b, so the grounded matrix L = -B is positive definite once reference coverage has been checked; the dense path can handle nonsingular indefinite cases. Every connected component must contain at least one reference bus. The DC OPF bundle (\(A\), \(b\), \(L\), costs, bounds, thermal limits, \(C_g\)) is prepared from a DcOpfInstance and documented in DC OPF bundle.

Bp and Bpp are the fast decoupled power flow matrices from MATPOWER makeB. Solvers reduce Bp to PV+PQ buses for active power mismatch to voltage angle updates, and reduce Bpp to PQ buses for reactive power mismatch to voltage magnitude updates. PowerIO exports the full \(n \times n\) matrices so you can apply your own bus type reduction.

The public DC calculations live on DcOperators: calc_incidence_matrix, calc_branch_susceptances, calc_bus_susceptance_matrix, calc_branch_flow_matrix, calc_branch_phase_shift_injection, calc_bus_phase_shift_injection, calc_bus_injection_dc, and calc_branch_flow_dc. A calc_* name means the call computes a new result; a plain noun is a stored field or a borrowed accessor. The incidence matrix follows PowerModels, branches by buses, with \(+1\) at the from bus and \(-1\) at the to bus, and the phase shift injection is a separate result. The sensitivity and DC OPF builders use a transposed incidence factor internally, and that factor stays internal rather than becoming a second public incidence API.

GridFM datasets

Reading and writing GridFM needs the gridfm cargo feature; the CLI and the Python wheel are built with it. The export is a Parquet dataset under <case>/raw/ with bus_data, gen_data, branch_data, and y_bus_data. A single parsed case writes one scenario. A scenario batch stacks the rows of snapshots that share the same element set, with the scenario column as the key; to build one you need unique scenario ids, one system base, and bus, branch, and generator row IDs that match across the snapshots. Column names and units follow the GridFM data kit output schema.

Reading a GridFM dataset recovers everything its balanced tables hold: bus types, voltages and limits; nodal load and shunt totals; generator dispatch, bounds, and quadratic costs; branch parameters and terminal flows; and base_mva. Dense bus indices, nodal demand, and a fixed quadratic cost triple are how the GridFM tables are laid out, so reading them reports no conversion loss.

Writing a richer network into GridFM reports each projection the format forces: bus renumbering, several load or shunt records aggregated into one, equipment and metadata left out, costs that do not fit the fixed quadratic columns, and terminal flows evaluated from bus voltages when the source has no branch solution. A GridFM dataset read and written back without an edit in between produces none of these findings.

Conventions

• Weighted bus solver factors. Stored nonzero off-diagonal entries are negative; diagonals are nonnegative and positive for buses incident to a positive weight branch. For \(L = C \operatorname{diag}(w) C^\mathsf{T}\) with nonnegative branch weights \(w\), \(L_{ii} = \sum_j \lvert L_{ij} \rvert\). This is the M-matrix form an SDDM (symmetric diagonally dominant M-matrix) or Cholesky solver expects once the grounded matrix is positive definite; a consumer can recover an edge weight as \(-L_{ij} > 0\).

• Bus indexing. Source bus IDs are preserved on the model as a newtype and need not be contiguous. IndexedNetwork::bus_index(id) maps them into dense zero based indices in \([0,n)\), returning None for an unknown source ID. The matrix builders turn that into Error::UnknownBus at the point they need a bus that is not in the network.

• Taps and shifts. \(\mathrm{tap} = 0\) means \(\mathrm{tap} = 1\) (Branch::calc_effective_tap). MATPOWER Bp clears bus shunts and line charging, sets tap magnitudes to one, and keeps phase shifts. MATPOWER Bpp keeps bus shunts, line charging, and tap magnitudes while clearing phase shifts. \(Y_{\mathrm{bus}}\) keeps both tap magnitudes and phase shifts.

• Branch shunt admittance is stored per unit. Branch::charging is the stored per terminal admittance when present: g_fr, b_fr, g_to, and b_to are already per unit on the system base. Branch::b is the legacy MATPOWER BR_B total projection for formats that carry only one charging value. Matrix builders use Branch::calc_terminal_charging(), so terminal values feed \(Y_{\mathrm{bus}}\) even when the legacy total is zero or stale.

• FDPF scheme. Scheme selects between the two MATPOWER fast decoupled forms. Xb clears resistance for Bp; Bx clears resistance for Bpp. The default is Bx.

• Zero impedance branches. BuildOptions::skip_zero_impedance controls the builders whose branch denominator can be zero. The default false returns Error::ZeroImpedance; true skips the branch and records the skipped source branch rows in MatrixStats as skipped_zero_impedance and skipped_zero_impedance_branches. Full AC admittance builders use \(r^2 + x^2\); DC incidence and reactance only FDPF forms use \(x\). The gridfm export still zeros its admittance and flow columns for these rows and records dropped_zero_impedance in gridfm_meta.json.

• Reference coverage. IndexedNetwork::check_reference_coverage verifies that every in service island has a reference bus.

• Branch susceptance formulas. BranchSusceptanceFormula selects the branch susceptance vector \(b\) and, for formulas that include phase shifts, the phase shift injection. In the PowerModels form, DcOperators::calc_incidence_matrix returns the \(m \times n\) branch by bus matrix \(A_{pm}\). Each branch row has \(+1\) at the from bus and \(-1\) at the to bus. The signed matrix combines with \(b\) to form the direct PowerModels operators \(B = A_{pm}^\mathsf{T} \operatorname{diag}(b) A_{pm}\) and \(B_f = \operatorname{diag}(b) A_{pm}\). The phase shift injection is \(p_{shift} = A_{pm}^\mathsf{T}(b \circ shift)\), so \(p_{bus}=-B\theta+p_{shift}\). \(b\) is negative for an inductive branch, the PowerModels series susceptance sign.

  Solver preparation retains the \(n \times m\) bus by branch factor \(A_s=A_{pm}^\mathsf{T}\). It uses the positive factor weight \(w=-b\), so its sparse matrix is \(L=A_s \operatorname{diag}(w) A_s^\mathsf{T}=-B\). The two orientations have separate names so that a transposition cannot slip across a language boundary unnoticed.

  The default SeriesSusceptance uses \(b = -x/(r^2 + x^2)\), which takes the whole series impedance into account, plus the phase shift injection vector p_shift. A tap does not scale it. It reduces to \(b = -1/x\) when the branch has no resistance.

  TapAdjustedReactance reproduces MATPOWER’s makeBdc: \(b = -1/(x\tau)\) for a transformer with tap ratio \(\tau\), plus p_shift.

  ReactanceOnly is the textbook \(b = -1/x\) with resistance, taps, and shifts ignored. The resulting \(-B\) matches MATPOWER Bp under Scheme::Xb when phase shifts are zero.

Output

Matrices are written as Matrix Market files or kept in memory. A symmetric matrix is stored as its lower triangle with the symmetric header and 1-based indices (io::mtx::emit_mtx). The sensitivities command writes <case>_ptdf.mtx, <case>_lodf.mtx, and <case>_sensitivity_meta.json. Pick the branch susceptance formula with --formula series-susceptance|tap-adjusted-reactance|reactance-only, the PTDF/LODF solve path with --solver dense|sparse|auto, and drop entries whose absolute value is at or below a threshold with --drop-tolerance <value>. On the sparse path the CLI writes the retained Matrix Market coordinates through temp files rather than holding the full sparse output in memory; the Rust calc_ptdf_lodf_with_options API still returns CsMat values and is meant for outputs that fit in memory. The metadata file lists the requested solver, the solver path used, matrix dimensions, nonzero counts, the tolerance, and how many entries were dropped. The dcopf subcommand writes its matrix family together with a JSON manifest.

The standard case solver property fixture lives at powerio-matrix/tests/fixtures/solver_matrix_stats.json. It holds bprime, bdoubleprime, and ybus_imag stats for case9, case14, case30, case57, and case118: n, nnz, min diagonal, M-matrix sign pattern, diagonal dominance margin, zero impedance skips, row sum checks, SPD checks, and a condition estimate when the solver input is SPD.

IndexedNetwork::to_petgraph returns the network as an undirected petgraph graph, one node per bus and one edge per in service branch. The connectivity report and the radial check are built on it, and you can hand the returned graph straight to other petgraph algorithms.

Formats and fidelity

The format table in the repository README lists each format with its token and its read and write support. This page covers the numeric conventions, the independent checks each reader and writer passes, and, format by format, what a reader keeps and what a writer reports.

Conventions

PowerIO’s numeric conventions follow MATPOWER and PowerModels.jl. For each quantity the table gives the reference implementation and the matching PowerIO code:

egret’s own MATPOWER parser uses the same reductions (bus type as matpower_bustype, polynomial coefficients reversed to a {degree: coefficient} map, piecewise to [[mw, cost], ...], impedances left per unit), which is why a MATPOWER case taken through powerio to egret JSON matches egret’s direct import.

Validation

The harness script evals/validation/run_validation.sh checks powerio against five independent tools, and each classic text reader and writer runs under an oracle. The conversion matrix covers MATPOWER, PSS/E, and egret sources against all five legacy text targets, each PowerWorld output is read back and bridged to PowerModels JSON, and the PMread leg covers the PowerModels JSON read side. pandapower JSON and PyPSA CSV folders have dedicated import validators, because pandapower has its own JSON schema and PyPSA is a directory format; both validate the write direction only, since the pandapower JSON and PyPSA readers have no external oracle. DOE GO Challenge 3 has a separate pinned reference job, described below. Surge JSON and the remaining source and target pairs (PowerModels JSON and PowerWorld sources into the targets other than PowerModels) rest on the Rust round trip suite.

• PowerModels.jl (validate_powermodels.jl, validate_psse.jl, core_json.jl) reads MATPOWER, PowerModels JSON, and PSS/E. The MATPOWER to PowerModels JSON path is checked field by field after per unit normalization, and the others by element counts and demand, generation, and shunt totals.
• egret (validate_egret.py) is the oracle for egret output, which PowerModels cannot read. It loads powerio’s egret JSON with egret.data.model_data.ModelData and compares counts, totals, and generator cost curves.
• ExaPowerIO.jl (validate_exapowerio.jl) reads MATPOWER through powerio’s C ABI and compares value for value.
• pandapower (validate_pandapower.py, validate_pandapower_converter.py) cross checks the MATPOWER parse and \(Y_{\mathrm{bus}}\), then imports powerio’s pandapower JSON output back into pandapower and compares counts and \(Y_{\mathrm{bus}}\).
• PyPSA (validate_pypsa.py) imports powerio’s PyPSA CSV folder output and checks counts, totals, line r/x/b rebased from ohms on the bus0 voltage, and transformer r/x/tap_ratio/s_nom rebased from the transformer s_nom base. A mismatch in the line and transformer split fails the case.

The conversion matrix

evals/validation/validate_matrix.py converts each source to each legacy text target and checks the electrical core of the output (bus, branch, and generator counts and the per unit demand, generation, and shunt totals) against the source’s own core as an independent oracle reads it. The diagonal is checked byte exact, meaning that writing a case back to its own format reproduces the file. Sources are the real native files where they exist (the vendored PSS/E .raw and egret .json) and representative MATPOWER cases otherwise: basic (case9), shunts and transformers (case14, case30), size (case118, case2869pegase), HVDC with a mixed piecewise and polynomial gencost (t_case9_dcline), and a piecewise cost case (pglib_opf_case5_pjm).

All 65 legacy text cells pass (13 source cases × 5 targets). Each writer preserves the core regardless of fidelity tier, which is why the core is the invariant checked across the whole matrix; cost, HVDC, and angle limits are tier specific and are covered by the dedicated checks above and the Rust suite. The pandapower JSON and PyPSA CSV validators run alongside this matrix and are reported as separate legs.

Running it

cargo build --release -p powerio-capi
python3.11 -m venv .venv
.venv/bin/python -m pip install --upgrade pip maturin -r evals/validation/requirements.txt
env VIRTUAL_ENV=$PWD/.venv .venv/bin/maturin develop --release
julia --project=evals/validation -e 'using Pkg; Pkg.instantiate()'
bash evals/validation/run_validation.sh

The oracle tools (PowerModels.jl, egret, ExaPowerIO.jl, pandapower, PyPSA) are declared only in evals/validation/Project.toml and evals/validation/requirements.txt, and no PowerIO release artifact depends on them. evals/validation/run_validation.sh expects the Python oracles to import in the selected Python 3.11+ environment, so a missing PyPSA, pandapower, or egret import is a setup failure.

Format notes

Each loss produces a coded diagnostic. A reader itemizes what it keeps only in the retained source, with the table and the count of affected rows; a writer reports what the target cannot represent, and emit returns those findings with the result. A code spells out the format and the reason, as in READ.CGMES.RECORD_UNMAPPED, READ.CGMES.FIELD_UNMAPPED, READ.XIIDM.FIELD_UNMAPPED, or EMIT.PSSE.FIELD_DROPPED for RAW and RAWX, so there is no generic parse warning that hides the cause.

XIIDM and JIIDM

PowerIO reads PowSybl IIDM 1.0 through 1.17 in the XML (xiidm) and JSON (jiidm) encodings and writes 1.17 in either; the IIDM versions table lists what each version changed. One element mapping serves both encodings, so a JIIDM document reads to the same network as the XIIDM document of the same network, and fresh JIIDM follows PowSybl’s JSON layout: plural array fields for repeated elements, typed scalars, and each element’s attributes in the order PowSybl’s sequential JSON reader consumes them.

The mapping covers substations, voltage levels, bus breaker and node breaker topology, busbar sections, switches, lines, tie and boundary lines, loads, generators, batteries, shunts, static VAR compensators, two and three winding transformers, tap changers and controls, operational limits, reactive limits, HVDC converters, aliases, properties, and PowSybl active power control. Areas, one level of nested XIIDM networks, nonlinear shunt section models, physical DC equipment, and VSC/LCC converters also parse and survive fresh emission. An unknown extension subtree stays available for byte exact same format emission and produces a diagnostic, but it does not become an unnamed field on the network. Fresh emission preserves detailed connectivity when the source has it and allocates any missing local node numbers without changing stable PowerIO identities. A three winding transformer whose ratedU0 differs from ratedU1 keeps that leg impedance base for fresh emission.

XIIDM gives electrical quantities in physical units and has no system MVA base, so the balanced calculation view uses 100 MVA as its internal normalization and does not report a missing source value. Fresh XIIDM or JIIDM emission reports a network base other than 100 MVA, because the target has nowhere to put that normalization; impedance and admittance conversion still uses the network’s actual base, so the physical electrical values come out unchanged.

CGMES

PowerIO reads CGMES 2.4.15 on CIM16 and CGMES 3.0 on CIM100. CGMES 2.4.15 uses the namespace http://iec.ch/TC57/2013/CIM-schema-cim16# with the ENTSO-E extension namespace http://entsoe.eu/CIM/SchemaExtension/3/1# (IEC TS 61970-600-1/-2:2017); CGMES 3.0 uses http://iec.ch/TC57/CIM100# and http://iec.ch/TC57/CIM100-European# (IEC 61970-600-1/-2:2021). Both use the IEC 61970-552 CIMXML instance syntax, in which rdf:ID defines a record, rdf:about extends one, and md:FullModel heads each profile document. EQ is required, and SSH, SV, and boundary profile data are used when present. SSH assignments take precedence over SV observations, so an SV shunt section count that differs from the SSH assignment is reported and not kept. A set with TopologicalNode data reads one bus per TopologicalNode, and that data wins even for node breaker equipment, so source TopologicalNode identities survive.

A set without TopologicalNode data still reads when its declared profile URIs describe node breaker equipment, using the same test PowSybl makes in CgmesModelTripleStore.computeIsNodeBreaker: each CGMES 2.4.15 document that declares EquipmentCore also declares EquipmentOperation (and each EquipmentBoundary document declares EquipmentBoundaryOperation), or the EQ is CGMES 3.0 CoreEquipment with ConnectivityNode records. The buses are then the connected components of the ConnectivityNode graph joined by switches that are closed and in service, which is the graph PowSybl’s NodeMapping and SwitchConversion hand to IIDM.

A switch is open when SSH Switch.open says so, otherwise when EQ Switch.normalOpen says so, and otherwise closed. SV SvStatus.inService, or failing that SSH Equipment.inService, decides service status, which CGMES defines as availability for topology processing (PowSybl 7.3 reads only the switch position, and since the official sets contain no closed switch out of service, both rules agree there). A terminal is connected unless SSH ACDCTerminal.connected is false; a disconnected terminal leaves its equipment on the bus of its ConnectivityNode with the equipment out of service, which is where PowSybl inserts a fictitious open switch. Each bus takes the nominal voltage of its nodes’ VoltageLevel (a Bay resolves to its VoltageLevel), a node in a Line container takes the base voltage of attached conducting equipment or transformer ends, and a node no terminal references gets no bus. A bus is named after a BusbarSection on it, or else after its first ConnectivityNode. Its mRID is the UUIDv5, under PowerIO’s CGMES namespace, of the sorted ConnectivityNode mRIDs it joins, so the same nodes always yield the same mRID and no source TopologicalNode mRID is invented; the bus_breaker_buses table stays empty and calculated_buses lists the nodes of each bus. READ.CGMES.TOPOLOGY_CALCULATED, a remark, gives the bus, node, and switch counts and the identity rule; READ.CGMES.CONNECTIVITY_INSUFFICIENT, an error, says which data is missing when a set has neither TopologicalNode records nor calculable connectivity, such as a bus branch EQ without TP.

The calculated topology has limits. SvVoltage observations reference TopologicalNodes, so bus voltages keep their defaults and READ.CGMES.RECORD_UNMAPPED counts the observations. No TopologicalIsland supplies an angle reference, so the reference bus comes from referencePriority, an external injection, or the largest machine. A closed switch between two voltage levels joins its nodes into one bus placed in the first node’s level, as PowSybl merges those levels. A 2.4.15 junction terminal in EQ_BD has no ConnectivityNode and is read as disconnected when there is no TP_BD. Finally, PowSybl’s bus view omits a component with no busbar section and fewer than two feeders while PowerIO keeps each component as a bus, so bus counts differ by those components. Each document’s Model.modelingAuthoritySet is read for the boundary and state variable authority checks, reported, and not kept; fresh output writes PowerIO’s own modeling authority.

A source can be an XML profile directory, a directory of profile ZIP files, or one ZIP containing the profiles. The mapping covers hierarchy, AC and DC equipment, detailed connectivity, current, active power, and apparent power operating limits, tap changers and controls, reactive limits, and the operating and solution values in SSH and SV. Diagram, geography, dynamics, and unrecognized CIM classes are counted in diagnostics. A field on a recognized class that the mapping does not consume gets a grouped READ.CGMES.FIELD_UNMAPPED diagnostic with the class, field, count, and sample identities.

Fresh output is a deterministic CGMES 3.0 EQ, TP, SSH, and SV profile set. Imported UUID mRIDs survive for mapped equipment, terminals, tap changers, operational limit sets, hierarchy, and topology records, and a missing mRID becomes a UUIDv5 derived from the component type and stable identity. Tap changer tables, tap controls and table points, reactive curve points, and individual limit values keep their electrical values and relationships but get deterministic subordinate mRIDs on fresh emission. Operational limit helper objects that PowerIO generates do not become source metadata on readback. Limit type objects keep the PATL or TATL name common CGMES importers require, while generated limit set objects omit an unrepresented display name. A third party subordinate identity or field without a typed record still gets a diagnostic. The source neutral limit model keeps permanent and temporary limits, so fresh output uses PATL and TATL; parsing reports a PATLT or TCT substitution and any fractional duration rounded to whole seconds.

CGMES input keeps each source Substation, including distinct substations joined by a transformer. XIIDM and JIIDM emission joins output container groups only when the IIDM rule that a transformer belongs to one substation requires it, and it reports that hierarchy change; the transformer stays a transformer with the same electrical data. Distinct BaseVoltage identities at the same kV also get a precise collapse diagnostic before fresh output uses one record keyed by voltage. Busbar VoltageLimit records are combined with the enclosing voltage level into the most restrictive valid low and high voltage range; an inconsistent pair is diagnosed and ignored, and fresh emission writes the resulting VoltageLevel fields instead of recreating the individual VoltageLimit records. CGMES uses physical units and has no system MVA base, so the balanced calculation view uses 100 MVA as its internal normalization and does not report a missing source value.

PSS/E

PowerIO reads RAW revisions 32 through 35 and RAWX revision 35, and RAW and RAWX share one electrical mapping. RAW 32 records end before the bus voltage limits (NVHI, NVLO, EVHI, EVLO), the load INTRPT field, the transformer VECGRP field, and the winding CNXA field that revision 33 added, so the reader lays each record out by the header revision, defaults those fields, and reports a revision 32 record that ends before its last typed field as READ.PSSE.VALUE_DEFAULTED with the record’s byte range. RAW 34 maps its substation section. RAW 35 and RAWX 35 map and freshly emit substations, nodes, switches, busbar sections, and equipment terminal references. Fresh RAW 34/35 and RAWX output preserves AC line and transformer names, and RAWX terminal rows use the exact type, buses, and local identifier chosen for their electrical equipment row. When a source neutral connectivity node has no PSS/E number, fresh RAWX allocates a positive number within its substation before resolving exact regulation targets, and reports the default.

An explicit RAW revision outside 32 through 35, an invalid system base or frequency, or a nonfinite record value is rejected. Fresh output accepts only revisions 33 through 35 and returns an error when detailed connectivity cannot form valid RAWX tables. A RAW 32 module keeps its source text like any other revision, but no emission target names revision 32, so writing it back as PSS/E produces fresh revision 33 text and its unmodeled sections survive only in the retained source.

Generator IREG/NREG, switched shunt SWREG/NREG, and transformer CONT/NODE resolve to exact terminal references, including an explicit target on the same bus. Each winding of a three winding transformer keeps its control mode, regulated terminal, limits, tap position and range, and number of tap positions. A positive COD enables automatic adjustment, a negative COD keeps the same mode with automatic adjustment disabled, and zero is fixed; |COD| = 4 controls a DC line quantity on a two winding transformer, and |COD| = 5 controls asymmetric active power flow. Unsupported RAWX tables, including multiterminal DC, FACTS, GNE, induction machine, multisection line, zone, owner, and interarea transfer records, remain only in byte exact same format emission and produce counted diagnostics. Unknown RAWX tables and caseid fields get the same retained source diagnostic, and fresh output diagnoses detailed records and fields that RAWX cannot carry. Three winding transformers are kept as typed records, and the indexed view lowers each one as a star into \(Y_{\mathrm{bus}}\)/connectivity; two terminal DC lines map to the neutral HVDC model. A switched shunt keeps its steady state susceptance BINIT as the shunt b along with its mode, voltage band, regulated bus, and step blocks, and a two winding transformer’s magnetizing susceptance survives a round trip through MAG2. The reader converts CW 1/2/3, CZ 1/2/3, and CM 1/2 into the neutral tap ratio, system base impedance, and magnetizing admittance, and fresh output uses the electrically equivalent canonical CW = CZ = CM = 1 representation.

UCTE-DEF

PowerIO reads UCTE-DEF revisions 2003.09.01 and 2007.05.01 and writes 2007.05.01 under the token ucte (alias uct, extension .uct). The column layout is the one PowSybl Core’s UcteRecordParser reads for both revisions; a 2003 file leaves the element name columns blank. The reader maps the ##N nodes to buses named by their 8 character node code, with a bus id equal to the node’s position in the block and the base kV taken from the voltage level digit (750, 380, 220, 150, 120, 110, 70, 27, 330, or 500 kV). Each ##Z country is a ControlArea area named by its ISO code, and the cross border nodes (country letter X) form one CrossBorder area named XX, so a tie line keeps both ends and the cross border node’s own load and generation. Node types PQ, PU, and UT map to PQ, PV, and reference; type QT (Q and angle constant) reads as PQ with a warning. A node’s load and generation become one load and one generator, with the PowSybl consistency rules applied and reported: a missing set point reads as zero, a missing limit as 9999, inverted limits are swapped, a set point outside its limits moves the limit, and a voltage regulating node with no voltage reference reads as PQ.

##L lines are branches on the voltage level base with the total susceptance split evenly. Busbar couplers (status 2 and 7) are switches, an equivalent element (status 1 and 9) keeps that mark in its extras, and a reactance under 0.05 ohm reads as 0.05 ohm, as PowSybl reads it. A coupler whose two node codes are equal is ignored with a diagnostic, following PowSybl Core’s UcteImporter, and a line joining two voltage levels is refused, as PowSybl refuses it. ##T transformers are branches from the regulated winding (node 2) to the non regulated winding (node 1), whose voltage level carries the impedance; the rated voltages set the tap, and the magnetizing admittance sits on the regulated side. ##R phase regulation multiplies the tap by \(1 + n’ \delta u / 100\) and becomes a voltage control when it has a target, while angle regulation applies the PowSybl asymmetrical or symmetrical formulas to the tap and the phase shift and becomes a disabled active flow control. A record with both folds the phase regulation’s ratio into the angle formula, as PowSybl does, instead of multiplying the two results. Both regulations stay in the branch extras so that fresh UCTE output can write them back as they were read. ##TT special descriptions stay in the transformer extras and ##E exchange schedules stay in the retained source only; both are reported with READ.UCTE.RETAINED_SOURCE_ONLY. UCTE uses physical quantities and has no system MVA base, so the balanced calculation view uses 100 MVA as its internal normalization and does not report a missing source value. Each finding points at its record through a source span.

Fresh output writes nodes grouped by country in bus order. A bus keeps its name when it is a UCTE node code; otherwise it receives <country><spot><level><busbar>: the country letter of its area’s ISO name, else the area number’s entry in the UCTE country table in ISO order; the bus id in base 36 as the five character spot; the voltage level digit nearest its base kV (380 kV when the bus has none); and busbar 1, bumped on a collision. Each derived code is reported with EMIT.UCTE.VALUE_SUBSTITUTED. A base kV that is not a UCTE level is written under the nearest level with a warning; ohm, kV, MW, and ampere values stay physical, so reading the file back expresses them per unit on that level. A phase shift becomes a one step symmetrical angle regulation, its step solved against the phase regulation written beside it, and a voltage control with a tap range becomes a phase regulation; a line joining two voltage levels is written as a transformer. UCTE requires a node’s generation bounds to contain its dispatch, so the writer widens an inconsistent interval and reports the substituted bounds. An out of service generator contributes no dispatch but still supplies the node’s plant type letter, which keeps that source classification stable on readback. Shunts, HVDC, storage, static VAR compensators, three winding transformers, costs, capability columns, angle limits, voltage bands and angles, rate B and C, remote regulation, and a frequency other than 50 Hz are reported as dropped.

PowerWorld

.aux is read and written, .pwb binary cases are read only, and a .pwd display file parses to a GeoLayer (Geographic and display data). .aux has no system base, so the reader defaults to 100 MVA. No third party .aux reader exists, so the writer is validated by PowerIO’s own read back plus a PowerModels JSON bridge. The .pwb layouts are reverse engineered; the decode evidence and coverage matrix are maintainer notes at powerio-tx/src/format/powerworld/FORMAT.md.

PSLF

.epc is read and written. The reader maps the static power flow core: buses, lines, two and three winding transformers, generators, loads, fixed shunts, controlled shunts at their initial g/b, and limited two terminal DC records. Three winding transformers are kept as typed records, and the indexed view lowers each one as a star into \(Y_{\mathrm{bus}}\)/connectivity. Unsupported sections stay in the retained source text and produce diagnostics.

MATPOWER

Canonical MATPOWER output, for a case that did not start as MATPOWER, omits dcline; the byte exact echo path keeps it when the case was read from MATPOWER. Storage is written as an mpc.storage block.

egret

egret output writes HVDC as dc_branch, the element its reader already reads, so the power, voltage, and loss fields survive a round trip; a dcline cost curve and storage are the only things dropped. The reader takes the power flow ModelData subset (numeric bus ids, scalar values). A document whose system.time_keys vary the scalar profile parses to TimeSeries<BalancedNetwork> through powerio::parse, whereas the component crate’s powerio_tx::parse reads only the static profile and refuses it.

pandapower JSON

The pandapower JSON writer lays the power flow core out as split oriented pandapowerNet tables. Line ohms are referred to the from bus voltage, as pandapower’s build_branch reads them, and a bus with baseKV 0 writes vn_kv set to \(1\) (warned) so the per unit impedances survive. A branch with a tap, a shift, or terminals on two voltage levels becomes a trafo row with tap_changer_type = "Ratio"; because pandapower’s magnetizing model is inductive only, its MATPOWER charging b goes out as one bus shunt per terminal (warned, \(Y_{\mathrm{bus}}\) exact). The file is labeled with f_hz set to \(50\) and c_nf_per_km compensated, so a 60 Hz source keeps its exact \(Y_{\mathrm{bus}}\). A reference bus without a generator gets an ext_grid row, which reads back as a Ref generator. The writer also warns on dropped HVDC, storage, capability columns, angle limits, rate B/C, nonfinite values (written as JSON null), and costs poly_cost cannot carry. The reader models ratio, ideal, and pandapower 2.x tap changers, off nominal vn_hv_kv/vn_lv_kv, lv side taps, and shunt vn_kv scaling; ZIP load composition, line shunt conductance, magnetizing branches, tabular tap changers, reactive cost coefficients, and any other table with rows warn with row counts.

PyPSA CSV folders

PyPSA CSV folders are canonicalized directory outputs rather than byte exact text conversions. The mapping covers static buses, generators, loads, lines (ohms on the bus0 voltage, as PyPSA computes them), transformers (rebased between the system base and the transformer s_nom), shunts, storage units, and base MVA. The reader maps links to HVDC with a warning, requires v_nom and balanced CSV quoting, and warns on stores, nonzero g, and each CSV it does not read (time series, carriers). The writer keys tables by bus name, falling back to the numeric id when names collide (warned), and warns on dropped HVDC, q limits, mbase, transformer angle limits, rate B/C, isolated buses, nonfinite p limits, and slackless or normalized networks. Nonnumeric bus names read back as dense synthetic ids with the originals on Bus.name.

DOE GO Challenge 3 JSON

DOE GO Challenge 3 JSON is a grid exchange format “for Challenge 3 and beyond,” so the format name is broader than any one calculation type. PowerIO recognizes its Challenge 3 input/problem data file and returns AcScucInstance. The instance has the declared time points and durations, initial commitment and dispatch, time varying bounds, costs and reserves, energy windows, contingencies, and one shared BalancedNetwork, which instance.network() returns. One directory or memory Source containing both the input/problem data file and its matching output/solution data file returns AcScucSolution; an output/solution data file on its own is rejected, because it has neither the component definitions nor the time axis. Problem data is parse only. A complete AcScucSolution emits the official output/solution data file, including bus voltage, shunt step, device commitment, dispatch and reserves, AC line status, transformer tap, phase shift and status, and DC line terminal power fields. The pinned GO-3 model validates PowerIO’s small problem and output documents and all of the D1/D2/D3 input/problem data files, and C3DataUtilities reports no data, ignored, or solution errors for those documents. The older pinned GO-3 model and D1/D2/D3 files still have network.bus.con_loss_factor, a field that version 1.1.1 of the data format removed; PowerIO keeps the original source and reports one bounded diagnostic instead of treating it as an electrical network or AC SCUC field. Optional bus location labels and incomplete coordinate pairs stay in Bus.extras, and optional consumer descriptions, voltage setpoints, and nameplate capacities stay in Load.extras; each reports READ.GOC3.OPTIONAL_FIELD_UNTYPED. A producer description has no generator metadata field to go to and reports READ.GOC3.RETAINED_SOURCE_ONLY.

Surge JSON

PowerIO reads and writes the versioned surge-json network document. The reader maps buses, loads, fixed shunts, branches, generators, storage, and HVDC links into BalancedNetwork, keeps the original source for same format echo, and warns about source sections that stay only in the retained document. The writer emits a canonical Surge network body for the supported power flow core, and richer MATPOWER generator capability or ramp columns and unsupported cost shapes are reported in the emission diagnostics. An HVDC link has the terminal voltage setpoints, the reactive limits, and the loss model on its converter terminals; a Surge link has no terminal reactive flow, no cost curve, and no received power (the reader derives it from the setpoint and the loss model), so those are warned. A link with converter or control detail beyond the neutral converter this writer emits (firing angles, converter transformer taps, commutation impedance, a DC voltage schedule) is warned on the way in.

DeepMind OPFData JSON

The DeepMind OPFData reader takes one raw JSON document from a FullTop or N-1 release into the balanced transmission model. Topology, limits, loads, shunts, and quadratic costs come from grid; solved bus voltages, generator dispatch, and branch flows come from solution. Powers and ratings are converted from per unit, angles from radians, link indices from zero based to one based, and flow columns from [pt, qt, pf, qf] into the canonical terminal order. Original bus IDs and names, areas and zones, and frequency are absent, and the solver’s initial generator values differ from the solved snapshot, so a conversion to another format reports those facts. The adapter works from the feature widths and the row and link counts in each file rather than from a case name registry or expected element counts, so the same path covers all published grid families (14 through 13,659 buses) and both FullTop and N-1 examples; generator and branch outages appear as absent rows and links and are validated against that example’s solution topology. The published releases are derived from PGLib-OPF cases, but the reader does not use PGLib case names or a case registry, so a document from another source is accepted when it follows the same object layout, feature column order, units, and link rules. The paper’s Appendix A is the published format definition and the PyTorch Geometric loader is the executable reference. No separate JSON Schema or format version marker is published, so a document that departs from that layout is rejected by the reader’s shape and topology checks. An unrecognized object field stays in the retained source and produces a projection warning, so same format echo still works. The raw source echoes byte exactly; there is no canonical writer, .pt cache reader, archive reader, downloader, or batch directory API.

IEEE Common Data Format

IEEE Common Data Format (ieee-cdf, alias cdf) is read only. The reader takes the title card MVA base and date; the bus records (number, name, area, loss zone, type, solved voltage and angle, load, generation, base kV, desired voltage, MVAr or voltage limits, shunt G and B, remote controlled bus); the branch records (tap and Z bus, circuit, type, R, X, B, the three MVA ratings, control bus and side, turns ratio, phase shift angle, tap limits, step size, and the controlled quantity limits); and the interchange records (area number, slack bus, export, tolerance, code, and name). The tap bus is the from bus and a nonzero turns ratio marks a transformer. A blank branch type reads as a transmission line, as the PowSybl reader reads it; a type 1 through 4 branch without a ratio reads as unity; and types 2, 3, and 4 get a regulating transformer control block whose ntp derives from the step size. A type 1 bus reads as PQ with a fixed reactive generator and the limit columns as its voltage band, and every type 2 or 3 bus, along with any bus with nonzero generation, gets a generator. The format has no active power limits, no machine base, and no voltage limits, so pmin 0 MW, pmax 9999 MW, mbase equal to the system base, and vmax/vmin 1.1/0.9 p.u. are assumed and reported as READ.IEEE_CDF.VALUE_DEFAULTED. Loss zone names, tie lines, the branch area and loss zone columns, alternate swing bus names, and the title originator, year, and season survive in the retained source only (READ.IEEE_CDF.RETAINED_SOURCE_ONLY).

A record cut before a mandatory field reads that field as zero and reports READ.IEEE_CDF.RECORD_TRUNCATED with the record’s span. A header item count, terminator, misplaced record, zero impedance branch, or undeclared bus reference is READ.IEEE_CDF.SOURCE_MALFORMED, and a type or side code outside the documented set is READ.IEEE_CDF.VALUE_SUBSTITUTED. A title card without a positive MVA base, or a record whose bus numbers or numeric fields cannot be decoded, ends the read with a spanned PARSE.IEEE_CDF.MALFORMED. The column ranges follow PowSybl Core’s IeeeCdfBusReader and IeeeCdfBranchReader, which read the public archive files; those files place the last two branch limits one column to the left of the 1973 table, and the reader accepts both layouts. A .txt or .cdf file whose first card is a CDF title card is detected without a declared format. Fresh output of this format is not required, so there is no writer; emit to ieee-cdf is refused as read only, and a case converts to any writable format instead. The PowSybl gate reads every public IEEE case with PyPowSybl’s own CDF importer, compares its bus, branch, generator, load, and shunt counts and its load and generation totals with the PowerIO parse, then reloads fresh MATPOWER written from each case.

GridFM Parquet datasets

GridFM Parquet datasets (behind the gridfm feature, following the GridFM data kit output schema) parse to a scenario set of balanced networks over one shared element identity map. Each scenario recovers the complete native balanced table data: bus types, voltages, and limits; nodal load and shunt totals; generator dispatch, bounds, and the cp0/cp1/cp2 polynomial as given; branch r/x/b/tap/shift/rate_a/angle limits and pf/qf/pt/qt terminal flows; and baseMVA. Dense bus indices, nodal demand records, and line classification for a unit tap with zero shift are GridFM source facts and do not produce reader diagnostics.

Writing a richer network reports the projections into GridFM’s fixed tables: source bus renumbering, several loads or shunts combined at one bus, metadata and equipment with no column, and costs outside the fixed quadratic representation. If a branch has no solution in the source, the writer evaluates pf/qf/pt/qt from the stored bus voltages and reports that derived value. Generated component identities give PowerIO stable references and are not treated as source metadata. A native GridFM network writes without findings. Matrices and graphs describes the dataset the writer produces. Both directions need the gridfm cargo feature, which the CLI and the Python wheel include.

IIDM versions

PowerIO reads every IIDM serialization version PowSybl has published and writes 1.17. A document of an older version is read with that version’s rules and reported with READ.XIIDM.VERSION_COMPATIBILITY, and a namespace naming a version outside this table is refused with PARSE.XIIDM.VERSION_UNSUPPORTED. The table lists, per version, what the reader does differently from 1.17, and each row is checked against the PowSybl fixture of the same network in tests/data/xiidm/powsybl.

JIIDM has no namespace, so the document’s version field selects the same rules and minimumValidationLevel selects the validation level. PowSybl ships JIIDM fixtures from 1.11 on; an older version value reads with that version’s XML rules.

Missing generator costs

PSS/E .raw files have no generator cost curves. Converting a PSS/E case to MATPOWER writes mpc.gen and omits mpc.gencost with a warning, because powerio does not invent zero costs. If your workflow needs costs, pick a policy explicitly:

powerio convert case.raw --from psse --to matpower --missing-gen-cost zero -o case.m
powerio dcopf case.m -o out --missing-gen-cost quadratic --default-gen-cost 0.01,2.0,0.0
powerio gridfm case.raw --from psse -o out --missing-gen-cost zero

• preserve: leave missing costs absent (default for conversion and GridFM export);
• require: fail on an in service generator without cost (default for DC OPF export);
• zero: fill missing rows with a MATPOWER polynomial cost [0, 0, 0];
• quadratic: fill missing rows with --default-gen-cost C2,C1,C0.

--gen-cost-csv overrides costs by generator row before the missing cost policy runs. The header is gen_index,bus,c2,c1,c0,startup,shutdown: gen_index is zero based in the current generator table, bus must match that generator’s bus id (which catches a stale table after reordering), and startup/shutdown default to zero. GridFM stores cp0/cp1/cp2 columns; missing or unsupported costs still write zero columns, and the manifest separates missing_cost_gens, unsupported_cost_gens, zeroed_cost_gens, and synthesized_gen_costs.

Geographic and display data

PowerIO keeps coordinates when a supported source provides them. They are optional. No parser invents them, and when you emit a located case to a network format that has no place for coordinates, the writer reports the loss.

A standalone geographic document parses to powerio.GeoLayer, a value like any other case. The canonical .geo.json, plain GeoJSON, CSV or JSON records with aliased field names, headerless buscoords CSV, and a PowerWorld .pwd display all parse to it; a .pwd becomes a diagram space layer whose features target substations.

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let module = parse("layer.geo.json")?;
    let PioValue::GeoLayer(layer) = module.value() else {
        panic!("a layer document parses to powerio.GeoLayer");
    };

    // A layer travels through PowerIO IR and out as the canonical document.
    serialize(&module, "layer.pio.json")?;
    emit(&module, "geo-json", "layer.geo.json")?;
    Ok(())
}

If you need the raw display record, PwdDisplay is still available; it has the canvas, the save stamp, and the symbol table in diagram coordinates.

Coordinate fields

Balanced and multiconductor networks use the same JSON shape for coordinates:

#![allow(unused)]
fn main() {
pub struct Location {
    /// Longitude for geographic coordinates.
    pub x: f64,
    /// Latitude for geographic coordinates.
    pub y: f64,
    /// Point origin when it differs from the network default.
    pub kind: Option<CoordsKind>,
}

pub enum CoordsKind { Source, Synthetic, Manual, Derived }

pub struct GeoMeta {
    pub space: CoordinateSpace,
    pub kind: Option<CoordsKind>,
}

pub struct Canvas {
    pub width: Option<f64>,
    pub height: Option<f64>,
    pub units: Option<String>,
}

pub enum CoordinateSpace {
    Geographic { crs: Option<String> },
    Projected { crs: Option<String> },
    Diagram { canvas: Option<Canvas> },
    Unknown,
}
}

Balanced networks reach these types as powerio::geo::{Location, CoordsKind, CoordinateSpace, GeoMeta, Canvas} through BalancedNetwork.geo and Bus.location; multiconductor networks use the matching powerio_dist::geo types through MulticonductorNetwork.geo and DistBus.location, and a package serialization test keeps the two JSON shapes identical. A branch can also have a polyline route (Branch.route, DistLine.route) when the source provides intermediate geometry. Without one, a renderer draws the branch endpoint to endpoint from the bus locations.

The coordinate space belongs to the network, and a point sets its own kind only when its origin differs from the network default. For geographic coordinates, x is longitude and y is latitude, which is GeoJSON axis order, and a missing CRS means EPSG:4326. kind says whether the coordinates came from the source, a generated layout, a manual edit, or a derived transform.

Harvest and emit

A parser promotes source coordinates into location, sets the space, and removes the raw keys from extras. Writers read location.

MATPOWER, PSS/E, PowerModels, egret, PSLF, and Surge have no place for geometry. Emitting a located case to one of them reports the dropped locations, in the same way it reports a dropped base_frequency. If you need the coordinates to survive, powerio geo extract writes them as a separate layer document.

The geographic document

Coordinates also arrive and leave as files of their own, such as a Buscoords CSV next to a DSS master or a GeoJSON export from a GIS tool, and a renderer can hand back the layout it computed the same way. The container for such a file is GeoLayer, which the Rust facade’s parse returns as PioValue::GeoLayer.

The canonical form is a GeoJSON FeatureCollection with one foreign member, powerio_geo, and the suggested extension is .geo.json:

{
  "type": "FeatureCollection",
  "powerio_geo": { "powerio_version": "0.11.0", "space": "geographic", "kind": "source" },
  "features": [
    { "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-80.05, 34.20] },
      "properties": { "target": "bus", "id": "312", "uid": "buses:11" } },
    { "type": "Feature",
      "geometry": { "type": "LineString", "coordinates": [[-80.05, 34.20], [-80.10, 34.30]] },
      "properties": { "target": "branch", "uid": "branches:4", "from": "312", "to": "410" } }
  ]
}

When the space is geographic this is valid RFC 7946 GeoJSON, so GIS tools open it directly.

Parsing is tolerant and emission is canonical. GeoLayer::parse takes UTF-8 text plus a file name hint and touches no filesystem. It accepts headerless buscoords CSV (bus, x, y), CSV and JSON records with aliased field names (bus_i/bus/id, lat/latitude/y, lon/lng/longitude/x, branch endpoint pairs), and GeoJSON Point and LineString features. A feature refers to its element by up to three key fields, tried in order: uid, then id, then case insensitive name. A branch route can also fall back to the unordered (from, to) bus pair. A bare integer branch id (branch, branchid, branchnumber, catsid) is accepted on the way in as a one based positional row alias and is not written back; the uid in the payload is the durable key. A branch key ignores a bare id property, because GIS exports and RFC 7946 tooling put a feature row counter there.

BalancedNetwork::to_geo_layer() turns a network’s coordinates into a layer, and BalancedNetwork::apply_geo_layer(&layer) applies one and returns a GeoApplyReport with the matched and unmatched feature counts plus unlocated_buses and unlocated_branches, the elements still without geometry when the pass ends. Together those counts let you tell a layer that matched nothing from a model that needed nothing, and report.require_located() is the one line check for a caller that wants everything placed. The multiconductor equivalents, to_dist_geo_layer and apply_dist_geo_layer, live in powerio::dist_geo. The CLI wraps the same functions:

$ powerio geo extract case.aux -o case.geo.json
$ powerio geo apply case.m layout.csv -o placed.m
$ powerio geo convert buscoords.csv -o case.geo.json

PowerWorld display files

The .pwd reader returns a diagram space GeoLayer whose features place the decoded substations. Python also keeps the raw display compatibility helper parse_display, which returns DisplayData(kind="powerworld", data=PwdDisplay(...)) with the canvas dimensions, a timestamp, and the substation symbols.

The facade helpers connect it to the geo model. to_geo_layer_from_pwd lifts the substation symbols into a diagram space GeoLayer, which is also what powerio geo extract case.pwd does. to_geo_layer_from_aux_text parses the Latitude and Longitude columns of an AUX Substation table straight into a geographic layer. apply_substation_points joins either layer onto buses through the SubNum extras key. to_lonlat_from_pwd_mercator is a documented, approximate inverse of the projection PowerWorld’s auto generated layouts use, for when you want to place a diagram on a map. The component crate keeps to_geo_layer_from_aux_substations(&AuxFile) for parser authors, since the facade does not expose its borrowed parser type.

A bus row in a complete case export has its own coordinates as well. The aux reader promotes the substation Latitude:1/Longitude:1 pair, or, when those are absent, the bus’s own bare Latitude/Longitude pair, into Bus.location, and a promoted pair leaves extras.

In Rust a display file parses to PioValue::GeoLayer. There is no path from a display file to a BalancedNetwork; it is always a layer, and both module emission and PowerIO IR handle it as one.

Distribution graph projection

MulticonductorNetwork::to_graph() returns a bus and terminal graph and does not need coordinates to do it; in Python that is dist_net.to_graph(). Graph topology and geographic placement stay separate data.

PowerIO stores and transports coordinates and does not compute them. Laying out a case that has none is renderer math and belongs in the consumer, which can store the result with kind = synthetic so the origin of the coordinates survives.

Python has parse_geo, and both network types have to_geo_layer() and apply_geo_layer().

Rust, Python, Julia, and C

Rust, Python, Julia, and C expose the same operations on the same power system types:

source -> parse -> PioModule<T> -> calculation or update -> emit
                         |
                         +-> serialize -> PowerIO IR

parse and emit handle grid exchange formats, while serialize and deserialize handle PowerIO IR. A calc_* function returns a derived matrix, vector, report, or count, and a to_* function transforms a value in memory into another semantic type. The nouns are stored values and fields: module, value, diagnostics, network, bus, branch, generator, load, operating point, time series, scenario set, instance, solution.

To find out what you parsed, Rust matches on the PioValue case that module.value() returns, Python uses isinstance, Julia dispatches on PioModule{T} and on the concrete value types, and C compares canonical structural type names with pio_value_is_type before calling the typed accessor for the type it handles.

Only Rust and C have a Source type, because both need an explicit owner for acquired bytes. A Python path, open file, or bytes-like object, or a Julia path, IO, or byte vector, already says where the bytes come from, and the interpreter owns them, so parse takes them directly and reads the source name from the path or from the name argument.

A format made of related files goes through the same parse. For GO Challenge 3, a directory holding the problem file returns AcScucInstance, and once the matching solution file sits beside it the same call returns AcScucSolution.

Member access

Member names match across the four languages; what differs is the syntax, which follows what each language’s users expect.

Rust containers (PioModule, BalancedNetwork, MulticonductorNetwork, instances, and solutions) keep their fields private because they maintain invariants; value_mut severs retained source bytes, for example, and add_diagnostic rejects a duplicate identifier. Rust element records (Bus, Branch, Generator, Load, and the rest) are plain public structs, because struct literals and pattern matching are how Rust users build and read them. Python keeps the n_* counts because a table property builds one dict per row. A Python element is a dict keyed by the Rust field names, while a Julia element is an immutable struct whose field names are the C ABI names, which spell out the quantity and unit (vm_pu, active_power_mw). Unifying those two sets of field names is listed under Known limits.

Collections

TimeSeries<T> and ScenarioSet<T> contain typed entries, and each language reaches them its own way.

An entry is either the contained value or a view rooted in the owning module, so indexing does not serialize, expand, or copy a complete network.

Calculations

The DC matrix and vector functions have the same names in each language:

calc_incidence_matrix
calc_branch_susceptances
calc_bus_susceptance_matrix
calc_branch_flow_matrix
calc_branch_phase_shift_injection
calc_bus_phase_shift_injection
calc_branch_flow_dc
calc_bus_injection_dc

Rust and C use zero based sparse matrix positions, Python sparse matrices use SciPy’s zero based positions, and Julia presents one based indices. Stable component identities and source identifiers do not change at a language boundary. Matrices and graphs gives the signs and equations.

Errors and ownership

Rust returns Result, Python raises PowerIOError subclasses, Julia throws a PowerIOError with structured diagnostics, and C returns a documented failure value and writes one PioError * through its error output. Each failure has a stable diagnostic code.

Python and Julia keep the native owner alive behind the borrowed typed views they hand you, whereas C callers retain and release opaque handles themselves. Ownership differs; the data types and the operation names do not.

Python API

Install the base package for parsing, emission, PowerIO IR, and typed values:

pip install powerio

The matrix and graph helpers need optional packages, so install the extra you want:

pip install 'powerio[matrix]'   # NumPy and SciPy
pip install 'powerio[graph]'    # NetworkX
pip install 'powerio[gridfm]'   # Polars
pip install 'powerio[all]'      # the three above
pip install 'powerio[pandas]'   # pandas and PyArrow tables, Python 3.10 or later
pip install 'powerio[mcp]'      # the MCP server, Python 3.10 or later

Importing powerio and calling parse, emit, serialize, or deserialize does not import any of those optional packages.

Parse one source

powerio.parse accepts a path, a file object, or a bytes-like object. A str is always a path, so wrap raw text in io.StringIO. There is no Python Source class, because a path, file object, or bytes-like value already says where the bytes come from and the interpreter owns them; parse takes it directly. Rust and C build a Source because they need that ownership made explicit, as Rust, Python, Julia, and C explains.

from io import StringIO
from pathlib import Path
import powerio

case = powerio.parse(Path("case9.m"))
case_from_text = powerio.parse(
    StringIO(matpower_text), format="matpower", name="case9.m"
)
case_from_binary = powerio.parse(
    pwb_bytes, format="pwb", name="case.pwb"
)

format is optional when the source name and content identify the format. name applies only to memory and file object sources, where it supplies a source name for diagnostics and format detection. There is no separate parse_file, parse_text, or parse_bytes API.

Parse a GO Challenge 3 solution

Put the GO Challenge 3 problem file and its matching solution file in one directory, and the ordinary parse call reads both:

solution = powerio.parse("scenario_002")
assert isinstance(solution.value, powerio.AcScucSolution)

With only the problem file, the same call returns AcScucInstance. A solution file on its own fails, because it has neither the component definitions nor the time axis. The solution module keeps both files and its diagnostics.

Module values and diagnostics

Parsing returns a PioModule[T], where module.value is the concrete Python value and module.diagnostics is the list of diagnostics stored on that module.

module = powerio.parse("case9.m")

if isinstance(module.value, powerio.BalancedNetwork):
    print(module.value.n_buses)

for diagnostic in module.diagnostics:
    print(diagnostic.code, diagnostic.severity, diagnostic.message)

Diagnostics live on the module rather than on the contained network or solution. To find out what you have, use Python’s normal type system; there is no .kind property, kind enum, or typed narrowing helper.

The value classes are BalancedNetwork, dist.MulticonductorNetwork, OperatingPoint, TimeSeries, ScenarioSet, GeoLayer, the PF, OPF, and SCUC instances and solutions, and SocwrOpfSolution.

Emit grid exchange formats

powerio.emit is the only function that writes a grid exchange format:

result = powerio.emit(module, "matpower")
text = result.text

result = powerio.emit(module, "psse", "case.raw")
result = powerio.emit(module, "pypsa", "case-directory")

With no destination the artifacts stay in memory; a path destination writes one file or a directory, and a writable file object accepts a single file artifact. An EmitResult has the artifacts (one Artifact per produced file, with its name and either data for a memory result or path after a filesystem commit), the layout, the fidelity, and the emission diagnostics. result.text is the UTF-8 memory artifact when there is a single one, and None otherwise.

PowerIO IR has its own pair of functions:

ir = powerio.serialize(module)
powerio.serialize(module, "case.pio.json")
same_module = powerio.deserialize(ir.artifacts[0].data)

The IR header is "schema": "pio-ir" with the integer "version": 2, and powerio.versions()["powerio_ir"] reports both. The producer record gives powerio.__version__ separately. deserialize refuses a document whose schema or version it does not support and reports what it found. PowerIO IR is not a grid exchange format, so it does not appear in format discovery.

Collections

TimeSeries behaves like a Python sequence and ScenarioSet like a mapping:

series = module.value
first = series[0]
for value in series:
    use(value)

scenarios = scenario_module.value
base = scenarios["base"]
for scenario_id in scenarios:
    use(scenario_id, scenarios[scenario_id])

Entries are owner rooted typed values, so indexing does not serialize or copy a complete network.

Typed updates

PowerIO supplies OperatingPointUpdate, NetworkUpdate, and CalculationUpdate. Each update targets a stable ComponentId, and power values use ActivePower, ReactivePower, or ApparentPower so the unit is explicit.

report = powerio.apply_updates(
    module,
    [
        powerio.OperatingPointUpdate.set_load_active_power(
            load_id, powerio.ActivePower.megawatts(42.0)
        )
    ],
)

for change in report.changes:
    print(change.component_id, change.field)
print(report.connectivity_changed)

The whole batch is validated before anything is mutated, so a failed batch leaves the module unchanged. The UpdateReport lists each change and says whether energized connectivity changed.

Matrices and vectors

The derived calculations are calc_* methods on BalancedNetwork:

A = network.calc_incidence_matrix()
b = network.calc_branch_susceptances()
B = network.calc_bus_susceptance_matrix()
Bf = network.calc_branch_flow_matrix()
p_branch = network.calc_branch_flow_dc(voltage_angles)
p_bus = network.calc_bus_injection_dc(voltage_angles)

calc_admittance_matrix, calc_bprime_matrix, calc_ptdf, calc_lodf, to_normalized, and to_networkx are methods of the same class. SciPy is imported only when you ask for a sparse matrix, NumPy only for the array based helpers, and NetworkX only inside to_networkx.

Other functions

Errors

A parse failure raises PowerIOParseError, and valid data that cannot satisfy an operation raises PowerIODataError. Both derive from PowerIOError and have a stable diagnostic code, so branch on .code rather than on the rendered message. A Rust panic inside the extension raises PowerIOError with code BIND.PY.PANIC instead of pyo3_runtime.PanicException, and the module is left unchanged, because each mutation is built in full before it is installed.

MCP server

The optional MCP server accepts paths, grid exchange content held in memory, and serialized PowerIO modules through the powerio_ir field. Electrical inputs and outputs stay PowerIO types and PowerIO IR; the server does not define another network, calculation, update, or solution schema.

Filesystem access is off unless POWERIO_MCP_ALLOWED_ROOTS lists the directories the server may read, and remote URI schemes are rejected. Host approval, request identifiers, timeouts, and cancellation are MCP transport concerns and do not touch the PowerIO data.

C ABI

powerio-capi exports ABI 7 through powerio-capi/include/powerio.h. The header is generated from the Rust declarations and checked in. Regenerate it with:

cbindgen --config powerio-capi/cbindgen.toml --crate powerio-capi \
  --output powerio-capi/include/powerio.h

scripts/capi-header-parity.sh compares the exported symbols with the header in every CI feature job, and scripts/capi-header-regen.sh regenerates the header with cbindgen and diffs it once. Do not edit the header by hand.

ABI 7 is the only C API in PowerIO 0.11; symbols from ABI 4, 5, and 6 are not exported and have no aliases. Compare pio_abi_version() with PIO_ABI_VERSION before you use the library.

The exported symbol set is fixed. The gridfm cargo feature adds GridFM Parquet parsing and emission behind the same entry points, and the arrow, matrix, dist, and prob feature names are still accepted by the build but gate nothing. pio_schema_report returns a JSON document with the release (powerio_version), the ABI (abi), the PowerIO IR schema name and generation (powerio_ir with schema and version), the BMOPF schema version, the compiled features, and the diagnostic namespaces and error categories.

Parse and inspect a module

PioError *error = NULL;
PioSource *source = pio_source_open("case9.m", 7, &error);
PioModule *module = pio_parse(source, NULL, 0, &error);
PioValueHandle *value = pio_module_value(module);

if (!pio_value_is_type(value, "powerio.BalancedNetwork", 23)) {
    /* handle an unexpected PowerIO type */
}

PioBalancedNetwork *network = pio_value_balanced_network(value, &error);
size_t buses = pio_balanced_network_bus_count(network);

PioDiagnostics *diagnostics = pio_module_diagnostics(module);
for (size_t i = 0; i < pio_diagnostics_len(diagnostics); i++) {
    PioStringView code = pio_diagnostic_code(diagnostics, i);
    /* code.data has code.len bytes and is not NUL terminated */
}

pio_diagnostics_release(diagnostics);
pio_balanced_network_release(network);
pio_value_release(value);
pio_module_release(module);
pio_source_release(source);

Use pio_source_from_memory for text or binary bytes you already hold in memory; both source constructors feed the same pio_parse. pio_geo_layer_parse reads a geographic layer straight from text, with no source object, for callers that have the layer document in memory.

pio_module_value returns an owner rooted value handle, and the exact typed accessors return owner rooted views without serializing or copying the module value. Releasing a module does not invalidate a child you have retained. Every opaque handle has matching retain and release functions, and release(NULL) is a no-op.

Structural type names have replaced ordinal kind integers. Check the type with pio_value_type_name or pio_value_is_type, then call the exact typed accessor for the type you handle.

Diagnostics and errors

Fallible functions take one PioError ** output and signal failure with a null return or a documented failure value. Inspect pio_error_code, pio_error_message, and pio_error_diagnostics, and branch on the stable code rather than the message text. If you pass a null error output the error is discarded.

Every string and buffer comes with an explicit length. PioStringView, PioByteView, PioSizeView, and PioF64View borrow their data from an owning handle and need not end in NUL.

Emit and serialize

pio_emit writes a grid exchange format. With a memory destination the artifact bytes stay in the returned PioEmitResult; with a path destination the artifacts are written to disk and the result holds the same list of artifacts and the same diagnostics.

PioDestination *destination = pio_destination_memory("case", 4, &error);
PioEmitResult *result = pio_emit(module, "matpower", 8, destination, &error);

for (size_t i = 0; i < pio_emit_result_artifact_count(result); i++) {
    PioArtifact *artifact = pio_emit_result_artifact(result, i, &error);
    PioStringView name = pio_artifact_name(artifact);
    PioByteView bytes = pio_artifact_bytes(artifact);
    /* consume name and bytes before releasing artifact */
    pio_artifact_release(artifact);
}

pio_emit_result_release(result);
pio_destination_release(destination);

pio_module_serialize writes PowerIO IR and pio_module_deserialize reads it. The IR header is "schema": "pio-ir" with integer "version": 2, and pio_schema_report reports both; the producer record names the PowerIO release separately. pio_module_deserialize refuses an unsupported schema name or generation and tells you what it found. ABI 7 has no reader for earlier generations and no module JSON aliases.

Collections, updates, and calculations

Time series and scenario set handles give you the length and owner rooted access to each element. Positions are zero based in C, and scenario sets can also be looked up by scenario ID.

Typed update constructors produce PioOperatingPointUpdate, PioNetworkUpdate, and PioCalculationUpdate. pio_apply_updates validates the whole batch before it applies anything and returns a PioUpdateReport listing the exact component IDs and fields it changed, and whether energized connectivity changed.

Named matrix and vector functions expose the public DC calculations directly:

pio_calc_incidence_matrix
pio_calc_branch_susceptances
pio_calc_bus_susceptance_matrix
pio_calc_branch_flow_matrix
pio_calc_branch_phase_shift_injection
pio_calc_bus_phase_shift_injection
pio_calc_branch_flow_dc
pio_calc_bus_injection_dc

Sparse matrices come back as owned CSR arrays and vectors as owned double arrays. The C API has no public DC data bundle.

CLI and MCP

The powerio command

The powerio binary runs the same operations from a shell, and with no subcommand it opens the interactive TUI.

powerio convert case14.m --to psse -o case14.raw   # parse + emit, findings on stderr
powerio summary case14.m                           # the canonical network summary JSON
powerio serialize case14.m -o case14.pio.json      # PowerIO IR
powerio verify case30.m --kind bdoubleprime        # matrix stats and the SDDM check
powerio batch -i tests/data -o out --matrices bprime,bdoubleprime
powerio sensitivities case30.m -o out              # PTDF and LODF
powerio dcopf case30.m -o out                      # the static DC OPF bundle
powerio gridfm case14.m -o out                     # a GridFM Parquet dataset
powerio geo extract case.aux -o layer.geo.json     # standalone geographic layers

The other subcommands are batch, which writes matrix families for every case in a directory, gen, which writes synthetic cases, geo apply and geo convert, corpus, the private corpus harness described in Corpus harness, and tui. dcopf accepts the alias dc-opf. --from and --to take the format tokens and aliases of the format table; iidm and rawx are accepted as input spellings only.

Format names, structural value types, and diagnostic codes are the same strings the language APIs use. Diagnostics print one per line on stderr as CODE: message.

Standard input and output

convert, summary, serialize, verify, dcopf, and sensitivities read the case from standard input when the input is -. A stream has no file name to infer a format from, so --from is required, and a gridfm dataset is a directory, so it cannot arrive on a stream at all. convert and serialize write a single text result to standard output when -o is - or omitted; a directory format such as pypsa-csv or cgmes needs an output directory.

cat case9.m | powerio convert - --from matpower --to psse -o - > case9.raw
powerio serialize - --from psse < case9.raw

Exit status

The categories are the ErrorCategory values the Rust and Python APIs report on every failure, so a shell script and a Python caller branch on the same five names.

Every failure the binary reports is a PowerIO error with a registered diagnostic code, including the ones the command line raises itself (REQUEST.CLI.FORMAT_REQUIRED, REQUEST.CLI.TARGET_UNSUPPORTED, REQUEST.CLI.OUTPUT_REQUIRED, REQUEST.CLI.FAMILY_MISMATCH, REQUEST.CLI.OPTION_INVALID, REQUEST.CLI.NO_CASES, PARSE.CLI.ERRORS_REPORTED, VALIDATE.CLI.INPUT_LACKS_DATA, EMIT.CLI.SIDECAR_PATH, EMIT.CLI.ERRORS_REPORTED). A reader that reports errors ends the run with PARSE.CLI.ERRORS_REPORTED and status 4 after the output is written; a writer that reports errors ends it with EMIT.CLI.ERRORS_REPORTED and status 6. A failure that reaches the top of the program without a registered code is reported as BIND.CLI.UNCLASSIFIED and exits 1.

Diagnostics format

--diagnostics-format text (the default) prints one CODE: message line per diagnostic as the command runs, wrote <path> when a file lands, and a failure as Error: and Caused by: lines.

--diagnostics-format json (accepted before or after the subcommand) prints one JSON array on stderr when the command ends, and nothing else. The array holds every diagnostic the run produced, warnings and errors alike, as PowerIO IR diagnostic records: the same encoding a module’s diagnostics field carries in a .pio.json document, with the same fields (id, severity, code, message, target, spans, related, details, suggested_action). A failure adds its record, and each further reason in its cause chain becomes a note record whose related names the failure record:

[{"id": "failure", "severity": "error", "code": "READ.IO.OPEN",
  "message": "cannot open source `case9.m`"},
 {"id": "d0", "severity": "note", "code": "READ.IO.OPEN",
  "message": "No such file or directory (os error 2)", "related": ["failure"]}]

The exit status stays the process exit status and is not repeated inside the records.

The MCP server

powerio-mcp (from the Python package) calls the public Python API directly. Its tools are parse, emit, summarize, diagnostics, to_normalized, calc_matrix, to_balanced_report, to_balanced, display, and about. parse returns serialized PowerIO IR, and the tools that accept powerio_ir deserialize that same IR rather than defining a network, collection, calculation, update, or solution representation of their own.

You address a collection entry with a plain zero based time_index or a scenario_id; no tool exports or expands an entry into a static network. emit(format, destination) writes a file or directory, and if you omit destination it returns the artifacts in memory. Diagnostics stay structured records with code, severity, message, target, and source spans.

pip install 'powerio[mcp]'   # Python 3.10 or later
powerio-mcp                  # stdio transport

The server accepts exactly one input source: serialized PowerIO IR, a grid exchange path, or grid exchange content in memory. Filesystem access is off unless POWERIO_MCP_ALLOWED_ROOTS names the directories the server may read, and remote URI schemes are rejected.

Known limits and versions

Known limits

• Format profiles are bounded. PyPSA support covers the CSV electrical profile; multi carrier components, investment periods, and stochastic data are retained and reported rather than typed, and PyPSA NetCDF does not parse. Egret support is the scalar network profile with time series, with unit commitment fields outside it. OpenDSS support is the static circuit; load shapes and solve instructions are retained and reported.
• DOE GO Challenge 3 problem data, DeepMind OPFData, PowerWorld PWB, and the IEEE Common Data Format are parse only, though a complete AcScucSolution does emit the official GO Challenge 3 solution file.
• PowerIO does not solve anything; instances feed external solvers.
• Balanced to multiconductor construction, load linearized multiconductor admittance from an operating point, and a general multi period planning instance are waiting on a later release, and dynamic simulation data has no representation.
• The multiconductor to balanced transformation is Rust and Python only. Multiconductor admittance assembly, powerio_matrix::calc_multiconductor_admittance_matrix, is Rust only.
• Only the MATPOWER and PSS/E readers attach source spans, marking the record each finding is about. Findings from the other readers, from transformations, and from writers have no byte range, and the text rendering of a diagnostic is still CODE: message.
• There is no one call convert in the library; you compose parse with emit. The command line does have powerio convert.
• The MATPOWER, PSS/E, and PowerWorld AUX readers tokenize without owned strings. PyPSA CSV, PSLF, and OpenDSS tokenize through owned strings, and the Egret, GO Challenge 3, OPFData, and pandapower readers decode through a generic JSON value tree first.
• Two sets of field names coexist. Rust records and Python dict rows use the MATPOWER derived names (vm, pg, rate_a, tap); C ABI 7 and Julia spell out the quantity and unit (vm_pu, active_power_mw, rate_a_mva, tap_ratio). Settling on one set of names for all four languages is a 1.0 decision, and it is separate from the PowerIO IR keys, which change only with a generation.
• Python tables return dict rows; typed element views like Julia’s are not offered yet.
• to_balanced and to_balanced_report live in powerio::transform rather than the facade root, and serialize_diagnostics returns a String where serialize returns an EmitResult.
• SocwrOpfSolution calls its branch flows branch_from_active_power where the other solutions say branch_from_active_flow, and its bus_order and branch_order are iterators rather than vectors. PowerIO IR generation 2 has the same split in its keys.

Versions

One PowerIO release version covers the Rust crates, the Python distribution, and PowerIO.jl. The boundaries checked independently are:

The release version is what you install. ABI 7 is what a compiled consumer has to match. The IR generation identifies the serialized document; its rule is in PowerIO IR. The MCP server passes PowerIO IR documents through and defines no electrical data shape of its own.

The 0.11.x line is for compatible fixes, performance work, and additive change; a break in the public Rust API that cannot be avoided goes into 0.12. The Rust API stays pre-1.0 as long as public signatures expose types from the pre-1.0 sprs and petgraph crates.

Developer guides

These pages are for contributors and for anyone whose code depends on PowerIO internals. They cover the change from 0.10, the PowerIO IR document and its field reference, the BMOPF mapping, the crate graph, the design decisions borrowed from LLVM and MLIR, the DC OPF bundle, the private corpus harness, benchmarks, and the checks a release runs.

Everything here describes the current implementation; earlier releases are in the changelog. The dated design record behind the 0.11 API lives outside the guide at docs/design/ and is not API authority.

From 0.10 to 0.11

PowerIO 0.11 breaks the 0.10 source API and the C ABI once, to remove duplicate ways of doing the same thing and to expose the same concepts in Rust, Python, Julia, and C. After that the 0.11.x line stays compatible, and any further unavoidable public break waits for 0.12.

One parse, one emit

Every grid exchange format now goes through parse, which opens the input itself. You can hand it a file or directory name, content already in memory, or a Source of named buffers, and all of them reach the same call.

let module = powerio::parse("case9.m")?;
let module = powerio::parse(case_directory)?;
let module = powerio::parse(bytes)?;

// Content in memory carries the name `<memory>`, which identifies no format,
// so a format read from a file extension is declared or named.
let module = powerio::parse_with_options(
    bytes,
    &powerio::ParseOptions::default().format("matpower")?,
)?;
let module = powerio::parse(powerio::Source::from_memory("case9.m", bytes)?)?;

Python accepts a path, a file object, or a bytes-like object. A str is taken as a path, so wrap text already in memory in io.StringIO.

module = powerio.parse("case9.m")
module = powerio.parse(io.StringIO(text), format="matpower", name="case9.m")
module = powerio.parse(binary_data, format="pwb", name="case.pwb")

Julia uses multiple dispatch on a path string, IO, or AbstractVector{UInt8}.

module_ = parse("case9.m")
module_ = parse(IOBuffer(text); format="matpower", name="case9.m")
module_ = parse(bytes; format="pwb", name="case.pwb")

In C you construct a PioSource with pio_source_open or pio_source_from_memory and then call pio_parse.

These 0.10 names are removed:

• parse_file
• parse_text
• parse_str
• parse_bytes

Read the module fields

PioModule<T> contains the typed value and its diagnostics, producer, sources, source mappings, history, and extensions. Rust, Python, and Julia expose these members using their usual language conventions: Rust has accessor methods such as value() and diagnostics(), and Python and Julia have properties such as .value and .diagnostics.

In Rust, dynamic parsing returns PioModule<PioValue>, so match on module.value() directly. In Python, use isinstance(module.value, BalancedNetwork); in Julia, dispatch on PioModule{BalancedNetwork} or another concrete parameter.

PioValueKind, .kind, try_into_typed, IntoTypedModule, and the binding wrappers that duplicated each language’s own type inspection are removed. The C ABI uses structural names such as powerio.BalancedNetwork and exact type predicates instead of an ordinal value kind enum.

Diagnostics belong to the module, so Python and Julia no longer have a callable diagnostics().

Emit formats; serialize PowerIO IR

emit is now the one way to produce a grid exchange format.

powerio::emit(&module, "matpower", "copy.m")?;

memory_result = powerio.emit(module, "matpower")
file_result = powerio.emit(module, "psse", "case.raw")

memory_result = emit(module_, "matpower")
file_result = emit(module_, "psse", "case.raw")

The result lists every artifact it wrote, the output layout, the fidelity, and the emission diagnostics, and the same call handles text, binary, single file, and directory formats.

PowerIO IR goes through serialize and deserialize instead. .pio.json is not a grid exchange format, so format discovery does not list it. Both calls use the PowerIO IR document shape, "schema": "pio-ir" with integer "version": 2, and the producer record names the PowerIO release separately. Documents from earlier generations have to be regenerated from their original power system data.

These 0.10 names are removed:

• write_to
• write_string
• write_file
• to_format
• module JSON read and write names
• BalancedNetwork::to_json, from_json, and to_json_with_diagnostics
• the model-json JSON classification family
• the pio-json format token

to_* is still there for a genuine semantic transformation in memory.

Use ordinary collection operations

TimeSeries<T> and ScenarioSet<T> hold real typed values, so you use them like any other collection. Rust has len, iter, and checked get; Python has iteration and indexing; Julia has length, iteration, and 1-based getindex; C has opaque length and element access.

Remove calls to StateInventory, StateSelector, SelectedState, list_states, select_state, and export_state and index the collection instead. What you get back is the contained typed value itself, or an owner rooted typed view of it; nothing is encoded and reparsed on the way out.

Apply typed updates

PowerIO 0.11 adds OperatingPointUpdate, NetworkUpdate, CalculationUpdate, apply_updates, and UpdateReport. An update identifies its component by stable ComponentId and gives an absolute value with an explicit unit; the whole batch is validated first and then applied atomically. In Julia the mutating functions end in !.

UpdateReport lists the component IDs and fields that changed and says whether energized connectivity changed. A bus demand update has to name a load or an explicit allocation rule, because PowerIO will not pick an arbitrary load to receive aggregate demand. LoadAllocation::ProportionalToCurrentActivePower keeps the current shares and refuses an all zero basis; LoadAllocation::Equal splits the replacement evenly, which is how you restore demand after setting every participating load to zero.

Use calculation names that state the result

The DC data types PioDcData, DcNetworkData, and dc_data, and the phrase “DC branch coefficients”, are gone, though the DC OPF bundle files written by powerio dcopf and emit_dcopf_bundle remain. Use the named calculations instead:

calc_incidence_matrix
calc_branch_susceptances
calc_bus_susceptance_matrix
calc_branch_flow_matrix
calc_branch_phase_shift_injection
calc_bus_phase_shift_injection
calc_branch_flow_dc
calc_bus_injection_dc

The public orientation and signs are:

A[e, from] = +1
A[e, to]   = -1

Bf = Diagonal(b) * A
B  = A' * Diagonal(b) * A

p_branch = -Bf * va + b .* shift
p_shift  = A' * (b .* shift)
p_bus    = -B * va + p_shift

BranchSusceptanceFormula picks between the documented series susceptance, tap adjusted reactance, and reactance only equations.

Calculation instances and solutions

PowerIO 0.11 registers these calculation pairs:

DcPfInstance       DcPfSolution
AcPfInstance       AcPfSolution
DcOpfInstance      DcOpfSolution
AcOpfInstance      AcOpfSolution
McAcPfInstance     McAcPfSolution
McAcOpfInstance    McAcOpfSolution
AcScucInstance     AcScucSolution

SocwrOpfSolution holds a PowerModels SOCWR relaxation, including its W-space values and objective lower bound. PowerIO does not call it an AcOpfSolution unless voltage recovery and AC residual checks support that claim.

The initial assignment of an instance is its initial_point field.

C ABI 7

PowerIO 0.11 replaces ABI 6 with ABI 7, which drops the ABI 4, 5, and 6 aliases and the Arrow export. Sources, destinations, modules, typed values, collections, diagnostics, artifacts, sparse matrices, and vectors are all opaque reference counted handles, every buffer comes with an explicit length, and a borrowed typed handle keeps its module owner alive.

PowerIO.jl moves to ABI 7 in the same release. Julia packages should depend on PowerIO.jl rather than call the C ABI directly.

Inputs accepted by 0.11

PowerIO still accepts documented aliases for names that external formats define, such as rawx for the canonical psse-rawx format token. An alias like that names the same third party format; it does not keep a prerelease PowerIO API or IR shape alive, and 0.11 has no beta source or document aliases at all.

PowerIO IR

A .pio.json file serializes one PioModule<PioValue>, which is one typed value together with its diagnostics, producer, sources, source mappings, history, and extensions. A current document begins like this:

{
  "schema": "pio-ir",
  "version": 2,
  "producer": { "name": "powerio", "version": "0.11.0" },
  "value": {
    "type": "powerio.BalancedNetwork",
    "data": {}
  }
}

Use serialize to produce it and deserialize to read it. PowerIO IR is not one of the grid exchange formats. MATPOWER, PSS/E, XIIDM, CGMES, OpenDSS, PMD JSON, BMOPF, and the other formats in the format registry exist to exchange power system data with other tools, and they enter through parse and leave through emit. PowerIO IR preserves PowerIO types and module records instead, and it is deliberately left out of grid exchange format discovery. Use it when both sides consume PowerIO values, including calculation instances, solutions, time series, and scenario sets.

The generated JSON Schema is checked in at docs/schema/pio-ir/2/schema.json and served from https://powerio.dev/schema/pio-ir/2/schema.json. That schema, the serializer, and the deserializer are all tested from the same Rust types. docs/schema/README.md lists the earlier pio-package and powerio.module documents as one history under pio-ir.

Module records

The document stores these common records when present:

Source bytes retained at runtime are not serialized. A source record names a source without exposing a local absolute path; a parser may keep the bytes in memory for byte exact same format emission while the process runs, but that buffer is separate from the stored module.

The deserializer checks the cross references before it returns a module: diagnostic source references and source mappings must name declared source IDs, byte ranges must fit the declared source length, and history references must name records in the same document. The MATPOWER and PSS/E readers attach the byte range of the record a finding is about to every diagnostic they raise at a known record, so a document serialized from one of their modules has those spans; the other readers attach none yet.

Typed values

value.type is the canonical structural type name used by Rust, C, Python, Julia, and the document schema. Examples include:

powerio.BalancedNetwork
powerio.MulticonductorNetwork
powerio.OperatingPoint<powerio.BalancedNetwork>
powerio.TimeSeries<powerio.MulticonductorNetwork>
powerio.ScenarioSet<powerio.TimeSeries<powerio.BalancedNetwork>>
powerio.DcOpfInstance
powerio.SocwrOpfSolution

value.data has the exact shape that type demands, and the deserializer rejects a document where the two disagree, as it rejects a wrong schema name or version, an unknown PowerIO type, duplicate IDs, invalid references, nonfinite values in untyped positions, or a collection whose entries disagree with its element type. PowerIO IR reference defines every structural type field by field: type, unit, sign convention, invariant, and the value a reader takes when a field is absent.

Typed floating point fields spell nonfinite values as "Infinity", "-Infinity", and "NaN". JSON null is not a floating point value.

Collections and operating points

TimeSeries<T> stores ordered time points and values of T, and ScenarioSet<T> stores named alternatives of T with optional probabilities and no implied time order. Nested collections keep their structural type; the document does not invent a flattened name for each composition.

An OperatingPoint<N> stores a shared base network and typed overrides keyed by stable component ID. The serializer preserves that relationship rather than expanding each entry into another complete static network.

Determinism

serialize is a function of the module alone. Serializing one module twice produces identical text, and serializing the module that text deserializes to produces the same text again. Members are written in a fixed order, record fields in declaration order and map keys (extras, quantities, extensions, details) sorted. Diagnostic IDs are minted d0, d1, … in record order for records that have none, so the minted IDs depend only on record order. Every float is written in the shortest decimal form that reads back to the same value, and nonfinite values use the three string spellings above. Equal modules therefore produce equal documents, which is what lets you use a document as a cache key, a golden file, or the input of a content digest.

Resource limits

Before it retains large input data, deserialization applies explicit limits on source count and byte lengths, diagnostics, source map and history records, extension data, collection lengths, ID lengths, and nested value depth. Hitting a limit produces a structured PowerIO diagnostic rather than an allocation failure or a truncated result.

Generations

The integer version is the generation of the serialized representation. It is a property of the document alone, separate from the Rust memory layout, the PowerIO release, any grid exchange format, and the C ABI, and it changes only when the representation changes. producer.version records the release that wrote the document; the reader reports it and ignores it when deciding compatibility.

When a generation bumps inside one minor release line, the release ships with a reader for the generation it replaces, so every 0.11.x release reads every generation any 0.11.x release wrote. powerio::IR_VERSION is the generation a build writes and powerio::IR_MIN_VERSION the oldest it reads; in 0.11 both are 2. A refused document is reported with the schema name, generation, and producer it claims and the remedy: a later generation needs a newer PowerIO, and an earlier schema name or generation has to be regenerated from its source data. docs/schema/README.md is the ledger of every generation and the archive of every published schema.

PowerIO IR reference

This page lists every structural value type in the PowerIO IR, field by field: each field’s type, unit, and sign convention, the invariant the deserializer or the constructors enforce, and what a reader uses when the field is absent. The generated schema at docs/schema/pio-ir/2/schema.json is the machine form of the same definitions. To keep the two from drifting apart, powerio/tests/ir_reference.rs reads this page and checks in both directions that each table lists the same fields the schema defines for its definition.

Reading the tables

Each field table sits under a line that begins with the words “Schema definition” and gives, in backticks, the $defs entries of the schema the table documents; that line is how the test pairs a table with its definitions. The columns are:

• field: the JSON member name in value.data (or in the nested record).
• type: float is a JSON number or one of the strings "Infinity", "-Infinity", and "NaN"; null is refused at a float position. float or null is a float the source may leave unstated. id is a bus identifier: a nonnegative integer, the source’s own bus number. matrix is an array of equal length float arrays. token is one of the listed strings.
• unit: the physical unit. p.u. is per unit on the network’s base_mva and the bus base_kv unless the row says otherwise.
• sign: the direction a positive value means; blank when the quantity is unsigned or the sign carries no convention.
• invariant: what the deserializer refuses or the constructors hold.
• if absent: required when the serializer always writes the field and the deserializer refuses a document without it; otherwise the value a reader takes when the member is missing.

uid on an element row is the stable component identity that operating points, solutions, and updates refer to. When the source gives none, parse and serialize assign {table}:{row}, so a document PowerIO writes has one wherever a table below says “assigned at serialization”. extras on an element is the map of source fields the typed model has no slot for, keyed by the source’s own field names; the member is required in the document but may be empty.

Structural type names

value.type is one of these names, and value.data has the shape of the schema definition beside it.

powerio.BalancedNetwork

The positive sequence transmission model, in the units MATPOWER uses: powers in MW and MVAr, voltage magnitudes in per unit, angles in degrees, and impedances in per unit on base_mva. Bus identifiers are the source’s own.

Schema definition: BalancedNetwork.

Bus

Schema definition: Bus.

Load

Schema definition: Load.

LoadVoltageModel is tagged by kind. constant_power has no further member. zip has p_constant_power, p_constant_current, p_constant_impedance (MW, summing to p) and q_constant_power, q_constant_current, q_constant_impedance (MVAr, summing to q), plus an optional v_nom (kV), an optional source load_type code, and an optional scaling factor. exponential has gamma_p, gamma_q, and v_nom, with P = p (V / v_nom)^gamma_p and Q = q (V / v_nom)^gamma_q.

Shunt

Schema definition: Shunt.

Schema definition: SwitchedShuntControl.

Schema definition: ShuntBlock.

Branch

Schema definition: Branch.

Schema definition: BranchCharging.

Schema definition: BranchRatingSet.

Schema definition: BranchCurrentRatings.

Schema definition: BranchSolution.

Schema definition: TransformerControl.

Generator

Schema definition: Generator.

Schema definition: GenCost.

Schema definition: ActivePowerControl.

Storage

The PowerModels storage model.

Schema definition: Storage.

Hvdc

A two terminal HVDC line in the MATPOWER dcline convention, whatever the source format.

Schema definition: Hvdc.

Schema definition: HvdcConverter.

Switch

A transmission switch. A closed switch stays a switch in the data; the matrix calculations do not lower it to a zero impedance branch.

Schema definition: Switch.

Transformer3W

Three windings joined at a star point; the indexed view star-lowers the record for matrix calculations.

Schema definition: Transformer3W.

Schema definition: Winding.

Schema definition: Impedance.

Area

Schema definition: Area.

StaticVarCompensator

Schema definition: StaticVarCompensator.

SolverParams

Each member is set only when the source has it.

Schema definition: SolverParams.

CaseMetadata

Schema definition: CaseMetadata.

Coordinates

Schema definition: GeoMeta.

Schema definition: Location.

Component references

Schema definition: ComponentId.

Schema definition: TerminalReference.

DetailedConnectivity

The hierarchy and bus breaker or node breaker connectivity a source gives beyond the balanced calculation view (XIIDM, CGMES, PSS/E RAW 35 and RAWX). Every collection is empty when absent. The schema defines the record types under the names below. Their field names end in their units (_kv, _mw, _mvar, _a, _ohm, _h, _f, _km, _degrees, _percent, _seconds), and terminal powers use the load sign convention (positive is consumption) where the record says so.

Schema definition: DetailedConnectivity.

powerio.MulticonductorNetwork

The conductor level distribution model, in SI units (watts, vars, volts, amperes, ohms, siemens, meters) with angles in radians. Bus identifiers and terminal names are the source’s own strings; for OpenDSS the terminal names are its node numbers. An element’s terminal_map lists, in conductor order, the terminals of the named bus it connects to.

Schema definition: MulticonductorNetwork.

DistBus

Schema definition: DistBus.

DistLineCode

Schema definition: DistLineCode.

DistLine

Schema definition: DistLine.

DistSwitch

Schema definition: DistSwitch.

DistTransformer

Schema definition: DistTransformer.

Schema definition: DistWinding.

DistLoad

Schema definition: DistLoad.

DistLoadVoltageModel is tagged by model. constant_power, constant_current, and constant_impedance each have v_nom (volts per active phase). zip has v_nom and the per phase coefficient arrays alpha_z, alpha_i, alpha_p (active power) and beta_z, beta_i, beta_p (reactive power), each triple summing to one. exponential has v_nom, gamma_p, and gamma_q.

DistCapacitor

Schema definition: DistCapacitor.

DistShunt

Schema definition: DistShunt.

DistGenerator

Schema definition: DistGenerator.

DistIbr

Schema definition: DistIbr.

DistControlProfile

Schema definition: DistControlProfile.

Schema definition: VoltVarControl.

Schema definition: VoltWattControl.

Schema definition: PowerFactorControl.

VoltageSource

Schema definition: VoltageSource.

UntypedObject

An object the reader recognized but does not type, kept so a conversion can report it precisely.

Schema definition: UntypedObject.

Distribution coordinates

Schema definition: DistGeoMeta.

Schema definition: DistLocation.

powerio.GeoLayer

A standalone geographic document: element points and routes in one coordinate space, keyed by element identity rather than embedded in a case. The canonical .geo.json, GeoJSON, aliased CSV or JSON records, headerless buscoords CSV, and a PowerWorld .pwd display all parse to one, and apply_geo_layer places it onto a network.

Schema definition: GeoLayer.

CoordinateSpace is tagged by space. geographic has an optional crs; x is longitude and y latitude in decimal degrees, and a null crs means EPSG:4326. projected has an optional crs for planar coordinates. diagram has an optional canvas for drawing coordinates with no earth referent. unknown has no further member and means the source declared no space.

Schema definition: Canvas.

GeoFeature

Schema definition: GeoFeature.

GeoGeometry is one tagged object: point is a single [x, y] position for a placed element, and line_string is an array of [x, y] positions for a route. Positions are in the layer’s coordinate space, a route has at least one, and every coordinate is finite.

ElementKey

Matching tries uid, then id, then case insensitive name; a branch additionally falls back to the unordered (from, to) bus pair.

Schema definition: ElementKey.

powerio.OperatingPoint<N>

An alternate electrical assignment, possibly partial, over the fixed component identities of one base network N: demand, setpoints, dispatch, voltages, injections, service status, switch positions, transformer taps, and phase shifts. Any quantity the point leaves out resolves to the network’s own value.

Schema definitions: StoredOperatingPoint, StoredOperatingPoint2.

Schema definition: StoredQuantity.

An operating point stored inside a collection or an instance omits the network, because the enclosing record gives it once.

Schema definition: StoredOperatingPointAssignment.

Balanced quantities. A bus quantity is keyed by the bus id’s decimal spelling; an element quantity by the element’s uid.