Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

SourceValue
MATPOWER, PSS/E, XIIDM, CGMES, UCTE-DEF, and the other balanced formatsBalancedNetwork
OpenDSS, PowerModelsDistribution JSON, BMOPF JSON, distribution CIMMulticonductorNetwork
a PyPSA directory whose inputs vary by snapshotTimeSeries<BalancedNetwork>
a GridFM Parquet datasetScenarioSet<BalancedNetwork>
a DOE GO Challenge 3 problem fileAcScucInstance
that problem file beside its solution fileAcScucSolution
a DeepMind OPFData fileAcOpfSolution
a geographic layer document or a PowerWorld .pwd displayGeoLayer

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.89 or newer. Add the gridfm feature when your application reads or writes GridFM Parquet directories: cargo add powerio -F gridfm.

Native SINCAL projects are the sincal feature, on by default. It compiles SQLite, which a wasm32-unknown-unknown build needs a C compiler with a WebAssembly backend for. A browser build that never reads SINCAL leaves it out:

powerio = { version = "0.11", default-features = false, features = ["matrix"] }

Such a build lists no SINCAL format and refuses a SINCAL source or target with REQUEST.SINCAL.FEATURE_DISABLED.

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 gridfm
# target/release/libpowerio_capi.so (Linux), libpowerio_capi.dylib (macOS),
# or powerio_capi.dll (Windows); 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

Convert files in the browser

Open PowerIO Convert to convert a file, a folder, or a batch without installing PowerIO. Files stay on the computer. The same Rust parsers and writers run locally through WebAssembly.

  1. Choose files, drop a folder, or select ZIP projects. PowerIO identifies each input format, including mixed transmission and distribution cases.
  2. Choose one or more output formats. Transmission defaults to MATPOWER; distribution defaults to PMD engineering JSON. Each case can override those choices.
  3. Convert, review the diagnostics, and download individual outputs or a ZIP containing all completed outputs and a conversion report.

The examples include a MATPOWER transmission case and a small OpenDSS feeder. The mixed example shows both in one batch.

Projects and recovery

Choose the complete folder or ZIP for an OpenDSS, PyPSA CSV, or CGMES project. Relative references stay within the supplied files. A project with several possible OpenDSS entry files asks which one to open. An incomplete project can accept missing files and retry. Formats can also be selected explicitly when detection needs help.

Each project permits up to 4096 files and 64 MiB of expanded input. ZIP archives have additional path and expansion checks. Batches have no fixed case-count limit; browser memory and local storage determine capacity. The command line is useful for larger projects.

A failed case does not prevent other cases from converting. Cancel stops the active worker and keeps completed results. Changing an input format, entry file, or dependency removes its old outputs before conversion. If a dropped file or folder cannot be acquired, its affected project stays blocked while independent cases continue. Remove that failed case and select its complete files or folder again; retry and format overrides cannot restore files that the browser did not acquire. Cancel also stops further acquisition.

Understand the result

Same-format emission preserves the source bytes. Cross-format emission reports data that the target cannot represent. A warning means the output needs review, even when a file was produced. The portal displays PowerIO’s diagnostic codes, messages, locations when available, and suggested actions. See Formats and fidelity for the supported profiles.

BMOPF output follows the Task Force’s proposed schema, the one BMOPF PowerIO writes. A BMOPF file from an older draft reads as BMOPF, with one warning. The BMOPF task force maintains the collaborative distribution-system optimization work. GO Challenge 3 writing requires a complete SCUC solution. The converter does not solve a network or synthesize missing solution data.

PowerIO IR, geographic-only data, GridFM/Parquet, matrices, and solver operations belong in the package or terminal workflow. The portal provides matching CLI commands for the selected input and outputs.

Privacy, sharing, and help

The converter has no file-upload endpoint. Files, filenames, paths, and raw diagnostics never enter analytics. Completed outputs may use temporary browser storage. Clear all removes the session’s files; abandoned temporary files are removed on the next visit. Closing or reloading the tab discards the queue, so download results before leaving.

Optional Umami statistics help identify formats and parser problems that need work. They are off by default; enable them in the Privacy section. Only activity after opt-in is shared. Statistics include standard format names, broad outcomes, reviewed parser codes, software version, and coarse batch-size and elapsed-time ranges. Unknown codes become other. Electrical diagnostics and grid properties stay local. Duplicate problems and event limits reduce repeated reporting.

The analytics script runs in an isolated iframe that cannot read files or the converter page. Umami receives IP and browser connection metadata with its requests and derives browser/device, approximate location, and visit statistics from that metadata. See Umami metric definitions. Switch statistics off at any time; Do Not Track and Global Privacy Control also disable them. Conversion works with analytics blocked. The committed analytics policy template lists every permitted event and value. The build supplies the one permitted PowerIO version in the generated policy shared by the application and frame.

Share settings copies a link containing output preferences only. It never includes files or filenames. Report a conversion problem prepares an editable GitHub issue report with engine/build information, browser major version, format names, and diagnostic codes. Review the report and add a small, shareable example if needed. The locally downloaded conversion report is more detailed and can contain private filenames and messages; review it before sharing.

Shared collection selections

Folder and expanded ZIP inventories use the same collection discovery as the Rust facade. OpenDSS masters may overlap and mixed standalone cases stay independently selectable. Discovery does not parse electrical values: use Inspect case or request conversion. The worker keeps one bounded inventory for repeated selections and releases parsed results between cases. Cancelling terminates the worker and retains completed outputs.

Existing XML/profile-ZIP grouping remains in place while explicit document-group controls are introduced. Unknown companions remain visible in the selected inventory. Candidate discovery does not certify complete dependencies or solver readiness.

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, AcOtsInstance,
McAcPfInstance, McAcOpfInstance, LinDist3FlowPfInstance,
LinDist3FlowOpfInstance, AcScucInstance
DcPfSolution, AcPfSolution, DcOpfSolution, AcOpfSolution, AcOtsSolution,
SocwrOpfSolution, McAcPfSolution, McAcOpfSolution, LinDist3FlowPfSolution,
LinDist3FlowOpfSolution, AcScucSolution
GeoLayer
ContingencySet, SubsystemSet, MonitoredSet
TypeMeaning
BalancedNetworkA self contained balanced case: equipment identities, terminals, physical parameters, ratings, limits, costs, and the source’s operating assignment.
MulticonductorNetworkThe conductor resolved distribution model.
OperatingPoint<N>A possibly partial alternate electrical assignment over fixed equipment. It makes no claim of completeness or power flow feasibility.
TimeSeries<T>Values of one type ordered in time.
ScenarioSet<T>Named alternatives of one type, optionally with probabilities and with no time order.
*InstanceThe complete input of one named calculation: fixed inputs, unknowns, bounds, objectives, horizon, contingencies, and formulation choices.
*SolutionThe result of one calculation: computed quantities, termination, residuals, multipliers, and the objective or bound.
GeoLayerCoordinates and routes for the elements of a case, as a document of its own.
ContingencySet, SubsystemSet, MonitoredSetThe PSS/E contingency, subsystem, and monitored element files (.con, .sub, .mon) as documents of their own; the contingency and monitored element sets resolve against a network on request.

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, BMOPF, and distribution CIM 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’s version names the release whose schema it follows, and a release reads the documents of its own release series. Later releases in a series add structural types, which a reader that does not implement them refuses. PowerIO IR is absent from grid exchange format discovery, so parse does not accept it. PowerIO IR defines the document and its version 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.

Input collections

Collection acquires a ZIP or folder once and exposes independent selections. Inspection suggests inputs without parsing electrical values. A file can be both an independent input and a companion of several other inputs. Conventional names such as Master.dss do not hide alternative masters.

use powerio::{Collection, CollectionLimits, CollectionSelection, ParseOptions};
let collection = Collection::from_directory("study", CollectionLimits::default())?;
for candidate in collection.inspect()? {
    println!("{:?}", candidate);
}
let selection = CollectionSelection::file("masters/weekday.dss").format("dss");
let result = collection.parse(&selection, &ParseOptions::default())?;
println!("observed dependencies: {:?}", result.dependencies);
Ok::<(), powerio::Error>(())

A selection’s primary is relative to its root. The default root is the collection root, so a master under masters/ can refer to ../shared/. A narrower root confines references. Each selection starts new parser state and new dependency observations. Standalone formats receive only their selected file. File names are portable, case sensitive, and never rewritten.

ZIP acquisition verifies all member sizes and CRCs under explicit input, expansion, count, and ratio limits. Folder acquisition uses the core confined reader, then retains a memory snapshot. Neither selection can subsequently read unsupplied host files. Nested transport ZIPs remain opaque. An explicit cgmes format sends a native profile ZIP intact to its existing adapter.

JSON inspection has per-file and cumulative probe budgets. A probe limit or unknown format leaves the input available for explicit selection. selectable means the suggested selection can be submitted; it does not certify the input, its dependencies, or solver suitability. CollectionResult::incomplete reports known missing-include warnings; false is not proof of study completeness. Electrical diagnostics remain on the module.

PowerIO IR candidates use deserialize. Co-location never synthesizes a time series or scenario set. A parser’s existing internal time/scenario value stays intact. Call parse independently for each selection and retain both successes and errors when processing several inputs.

original_zip() returns original container bytes. Source-format emission has the existing adapter’s replay scope: OpenDSS retains companions, including unused ones within the selected root. It is not a minimal project exporter. IR omits retained source bytes as before.

Dataset discovery recognizes network.csv (PyPSA) and bus_data.parquet (GridFM). Select the candidate’s root with no primary and its explicit format. Nested datasets remain separate, including during retained-source replay. GridFM candidates remain visible with unsupported-build when the feature is disabled. Missing required companion tables produce an incomplete candidate.

Use CollectionSelection::group(format, members) for cgmes, cim-dist, or goc3-json. Members are relative to the selected root and only those members reach the adapter. GO problem/solution roles are validated by the existing reader; discovery never pairs them automatically. CIM members must be top-level XML files under their selected root. CGMES also accepts explicitly selected profile ZIPs, with its existing validation and echo behavior.

Select a .sinx primary with sincal-balanced or sincal-multiconductor and pass the native options through ParseOptions. The container reaches SINCAL intact; outer collection members cannot satisfy its internal references.

Command line

powerio collection inspect study.zip
powerio collection parse study.zip --entry masters/day.dss --entry masters/night.dss --from dss -o modules
powerio collection parse datasets --root day --from pypsa-csv
powerio collection parse study.zip --root go --member problem.json --member solution.json --from goc3-json

Inspection and parse reports are JSON. Batch results use stable positional IDs (case-0001, etc.) in the requested entry order. Every entry is attempted; errors and incomplete dependencies produce a nonzero exit after the full report. --output serializes successful modules to those IDs with .pio.json suffixes. Native SINCAL selection flags are accepted with the explicit native profile.

Python

from powerio import Collection
with Collection.open("study.zip") as collection:
    candidates = collection.inspect()["candidates"]
    result = collection.parse(candidates[0]["selection"])
module = result.module  # still valid after closing the collection

from_zip(bytes) and from_files({path: bytes}) use the same inventory and selection behavior. max_bytes and max_files bound admission before copying input payloads. Native SINCAL options can be passed to parse.

C and Julia

C callers own a PioCollection from pio_collection_open, pio_collection_from_zip, or pio_collection_from_files, with explicit byte and file limits. pio_collection_inspect returns metadata JSON. Pass a selection JSON object to pio_collection_parse to obtain the usual typed PioModule; its optional report contains observed dependencies and the incomplete flag. Release returned strings and handles with their matching functions. Closing the collection does not invalidate parsed modules. Existing typed parser options remain available, but collection parsing refuses host acquisition roots.

The companion Julia API uses InputCollection(path), InputCollection(bytes) for ZIP bytes, or InputCollection(Dict(path => bytes)). inspect_collection returns metadata; parse(collection, selection) returns CollectionResult with a typed PioModule{T}. close(collection) releases its handle and copy retains an independent handle. These additions change no existing C ABI layout and do not serialize electrical values to provide typed access.

Explicit nested ZIPs and session budgets

collection.open_nested("child.zip") opens exactly one child. Discovery never recurses automatically. The child has its own file namespace, so it cannot find a missing dependency in its parent or a sibling. The default is two ZIP decoding layers, including a native .sinx or CGMES ZIP decoded by its adapter. A memory folder starts at zero layers; opening the outer transport ZIP consumes one. Native interpretation stays with the existing adapter, with a bounded payload verification pass before delegation.

Cloned handles and all descendants share monotonic entry and expansion counters for the archive content admitted into the session: the acquired tree plus every nested child opened from it. The byte/file caps cover that content for the whole session rather than resetting in each child, so reopening a child counts again; a child that fails verification retains nothing and releases its reservation. work_bytes (default 256 MiB) bounds one operation: the scoped parser inputs, the decompression a native container’s verification performs, and a nested open’s container and declared expansion, charged conservatively. Every operation starts from zero, so parsing the same selection repeatedly, as a batch run or a converter session does, never fails because of earlier operations. It is not a measure of model/Arrow memory or a replacement for parser limits. Set CollectionLimits before acquisition to tighten either bound.

Cancellation can be supplied to from_zip_cancellable and obtained through cancellation(). It is checked during discovery and between decompressor reads. Already returned modules remain valid. Synchronous electrical parsing retains its existing bounds; browser callers can terminate the worker to interrupt it. The initial Python/C/Julia APIs retain their bounded defaults; nested inspection is exposed first through the Rust collection API.

Manifests and source export

A version 1 manifest records explicit selections without becoming an electrical PioValue. For example:

{
  "schema": "powerio-collection",
  "version": 1,
  "cases": [{
    "id": "weekday",
    "selection": {"primary": "masters/day.dss", "format": "dss"},
    "attachments": ["notes.txt"]
  }]
}

read_manifest accepts at most 1 MiB and the host inspection budget. It rejects unknown fields, duplicate IDs, escaping paths, unsupported identity/version, and excessive case/member lists. It checks ordinary selected sources and attachment existence without electrical parsing. A case can name a containers array of explicit child ZIP members; those children are acquired only by parse_manifest_case(manifest, id), under the same session limits. Optional reader_options records SINCAL variant, snapshot, acquired-table name, and the multiconductor inactive-control assumption. It cannot choose a host acquisition root or raise resource limits. Attachment associations remain metadata.

source_bundle(selection, scope) requires an explicit export policy:

  • SelectedMembers exports only the primary or named document group. It makes no claim that a DSS primary alone is a complete editable project.
  • Project exports every file inside the selection’s permitted root, including unused companions and other cases in that root. Choose a narrower root when the project has one; parent-relative references must still fit that scope.
  • ExplicitMembers(names) exports exactly the listed root-relative files. Observed dependency names can inform this list, but do not certify completeness.

A bundle shares exact leaf bytes and owns them independently of the collection. deterministic_zip(ArchiveLimits) produces a new archive with sorted names, fixed metadata and stored payloads, bounded including ZIP overhead. It does not rewrite references or claim original-container fidelity. original_zip() is still the distinct exact-byte download of the acquired archive, if retained. The writer also accepts explicit named output files for converted-case packaging.

origin() and selection_origin() separate the original collection name, container-member chain, and selected root/primary/group into structured fields. They never parse punctuation in a display name. These metadata are held outside network values; PowerIO IR still omits retained source payloads. Reproducible selection metadata alone is not a source-preserving IR document.

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. Thermal ratings use ordinary floating-point numbers: zero is a zero bound and positive infinity means no bound. Neither changes branch status. Readers and writers translate formats such as MATPOWER, whose file value zero means no bound.

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.

Merging buses

A closed switch or a zero impedance branch joins two buses into one electrical node, which no finite admittance describes. merge_buses resolves them explicitly: each set of joined buses becomes one bus, every element moves onto it, and the joining elements are removed. The rule states what joins buses, and no threshold applies unless the rule names it.

RuleMerges
closed switchesthe two buses of every closed switch
exactbranches with r = 0 and x = 0 (a transformer only at nominal ratio with no shift)
PSS/E thresholdnon-transformer branches with r = 0 and abs(x) at most the threshold, by default the THRSHZ the case states
impedance magnitudenon-transformer branches with abs(r + jx) at most the threshold

Every rule considers in-service branches only. The surviving bus of a set is its reference bus, else a bus with an in-service generator, else a bus a generator regulates, with the smallest id breaking each tie. In Rust, BusMergeRule::with_survivor keeps the smallest id or each merged element’s from bus instead, the survivors of merge_zero_impedance_buses and reduce_zero_impedance. The survivor takes the strongest bus kind of its set. Loads, shunts, generators and their regulated buses, storage, branch, switch, and HVDC ends, three winding transformer windings, control buses, and area swing buses all follow the survivor. The result lists every removed element with its source row, identity, and ratings, and maps each source branch and switch row to its merged row. A removed in-service branch becomes a fixed shunt with its full equivalent admittance Yff + Yft + Ytf + Ytt at the survivor. This includes the series contribution of a bypassed transformer with an off-nominal tap or phase shift, and terminal charging with the from side divided by the tap squared. charging="drop" discards only terminal charging; the series equivalent remains. charging_shunts lists all these generated shunt rows. A branch the merge shorts, such as a line in parallel with a jumper, is removed and reported. Bypassing an ideal transformer with a nonunity tap or phase shift returns an error: no finite shunt can preserve that voltage constraint. A jumper whose merge would join two windings of one three winding transformer stays, also reported. Merging the result again changes nothing.

The removed elements’ flows are not variables of the merged network. calc_removed_flows recovers their active power from a solution of the merged network. Kirchhoff’s current law fixes the flows where the removed elements form a tree, the elements’ reactances split a loop, and a loop of zero reactance elements, such as a ring of closed switches, gets the minimum norm split and a diagnostic.

merge = network.merge_buses(zero_impedance="psse")
merged = merge.network                 # solve this network
flows = merge.calc_removed_flows(p_from, p_to)
powerio summary case.raw --merge-buses psse
powerio convert case.raw --merge-buses psse=0.0001 --to matpower -o merged.m

Islands and reference buses

A large case can hold several AC islands: systems joined only by HVDC, pockets behind an open breaker, and stranded equipment. calc_islands partitions the energized buses into islands joined by in-service branches, closed switches, and in-service three winding transformers. Buses typed isolated belong to no island, and HVDC lines do not join islands. Each island lists its buses, reference buses, in-service generators, and the in-service HVDC lines that tie it to another island, largest island first.

subset_buses(&buses) returns a BusSubset: the cut network and a map for all eleven tables (buses, branches, switches, three winding transformers, generators, loads, shunts, SVCs, storage, HVDC lines, and areas). Each map has one entry per source row: Some(row) points into the result table and None means that row was excluded. IDs are preserved. For example, cut.branch_rows[source_row] locates a statement’s branch in cut.network without reproducing the cut’s filtering rules.

A dead winding can bring its bus along as an isolated stub: its bus_rows entry is present, while injections excluded from that stub map to None. Detailed connectivity follows the cut, including calculated buses, topology connections, equipment metadata and remote regulation references. Unassigned source topology remains when no calculated bus identifies it as excluded. Empty voltage levels are pruned and nodes stranded by a cut retain explicit calculated-bus records so fresh XIIDM emission preserves the selected buses. The older selector-based subset shares this filtering but still returns a network directly.

To keep row indices fixed instead, keep_island(&buses) works in place: it de-energizes every other bus not already typed isolated and returns those buses, so the equipment outside the island stays in its table, out of service. de_energize_buses(&buses) is the step it builds on, the same one assign_island_references applies to an island with no source; it also takes the generators at those buses out of service.

A power flow needs one reference bus per island, and an island with no source cannot be solved. assign_island_references with the per island policy gives each island exactly one, on a bus that hosts an in-service generator:

  • a stated reference that hosts no in-service generator cannot balance its island and is demoted to PQ first; the rules below count only the references that remain;
  • an island with one reference keeps it;
  • an island with none takes the bus of its largest pmax in-service generator, the smallest bus id breaking ties;
  • an island with several keeps the one hosting the most generation and demotes the others to PV;
  • an island with no in-service generator is de-energized: its buses are typed isolated and the equipment on or touching them is taken out of service. Three winding transformers lose only windings on those buses; the whole transformer goes out when fewer than two live windings remain. Supply counts in-service generators only, so an island that only an HVDC line feeds is de-energized too, and the line with it. It gets its own code, CANONICALIZE.ISLAND.HVDC_FED_DE_ENERGIZED, which names the lines and the power they schedule into the island; model that infeed as a generator at the converter bus to keep the island.

Every change is reported under CANONICALIZE.ISLAND. Normalization applies the same rule when asked, picks the same reference buses, and leaves the unsupplied islands out of the normalized network; by default it keeps the case’s references and designates one only when none survives. powerio summary lists the islands under topology.islands.

normalized = network.to_normalized(island_references="per_island")

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

PSS/E impedance correction before topology reduction

BalancedNetwork::apply_impedance_correction() applies retained PSS/E transformer correction tables at the present tap or phase shift. Call it before merge_buses or closed-switch normalization: a bypassed transformer becomes a shunt, whose admittance must include the correction. Reapply after editing tap or shift values while the transformer still exists; the nominal cache prevents repeated scaling.

The original table range selects ratio or angle. Ratio tables use bus-base per-unit winding ratios regardless of the RAW CW setting. A branch table is mapped to its effective t1/t2 tap coordinates. Three-winding ZCOD=0 scales star impedances; ZCOD=1 scales Z12/Z23/Z31 at the one nonfixed control winding, even when automatic regulation is disabled. Ambiguous RAW ZCOD=1 input is refused; an edited in-memory transformer with no unique controlling winding is skipped by correction application.

Fresh RAW35 output states nominal impedances beside the tables and preserves their interpolation and angle/ratio classification. When winding 2 cannot be set to one without changing a ratio table’s meaning, the writer chooses an equivalent nonunit ratio. RAW33/34 cannot state ZCOD=1; output freezes its present corrected pairwise impedances and reports the lost dependence on tap position. RAWX reads and writes the same tables as its impcor table, one itable, tap, refact, imfact row per point, with the RAW 35 rules.

Distribution networks

A multiconductor network is the conductor level distribution model, and OpenDSS, GridLAB-D, PowerModelsDistribution ENGINEERING and MATHEMATICAL JSON, BMOPF JSON, the multiconductor MG-RAVENS JSON profile, three-phase pandapower JSON, and distribution CIM all parse to it. When you need a calculation, construct an McAcPfInstance, McAcOpfInstance, LinDist3FlowPfInstance, or LinDist3FlowOpfInstance from it explicitly (see Calculation instances and solutions).

The explicit SINCAL multiconductor profile also produces this existing type, including when its selected powers happen to be symmetric. Required unsupported SINCAL components reject the entire parse rather than returning a partial network. Its balanced profile belongs to the separate transmission backend; neither path silently falls back to the other.

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.

Rust VoltageSource::with_reference_terminal specifies phase voltages relative to a declared terminal on the source bus. That terminal can float: it is not implicitly connected to earth or an external neutral. The multiconductor matrix builder retains the voltage differences and the equal opposite reference currents. IR 2 uses a distinct tagged source record, so older readers reject this new physics; ordinary earth-referenced records are unchanged. McAcPfInstance::source_boundary borrows both voltage endpoints and their phasor differences. The additive C PioVoltageSourceBoundaryView serves network and PF instance callers without changing the existing C ABI layouts. Legacy C source views reject references they cannot describe. The OpenDSS writer preserves referenced constraints through exact equivalent circuits. GridLAB-D and the JSON writers accept an already perfectly grounded reference; floating references still need a qualified mapping for those targets. Balanced/LinDist3Flow projections and neutral Kron reduction retain their explicit reference-source restrictions.

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.

OpenDSS imports represent source impedances as coupled branches with ideal voltage constraints, and each ordinary line carries its effective matrices at the snapshot frequency. LineCode assignment and later edits follow script order. Lines that keep an assigned LineCode unchanged share one per meter linecode named after it; a LineCode edited between assignments, or a line that changes what it fetched, gets its own. Native switch=yes lines retain their finite impedance. Unknown length units are reported; electrical equivalents do not invent a physical distance. Canonical DSS output uses the typed frequency, snapshot mode and disabled controls. It preserves unequal phase voltages, zero EMFs and floating source returns using exact equivalent circuits. Reimport can introduce auxiliary components, so canonical output is electrically equivalent rather than a text fixed point. Unchanged source replay remains byte exact.

Names from other formats can be free text (a CIM IdentifiedObject.name such as Cable type A), but OpenDSS splits a token on whitespace, ,, =, quotes, and brackets, reads ! and // as comment openers, and reads a . in a bus reference as the node separator. Canonical DSS output replaces each such character with _ in the element, line code, bus, and circuit name and in every typed reference to it, adds a numeric suffix when the result is already taken in the same OpenDSS class, and reports each replacement (EMIT.DSS.VALUE_SUBSTITUTED). The written deck reads back with every element connected; the model keeps the original names.

Direct Open/Close commands and explicit SwtControl.State on lines preserve their fixed terminal states through equivalent circuits. Other device classes remain unresolved. Active Action/Normal control execution is excluded and reported. Unsupported geometry blocks numerical use or canonical conversion. These restrictions do not establish complete static OpenDSS support.

OpenDSS load models 1, 5 and 8 carry a typed BoundedZip law, including low-voltage current interpolation, upper-voltage impedance continuation and ZIP dropout. Model 2 remains constant impedance. Models 3 and 4 carry a typed BoundedExponential law: their middle-band P and Q exponents are respectively (0, 2) and the native CVR exponents (default (1, 2)). Outside the band, both powers follow the native fallback independently of those exponents. The Rust power_scale method evaluates these per-branch multipliers. IR retains the distinct tagged models; readers without a configuration reject it. Canonical DSS writes the typed exponents and voltage limits ahead of stale extras or writer defaults. Unequal per-branch parameters emit separate single-phase loads.

PowerModelsDistribution engineering JSON imports every component section the typed model has a slot for. Its time_series section has none: the series stay in the untyped table with a diagnostic, and a fresh PMD write restores them together with each component’s time_series references. A multinetwork document, the output of PMD’s make_multinetwork with one network per time step under nw, parses to PioModule{TimeSeries{MulticonductorNetwork}}, one network per step in mn_lookup time order. Each time point is labeled by its nw key and carries the step’s time_elapsed as its duration. Reading such a document as a single network is refused with a message saying so.

BMOPF and PMD project voltage-bounded loads to their nominal laws with a diagnostic; PMD also diagnoses its lack of exponential load fields. The multiconductor IVR OPF and LinDist3Flow preparations refuse these loads by default; each has an explicit opt-in that projects to the nominal law with a diagnostic (BoundedLoadLawPolicy::ProjectToNominal, and the approximate or permissive LinDist3Flow policy), described in the multiconductor IVR guide. Legacy C load views cannot expose the voltage window and reject these loads; additive binding views remain unfinished. Models 6 and 7 still need complete typed laws.

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.

LinDist3Flow construction is likewise explicit. A module with an explicit neutral first passes through the facade’s neutral_kron; the returned network records the projection provenance and the module records the transform and its diagnostics. Instance construction then checks the supported radial model slice, fixes the voltage reference, and creates the portable input:

use powerio::{neutral_kron, to_lindist3flow_opf_instance};

let (reduced, report) = neutral_kron(&feeder)?;
let instance = to_lindist3flow_opf_instance(&reduced)?;

powerio_dist::neutral_kron_reduce remains available when an application needs the independently owned network projection without module records. The projection rejects finite current limits on eliminated neutrals. Such limits need a constraint on the recovered neutral current, which this reduced network type cannot represent.

powerio-matrix compiles that instance to sparse affine rows, bounds, and second-order cones. It does not select or invoke a solver, so the same bundle can be handed to a native or WebAssembly-compatible conic backend. The supported physical slice, rejected equipment and validation evidence are recorded in the multiconductor LinDist3Flow design review.

MG-RAVENS JSON

MG-RAVENS is LANL’s CIM derived microgrid interchange schema (https://github.com/lanl-ansi/MG-RAVENS): one JSON document of name keyed tables nested under the CIM class hierarchy. The format has one token, ravens-json, and two profiles that share the top level shape and differ in the classes they use. A document whose equipment is per phase (ACLineSegmentPhase, PerLengthPhaseImpedance, EnergyConsumerPhase, TransformerTank) is the multiconductor profile and parses here; a document of balanced equipment (PowerTransformer ends with PowerTransformerEnd, positive sequence line parameters, generating units with cost curves) is the balanced profile and parses to a BalancedNetwork through the transmission hub. The facade and the CLI pick the reader from the content, so powerio convert feeder.json --to dss and powerio convert case9.json --to matpower both work without a profile flag; powerio_tnd::formats::ravens is that dispatch for library users, and a document mixing the two profiles is refused.

MG-RAVENSModel
ConnectivityNode, Terminal.phasesbuses, with the terminals the equipment uses; a Ground at a node grounds the conductors its phase code names
ACLineSegment with ACLineSegmentPhaselines, every conductor in sequenceNumber order, the neutral included; each end’s Terminal.phases is its own map, so a lateral landing on another phase keeps both
PerLengthPhaseImpedanceline codes in ohm/m and S/m
EnergyConsumer with EnergyConsumerPhaseloads; a wye load returns on the neutral terminal, and grounded says whether that neutral is grounded at the bus; a single phase load stating grounded false whose neutral nothing but such loads reaches is kept as stated with a READ.RAVENS_DIST.VALUE_CONFLICT finding, since its neutral floats (the CIM reader grounds it)
LinearShuntCompensatorshunt banks; Yn is a wye bank whose neutral is grounded, Y one on an ungrounded neutral
the Switch classes with SwitchPhaseswitches with their state
PowerTransformer, TransformerTank, TransformerTankEnd, TransformerEndInfo with its teststransformers, one tank per unit; each end’s phaseAngleClock is the vector group shift, as in distribution CIM below (clock 11 on a delta–wye unit reads as leadlag euro), or the tank stays untyped with the represented clock named; the writer states each end’s clock and the vector group (Dyn1, Dyn11)
EnergySourcevoltage sources; a source whose phasors are not one balanced set is written as one single phase EnergySource per conductor with the same phasors
RotatingMachine, PowerElectronicsConnectiongenerators and inverter based resources

A segment with a PerLengthPhaseImpedance takes it. A segment without one, on a WireSpacingInfo, takes the impedance of its wires, calculated as the CIM reader does (see Wire catalog lines). A segment whose wires cannot be calculated stays untyped at its source path with the reason, and the catalog records stay untyped as well. In-service equipment kept untyped this way (a segment, switch, tank or load the reader cannot type) round trips to MG-RAVENS, and conversion to any other format refuses it (READINESS.RAVENS_DIST.EQUIPMENT_UNRESOLVED) rather than writing the feeder without it.

Voltage limits follow the upstream converter’s line-to-line base, including single-phase equipment. PowerIO converts them to phase-to-ground bounds in the typed network. When an unbalanced source has a coupled Thevenin impedance, emission writes one shared impedance branch ahead of the per-phase ideal sources. Malformed or asymmetric source matrices are refused rather than projected onto a different circuit.

Everything the schema cannot name is reported: a conductor outside the four CIM phase identities (the fifth wire of a five wire code) has no ACLineSegmentPhase, so such a segment is dropped with a finding, and a network’s generation costs, which belong to the balanced profile, are dropped from the multiconductor one. Objects the reader has no typed slot for stay untyped at their source paths and are written back there. Writing is byte stable: a document written, read, and written again is identical. tests/data/dist/ravens/ holds the vendored example (Apache-2.0).

The RAVENS schema CI gate validates regenerated output after a PowerIO IR round trip against the pinned upstream schema generator. Distribution output uses the unmodified schema. The upstream balanced MATPOWER converter emits two fields its own schema omits: ConnectivityNode.SvVoltage and MySettings. Balanced output is checked against that schema with a strict supplement for these two fields. The report distinguishes these profiles, lists every case and diagnostic, and includes controls that reject malformed output. See evals/validation/ravens/ for the revision, commands, and scope; schema validity alone does not establish electrical equivalence.

pandapower three-phase JSON

pandapower JSON has one token, pandapower-json, for balanced and three-phase networks. A document whose asymmetric_load, asymmetric_sgen or res_bus_3ph table has rows is a network for pandapower’s runpp_3ph, and powerio_tnd::formats::pandapower reads it here. The facade and the CLI pick the reader from the content. Every bus has the phase terminals 1, 2 and 3 and a grounded neutral 4, lines turn their sequence data into phase matrices, an external grid is an ideal source, and loads and static generators are constant power, balanced or per phase.

This reading does not map transformers, shunts, switches and the other element tables yet, and reports each one it drops. A document with rows in a table only the balanced reader maps (trafo, shunt, gen, storage, dcline) keeps reading balanced, as in PowerIO 0.12.0, when that reader accepts it. A transformer or a switch that joins or splits buses changes the connectivity, so powerio batch skips a three-phase network read without one. An element on an out-of-service bus is kept with in_service false in its extras. Writing a three-phase network to pandapower-json returns its unchanged source; any other multiconductor network is refused with EMIT.DIST.PANDAPOWER_UNSUPPORTED.

PowerModelsDistribution MATHEMATICAL model

pmd-math-json is the PowerModelsDistribution MATHEMATICAL model, the per unit, index keyed form that PMD builds its JuMP models from. The writer follows transform_data_model: it lowers each transformer into PMD’s loss model (one virtual bus and resistance branch per winding, star reactances between windings, the no load admittance at the first winding’s internal bus, and an ideal two winding unit per winding), lowers sources into generators behind their Thevenin impedance, floods settings.vbases_default across lines and switches and through the ideal units’ ratios as calc_voltage_bases does, and rebases every object as make_per_unit! does. A grounded neutral is Kron reduced by default (PmdMathEmitOptions::kron_reduce), and the document says is_kron_reduced. The map entries PMD writes are written too, and the reader folds through them: a load’s ZIP parts, a transformer’s virtual buses and branches, and a source’s generator and virtual bus come back as one element each; a wye load that lists as many connections as powers returns on the neutral the reduction eliminated, restored at its bus as a grounded terminal. The reader restates the winding impedances on the emergency rating, since the MATHEMATICAL model carries no winding power rating, and says so. A load without a nominal voltage and an island no stated base reaches are written with a stated default and a finding where PMD’s own functions would stop. tests/data/dist/pmd/math/ holds PMD v0.16 exports of five of its own cases, ENGINEERING and MATHEMATICAL side by side, which the tests compare the writer against field by field.

Distribution CIM

The cim-dist format reads and writes CIM RDF/XML for unbalanced feeders in the profile the GridAPPS-D and CIMHub tools exchange: one document in the http://iec.ch/TC57/CIM100# namespace, the iec61970cim17v40 and iec61968cim13v13 release that CGMES 3.0 also uses, with ConnectivityNode connectivity and per phase equipment. The reader also accepts the older versioned CIM-schema-cimNN namespaces and refuses a document set that mixes CIM16 and CIM100. Input is one document, or a directory whose top level .xml documents read as one case, with rdf:about records extending the ones another document defines. Files in subdirectories are not part of the case, and ZIP archives are not read yet. A .xml document, a nameless source, or a directory routes here when it carries per phase classes or the IEC 61968 customer classes (ServiceLocation, UsagePoint) and no CGMES md:FullModel header.

CIMModel
ConnectivityNode, Terminalbuses, with the terminals the equipment uses
ACLineSegment with ACLineSegmentPhaselines, conductors in sequenceNumber order; each phase’s sequenceNumber names its PhaseImpedanceData row and column
PerLengthPhaseImpedance, PerLengthSequenceImpedance, segment r/x totalsline codes in ohm/m and S/m
EnergyConsumer with EnergyConsumerPhaseloads, per phase power
LinearShuntCompensator with its phasesshunts; sections multiply the per section admittance
the Switch classes with SwitchPhaseswitches with their state and rating
PowerTransformer with PowerTransformerEnd, TransformerMeshImpedance, RatioTapChangertransformers of any winding count, with taps
TransformerTank with TransformerTankEndone transformer per tank, grouped by its PowerTransformer in the cim_power_transformer extra
Asset linking a tank to TransformerTankInfo, with TransformerEndInfowinding ratings, connections, and resistances
ShortCircuitTestshort circuit reactances between winding pairs, and winding resistances when no end info states one
NoLoadTest, TransformerCoreAdmittancethe %noloadloss and %imag extras
EnergySourcevoltage sources, with the series impedance in rs/xs extras
WireInfo.ratedCurrent of a segment’s PowerSystemResource.AssetDatasheetthe segment’s ampacity, i_max on each conductor
Diagram with its DiagramObjects and DiagramObjectPointscoordinates: a segment’s points, in sequenceNumber order, are its route, the first at terminal 1. A connectivity node takes its own drawing, else that of a terminal there: one point is a stated bus location, and the centroid of several is derived. Without either, its bus takes the end of the first segment there, else the point of other equipment at it or of the composite switch that holds a switch; these are derived. A drawing that places nothing is reported unmapped with its points

SinglePhaseKind A, B, C, and N map to terminals 1, 2, 3, and 4, and the split phase s1 and s2 to 1 and 2. A conductor beyond those four has no CIM phase, so the writer reports it. An enumeration written as text (<cim:Terminal.phases>A</cim:Terminal.phases>), as some CIM16 exports state it, reads like the reference form.

One Diagram gives the coordinates: the first whose name or description names an EPSG: code, else the first. A code known to be geographic (EPSG:4326, EPSG:4258, and other widely used ones) reads as x = longitude and y = latitude. Any other code is projected when a coordinate lies outside the range of degrees. Otherwise the coordinates fit either reading, so the space stays undeclared with a READ.CIM_DIST.VALUE_UNSUPPORTED finding naming the code. A diagram without a code is a drawing. PowerIO does not reproject: the network’s geo metadata names the CRS, and a geographic layer applied with apply_geo_layer replaces the coordinates with reprojected ones.

Wire catalog lines

A segment with no PerLengthImpedance that names a WireSpacingInfo takes the impedance of its conductors: each ACLineSegmentPhase names a WirePosition by its sequenceNumber and a wire catalog entry by its PowerSystemResource.AssetDatasheet (OverheadWireInfo, WireInfo, ConcentricNeutralCableInfo or TapeShieldCableInfo). The OpenDSS line constants that read geometry calculate it, under OpenDSS’s default earth (Deri, 100 ohm-m) since CIM states none, reported once as a VALUE_DEFAULTED finding. Positions and diameters are meters and resistances ohm/m, as CIM states them; diameterOverScreen is the tape’s inside diameter. A position repeated with the same coordinates is one position. A neutral (N) phase the segment’s Terminal.phases does not state is Kron reduced, as an OpenDSS line on a spacing with more conductors than phases reduces its neutrals; one the terminals state stays a conductor.

A position no phase names leaves the impedance unknown (an unstated neutral changes every phase entry), and the segment is refused with the position named: READ.CIM_DIST.IMPEDANCE_UNRESOLVED, or an untyped segment in MG-RAVENS; either way conversion to another format refuses it. The MG-RAVENS IEEE13_Assets example, as XML or JSON, is such a document: it names no wire for the neutral of nine of its eleven segments (650632, 632670, 670671, 671680, 632633, 632645, 671684, 684611 and 684652); 645646 states a PerLengthImpedance. Its one complete wire catalog segment (692675, concentric neutral) matches OpenDSS to 2e-5, the difference of the exporter’s 1609.3 m mile; the same conductors stated completely, neutral included, match OpenDSS to 1e-13 of each matrix’s largest entry.

Without a BaseFrequency, distribution CIM reads at 60 Hz in both CIM16 and CIM100, with a READ.CIM_DIST.VALUE_DEFAULTED finding. The namespace identifies the schema, not the grid’s operating frequency; state BaseFrequency for 50 Hz or another frequency. Circuit, CompositeSwitch, and PSRType are context (READ.CIM_DIST.CONTEXT_UNMAPPED). The IEC 61968 customer classes route a document here but are not mapped yet, so ServiceLocation and UsagePoint are reported as unmapped classes.

A tank end’s terminals follow from its TransformerTankEnd.phases, in the form the dss reader gives the equivalent OpenDSS transformer: a line to neutral end A is terminals 1, 4 (bus.1.0), a line to line end AB is a delta winding on 1, 2, a three phase end is 1, 2, 3 in delta or 1, 2, 3, 4 in wye, and the center tap halves s1 and s2 are 1, 4 and 4, 2 (bus.1.0 and bus.0.2), so they stack to the full secondary voltage. Catalog values use ratedU, ratedS, and r in V, VA, and ohm. ShortCircuitTest.leakageImpedance is the standard impedance magnitude in ohm referred to the energised end; the pair reactance is derived with X = sqrt(|Z|² - R²) after resolving the winding resistances, including when a test loss is zero/unstated. Test losses are in kW; NoLoadTest.excitingCurrent is percent of rated current at the test’s basePower, and percentages are rescaled to winding 1’s rating. The producer-specific GridAPPS-D convention that places X in this magnitude field is not supported or automatically inferred; those inputs need normalization to the standard convention before import. End resistances (TransformerEndInfo.r) take precedence over resistances split from test losses, a loss of 0 states nothing, and a nonzero loss that disagrees with the end resistances is reported (READ.CIM_DIST.VALUE_CONFLICT).

Tank phase clocks are the vector group shift the physics stamps (powerio_dist::transformer’s delta orientation): aligned connections are clock 0, a three-phase D/Y unit is clock 1 when the high voltage winding leads (OpenDSS’s default leadlag) and clock 11 when the low voltage winding leads, and reversed single-phase center-tap halves are clock 6. A D/Y unit stating clock 11 reads with leadlag euro, so it stamps the -30 degree shift. Other clocks, invalid clocks, inactive tanks or parents, and disconnected end terminals are refused. An absent clock is assumed to match the layout with a diagnostic. Fresh writing derives the clock from the current windings and leadlag and reports conflicting retained metadata; the PowerTransformerEnd form states its clocks whenever OpenDSS’s default convention does not represent them, so a unit neither convention represents (a Y-D-D unit whose deltas roll opposite ways) is written with its clocks and refused on reading, never read back with a winding shifted.

A transformer whose extras carry cim_form = "tank" is written as tanks, grouped under the PowerTransformer its cim_power_transformer extra names, with tanks of identical catalog data sharing one TransformerTankInfo; every other transformer, including those from other formats, takes the PowerTransformerEnd form.

Regulator controls, distributed energy resources (PowerElectronicsConnection), machines, operational limits, LoadResponseCharacteristic, and TopologicalNode only documents are not mapped yet, and the reader reports each of them: a class with no mapping is counted per class (READ.CIM_DIST.CLASS_UNMAPPED), a property no mapping reads is counted per class and property (READ.CIM_DIST.FIELD_UNMAPPED), and a segment with no impedance is an error severity finding (READ.CIM_DIST.IMPEDANCE_UNRESOLVED). Conversion to another format refuses such a segment (READINESS.CIM_DIST.IMPEDANCE_UNRESOLVED): its placeholder line code has zero impedance, which would be a short circuit between its buses. OpenDSS geometry lines are refused for the same reason; Electrical readiness describes both checks.

Disconnected or out-of-service switches read as open, preserving connectivity. For other mapped equipment, the reader refuses an out-of-service state or a disconnected terminal because the 0.11 model cannot represent that electrical status. inService takes precedence over normallyInService. Per-phase delta compensators and incomplete-phase delta banks are refused rather than converted to phase-to-ground admittances; balanced three-phase delta banks remain supported.

A network read from distribution CIM records cim-dist as its source format. A same format write of a single document returns its bytes. Canonical output is one CIM100 document with no md:FullModel header. Imported mRIDs pass through and the rest are UUIDv5 values, and the written numbers are the ones the reader maps back exactly, so write, read, write is byte stable. The output is not fully qualified against external producer corpora. The committed synthetic tank cases are checked against native OpenDSS grounded admittance stamps and loaded coil phasors by evals/validation/validate_cim_tanks.py, including fresh CIM writing, a clock-1/clock-11 control and a clock 11 tank read as leadlag euro. This does not establish support for producer dialects outside the documented electrical profile.

Distribution CIM status

  • CIM release. CIM100 (http://iec.ch/TC57/CIM100#): IEC 61970 cim17v40 with IEC 61968 cim13v13. The reader also takes the older CIM-schema-cimNN namespaces; the writer always emits CIM100. cim18v17, and the IEC 61970-460 and -470 profiles that replace IEC 61968-13 CDPSM, are not implemented.
  • Application profile. The single document feeder profile the GridAPPS-D and CIMHub tools exchange, with ConnectivityNode (node breaker) connectivity and per phase equipment. Format discovery (powerio::grid_formats) labels the cim-dist token “CIM distribution (CIM100 cim17v40, GridAPPS-D profile)”.
  • Input. One document, or the top level .xml documents of a directory, read through the same Source acquisition as every directory format: the POWERIO_MAX_REFERENCED_BYTES budget applies and symbolic links are refused. ZIP archives are not read; the bounded ZIP reader is still private to the CGMES reader.
  • Validation. The CIM schema workflow checks fresh output for every committed distribution fixture against the cim17v40 vocabulary and the GridAPPS-D rc4_2021 profile classes CIM-Graph generates (evals/validation/cim_dist); PowerIO output has no vocabulary errors. evals/validation/validate_cim_tanks.py compares the tank fixture with native OpenDSS. CIM-Graph round trips and cimhub-opendss comparisons are not run yet.
  • Not mapped. Regulator and tap changer controls (RegulatingControl, TapChangerControl), distributed energy resources (PowerElectronicsConnection) and machines, operational limits, and LoadResponseCharacteristic are reported on read (READ.CIM_DIST.CLASS_UNMAPPED, READ.CIM_DIST.FIELD_UNMAPPED). A document that connects equipment through TopologicalNode (bus branch) only is refused. On write, generators, inverter based resources, and control profiles are reported as dropped (EMIT.CIM_DIST.RECORD_DROPPED), as are conductors beyond A, B, C, and N (EMIT.CIM_DIST.FIELD_DROPPED). Because generators do not survive a CIM round trip, cim-dist is not yet in the conversion matrix.

GridLAB-D profiles and projects

The .glm extension selects the PNNL 5.3 profile (gridlabd, aliases glm and gridlabd-pnnl). Select gridlabd-arras explicitly for Arras 4.3. The profiles differ in source interpretation, including conditional preprocessing; sharing a file extension does not establish equivalent electrical behavior.

powerio summary feeder.glm --from gridlabd-arras
powerio convert feeder.glm --from gridlabd-arras --to gridlabd-arras -o copy
powerio serialize feeder.glm --from gridlabd-arras -o feeder.pio.json
powerio convert feeder.pio.json --to gridlabd-arras -o canonical

Both GLM targets emit directories. An unchanged same-profile module retains the entrypoint’s original relative path and all acquired include files, byte for byte. Parsing or writing never executes the simulator. Replay reads only the retained dependency buffers, even if the original files have since disappeared. Unreferenced supplied buffers remain on the source module but are not copied to the emitted project. Absolute include paths cannot be relocated byte exactly and are refused. When a caller supplies external definitions through glm::PreprocessOptions, replay reports that those inputs must accompany the files; the module’s org.powerio.gridlabd extension records them. The profile also appears in source descriptors. The legacy network source_format field stays unset so the existing IR 2 record remains compatible.

Unused passive equipment definitions remain in source with a diagnostic. The reader follows configuration, conductor and spacing references from instantiated objects; a connected unsupported device still fails. This lets shared equipment libraries contain unused transformer or triplex definitions.

Fresh networks, edited modules, IR-restored modules and cross-profile writes generate case.glm from the typed network. Rust’s powerio_dist::glm::emit_canonical offers single-file output directly from a network value. Emission validates physical support before writing any output. Names beginning with a digit or hyphen retain their IDs; canonical output enables native relaxed naming when required.

The currently qualified electrical profile covers phase-to-earth sources, node/meter/load objects, independent P/I/Z load terms, parented loads, and overhead and underground lines with explicit phase matrices or conductor/spacing configurations at 50 or 60 Hz. Overhead geometry uses the pinned modified-Carson constants and enabled image-potential capacitance. The resulting linecode records its calculation and neutral-reduction provenance; canonical output writes current matrices. Diagnostics report coefficient calculation and the loss of geometry provenance on canonical emission. Map coordinates never determine conductor spacing or length. Three-phase subsets keep their A/B/C identities. Bus earth returns do not constitute explicit line neutrals. A geometry configuration with a neutral imports GridLAB-D’s reduced phase circuit, with zero neutral voltage at both ends; it does not provide separately solved neutral voltage/current values. Underground geometry supports concentric-neutral and tape-shield cables. The selected dialect matters: PNNL includes a separately declared neutral in the reduction; pinned Arras omits it for concentric-neutral cables. Arras’s tape-shield model uses the first active phase’s neutral parameters for the separate neutral’s self impedance. The reader preserves these native differences in the resulting matrices and reports the selected interpretation. Arras tape-shield geometry without a separate neutral is singular and is refused. Unshielded phase-cable geometry is accepted only for Arras, whose native model omits its separate neutral and charging capacitance; PNNL rejects that geometry. Canonical output carries the calculated matrices, so it does not reinterpret geometry under the target fork.

Numerical iteration_limit settings and voltage/current dump objects remain in retained source and are reported; they do not become network components. line_limits, positive default voltage convergence tolerances and multi_recorder objects are also retained and reported. Passive equipment names resolve case-sensitively, including names differing only by case; typed component names still need distinct case-insensitive identities. Ordinary transformers support three-phase WYE_WYE (also numeric 1) and single-phase SINGLE_PHASE connections with explicit voltages and positive series resistance/reactance. They map to grounded winding records and retain device coordinates. Canonical output uses the current winding voltage, resistance and reactance; source-only configuration objects are not required after an IR round trip. OpenDSS output explicitly disables its additional anti-floating admittance for these imported circuits. The total rating can be explicit or the sum of phase ratings; conflicting totals beyond the native 1% limit fail. Individual phase nameplate declarations remain in source and are reported.

FBS grounded-wye transformers preserve the finite default core admittance in the existing no_load_shunt winding-2 record. Canonical NR GLM represents it as a constant-impedance load at the secondary bus, with a diagnostic identifying its contribution to the transformer port current. OpenDSS uses its equivalent winding-2 exciting branch. A connected directed FBS tree without an explicit source uses its unique upstream root’s phasors; ambiguous roots, cycles and implicit-source switch/regulator networks fail. Other transformer connections, non-unit ordinary-transformer taps and explicit source magnetizing parameters still need qualification.

For both pinned engines, NR DELTA_DELTA (also numeric 2) stamps three grounded-wye branches, including zero-sequence transfer. The reader preserves that native circuit in existing winding records and issues READ.GLM.TRANSFORMER_EQUIVALENT. The gridlabd_declared_connection extra keeps the original label across IR; it does not carry electrical parameters. Canonical GLM writes the effective WYE_WYE circuit and diagnoses the label change. This is native-engine compatibility, not physical delta winding isolation; physical delta export still requires its own mapping.

FBS DELTA_DELTA instead imports its native hybrid equations as a nine-terminal admittance with two ideal external contacts. Three auxiliary voltages encode scaled output currents: the native law removes common-mode input voltage but transfers common-mode current. This preserves the pinned solver’s behavior for unbalanced grounded loads without substituting physical delta isolation. Coordinates follow the equivalent’s shunt and contacts; ratings remain source-only and are diagnosed. Twelve native comparisons cover both forks, step-up/down/equal voltages, and wye/delta loads through IR and OpenDSS. OpenDSS writing preserves the full asymmetric admittance with coupled two-port blocks and exact diagonal corrections. Internal negative-element losses are not physical device losses; measure the aggregate external ports. Canonical GLM writing of this auxiliary-node equivalent remains unsupported.

DELTA_GWYE (also numeric 3) imports for NR and FBS as three single-phase coils. Each primary joins two phase terminals; each secondary joins its phase to ground. The native step-up and step-down orientations differ, including their phase shifts. The mapping preserves that orientation and zero-sequence blocking without depending on a target’s default transformer clock angle. Coil ratings use one third of total power and secondary coil voltage uses line-to-neutral voltage. Both pinned engines and IR-restored OpenDSS agree on unbalanced step-up, step-down, equal-rating and IEEE8500-parameter circuits. Coordinates attach to all three coils. Canonical GLM groups a complete coherent three-coil bank into one native DELTA_GWYE transformer. Its configuration uses the current effective winding voltages, total rating and series impedance, including edits after IR restoration. Diagnostics identify the grouped coil names; coincident component points remain on the bank. Conflicting points fail.

The coils must share effective voltages, ratings and impedance, and their phase pairs must match the native orientation for the current voltage ratio. Incomplete or unequal banks, parallel banks at the same endpoints, grounded primary returns, and ratio edits that cross the native orientation boundary require additional mappings and fail explicitly. Component qualification covers step-up, step-down, equal-voltage and IEEE8500 nameplate cases on both forks. Complete IEEE8500 canonical qualification is described below; the other bank restrictions remain.

NR WYE_WYE regulators preserve Type A/B per-phase ratios and series resistance as single-phase winding records. An object tap overrides its configuration tap. Manual missing taps use the native neutral position; an active controller needs explicit taps on every active phase and produces a frozen-control warning. Unit suffixes follow the selected engine: PNNL’s regulation field has no unit, while Arras publishes %. Bare numeric values retain their native meaning. The winding’s 1 VA normalization base is marked as defaulted and is not a declared nameplate rating. The rating_is_normalization_base extra preserves that fact in IR; cross-format writers diagnose loss of that metadata. Device coordinates attach to every resulting phase record. Canonical GLM emits manual regulator equivalents from current winding values; OpenDSS uses xscarray=(0) to avoid its scalar zero-reactance substitution. FBS WYE_WYE regulators instead retain ideal zero-leakage winding constraints; the native FBS solver ignores declared regulator resistance. OpenDSS emission uses a one-ohm winding resistance followed by its exact negative, eliminating both at an unloaded internal bus. This preserves the ideal ratio and external currents without an arbitrary small leakage. A diagnostic identifies the added line: physical secondary powers and total losses include it. The typed value and IR retain zero leakage.

Canonical GLM now writes grounded ideal phase ratios as a series of native FBS manual regulator stages. Each stage changes one phase and passes the other connected bank phases at unity ratio. This avoids native current/loss errors from parallel single-phase regulator objects. Ratios come from current effective winding voltages; unrelated ratios do not need a common integer tap lattice. Generated intermediate buses are internal to the equivalent, and diagnostics identify the physical bank ports. Distinct component points remain on separate stages. Declared winding ratings are diagnosed as omitted because native regulator configurations have no power-rating field. Reimport absorbs redundant unity coils without multiplying the stage count. Open-delta connections, banked initialization and floating-return GLM writing remain unfinished.

Plain ideal closed switches likewise use cancelling resistances in OpenDSS; plain open contacts are disabled and have no artificial line charging or leakage. Switches retaining source-specific impedance declarations use the existing source-aware path. OpenDSS Line objects with switch=yes retain their finite line impedance and fixed terminal states. Operating-point switch_closed columns address typed ideal DistSwitch contacts. An application can add an explicit series contact while retaining the imported finite branch; this supplies contact states without executing an OpenDSS switching sequence. Transformer cancellation currently covers complete two-coil, single-phase winding records with grounded or floating secondary returns and no core or neutral shunts. A floating return uses two cancelling conductors, preserving common-mode displacement. Other ideal-transformer profiles need further qualification.

Canonical node convergence is set to 1e-9 V. FBS output permits 1,000 iterations so larger edited feeders can reach that stopping precision. The tighter former absolute setting could prevent IEEE13 from converging despite stable electrical values. This is an engine stopping criterion, not the validation comparison tolerance.

The pinned IEEE13 and IEEE37 NR feeders are qualified against PNNL, Arras and OpenDSS for all bus-phase voltages, source currents, line/transformer terminal currents, terminal powers and losses, and original load-object currents/powers. Checks include independently edited input, IR-restored canonical output and current balance at every bus. This evidence applies to those feeders and their documented edits; it does not establish the unfinished profiles above. IEEE37 starts downstream of its regulator; its NR delta transformer uses the equivalent described above. Its parent-directory include uses the existing explicit acquisition-root API. See evals/gridlabd/README.md for the reproducible oracle and measurement conventions.

The legacy IEEE4 grounded-wye step-down feeder has fixed-state qualification with its original default FBS solver and implicit upstream source. Both pinned forks and OpenDSS agree on all bus and device-port measurements; deliberately omitting its small default core current fails the comparison. This does not qualify every IEEE4 transformer configuration.

IEEE34 and IEEE123 NR also have fixed-state qualification across both forks and OpenDSS, including per-phase manual capacitor admittances and switch/regulator states. Their edited-state qualification remains pending. The harness documents per-feeder stopping settings and numerical comparison budgets.

Capacitor VAR, VOLT, VARVOLT and CURRENT controls import as fixed snapshots only when every phase has an explicit switch state and control is individual. READ.GLM.CONTROL_FROZEN reports excluded control execution. Thresholds, sensing references and delays remain in source; canonical output uses manual coils with the current typed admittances. Missing switch states and unqualified banked initialization fail. A single-phase manual bank sensing its own phase is supported. An explicit cap_nominal_voltage sets its admittance base; otherwise native initialization uses the parent bus nominal voltage.

The IEEE8500 native reference harness compares its original PNNL input with explicit static configurations on both forks. Arras requires triplex_load constant power declarations where this older input uses triplex_node.power_1/power_2. The harness also handles different dump-mode spellings. That initial dump-only reference remains separate from full-precision import qualification.

The complete pinned IEEE8500 fixed-state case now has native-to-OpenDSS import qualification through IR, across both forks. The full-feeder harness compares all 4,879 native bus objects and 4,876 device ports, including center-tapped services, triplex neutral currents and ideal regulators/switches. It verifies physical powers and losses, native loss-report conventions, and current balance at all non-source, non-ground bus terminals. The original PNNL input and portable static input produce identical typed circuits. Native convergence is tightened from a nominal-voltage fraction of 1e-4 to 1e-12 for comparison; electrical data and the common comparison budgets are unchanged. A deliberately wrong regulator tap must fail.

The pinned IEEE8500 case also qualifies fresh canonical GLM on both forks, including IR-restored, rebased, explicitly grounded-source and typed edited circuits. Reimported GLM and both DSS outputs agree at every original bus and physical link port. Edited circuits change load powers, winding voltages/taps, leakage and line lengths; their results are checked against the independent DSS engine and bus current balance. The harness preserves all 82,901 electrical observations per comparison. The ten engine/stage cases pass 38 comparisons and 187,550 current-balance observations without relaxing comparison budgets. This does not establish the remaining IEEE9500 or general OpenDSS profiles.

Grounded center-tapped services import as four typed windings and a constant-impedance load at an auxiliary core bus. The fourth winding exposes the internal core branch after primary leakage; the two secondary windings preserve opposite polarity. Configuration phase ratings determine the impedance base. Triplex loads retain separate leg and line-to-line P/I/Z terms. These circuits have native-to-OpenDSS import qualification on both pinned forks, including IEEE8500 service parameters and an IR round trip. The internal core load must be included when aggregating physical transformer losses.

Triplex line geometry imports as a full three-conductor impedance matrix with neutral grounded at both endpoints. This is equivalent to the native grounded neutral reduction and retains its reconstructed neutral current. Unequal conductors, 50/60 Hz, NR/FBS, mixed loads and connected IEEE8500 service parameters have native-to-OpenDSS qualification, including both-end powers and losses. Direct triplex 2×2 matrices also import. GridLAB-D’s reversed leg-2 voltage convention requires negating the second matrix row to obtain physical terminal voltages and currents. The resulting matrix can be nonreciprocal; import preserves it and reports READ.GLM.REDUCED_TRIPLEX. Such input does not define a physical neutral/ground-current model. OpenDSS output uses an exact source-and-line equivalent, including an open auxiliary third port, when needed. Aggregate its physical end ports for powers and losses; internal element losses alone are not the original line’s losses. Both forks and solvers have direct-matrix microcase qualification through IR and DSS, including deliberate wrong-load checks. Floating service neutrals, service switches and additional geometry models remain unfinished and fail explicitly. Grounded services can participate in a checked FBS forest with ordinary-phase ideal contacts; the private core bus is contracted for topology validation. Native checks cover impedance and mixed P/I/Z services, IEEE8500 cable parameters and direct hot matrices through edits and repeated output. Every contact port is included in these checks.

Canonical GLM can now write grounded center-tapped services from their current four-winding circuit and private impedance core load. Effective winding ratios, leakage and core admittance set the native configuration; retained source parameters do not override edits. The core bus must have no additional device or external connection. Unequal effective leg ratios require another mapping. Triplex power and impedance terms keep separate load objects. Current terms are combined on the root triplex_load so native NR updates their voltage angle every iteration; diagnostics report the grouped identities. Distinct geographic points on grouped current terms fail instead of being merged silently.

Full three-conductor triplex matrices emit a native geometry derived from the current coefficients, with every primitive entry checked before writing. This preserves grounded-neutral currents for that geometry family; it does not fit arbitrary edited matrices or recover the original construction. Direct hot-conductor matrices instead emit with the inverse leg-2 row convention and report that no physical neutral-current model is inferred. Line, configuration and transformer coordinates use the current typed points. These component profiles have separate complete IEEE8500 qualification above. Floating or arbitrary neutral circuits and unequal service leg ratios remain unsupported.

Nonzero triplex base_power_1, _2, and _12 initialize separate constant-power, constant-current and constant-impedance terms, overriding explicit coefficients on that connection. Import reproduces native power-fraction normalization and signed power factors, with READ.GLM.LOAD_NORMALIZED. Zero base power leaves explicit P/I/Z coefficients in effect.

A missing or zero overhead mutual spacing produces zero mutual impedance in the pinned engines. Import preserves this behavior and reports it instead of inventing a spacing. Capacitance geometry still requires its qualified positive dimensions. Seasonal conductor/configuration ampacities are validated and retained in source with READ.GLM.SOURCE_ONLY; projection into typed ampacity limits remains unfinished. Full OpenDSS static compatibility is not yet established.

Electrical parents are zero-length bus attachments. Qualified node/meter/load chains flatten onto their root bus while retaining each load’s own P/I/Z law and geographic point. Canonical output attaches loads directly to that bus. PNNL 5.3 NR and both FBS profiles are qualified for two- and three-level chains, including phase subsets, reversed declaration order and intermediate demands. Arras 4.3 NR rejects electrical parent chains deeper than one level: the pinned engine can omit descendants or crash, so flattening would not preserve its source behavior. Direct child loads remain supported. This native profile gap is unresolved; parsing never silently turns omitted descendants into zero loads.

Loads support legacy A/B/C terms and explicit AB/BC/CA/AN/BN/CN power, current and impedance terms. Terms add independently, including legacy and explicit terms on the same connection. Explicit pairs map to two-terminal typed loads; current terms follow the connection voltage angle. Canonical output preserves each load’s voltage base and can express a complete typed three-channel delta load as explicit pairs. It reports the resulting component identity split and any terminal orientation normalization. A load’s traditional D flag maps legacy A/B/C terms to AB/BC/CA respectively; its stated nominal voltage remains phase-to-earth, so the pair voltage base is √3 times that value. Real/reactive setters (_real, _reac) update the corresponding complex part in source order, with native units. They work for legacy and explicit channels. The D flag on node/meter/load objects does not create a neutral conductor or change the source phasor reference. Incomplete typed delta channel layouts, split-phase services and explicit line neutrals remain under implementation.

Ordinary-phase switch objects import their fixed status, banked or individual phase states and native contact impedance. Finite closed contacts become exact uncoupled line equivalents with unit normalization length and a diagnostic; open and ideal closed contacts remain typed switches. A mixed state splits into closed and open phase groups, each retaining the original object’s point. Banked initialization applies majority state, uses overall status to break a two-phase tie, and honors an overall open status. Any change from the stated phase states is reported; no controller or protection sequence is executed.

The solver setting affects impedance defaults. Both pinned profiles default to FBS, whose unspecified contacts are ideal. NR uses the module’s default_resistance (default 1e-4 ohm); unspecified resistance/reactance become +default_resistance and -default_resistance, while explicitly zero NR components become positive default_resistance. Supported numeric global overrides must be finite and positive. Scalar impedance aliases follow native assignment order and unit interpretation. Canonical GLM emits finite contacts as overhead-line equivalents and fixed open contacts as open switches.

Ideal closed contacts select FBS and emit explicit zero contact impedance. Conducting links must form a forest with one source bus per component. The check includes grouped ideal regulators, delta-grounded-wye banks and grounded service transformers, with their private core circuits contracted. Links are oriented away from their sources, and disjoint switch phases between the same buses are grouped into one native object. Endpoint reversal and grouped identities are reported. Matching component points survive grouping; conflicting points fail explicitly. Fully open ties between already connected endpoints use unloaded child nodes parented to their physical endpoints. These aliases preserve both terminal voltages, zero currents and losses, and the switch point. They avoid native rank cycles and outgoing-current contamination; reimport recovers the original bus attachments. Other open links retain their island attachment. Closed cycles, parallel contacts on the same phase, connected multiple source buses and bus phases absent from the incoming link need additional equivalents. No small impedance replaces an ideal constraint, and the input network is unchanged.

For noncommuting line impedance and capacitance matrices, the pinned engines use a source-end current equation that differs from the physical pi-line law. NR uses it for reporting, so NR import retains the physical circuit and warns about the reporting discrepancy. FBS uses it during its solve: FBS import now preserves the native equations as a conductor admittance with auxiliary current variables and ideal external contacts, reporting READ.GLM.LINE_EQUIVALENT. Line coordinates follow the shunt and contacts; configuration coordinates and calculated coefficients remain on the retained linecode. OpenDSS output preserves this nonreciprocal circuit. Eight analytic/native/IR/DSS cases cover two- and three-phase examples, and IEEE13 FBS matches both pinned engines. IEEE34 still has two loss comparisons just above the strict tolerance; IEEE123’s zero-voltage configuration has one undeclared-phase voltage discrepancy. Neither is claimed as a complete raw match. Canonical GLM writing of these native FBS auxiliary-node equivalents remains unsupported.

For physical pi-line networks, canonical output replaces native line capacitance with exact phase-pair and earth-return impedance loads at each end. Conductive or unequal end shunts use the same equivalent in either solver. End-shunt expansion requires symmetric matrices; a nonreciprocal equivalent needs additional mapping and fails explicitly.

Generated shunts remain attached to their physical ends when a line reverses for FBS. Line coordinates stay on the series link. Diagnostics name the generated loads: physical line port currents, powers and losses include these loads as well as the series link. Reimport preserves the equivalent circuit as separate typed loads rather than reconstructing the original line identity. Native power_losses also makes each phase’s real loss positive before summing; with mutual coupling, physical total loss must use signed powers at both ports.

Finite scalar lines with impedance magnitude between 1e-8 and 1e-5 ohm can emit a current-variable equivalent in NR GLM and OpenDSS. This profile requires matching single-conductor endpoint maps, no line end shunts and no unresolved electrical extras. It preserves the exact finite impedance; it does not replace the line with an ideal contact or add an impedance floor.

The generated auxiliary voltage represents current with a one-ohm scale. Physical terminal currents include the generated endpoint shunts, and physical loss is the sum of signed terminal powers. Internal resistor losses are not the original line loss. Emission diagnostics identify the equivalent elements and report omitted thermal limits and routes. Reimport keeps the explicit circuit; coupled matrices and more extreme impedances retain their existing projection and are not covered by this qualification.

Canonical NR output sets default_maximum_voltage_error to 1e-9 per unit and lets each node derive its absolute convergence limit from nominal voltage. This avoids an absolute nanovolt stopping threshold on large feeders. FBS keeps its previously qualified absolute node setting. These are engine stopping criteria; the independent electrical comparison budgets remain separate. Zero-admittance shunts emit zero-current loads with their current component points and a class-rebasing diagnostic. No nonzero capacitor rating is invented.

Output without ideal closed contacts selects NR. The pinned engines can return NaN results for some valid circuits even with a successful process exit. One qualified impedance case reproduces this with either a native switch or its line equivalent; FBS solves the same circuit and matches the analytic solution. Engine validation therefore checks finite voltages, currents and powers, and reports these NR failures separately from successful electrical comparisons.

Standalone substation objects can supply fixed zero-, positive- and negative-sequence voltages. The reader applies the native reference_phase rotation and keeps the resulting phase voltages. Nonzero sequences require an explicit ABC SWING bus and override phase-voltage declarations. With all sequences zero, ordinary node initialization applies. Parented substations and external transmission coupling remain unsupported; standalone reporting settings are retained with a diagnostic.

Static series_reactor objects map to uncoupled line impedances with unit normalization length. Scalar resistance/reactance aliases apply in source order. Zero impedance uses an ideal contact in FBS; NR uses the pinned native fallback 1 / (10000 + j10000) ohm. Mixed ideal and finite phases remain separate typed components with their source coordinates. Current ratings remain in source with a diagnostic; typed rating projection and open reactor states remain unfinished. Canonical GLM output uses the existing line, switch and fixed-source equivalents.

PNNL 5.3 diesel_dg in CONSTANT_PQ mode reads as three single-phase constant-power generators, retaining unequal signed P/Q, the initialized per-phase rating limit, and component coordinates. Scalar power fields override the complex fields at initialization; the native -1 sentinel leaves that component unchanged. Missing or nonpositive Rated_VA uses the pinned engine’s 500 kVA default. Positive Rated_V must match the parent’s line-line nominal voltage within 1%. An ordinary ABC parent and module generators; are required. Dynamic modes and Arras’s different diesel model remain unsupported.

OpenDSS emission of generators without retained voltage bounds supplies a 0..2 pu constant-power band and reports the substitution. Above the emitted upper bound OpenDSS uses constant impedance. Generators parsed from OpenDSS retain their explicit bounds or native 0.9..1.1 pu defaults. Generator rating limits remain in IR; their OpenDSS mapping is unfinished and reports a loss. Canonical GLM writes current fixed generator injections as signed constant-power loads, preserving phase/phase-pair connections and component points. Reimport retains their electrical law under load identities. Ratings, optimization bounds and costs have no matching load fields and are diagnosed as omitted. Generator electrical extras or voltage/current laws outside this profile remain unsupported. This device qualification does not qualify the complete IEEE9500 feeder.

Solar-fed FOUR_QUADRANT inverters in CONSTANT_PF mode read as fixed per-phase inverter injections, including native efficiency and rating clipping. The supported solar profile is BASEEFFICIENT with default orientation and static climate temperature and direct irradiance. The reader evaluates its thermal equation; the inverter’s declared P_Out does not set dispatch in this mode. Split-phase inverters connect across the two hot terminals. OpenDSS emission derives their line-line voltage base from winding polarity and conductor mappings; retained OpenDSS voltage bases still take precedence. Component coordinates remain attached to the typed inverter records.

Both pinned forks are checked on ordinary and split-phase circuits, including the IEEE9500 solar parameters. Arras requires a meter or triplex-meter parent. An internal LI_ION battery on this inverter profile initializes with zero DC input and therefore zero AC injection, even if P_Out requests charging. Import preserves that idle electrical state and reports READ.GLM.BATTERY_IDLE; energy, state of charge and inactive load-following settings remain source-only. Native checks cover both solvers and forks. Other battery operating modes, weather files, multipoint efficiency remain unfinished. Canonical GLM writes explicitly fixed inverter P/Q bounds as signed constant-power loads on the current ordinary or split-phase connection. Available power alone is not dispatch; missing or nonfixed bounds, active profiles and unresolved voltage/current laws fail. Points remain attached to the equivalent, while prime-mover, availability and rating metadata losses are diagnosed. Climate coordinates and thermal inputs remain source-only with diagnostics.

OpenDSS rated wye reactors with kV/kvar and explicit R or Rp map to the existing shunt admittance. R=0 retains the rating-based reactance; R does not select the explicit-X specification mode. The profile preserves resistance, parallel damping and the snapshot-frequency admittance. Canonical output uses the current typed matrix, including edits after reimport. Copied state, competing specifications, curves and delta resistance remain unsupported in this profile. Native tests cover thirty phase/frequency/impedance cases.

OpenDSS Transformer Open/Close commands preserve fixed conductor states for one-, two- and three-phase circuits. Open ports move to internal zero-current terminals while retaining editable winding parameters; ideal contacts preserve closed connections. The equivalent includes the native external diagonal stabilization. A whole-terminal command changes phase conductors, leaving the neutral state unchanged. Two-phase delta windings retain their third hot terminal. Native checks cover 84 cases through IR, canonical DSS and reimport, including three-winding units. Aggregate losses must use the external ports. Layout, XfmrCode or copy changes after terminal commands, and disabled units with terminal commands, remain unresolved. Canonical GLM mapping of these circuits remains unfinished. Enabled unconverted Fault objects block electrical emission until their static admittance and switching state are represented.

OpenDSS Generator model 6 delegates its voltage/current law to an external library. The three-phase delta IndMach012a fixed-slip profile reads into the existing full shunt admittance, including positive- and negative-sequence behavior. Canonical DSS derives its equivalent circuit from the current typed matrix. Native checks qualify both public four-wire lagging/leading feeders, including IR, canonical reimport and all original motor terminals. A separate 27-case native sweep covers voltage, slip, initialization order and typed matrix edits. Explicit positive kV/kVA bases and named numeric userdata are required; library reloads, successive edits and slip-limit setter order are preserved. Variable slip, copied hidden state, other connections/user libraries and unsupported parameters remain blocked by READINESS.DSS.GENERATOR_USER_MODEL_UNRESOLVED. Retained same-format source emission remains available. No new network type or IR schema is needed.

OpenDSS Storage voltage model 1 reads fixed idling, charging and discharging power as signed BoundedConstantPower loads. The profile covers one-phase wye and two-/three-phase wye or delta, including reactive-only states. It preserves voltage bounds, current limits, setter order and end-of-edit state-of-charge guards. Canonical DSS derives fixed equivalents from the current typed powers, including edits that mix consuming and generating branches. Energy integration and dispatch remain source-only. Inverter curves, P/Q clipping, copied inverter state and one-phase delta remain unsupported and block electrical readiness.

The PNNL NR profile accepts future manual reliability events only when their start date is strictly after the complete clock window, all references resolve, and every declared phase reaches a fixed source. Connected SWING_PQ buses in the grid-association profile remain PQ buses, as in native initialization. Island promotion, active outages and protection execution remain unsupported. These choices produce explicit static-state diagnostics. Per-phase link current ratings are validated and retained in source; typed ampacity mapping is pending.

Both original CIMHub IEEE9500 balanced and unbalanced projects now parse through IR and produce solvable OpenDSS circuits with their DER and fixed device states. Both projects also produce canonical GLM from their current typed fixed injections and passive networks. This is output availability, not full-feeder qualification of canonical GLM. Both complete cases meet the documented one-part-per-million feeder accuracy profile for all 84,501 original voltage, current, power and loss measurements through import, IR and repeated DSS output. Independent external-terminal current balance also passes. The tighter analytic calibration comparisons remain separate and retain their discrepancies, including native NR line-current reporting when impedance and shunt matrices do not commute. Reimported disabled contacts retain inactive-state metadata; canonical DSS reports their omission, with zero external currents and endpoint voltages still checked. Physical terminal powers use endpoint voltages and boundary currents, not internal equivalent-source powers. Fresh canonical GLM now solves both complete cases on both pinned forks with the same feeder accuracy and physical current-balance checks. An edit that introduces source zero-sequence voltage exposes a native NR delta-grounded-wye primary-stamp discrepancy. NR input containing these banks and canonical NR output therefore refuse nonzero zero-sequence voltages at complete three-phase fixed sources. Balanced edits remain supported, and the FBS reader keeps its separate mapping. This is an explicit profile restriction, not a numerical correction or tolerance change. Broader format compatibility remains unfinished.

GridLAB-D object latitude and longitude map to the network’s typed component_locations table. Each point identifies its component table and exact name, with optional latitude, longitude, datum and point origin. Missing axes are distinct from zero; an absent datum stays unknown. This geography is independent of legacy bus drawing positions and line routes. The current GLM mapping covers root buses, parented loads, lines, fixed switch groups and used line configurations. Coordinates on a parented node/meter without a mapped device, unused equipment or source-only instrumentation still require additional attachment support and are refused explicitly.

Fresh and edited GLM emission uses current typed points. Declared link locations remain distinct from the endpoint midpoints the engines calculate at startup; neither establishes a line route or electrical length. GLM cannot declare a datum or point origin, so writing those fields reports their loss without transforming the numeric angles. Other exchange writers and the legacy GeoLayer extraction report omitted component geography. Cross-format coordinate mapping and dedicated binding accessors remain unfinished.

Networks without component geography keep their existing IR body. A network with points uses the additive nested "powerio.LocatedMulticonductorNetwork" record; the electrical network inside it retains the legacy layout. Older IR readers reject this new record instead of silently losing locations. Rust accessors borrow the typed table; edits copy shared network tables only on the first write. IR preserves these points in calculation and collection modules as well as standalone networks.

Neutral reduction and LinDist3Flow preparation validate point attachments on entry and exit. A replacement line, shunt or generator keeps the original device’s point, including partial axes, datum and origin. A split line configuration copies its point to each derived configuration. When a component is removed, its complete point stays in the corresponding action’s details.source_location; it is no longer an attachment in the output network. These actions are also retained in the network’s transformation metadata for IR storage. Point metadata never changes the transformation’s electrical data. When a later transformation replaces a stored audit, the previous record moves to the flat powerio_transform_history array in network metadata. Each entry has metadata_key and record; the established metadata keys still expose the latest audits. Identical records are not archived again. The archive is bounded at the module-history limit, and malformed or full archives cause an explicit error before replacing a record. Returned reports describe only the current call, while IR retains both current and archived records.

The GridLAB-D oracle harness documents pinned engines, supported physics, canonical and project checks, and remaining limitations.

BMOPF schema

There is one BMOPF. PowerIO reads and writes the schema proposed in dsopt-schema#2, subject to Task Force ratification. No PowerIO format token, option, or type names a BMOPF version. Producer provenance records the proposal revision and schema digest.

A document from an older BMOPF draft is read as BMOPF and reported once with READ.BMOPF.SCHEMA_LEGACY; the older drafts include the bmopf-report drafts and the early draft PowerIO 0.11 wrote. The reader accepts the older layouts (tables and transformer fields under extras, the tap and cost spellings, v_min/v_max, vn_max, the extras.geojson layer). A bmopf-json emission preserves an unchanged source byte for byte only when that source states the current schema; an older document is written in the current schema:

powerio convert legacy.json --to bmopf-json -o feeder.json

bmopf-json is the one BMOPF format string; a bmopf-json@<version> string is refused. It works with Rust powerio::emit, Python powerio.emit, C pio_emit, Julia emit and the PowerIO MCP emission tool. Rust also exposes BmopfEmitOptions for the distribution writer.

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, PowerIO 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. In the document the phase to ground bound is vpg_min/vpg_max, and the schema rejects the older spelling v_min/v_max; the neutral to ground cap is vng_max, vn_max in older drafts. Output writes vpg_* and vng_max; the reader takes either spelling, and a current document that uses an old name gets one READ.BMOPF.SCHEMA_LEGACY. PMD voltage arrays instead follow terminal order and use engineering voltage units.

The schema also declares geometry: bus.*.geo (GeoJSON Point), line.*.geo (GeoJSON LineString) and meta.crs, and a geo on every other located element. Output writes bus locations and line routes there, and component locations as the geo Point of the element they attach to. The extras.geojson FeatureCollection PowerIO 0.11 wrote still reads. See Geo and display.

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.

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 two-winding WYE transformers with grounded or explicitly floating neutral terminals. Each phase constrains (Vp - Vpn) = ratio * (Vs - Vsn); the transpose supplies both phase and neutral currents to nodal balance. Fixed taps enter the ratio. A one-terminal single-phase winding keeps its implicit-ground meaning; otherwise the final terminal is the neutral, and only an explicit ground or closed grounding switch grounds it. The builder rejects leakage, other winding connections, winding-neutral impedance parameters requiring an additional circuit, core shunts and tap-control decisions. Malformed winding maps and invalid ratios fail instead of producing an incomplete matrix.

The BMOPF proposal schema is pinned to 6796394, with SHA-256 9c9217afe0a62af77506f7d6ce6e0726d03f338f164a1621a7631cb03c638bdc, the revision that reconciled the proposal with the Task Force’s schema (vpg_* bounds, typed geometry, one identifier) and applied the Task Force review answers (vng_max, geometry for every located element), the review fixes, and the identity and consistency changes. The pin moves to the release tag the schema’s $id names once the Task Force ratifies the proposal. Output states only meta.schema_version, which the schema requires as the document’s one version identifier, and no meta.$schema: a URL per release made every patch release reject every earlier document, and consumers had to allow-list producer archive URLs (BMOPFTools #487). Output records the schema’s $id, the proposal commit, the schema digest, and the retrieval permalink of the exact bytes under meta.provenance.powerio_bmopf. Existing provenance is preserved; a name collision uses a numbered producer entry. Reading the PowerIO archive URLs that 0.11 stamped, the dsopt-schema commit permalinks, and the version-directory identifiers remains supported without fetching remote data.

The schema ships in the Rust crate at schemas/bmopf/bmopf.schema.json, in the Python package at powerio/schemas/bmopf/, and in each C/Julia library archive at schemas/bmopf/. The manifest records the exact bytes and upstream review references. Older drafts’ schemas are not shipped. Python can read them with importlib.resources.files("powerio"). Upstream review changes do not alter an installed release’s schema. A new schema interpretation requires a reviewed PowerIO release; a PowerIO release does not establish Task Force acceptance.

Energy prices

BMOPF 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 PowerIO 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; output always writes energy_cost_rate. PowerIO stores the coefficients; the selected solver determines whether and how they enter its objective.

LinDist3Flow bindings

Python and Julia expose LinDist3FlowOpfInstance and LinDist3FlowOpfSolution as typed module values. Rust and Python also expose the distinct fixed-dispatch LinDist3FlowPfInstance and LinDist3FlowPfSolution types. to_lindist3flow_opf_instance constructs an instance from a supported phase-only network or multiconductor AC OPF instance. instance.metadata supplies the node and conductor axes, roots, and fixed reference voltages. It also reports whether the retained conductor graph is meshed. Line powers follow the reported parent-to-child direction. Python positions are zero based; Julia positions are one based.

Cycles and parallel lines remain in the LinDist3Flow equations. PowerIO emits BUILD.LINDIST3FLOW.MESH_APPROXIMATION for such an instance because it does not add angle recovery, loop-consistency equations, circulating-flow regularisation, or automatic radialisation. Mesh feasibility therefore means feasibility of this declared linear approximation, not AC feasibility or a unique physical allocation of branch flows.

LinDist3FlowBuildOptions::unsupported selects the component-preparation policy. Reject keeps the strict boundary. Lower applies audited static neutral, switch, line-shunt and capacitor transformations. Approximate also linearizes supported load models and maps IBRs to static generators while freezing named controls. Bounded ZIP, exponential and constant-power laws can be projected only when nominal voltage lies strictly inside a smooth law region, above dropout and below any current-limiting transition. The action retains the original source_voltage_model and its bounds; strict preparation keeps the complete piecewise law. The source network is not mutated. Permissive can additionally omit retained untyped records. instance.source_network() remains the caller’s input, instance.network() is the prepared calculation network, and instance.preparation() records every action. The serialized instance stores the source network and reconstructs the preparation report on read.

Solutions expose their instance, termination, objective, and named primal columns: terminal_voltage_magnitude_squared, line_active_power, line_reactive_power, generator_active_power, generator_reactive_power, source_active_power, and source_reactive_power. Voltage values use squared volts and power values use watts or vars. Node and line columns follow the metadata axes; generator and source columns follow network table order, then channel order. Each returned column is an independent copy.

to_lindist3flow_pf_instance requires finite prescribed generator/IBR P/Q (or equal lower and upper bounds), clears the objective, and removes conductor limits from the conic constraint set. After a converged solve, evaluate_lindist3flow_pf_limits reports retained line apparent-power and both-end current ratings in VA or A, including loading ratios and overload flags. These checks explicitly state constraint_enforced = false. Transformer/regulator lowering and their thermal checks remain unsupported; the preparation report records any selected omission rather than presenting an incomplete report as comprehensive.

The C ABI adds pio_value_lindist3flow_opf_instance, pio_value_lindist3flow_opf_solution, and pio_module_to_lindist3flow_opf_instance. The generic calculation accessors read the instance, network, objective, constraints, termination, and solution columns. pio_lindist3flow_opf_instance_node_at and pio_lindist3flow_opf_instance_conductor_at return borrowed typed axis views. Their strings stay valid while the instance handle remains alive. Sparse conic preparation and solver adapters remain Rust APIs. The fixed-dispatch types add no C ABI symbols; they remain available through Rust, Python, and PowerIO IR until a future C ABI revision can add a fixed symbol set deliberately.

PowerIO 0.11.1 added the OPF pair to PowerIO IR, and 0.11.4 added the fixed-dispatch pair. Readers without those structural types reject them, while existing network and calculation records keep their representation.

Solver adapters, including Tellegen

A solver adapter can retain PowerIO’s typed module throughout parsing, projection, calculation, and result storage:

  1. Parse a MulticonductorNetwork module and apply explicit neutral Kron projection when needed. Keep the projection report and reject unsupported equipment through the instance constructor’s diagnostics.
  2. Construct LinDist3FlowOpfInstance and call powerio_matrix::build_lindist3flow_standard_form(instance.value()). The result supplies CSC matrices p and a, vectors q and b, and ordered zero, nonnegative, and second-order cone blocks for min 1/2 x' P x + q' x subject to A x + s = b, s in K.
  3. Map those blocks to the selected conic solver. Keep row_origins, canonical.variables, and the instance’s node and conductor identities for diagnostics and result display. Default solver coordinates use a 1 MVA per-unit base; the explicit options also support SI coordinates.
  4. Decode the primal vector with lindist3flow_values_from_standard_primal, then construct LinDist3FlowOpfSolution with the retained instance, termination, decoded values, and objective. Store the result in a module and call powerio::serialize for IR 2 output.

For fixed dispatch, use build_lindist3flow_pf_standard_form, decode with lindist3flow_pf_values_from_standard_primal, and construct a LinDist3FlowPfSolution. Its constructor evaluates retained ratings after a converged result; evaluate_lindist3flow_pf_limits exposes the same report for preview. The compiled objective is identically zero; line thermal cones are intentionally omitted.

Tellegen can reuse this Rust boundary for native and WebAssembly adapters. The remaining consumer work is solver dispatch, capability checks, and presentation of the supported distribution results. Parsing, neutral projection, electrical coefficients, physical axes, and primal scaling stay in PowerIO. The LinDist3Flow OPF types require PowerIO 0.11.1 and the fixed-dispatch types 0.11.4; existing saved IR 2 networks require no format migration.

Electrical readiness before analysis

Parsing, preservation and numerical readiness are separate results. powerio_dist::audit_electrical_readiness reports structural blockers and source defaults. require_electrical_readiness rejects the first blocker. Multiconductor calculation-instance constructors and admittance assembly call that check before numerical use.

OpenDSS line geometry

The dss reader calculates conductor impedances from OpenDSS geometry, spacing, wires, cncables and tscables with the pinned engine’s line constants: overhead conductors, concentric-neutral cables (CNData) and tape-shielded cables (TSData), under the earth model and resistivity the source states. A line whose geometry falls outside that calculation, for example one mixing CNData and TSData cables, is retained as an untyped source object and reported as READ.DSS.GEOMETRY_UNRESOLVED with error severity, naming the reason. The reader creates neither a typed line nor a synthetic linecode or terminal map for that object.

The original, unmodified source module can still emit its exact source bytes. IR retains the untyped object, but canonical OpenDSS, PMD and BMOPF conversion reject unresolved geometry because they cannot reconstruct its electrical meaning. Retain the source module or provide explicit conductor impedances before requesting those conversions. Numerical calculations reject both these untyped records and geometry-dependent typed lines from earlier IR documents.

This intentionally rejects calculations and canonical conversions that could otherwise use incomplete electrical data. It does not infer conductor count from a phase count. Explicit linecode data without geometry-dependent properties remains eligible when the remaining checks pass.

Distribution CIM segments without impedance

A CIM ACLineSegment whose impedance the reader cannot read, for example one on a WireSpacingInfo with a position no ACLineSegmentPhase names a wire for, parses with a zero placeholder line code and an error finding, READ.CIM_DIST.IMPEDANCE_UNRESOLVED. The audit blocks it as READINESS.CIM_DIST.IMPEDANCE_UNRESOLVED, because the placeholder would be a short circuit between its buses. Numerical calculations and conversion to another format reject it, as they reject an OpenDSS geometry line, and a same format write of a single source document still returns its bytes.

MG-RAVENS equipment the reader cannot type

The MG-RAVENS reader keeps an in-service ACLineSegment, Switch, TransformerTank or EnergyConsumer it cannot type (an incomplete wire catalog, fewer than two terminals, a tank without a datasheet or with phase clocks neither leadlag convention represents, an unresolvable delta load) as an untyped object, with a READ.RAVENS_DIST.RETAINED_SOURCE_ONLY warning naming the reason. It round trips to MG-RAVENS. The audit blocks it as READINESS.RAVENS_DIST.EQUIPMENT_UNRESOLVED, so numerical calculations and conversion to another format refuse it instead of writing a feeder with the equipment missing. Out-of-service equipment is retained the same way but not blocked, since it contributes no network equation.

Other structural checks

The audit checks source-specific identifier equality, unresolved line endpoints and linecodes, terminal references, line lengths, conductor counts, matrix shapes and finite matrix entries. It reports source defaults as warnings.

let readiness = powerio_dist::audit_electrical_readiness(network);
for finding in readiness.findings {
    eprintln!("{} {}: {}", finding.code, finding.element, finding.message);
}
powerio_dist::require_electrical_readiness(network)?;

A passing audit establishes only these structural properties. The selected calculation still checks its support for transformer connections, controls, loads and other required physics. PowerIO preserves data that a particular calculation may not support.

PSS SINCAL

SINCAL is one native project format capable of holding both balanced and conductor-resolved networks. Select the electrical profile explicitly. The current balanced reader produces the existing BalancedNetwork; it does not infer balance from equal phase values or automatically reduce unbalanced data. The explicit multiconductor profile produces MulticonductorNetwork through powerio-tnd; neither profile silently retries the other family.

Build feature

Both readers, the byte-exact native echo and the experimental writer are the sincal cargo feature of powerio-tnd, enabled by default by powerio, so the CLI, the Python wheel, the C ABI and the browser converter include them. The feature brings in SQLite through powerio-tnd, which a wasm32-unknown-unknown build compiles only with a C compiler that has a WebAssembly backend. A facade built with default-features = false needs no C compiler: grid_formats lists no SINCAL format, ParseOptions and EmitOptions have no SINCAL field, and a SINCAL source or target fails with REQUEST.SINCAL.FEATURE_DISABLED (REQUEST.DIST_FORMAT.SINCAL_FEATURE_DISABLED from powerio-dist used directly). resolve_format still describes the tokens, because format metadata is not a build probe.

Balanced reader

The sincal-balanced input token selects positive-sequence load flow. The current profile accepts native SQLite schemas 14.8, 15.5 and 16.0 and .sinx archives, with one base variant. Rust also accepts explicitly acquired schema-11.5 Access records and selected absolute daily snapshots, as described below. It covers buses, positive-sequence lines, static loads, external sources, converter injections and two-winding transformers with fixed common taps, plus fixed capacitor banks. Ideal external sources support absolute and relative source/terminal voltage prescriptions and voltage-only limits. Open terminals and inactive equipment remain in the network. Unknown required modes fail with table, native record ID and field context.

let options = powerio::ParseOptions::default().format("sincal-balanced")?;
let module = powerio::parse_with_options("case.sinx", &options)?;
assert!(matches!(module.value(), powerio::PioValue::BalancedNetwork(_)));
powerio::emit(&module, "matpower", "case.m")?;
Ok::<(), Box<dyn std::error::Error>>(())
powerio summary case.sinx --from sincal-balanced
powerio convert case.sinx --from sincal-balanced --to matpower -o case.m
powerio serialize case.sinx --from sincal-balanced -o case.pio.json

Python uses powerio.parse(path, format="sincal-balanced"). The C ABI uses the existing pio_parse format argument and pio_value_balanced_network typed accessor. No new network type or binding ABI is introduced.

Bare sincal and an undeclared .sinx require profile selection. Explicit selection does not authorize discarding incompatible phase-resolved data: unsupported terminal or load modes are errors, with no fallback to another family. The native model’s source-format identity is sincal; the retained source records the selected input profile as sincal-balanced.

Multiconductor reader

Use sincal-multiconductor to select the conductor-resolved reader. A symmetric operating point still produces MulticonductorNetwork. The verified electrical profiles include schema-14.8/15.0 native SQLite/archive inputs and schema-11.5/12.8 Access acquisition records. Shared structural admission of other versions does not imply their electrical support. Unsupported equipment or missing required sequence data rejects the complete parse; no partial feeder is returned. The documented global Flag_LFZ0=2 missing-zero-sequence policy is supported for three-phase sequence lines and the verified ideal-source profile. Explicit zero-sequence inputs retain precedence; applied defaults are recorded. This does not enable missing-data supplementation for transformers or finite sources. Nominal delta–delta transformers support one, two or three installed coils, including reversed polarity and open terminals. Winding selectors expand to actual phase pairs; no unused phase is invented. Partial mixed-winding transformers and inconsistent native core-loss inputs still reject.

powerio summary case.db --from sincal-multiconductor
powerio convert case.db --from sincal-multiconductor --to pmd-json -o case.json
powerio convert case.db --from sincal-multiconductor --to sincal-multiconductor -o copy.db

Python’s existing parse(..., format="sincal-multiconductor") and the C ABI’s existing pio_parse route native SQLite/archive inputs to their established multiconductor typed accessors. No ABI entry point or network family is added.

The Rust facade exposes explicit variant/snapshot/acquisition selection through ParseOptions.sincal_multiconductor. Python uses dist.SincalReadOptions, and the CLI exposes the same selections on summary, convert and serialize. Access parsing requires the original MDB plus the optional helper’s acquired tables, supplied as a relative source companion. Parsing does not run MDB Tools. The recorded original length and SHA-256 must match the MDB; this catches mismatched input files, but is not an attestation that caller-supplied table contents are authentic.

let mut selection = powerio::dist::SincalReadOptions::default();
selection.variant = Some(1);
selection.snapshot_hours = Some(12.0);
selection.acquired_tables = Some("acquired.json".into());
let mut options = powerio::ParseOptions::default().format("sincal-multiconductor")?;
options.sincal_multiconductor = Some(selection);
let module = powerio::parse_with_options("project/original.mdb", &options)?;
assert!(matches!(module.value(), powerio::PioValue::MulticonductorNetwork(_)));
Ok::<(), Box<dyn std::error::Error>>(())

Create project/acquired.json with evals/sincal/import_access.py. In-memory sources supply the companion with Source::with_named_buffer; file companions stay under the source’s acquisition root. For example:

import powerio
from powerio.dist import SincalReadOptions

module = powerio.parse(
    "project/original.mdb", format="sincal-multiconductor",
    sincal_multiconductor=SincalReadOptions(
        variant=1, snapshot_hours=12, acquired_tables="acquired.json"),
)
powerio summary project/original.mdb --from sincal-multiconductor \
  --sincal-variant 1 --sincal-snapshot-hours 12 \
  --sincal-acquired-tables acquired.json

Python memory inputs supply named_buffers={"acquired.json": records_bytes}. They never read companions from disk. File inputs may explicitly widen the root with acquisition_root=... in Python or --acquisition-root in the CLI; the root must contain the primary and referenced files. The normal root is the primary file’s parent directory. Julia uses the same keywords with its exported SincalReadOptions:

using PowerIO
module_ = parse("project/original.mdb"; format="sincal-multiconductor",
    sincal_multiconductor=SincalReadOptions(
        variant=1, snapshot_hours=12, acquired_tables="acquired.json"))

Julia memory/IO inputs take named_buffers=Dict("acquired.json" => records_bytes). C uses pio_parse_with_options with borrowed PioParseOptions and PioSincalReadOptions; zero initialization leaves optional values absent, and presence flags distinguish an omitted snapshot from explicit midnight. The existing pio_parse remains unchanged. For memory inputs, pio_source_from_memory_with_buffers copies the primary and named companions before returning; caller buffers may then be released. These additions require the matching development library and Julia companion. Existing C ABI layouts and typed network accessors are unchanged.

Legacy UI-manipulator references on loads retain their IDs as provenance. Their edits are already stored in the load input fields, so stored power factors apply once; the UI definition is not evaluated again. This follows Siemens Release Notes 21.0, pp. 4–6. Conflicting daily timestamps remain errors.

Active daily profiles require an explicit snapshot; no midnight default is assumed. In schema 11.5, absolute P/Q profiles replace aggregate powers, while common relative-factor profiles scale the defined powers, preserving unequal Wye or delta branches and their voltage dependence. Relative profiles currently require the documented direct-scaling coefficient settings: Power_a1=0, Power_b1=0, Reduce_a2=0, Reduce_b2=1. They accept finite nonnegative factors, linear or step interpolation and cyclic repetition. Separate P/Q-factor modes, topology-dependent coincidence and absolute-profile allocation to unequal branches remain unsupported. Generic time-series and inherited variants remain under development.

Schema-11.5 NULL transformer tap status uses the documented fixed-status default and records that interpretation. Active controllers and unresolved partial mixed-winding circuits still reject; the default does not supply missing physics.

Fixed reactor and capacitor banks retain their phase connections, losses, grounding and open/inactive states as typed shunts and switches. Supported three-phase grounded banks retain separate positive- and zero-sequence inputs. Explicit neutral impedances, automatic regulators and stepped direct zero-sequence impedances still require additional mapping. Documented optional schema-11.5 defaults are recorded; required ratings are never filled in. The Access acquisition helper includes both bank tables by default. For schema 11.5, a NULL voltage-level line/cable temperature uses its documented 20 C default. The selected field is recorded in network.defaulted; explicit temperatures retain their correction, and missing columns or modern NULLs fail. The same legacy profile admits documented defaults for optional line flags, dielectric losses, parallel counts, rating factors, rated frequency and active temperature coefficients. Required impedances and sequence declarations remain strict. Ideal connections record their applied defaults as well.

Every SINCAL parse shares a fixed budget of SQLite work. Both readers read terminals once per parse and group them by element, so the work per element does not grow with the size of the terminal table: a native-width feeder with 1,000 lines reads within the budget. A project that does exceed it fails with a message saying it exceeds the reader’s bounded query work, never with partial output.

Access MDB inputs use the core primary-file limit, which defaults to 1 GiB; POWERIO_MAX_PRIMARY_BYTES can set an explicit bound. CSIRO09 is 69,181,440 bytes, and its validation uses that exact, tighter bound. Native SQLite/.sinx acquisition and acquired table documents retain their separate fixed 64 MiB limits. These are distinct limits; the library does not silently raise them.

Fidelity and output

In the balanced profile, native physical quantities use a declared 100 MVA internal conversion base. The multiconductor model uses its usual SI units. Both readers correct cable resistance for the voltage-level temperature in every schema. The balanced reader refuses a line built from LineSeg sections, as the multiconductor reader does. Both readers apply Line.fr as a factor on the thermal current Ith: the line’s current limit is Ith * ParSys * fr, and fr does not change its impedance. Disabled native generator capability limits become unbounded typed limits, not zero capability. Diagnostics identify this and data outside the chosen snapshot. Disabled modern profile references do not replace static powers. Active profiles require a supported adapter and explicit snapshot selection; currently only the declared schema-11.5 absolute daily profile is accepted. Fault, dynamic, protection, economic, untyped diagram and stored-result data remain in the retained source. Selected drawing coordinates are typed as described below. Cross-format output reports their omission.

An unchanged module can emit sincal or its matching explicit profile token to reproduce its primary native bytes exactly. A SQLite input echoes SQLite bytes; an archive echoes archive bytes; an explicitly acquired Access case echoes the original MDB, never the intermediate tables. An explicit output profile for the other network family is refused. Use an appropriate destination filename:

powerio convert case.sinx --from sincal-balanced --to sincal-balanced -o copy.sinx

This is source echo, not a fresh writer: format metadata reports can_emit=false. Editing the value removes its retained native source. PowerIO IR retains typed values and provenance, not the original native project bytes. Edited, constructed and IR-restored modules therefore refuse native output through ordinary emit. Fresh writing requires the explicit experimental option below.

Access/MDB acquisition currently uses the explicit optional helper under evals/sincal; ordinary library parsing never starts external programs. Its internal typed records are not native SQLite output. The Rust balanced selection API accepts them as a companion to their original MDB.

Experimental fresh writer (Rust)

emit_with_options accepts an explicit sincal_experimental request. It always writes the current typed value, even when an unchanged module retains native source bytes. The result has Fidelity::Canonical, experimental warnings and loss diagnostics. Default options are equivalent to ordinary emit, including byte-exact echo. Unsupported physics or packaging errors produce no partial file, and existing destination files are not overwritten.

let module = powerio::parse_with_options(
    "case.sinx", &powerio::ParseOptions::default().format("sincal-balanced")?,
)?;
let mut request = powerio::SincalExperimentalOptions::default();
request.container =
    powerio::SincalContainer::archive_with("converted", powerio::ArchiveOptions::default());
let mut options = powerio::EmitOptions::default();
options.sincal_experimental = Some(request);
let result = powerio::emit_with_options(&module, "sincal", &options, "fresh.sinx")?;
assert_eq!(result.fidelity(), powerio::Fidelity::Canonical);
for diagnostic in result.diagnostics() {
    eprintln!("{}: {}", diagnostic.code(), diagnostic.message());
}
Ok::<(), Box<dyn std::error::Error>>(())

SincalContainer::Sqlite (the default) produces a single SQLite database. SincalContainer::archive_with produces deterministic candidate .sinx packaging containing that database and manifests. ArchiveOptions has no fields yet; it starts from Default so packaging options can be added later without breaking callers. The struct variant SincalContainer::Archive { project_name } is kept for compatibility and packages the same bytes. The project name accepts 1–128 ASCII letters, digits, underscores or hyphens. The destination filename does not select the container. Neither path writes an Access database, desktop .sin file, diagrams or results. Native SINCAL open/save/calculation remains an external acceptance gate.

The module’s existing electrical type selects the backend. BalancedNetwork uses the transmission writer. MulticonductorNetwork uses the distribution writer and requires request.nominal_ll_volts: a map from every typed bus ID to a finite positive line-line voltage in volts. Transformer auxiliary buses that are eliminated during primitive reconstruction span two voltage levels; their entries may be omitted. No source voltage, bound or metadata value is silently interpreted as bus nominal voltage. A balanced network rejects this map. Explicit sincal-balanced and sincal-multiconductor targets reject a value from the other family; the bare sincal target uses the typed family. Neither electrical family is transformed implicitly or retried through the other backend.

The initial balanced subset covers ideal reference sources, fixed PQ injections, static loads, same-voltage lines and fixed two-winding transformers. The multiconductor subset covers ideal positive-sequence sources with grounded or isolated floating reference, unequal phase and phase-pair static loads, sequence-representable lines and finite DD or solid DY/YD transformers with fixed taps. Supported native transformer primitives can be rewritten from their actual conductor matrices, including after IR restoration and compatible edits. Reconstruction reports its canonical nameplate parameter base explicitly. External neutral circuits, other transformer/core modes, general shunts, controls and profiles are not yet covered by this writer subset.

Open switches on canonical phase selections retain separate endpoints and explicit open native terminal states. Optional uniform ampacities are preserved. Native readback may introduce auxiliary buses and ideal connections; closed-switch collapse can omit those connections’ ratings on a subsequent fresh write, with loss diagnostics. Neutral switching, conductor permutations and nonuniform switch ratings remain unsupported.

This opt-in is currently exposed by the Rust facade. CLI, Python and C emission continue to use their existing ordinary emission path. can_emit remains false because the experimental subset is not a universal native writer. Fresh multiconductor output is verified through the public reader described above. Neither internal readback nor independent electrical validation establishes native SINCAL desktop acceptance.

Validation

The reader maps all 15 nodes and 32 equipment records of the small licensed SimBench native case. Rust tests cover malformed/unsupported input, service states, open terminals, typed routing, binary echo and IR behavior. The evals/sincal/check_balanced_simbench.py harness checks actual Rust output against paired publisher CSV inputs and a fresh pandapower 3.5.6 calculation, including derived nonzero taps on either winding. Stored native results are separate evidence; no SINCAL desktop execution has been performed.

Three external cases also map completely: IEEE18 (18 native nodes, 44 elements), IEEE33 (33 nodes, 67 elements), and the student study (40 nodes, 84 elements). Their fresh independent pandapower comparisons agree within 4.5e-12 pu in complex bus voltage. The student file’s saved static load powers are zero with profiles disabled; its historical profile results are not the state parsed here. The external validation report records this distinction. No external native model files are vendored.

Additional schemas, active profiles, variants and corpus cases remain under development. Native fixtures require redistribution rights; external research models are not silently copied into the test suite.

The public multiconductor facade maps all 688 CSIRO09 elements at five selected daily snapshots. Its original powers are symmetric; five separately labelled unequal-delta-branch stress cases exercise asymmetric behavior. Independent OpenDSS comparisons cover every phase at 617 energized native nodes and four isolated nodes, with maximum voltage difference below 0.000372 V. The finite OpenDSS source approximation is checked separately. The same public path checks original MDB echo and IR value preservation; see evals/sincal/csiro09-public.json. A second published native case, Truong’s schema-15.0 12-bus model, maps all 45 elements, including 33 unequal single-phase loads. Independent OpenDSS comparisons cover all 36 phase voltages and 66 line-terminal currents/powers; maximum voltage error is below 0.000006 V. Native source echo, IR, generic matrix and PF-instance checks also pass; see evals/sincal/truong12-public.json. Its source has no redistribution license and remains external. These are two complete conductor-resolved cases, not complete corpus coverage or native SINCAL desktop acceptance. The 12-bus case does not close the larger-case review gate.

Explicit balanced Access snapshots

The balanced reader also accepts schema-11.5 Access acquisition records through powerio_tnd::formats::sincal::SincalBalancedReadOptions, carried by powerio::ParseOptions::sincal_balanced. Select sincal-balanced explicitly, set variant and snapshot_hours when required, and set acquired_tables to the relative companion containing import_access.py output. Memory sources attach that companion with Source::with_named_buffer; file sources use the acquisition root. Parsing verifies the original MDB header, byte count and SHA-256 against those records and never invokes MDB Tools. Include NetworkGroup and NetworkGroupTrans in acquisition so balanced interchange controls are checked.

CSIRO19 is checked at seven daily snapshots through this public path. Profiles currently admit absolute daily P/Q with linear or stepped interpolation. Modern active profiles, inherited variants and other profile modes still reject. Legacy voltage/temperature defaults are narrowly scoped and retained in component metadata. The CLI uses the same selection flags for either explicit family:

powerio serialize original.mdb --from sincal-balanced --sincal-variant 1 \
  --sincal-snapshot-hours 6 --sincal-acquired-tables acquired.json

The acquired companion must be beneath the source directory or the explicitly selected --acquisition-root. Unknown or missing profiles never trigger a balanced/multiconductor fallback. Python exposes SincalBalancedReadOptions through parse(..., sincal_balanced=...); Julia uses the same type and keyword. C uses PioSincalBalancedReadOptions through PioParseOptions.sincal_balanced. The separate distribution selection type remains SincalReadOptions.

import powerio as pio

module = pio.parse("project/original.mdb", format="sincal-balanced",
    sincal_balanced=pio.SincalBalancedReadOptions(
        variant=1, snapshot_hours=12, acquired_tables="acquired.json"))
pio.serialize(module, "case.pio.json")

Experimental legacy source-control compatibility

Rust SincalReadOptions.assume_inactive_source_controls = true and the CLI --sincal-assume-inactive-source-controls allow schema-11.5 NULL values in Infeeder.Flag_LfLimit, Flag_LfCtrl, Flag_Qctrl, Flag_Macro and Kr to be interpreted as zero/inactive. The default remains strict. Python and Julia expose the same boolean on SincalReadOptions; C exposes it on PioSincalReadOptions. It is unavailable on balanced reader options. Active controls, missing columns and missing electrical parameters still reject.

powerio summary project/original.mdb --from sincal-multiconductor \
  --sincal-acquired-tables acquired.json --sincal-variant 1 \
  --sincal-snapshot-hours 12 --sincal-assume-inactive-source-controls

An applied assumption emits READ.DIST.SINCAL_ASSUMED_INACTIVE_SOURCE_CONTROLS. The affected component and fields survive IR serialization in extras.sincal_compatibility_assumptions. Original MDB echo remains byte exact. These assumptions admit the complete CSIRO12 feeder, with independent OpenDSS checks, but do not establish what native SINCAL does with these NULLs.

Native node records with no declared equipment conductors are retained in extras.sincal_unconnected_nodes, with READ.DIST.SINCAL_UNCONNECTED_NODES, instead of inventing phases. Nodes attached to open or inactive equipment remain electrical buses; unsourced islands still require explicit downstream handling.

Fidelity findings and working trial routes

Both readers report source-only tables with row counts and an explicit scope (selected native variant or all rows). Enumerated source-only harmonic and reliability fields are named separately; this is not an exhaustive field-level schema audit. Access tables excluded during acquisition have unknown counts, reported as such. Findings have structured diagnostic details, survive IR, and are attached to ordinary cross-format loss warnings. The inventory is a parse-time description, not a copy of the native payload.

Balanced schema defaults identify affected components and values. Distribution defaults identify components and fields in sincal_defaulted_fields extras; experimental assumptions remain separately identified. Retained native bytes are absent from IR, and neither IR nor edited values can recreate native echo.

The installed-wheel trial harness evals/sincal/check_trial_workflows.py checks these public paths on external models. All four cases preserve original source echo and typed IR. Matrix and numerical evidence is in the separate case-specific Rust/oracle harnesses.

Case / selected profilePF instance preparationOrdinary target emission and reparse
CSIRO19 / balanced, noon snapshotPassMATPOWER pass, with loss diagnostics
Truong12 / multiconductorPassDSS, PMD JSON and BMOPF JSON pass, with loss diagnostics
CSIRO09 / multiconductor, noon snapshotRefused: unsourced native islandsRefused: reference-terminal voltage sources
CSIRO12 / multiconductor, noon snapshot, compatibility opt-inPassRefused: reference-terminal voltage sources

Emission/reparse here establishes a usable format path, not numerical equality of the exported target. The OpenDSS numerical oracles independently construct circuits from native SINCAL fields; they do not validate PowerIO’s target exports. PF preparation constructs a calculation instance; PowerIO does not solve it.

For distribution Access cases, keep the original and acquired records together:

import powerio as pio

module = pio.parse("project/original.mdb", format="sincal-multiconductor",
    sincal_multiconductor=pio.dist.SincalReadOptions(
        variant=1, snapshot_hours=12, acquired_tables="acquired.json",
        assume_inactive_source_controls=True))  # CSIRO12 only; inspect diagnostics
print(pio.diagnostic_records(module.diagnostics))
pio.serialize(module, "case.pio.json")
instance = module.to_mc_ac_pf_instance()  # CSIRO12 succeeds; CSIRO09 rejects islands

CSIRO09’s primary file is 69,181,440 bytes. The checked command sets POWERIO_MAX_PRIMARY_BYTES=69181440 explicitly; the default input limit remains unchanged. The native models stay external, subject to their own data rights.

Drawing coordinates and line routes

Both reader families populate the existing bus-location and line-route fields from native graphic tables. A declared schematic view (GraphicAreaTile.Flag=2) uses Diagram space; other views remain Unknown. This profile does not infer WGS84, a projected CRS, or the meaning of Node.lat/lon and Node.hr/hh. Use them as native layouts unless you independently establish the coordinate reference system.

A point-shaped node keeps its source point. An extended busbar uses a derived midpoint; extras.sincal_geometry preserves its two native endpoints. Lines use native terminal identities and attachment positions, with ordered bends on both ports (NoPoint=1..n), following the Siemens database-interface manual. Gaps, duplicate orders and collapsed routes are diagnosed and omitted. Conflicting drawings, invalid optional records and multiple areas do not change the electrical model. No position is fabricated for generated auxiliary buses.

SQLite databases and .sinx archives supply graphics directly. For Access, include optional graphics in the explicitly acquired companion:

python evals/sincal/import_access.py model.mdb acquired.json --include-graphics

Keep any additional electrical table selections your case already requires. Electrical-only companions still work; omitted graphics are reported. READ.SINCAL.GEOMETRY or READ.DIST.SINCAL_GEOMETRY reports the mapping counts, coordinate space and any omissions. View identity, origin, page dimensions, scales and optional CRS/reference fields are retained as native values in the module’s SINCAL view metadata extension and survive IR (the full extension key is documented in the implementation guide below). No origin or scale transform is applied; page centimetres do not define a metre-space canvas. Graphical style and artwork remain only in source. Unchanged native echo stays byte-exact; IR retains mapped geometry. Fresh experimental SINCAL output still omits it with a diagnostic.

Existing extraction paths work without new options or binding types:

powerio geo extract case.sinx --from sincal-balanced -o case.geo.json
powerio geo extract case.db --from sincal-multiconductor -o case.geo.json

For Access or another input requiring snapshot/compatibility selections, first serialize the selected module to IR, then extract that IR’s geometry. Canonical geo JSON carries Diagram or Unknown space; it is not an earth-referenced GIS layer. Full native view metadata is retained on the module and in IR, rather than on the extracted geometry layer. Rust uses BalancedNetwork::to_geo_layer() or powerio::dist_geo::to_dist_geo_layer(&network).

Validation covers SimBench, CSIRO09/12/19 and the externally held Truong model: 862 typed locations and 674 routes, including three native bends. All preserve electrical fields, native echo and IR. CSIRO12 retains its existing explicit compatibility assumptions. Additional shared-decoder checks cover CSIRO03 (774 routes, up to 40 vertices) and CSIRO13 (874 routes); these are geometry-only checks and do not claim complete electrical parsing of either case. See the implementation and evidence for case accounting and the deferred georeferencing and desktop acceptance gates.

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.

SourceParses to
PyPSA CSV directory, snapshot axis with varying inputsTimeSeries<BalancedNetwork>
PyPSA CSV directory, fixed network with electrical assignments per snapshotTimeSeries<OperatingPoint<BalancedNetwork>>
Egret JSON with system.time_keys in the scalar profileTimeSeries<BalancedNetwork>
GridFM Parquet dataset (the gridfm feature)ScenarioSet<BalancedNetwork>

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.

PyPSA lines-s_max_pu.csv and transformers-s_max_pu.csv set each snapshot’s thermal bound to s_nom * s_max_pu. Zero and positive infinity are preserved; the equipment’s status and transformer impedance base remain separate.

Egret electrical time series

Egret branch ratings use null (or an absent scalar field) for unlimited flow. Canonical output writes, for example, [null, 150.0] when PowerIO’s rate_a values are [Inf, 150.0]. This applies to long-term, short-term, and emergency ratings. A native Egret numeric zero imports as 0.0 and emits as zero, including inside a time series. The branch remains energized; its status is a separate field.

PowerIO 0.11.10 and earlier reject null inside rating time series. Upgrade those readers before reimporting corrected canonical output. Native Egret accepts these unlimited points.

Earlier PowerIO output could put numeric zero in mixed rating series. Regenerate those files from the original model. Change zero to null in an existing Egret file only after confirming that the source intended unlimited flow. An older PowerIO IR document that already converted a native Egret zero to unlimited has lost that distinction and must be regenerated from its original Egret input. The IR document version determines how old numeric zeros are read; current documents preserve zero and infinity as distinct bounds.

Egret system.time_keys and per-element data_type: "time_series" values parse into TimeSeries<BalancedNetwork>. Labels must be unique. A stated time_period_length_minutes must be finite and positive and is retained in each time point. Canonical Egret emission survives IR serialization and also accepts balanced operating-point series, including the supported PyPSA profile. It writes native branch results pf, qf, pt, qt in MW/MVAr, with each end’s injection sign. Partial DC-only results remain partial; missing reactive values are not invented.

The writer supports changing loads, dispatch and bounds, voltage states and bounds, shunts, branch ratings/taps/shifts/status, and complete branch flows. Topology, element identities and unsupported attributes must remain static, and all points must share one optional duration. Unsupported variation is refused, including a single-point series. This is an electrical snapshot profile, not Egret’s unit-commitment formulation: commitment, ramping, reserve and other intertemporal optimization semantics are not modeled. Selecting a snapshot can feed any compatible static writer; arbitrary temporal export to every format is not promised. Retained source bytes still provide exact same-format replay.

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 ten instance types, from DC power flow through AC optimal transmission switching, LinDist3Flow, and multiconductor AC OPF to AC security constrained unit commitment, and eleven 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
AcOtsInstance      AcOtsSolution
McAcPfInstance     McAcPfSolution
McAcOpfInstance    McAcOpfSolution
LinDist3FlowPfInstance   LinDist3FlowPfSolution
LinDist3FlowOpfInstance  LinDist3FlowOpfSolution
AcScucInstance     AcScucSolution

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

SourceParses to
DOE GO Challenge 3 problem fileAcScucInstance
that problem file beside its solution fileAcScucSolution
DeepMind OPFData JSONAcOpfSolution
BMOPF JSON or distribution CIMMulticonductorNetwork; construct the instance explicitly

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 tap_adjusted_series_susceptance, series_susceptance_no_phase_shift, series_susceptance, tap_adjusted_reactance, or reactance_only. Matrices and graphs defines the five conventions.

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. LinDist3Flow is an explicit exception to that general AC choice because its fixed-reference linear approximation, declared mesh limitations, and applicability decisions define the mathematical problem.

AcOtsInstance is an AC OPF whose branch statuses are decisions. It keeps every physical branch, takes the network’s in_service bits as the initial topology, and states which branches may switch, what opening or closing each one costs, budgets on open branches and on status changes, whether an island of the initial topology may split, and which branch current limits apply. to_ac_ots_instance builds the default from a network or an AC OPF: every initially in-service branch may switch, at zero cost. A solver chooses the final statuses; fix_ac_ots_topology derives the AC OPF to solve over them and reports what that problem leaves out, and ac_ots_solution attaches its solution after checking that it solves exactly that problem and that open branches carry no flow. The AC OTS solution keeps the instance’s network with the initial statuses; materialize_ac_ots_solution returns the network with the final statuses and solved values for emit.

LinDist3FlowPfInstance is the fixed-dispatch form: generator and IBR P/Q must be prescribed, its objective is zero, and retained line thermal limits are evaluated after convergence instead of constraining the solve. Its LinDist3FlowPfSolution carries those SI-valued monitored checks separately from solver feasibility.

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.

Explicit DC conventions

For an inductive branch let k = x/(r²+x²), τ be the effective tap (zero in source data means unity), and φ the phase shift in radians. From-end active power is:

TokenFlow
series_susceptance (unchanged default)k(θf−θt−φ)
series_susceptance_no_phase_shift (PowerModels DCP)k(θf−θt)
tap_adjusted_reactance (MATPOWER / PowerModels DCMP)(θf−θt−φ)/(xτ)
tap_adjusted_series_susceptance (ignore conductance)k(θf−θt−φ)/τ
reactance_only(θf−θt)/x

PowerModels DCP parity assumes the same branch orientation and impedance reference side. Its parser can reverse an antiparallel transformer, multiplying r and x by τ², replacing τ by 1/τ, and negating φ. The two tap-adjusted coefficients are invariant under this transformation; the three tap-ignoring coefficients change by 1/τ². PowerIO keeps the source orientation. Consequently, selecting the DCP token alone does not guarantee parity with a PowerModels-parsed file containing reversed off-nominal transformers.

The nodal balance in per unit is p_g,i − p_d,i − g_s,i = Σ_from(e)=i f_e − Σ_to(e)=i f_e, where each f_e includes its convention’s phase-shift term and g_s,i is the active shunt withdrawal at unit voltage. When fixed HVDC injections are present, add their net injection to the left-hand side.

The selected coefficient also scales the nodal phase injection. Thermal ratings keep their original units and values. These are lossless, cold-start models; none guarantees the closest AC result on every network. Matching an OPF benchmark also requires matching its costs, limits, shunts and reference buses. Older readers reject the new tokens instead of substituting another model.

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

matrixshapecalculationnotes
MATPOWER Bp (FDPF)\(n \times n\)calc_bprime_matrix-Im(Y_bus) after the makeB Bp edits
MATPOWER Bpp (FDPF)\(n \times n\)calc_bdoubleprime_matrix-Im(Y_bus) after the makeB Bpp edits
\(\Re(Y_{\mathrm{bus}})\), \(-\Im(Y_{\mathrm{bus}})\)\(n \times n\)calc_admittance_matrixfull admittance, keeps taps and shifts
LACPF (linear AC power flow) block\(2n \times 2n\)calc_lacpf_matrix\(\begin{bmatrix}G & -B \\ -B & -G\end{bmatrix}\), flat start, indefinite
PowerModels DC incidence \(A\)\(m \times n\)DcOperators::calc_incidence_matrixrow \(e\) has \(+1\) at the from bus, \(-1\) at the to bus
DC branch susceptances \(b\)\(m\)DcOperators::calc_branch_susceptancesone signed susceptance per in service branch
DC branch flow matrix \(B_f\)\(m \times n\)DcOperators::calc_branch_flow_matrix\(B_f = \operatorname{diag}(b)A\)
DC bus susceptance \(B\)\(n \times n\)DcOperators::calc_bus_susceptance_matrix\(B = A^\mathsf{T}\operatorname{diag}(b)A\)
DC branch phase shift injection\(m\)DcOperators::calc_branch_phase_shift_injection\(b .* shift\)
DC bus phase shift injection \(p_{shift}\)\(n\)DcOperators::calc_bus_phase_shift_injection\(p_{shift} = A^\mathsf{T}(b .* shift)\)
DC bus injection \(p_{bus}\)\(n\)DcOperators::calc_bus_injection_dc\(p_{bus} = -Bv_a + p_{shift}\)
weighted bus factor \(L\)\(n \times n\)calc_weighted_laplacian\(L = C \operatorname{diag}(w) C^\mathsf{T}\); internal solver data
solver branch flow matrix\(m \times n\)calc_solver_branch_flow_matrixpositive solver susceptance magnitudes times \(C^\mathsf{T}\); internal solver data
Per-island PTDFone matrix per componentcalc_ptdf_by_islandpartitions one global PTDF solve and returns source bus/branch index mappings
PTDF\(m \times n\)calc_ptdfroutes through Auto solver selection; calc_ptdf_lodf_with_options exposes the choice
LODF\(m \times m\)calc_lodfroutes through Auto solver selection; option based builds can prune small output entries
selected PTDF rows, PTDF columns, LODF columns\(k \times n\), \(m \times k\), \(m \times k\)calc_ptdf_rows, calc_ptdf_columns, calc_lodf_columnsone solve per requested row or column, in the order requested; the full matrices are never formed
AC power flow Jacobian\(2n \times 2n\)calc_power_flow_jacobianpolar or rectangular voltage coordinates
multiconductor admittanceconductor by conductorcalc_multiconductor_admittance_matrixfrom a MulticonductorNetwork; Rust only in 0.11
adjacency\(n \times n\)calc_adjacency_matrixsparse graph adjacency
graph edgesone per in-service branchIndexedNetwork::branch_edges(branch, from, to) over dense bus indices

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 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. With positive internal factor weights w = -b the grounded matrix L = -B is positive definite and the sparse path uses a Cholesky factorization. A negative weight, a series capacitor’s, can make it indefinite; the sparse path then uses LDLᵀ, and LU with partial pivoting when that fails, reported as the sparse_ldlt and sparse_lu solver paths. Each factorization must solve a probe right hand side with a normwise backward error below 1e-10 and a relative forward error below 1e-4; a matrix every factorization fails is refused as singular. Every connected component must contain at least one reference bus.

When only some branches or buses matter, calc_ptdf_rows(case, options, branches), calc_ptdf_columns(case, options, buses), and calc_lodf_columns(case, options, outaged) return just those rows or columns, indexed by dense branch and bus index in the order requested. They factor once and solve one right hand side per requested row or column, so a 100k bus case never forms its \(m \times n\) PTDF or \(m \times m\) LODF. 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.

Stated-state balance

A case saved from a converged power flow stores bus voltages that balance its injections. calc_stated_state_mismatch evaluates every bus’s AC balance at those stored voltages, with each device at its stated output, so a residual points at equipment PowerIO reads differently from the program that solved the case.

  • Network side. Every in service branch and three winding transformer winding at its stated tap and shift, and every in service fixed and switched shunt at its stated admittance, through the same branch admittances as calc_admittance_matrix.
  • Device side. Generators at their stated pg and qg, loads through their voltage model at the stored magnitude, static VAR compensators and storage at their stated terminal power, and HVDC lines as fixed injections unless HvdcTreatment::Ignore is selected. Each converter of a line read from a PSS/E two-terminal record draws the reactive power its bridge equations give at the stored AC voltages (Hvdc::calc_lcc_operating_point: firing and extinction angles, overlap, and the fundamental power factor), unless LccReactivePower::Stated keeps the line’s stated reactive powers. A record that reaches no operating point at a positive power factor keeps the stated reactive powers too, with a BUILD.STATED_STATE.LCC_MODEL_UNAVAILABLE warning. The active powers stay the reader’s pf and pt, which price the DC current differently from the bridge model (see powerio_tx::lcc).
  • Sign. A bus mismatch is the power the network draws at the stored voltages minus the stated injection, MW and MVAr, the mismatch MATPOWER’s newtonpf drives to zero. An injection equal to it closes the bus, and closure_injections(mask) returns that injection at every bus carrying a flag in mask.
  • Flags. Each bus carries StatedBusFlags naming the attached equipment a residual is commonly traced to: hvdc, vsc, facts, generator_on_pq_bus, star_bus, merged_group, voltage_dependent_load, switched_shunt, reference, storage, and low_impedance_branch (a branch below low_impedance_threshold, default (10^{-3}) per unit, whose flow the rounding of the stored voltages can move).
  • Totals. The result sums each island of the in service topology, largest first, and ranks the top_k largest bus mismatches. A bus typed isolated has no balance and belongs to no island.
  • Refusal. The stored voltages do not determine the flow through a branch with zero series impedance, so such a branch is refused with Error::UnmergedZeroImpedance. The balance stamps branches only, so a closed switch joining two buses is refused with BUILD.SWITCH.CLOSED, as the PTDF and LODF builders refuse it. Merge the buses either joins first: BalancedNetwork::merge_buses in Rust, or --merge-buses switches (closed switches) or --merge-buses exact (and zero impedance branches) with powerio verify --stated-state.

calc_stated_branch_flows returns the active and reactive power entering both ends of every branch and winding at the stored voltages. From the command line, powerio verify case.raw --stated-state prints the island totals and the largest bus mismatches with their flags, and Python exposes both calculations on BalancedNetwork.

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 the DC OPF use \(r^2 + x^2\) under the formulas that read resistance (series_susceptance, tap_adjusted_series_susceptance, series_susceptance_no_phase_shift) and \(x\) under the reactance formulas; 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. BalancedNetwork::merge_buses resolves them explicitly instead, together with closed switches (see Merging buses).

  • Reference coverage. IndexedNetwork::check_reference_coverage verifies that every in service island has a reference bus. Islands are joined by in service branches and closed switches.

  • Closed switches. The builders stamp branches only, so on a network that still carries a closed switch they leave its two buses apart. Normalization merges closed switches by default (ClosedSwitchPolicy on NormalizeSettings keeps or refuses them instead), and merge_buses merges them on request (see Merging buses). IndexedNetwork::check_closed_switches refuses a network that skipped both with BUILD.SWITCH.CLOSED, counting the closed switches. Default merging also fails with that code if it cannot eliminate an eligible closed switch, such as a connection between two windings of one three winding transformer. It reports original source rows and returns no partial normalized network. Explicit Keep remains for consumers that model switches themselves.

  • 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.

    SeriesSusceptanceNoPhaseShift uses the same series coefficient but drops phase shifts as well as taps, matching PowerModels DCP on the same branch orientation and impedance reference side. PowerModels’ parsing can reverse antiparallel transformers and rescale their impedances, changing this tap-ignoring coefficient; see the orientation caveat. The unchanged default is also not identical to DCP on phase-shifting branches.

    TapAdjustedSeriesSusceptance divides that series coefficient by the effective transformer tap and includes phase shifts. It is the ignore-conductance convention; see the formula table.

    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|tap-adjusted-series-susceptance|series-susceptance-no-phase-shift, 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::branch_edges yields in-service branches as undirected edges (branch, from, to), with branch an index into the branch table and from and to dense bus indices. Parallel branches stay separate edges. Build a graph by adding view.n() nodes, including buses with no in-service branch, then one edge per item. The iterator does not include closed switches. The connectivity report and radial check also account for closed switches from IndexedNetwork::closed_switches. To build an equivalent graph, add those switch edges after mapping their bus IDs through bus_index, or merge closed switches before building the graph.

calc_ptdf_by_island returns one sparse PTDF per connected component. It uses the same single factorization and global solve as the ordinary PTDF builder, then scatters stored entries into component-local matrices in one pass. Each result carries dense source bus indices and source branch indices so callers can relate local matrix rows and columns back to the network. Closed switches must be merged before this call; the DC incidence matrix models branches, not unmerged switch connections.

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:

QuantityConventionReferencepowerio
Bus type codes\(1 = \mathrm{PQ}\), \(2 = \mathrm{PV}\), \(3 = \mathrm{ref}\), \(4 = \mathrm{isolated}\)MATPOWER idx_busnetwork::BusType
Impedance, susceptanceper unit on baseMVA, never rescaledMATPOWER idx_brch (BR_B already per unit)matpower
Branch terminal admittanceMATPOWER BR_B splits half to each end; richer sources use canonical g_fr/b_fr/g_to/b_to; one-value targets receive the total susceptance projectionPowerModels matpower.jl; MATPOWER idx_brchnetwork::BranchCharging, Branch::calc_terminal_charging
Tap ratio0 means a line (treated as 1); nonzero is a transformerMATPOWER idx_brch TAPBranch::calc_effective_tap
Phase shift, angledegrees in the model; PowerModels JSON carries radiansPowerModels make_per_unit!powermodels-json
Angle limitsangmin/angmax default ±360 (unconstrained)MATPOWER idx_brch ANGMIN/ANGMAXBranch::has_angle_limits
pandapower/PyPSA impedanceline r/x are converted between per unit and ohms with \(Z_{\mathrm{base}} = V_{\mathrm{kV}}^2 / \mathrm{baseMVA}\); pandapower line charging is capacitance per km (c_nf_per_km, converted via \(2\pi f \ell Z_{\mathrm{base}}\)); PyPSA line b is siemenspandapower PPC conversion, PyPSA static componentspandapower-json, pypsa-csv
dcline Pt/Qf/Qtsign flips vs MATPOWERPowerModels matpower.jlpowermodels-json
Generator cost\(c_2 p^2 + c_1 p\) maps to \(q = 2c_2\), \(c = c_1\); coefficients high order firstMATPOWER idx_cost, egret matpower_parserGenCost::calc_quadratic
source_id["bus", id] for bus-tied elementsPowerModels matpower.jlpowermodels-json
PSLF shuntsEPC pu_mw/pu_mvar are per unit on sbase; Shunt stores MW/MVAr at \(V = 1\)paired EPC/RAW case checkspslf
DOE GO Challenge 3an input/problem data file parses to AcScucInstance; one Source containing that file and its matching output/solution data file parses to AcScucSolution; instance.network() returns the shared BalancedNetworkpinned GO-3 data model, C3DataUtilities, and GOC3Benchmark.jl D1/D2/D3 filespowerio::parse, powerio::emit
Surge anglesSurge JSON carries voltage angles, phase shifts, and angle limits in radians; BalancedNetwork stores degreesRust Surge round trip testssurge-json
DeepMind OPFData JSONDeepMind OPFData carries p.u. powers and radian angles; BalancedNetwork stores the solved snapshot in MW/MVAr and degrees, with zero based links mapped to one based bus IDsPaper Appendix A, the PyG loader, the smallest complete official fixture, and size independent FullTop and N-1 property testsopfdata-json
UCTE-DEF units and signsohm, microsiemens, kV, MW, MVAr, and ampere on the node voltage level; generation and its limits are negative for an injection and the reader negates them; a current limit becomes rate_a as \(\sqrt{3}, U I / 1000\) MVA; no system base, so the balanced view uses 100 MVA at 50 HzPowSybl Core UcteImporter and UcteNode.fixucte
IEEE CDF shunts and tapsbus G/B are per unit on the title card MVA base and Shunt stores MW/MVAr at \(V = 1\); the tap bus is the from bus and the final turns ratio is the MATPOWER TAP; the phase shifter angle keeps its signMATPOWER cdf2mpc, PowSybl IeeeCdfBusReader and IeeeCdfBranchReader, the vendored 14 and 30 bus cases against case14.m and case30.mieee-cdf

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.

The PowerIO PowerModels JSON profile accepts an optional top-level base_frequency in Hz as a PowerIO metadata extension, not a standard PowerModels field. Its value must be a positive finite JSON number; omission defaults to 60 Hz, while null, strings and invalid numbers are rejected. Fresh PowerIO output includes the field. Formats without frequency support, including MATPOWER, still report the loss of a non-default frequency.

PowerModels JSON and egret JSON documents are open dictionaries: PowerModels.jl and egret keep keys they do not know. PowerIO writes these extension keys there, and reads them back, for data the standard fields cannot hold:

DataPowerModels JSONegret JSON
area recordstop-level areas table: area_i, price_ref_bus, and name, net_interchange_mw, tolerance_mw, area_type, uid; the reader also takes the col_1/col_2 rows PowerModels.jl writes for mpc.areasone elements.area entry per area number: slack_bus, net_interchange_mw, tolerance_mw, name, area_type, uid; egret’s own name-keyed areas are skipped
case metadata from a grid exchange formattop-level case_metadatasystem.case_metadata
system frequencytop-level base_frequencysystem.base_frequency
a source-assigned element identityuid in the element rowuid in the element entry
branch rating sets beyond the three ratingsrating_sets (name, rate_mva)rating_sets (name, rate_mva)
fields no typed slot holds (extras)the element row’s own keysthe element entry’s own keys
MATPOWER generator capability and ramp columnsstandard PowerModels fieldsthe MATPOWER column names
a dcline coststandard PowerModels fieldsp_cost, as a generator states it
detailed connectivity (substations, voltage levels, node breaker topology)top-level detailed_connectivitysystem.detailed_connectivity
the coordinate reference of locations and routestop-level geosystem.geo
bus location; branch name, route, and transformer control; switched shunt section_count and controlthe element row, under the PowerIO IR namethe element entry, under the PowerIO IR name
generator energy_source, voltage_regulation_on, regulating_terminal, regulated_bus, active_power_controlthe generator rowthe generator entry
HVDC resistance_ohm, nominal_voltage_kv, converters_mode, converter1, converter2the dcline rowthe dc_branch entry
storage active_power_controlthe storage rowegret states no storage

The typed values use the PowerIO IR’s field names and units, as the PowerIO IR reference gives them, and leave out an absent optional field. A standard field always wins a key collision with an extra. A key whose value does not have the PowerIO shape is kept as an extra, so a document another tool wrote with a key of the same name still reads. PowerModels and egret compute with their own fields only: a transformer or switched shunt control, a remote regulated bus, and an HVDC converter’s detail ride along for PowerIO and do not change what either tool solves.

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. A CIM100 document with no md:FullModel header and with per phase distribution classes (ACLineSegmentPhase, EnergyConsumerPhase, …), or a header-less document with the IEC 61968 customer classes (ServiceLocation, UsagePoint), is distribution CIM and routes to cim-dist instead; see Distribution networks. 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, and RAW 34 and 35 both carry a system switching device section between branch and transformer data, which fresh output writes at either revision. The two revisions place their node columns differently: PSS/E 34 appends the transformer winding NOD after CNXA, the generator NREG after WPF, the switched shunt NREG after the eighth step pair, and the two-terminal DC converter NDR/NDI after XCAPR, and revision 35 moves each next to the bus it qualifies. The reader and fresh output follow each revision’s layout, and fresh revision 34 output keeps a switched shunt to the eight step pairs before NREG and reports the rest. 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.

The three text files a PSS/E contingency analysis reads beside the case are values of their own: a .con parses to a ContingencySet, a .sub to a SubsystemSet, and a .mon to a MonitoredSet. Each reader keeps a statement outside its grammar as the trimmed line and reports it, so a file written for another solver reads completely, and each writes back with to_con, to_sub, or to_mon. A kept statement is written where it was read: inside the case, the selector group, or the monitored block it was stated in, and a statement read after the file END is written after the END the writer states, in all three files. Binding a set to a network is the separate step that reports, per case, which elements each statement named and which named nothing. PSS/E contingency analysis files has the readers, the binding, the tokens, and the command line.

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. A shunt FACTS device (J = 0) reads as a static var compensator: SHMX bounds its susceptance at the device bus base kV. VSET uses the regulated bus base kV (the device bus when FCREG/REMOT is zero), including remote terminals on another voltage level. MODE 0 takes it out of service, and PSS/E output writes each static var compensator back as one. RAW/RAWX detailed FACTS terminals and NREG map to typed equipment and regulation references. Revision 34 puts NREG after MNAME; revision 35 puts it before. Revision 33 drops the node with a diagnostic. Retained names are reserved before generated names; sanitation collisions receive unique names and a diagnostic, and detailed terminals use those same allocated names. SHMX is a current limit, MVA at unity voltage, so the susceptance bound matches the PSS/E reactive limit at 1 p.u. and is slightly tighter below it and looser above it. Both reading into the fixed susceptance model and fresh PSS/E/RAWX writing report this approximation; same format retained-source emission stays byte exact. Series FACTS devices are not modeled. Unsupported RAWX tables, including multiterminal DC, GNE, induction machine, multisection line, zone, owner, and interarea transfer records, and series FACTS devices, 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. VSC DC lines (RAW section and RAWX vscdc table) map to it too: the MW-controlling converter (TYPE 2) states the schedule, the DC voltage-controlling converter (TYPE 1) takes the remainder after both converters’ ALOSS/BLOSS/MINLOSS losses and the RDC drop, a fixed power factor converter (MODE 2) injects the reactive power its factor implies (a positive factor injects and a negative one absorbs, at a rectifier as at an inverter, as PowSybl’s PSS/E importer reads it), and an AC voltage-controlling one (MODE 1) records its regulation and states no reactive power. An RMPCT outside \((0, 100]\) reads as 100 with a diagnostic. The converter control fields ride in extras, and PSS/E and RAWX output restate the record in its own section. A switched shunt keeps its steady state susceptance BINIT as the shunt b along with its mode, voltage band, regulated bus, and step blocks. MODSW 0 reads as locked, 1 as discrete, and 2 as continuous voltage control; 3 to 6 adjust in discrete steps to control another quantity, read as discrete, and keep their code for PSS/E output. PSS/E connects a two winding transformer’s magnetizing admittance MAG1 + jMAG2 from bus I to ground, outside winding 1’s ratio, while the neutral branch charging sits inside the tap. The reader therefore stores the admittance times the square of the tap, so bus I sees exactly the stated admittance, and the writer divides the square of the tap back out as the shortest decimal that reads back to the same charging, so the admittance survives a round trip through MAG1/MAG2. A transformer with a nonzero admittance records that factor as psse_magnetizing_referral in its extras. The writer divides by the recorded factor, so a tap moved after reading leaves MAG1/MAG2 as the source stated them, and a consumer that moves the tap keeps bus I’s admittance at the charging divided by this factor. The indexed view still places a three winding transformer’s magnetizing admittance at its star bus. 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. A two winding transformer whose winding 2 ratio on its bus base is not one records that ratio as psse_winding2_ratio: the branch tap is winding 1 divided by it and r + jx already includes its squared referral, so a consumer can separate the two again. Fresh two-winding output usually puts winding 2 at one; if that would change a retained correction table from ratio to angle, it writes equivalent nonunit winding ratios and impedance instead. A two winding transformer’s branch tap is the winding 1 ratio over the winding 2 ratio \(t_1 / t_2\), each in per unit of its bus base voltage, and its series impedance and tap control range are referred across \(t_2\): the impedance scales by \(t_2^2\) and the range divides by \(t_2\), so the branch states the same two port admittance as the PSS/E circuit.

PSS/E DYR dynamics

PSS/E .dyr is parsed separately from .raw/RAWX because it describes transient-stability models, not the steady-state electrical network. Use parse_dyr (or parse_dyr_bytes) to obtain a DynamicCase; the parser keeps original source text for exact write-back and retains unknown/custom model names and ordered parameter tokens. DynamicStudy::new(network, dynamics) explicitly pairs that data with a parsed BalancedNetwork.

The generic study link check only reports DYR bus IDs absent from the static case. It does not infer that a record’s second key is a generator ID. typed_model reads the machine, exciter, governor and stabilizer models in SUPPORTED_MODELS through their PSS/E parameter schemas, and DynamicStudy::machines() attaches those records to generators by (bus, machine id); other records stay raw and are reported, not dropped. Typed views for further models, load and dc-line model linking, DYR-to-AUX/DYD/SWI conversion, and transient simulation are not provided yet. See Dynamics and DYR for the API definition.

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

A solved case’s branch matrix states the flows PF, QF, PT, and QT (MW and MVAr, columns 14 to 17 of idx_brch) after ANGMAX. The reader reads them as the branch solution, and the writer states them when every branch has one; a matrix states the columns for every row or none, so a partial set is dropped and reported.

The reader applies a bounded, straight-line unit-conversion profile after the numeric literals. This covers MATPOWER’s case33bw.m: demand columns PD/QD are divided by 1000, and branch BR_R/BR_X by Vbase^2 / Sbase. Its interpreted network contains 3.715 MW / 2.300 MVAr of demand and first-branch impedance 0.005752591161723931 + j0.002932448856844086 per unit, rather than the raw kW/kVAr and ohm values.

Supported statements are all-row, same-selection self-scaling of bus columns 3/4 or branch columns 3/4 by a finite, positive scalar. Columns may be stated numerically or through earlier scalar definitions or positional output bindings from idx_bus / idx_brch. Scalar expressions may use finite numeric literals, earlier scalar locals, mpc.baseMVA, mpc.bus(1, BASE_KV) (or column 10), parentheses, multiplication/division, and squaring. .*, ./, and .^2 are accepted for scalar arithmetic; the scale operand itself must be one atom or a parenthesized expression. Scalars and repeated conversions follow source order. The voltage lookup is the first matrix row, not the bus whose ID equals one. Only constant scalar definitions and these two known index functions are interpreted; no MATLAB code or arbitrary function is executed.

This is not general MATLAB support. Control flow, arbitrary calls, partial-row indexing, mismatched or duplicate selected columns, other mutations, nonliteral matrix expressions, unresolved symbols, nonpositive scales, and nonfinite results are unsupported. The entire conversion plan is discarded if any executable statement is outside the profile, even if earlier conversions were recognized. Original literal values remain available with span-bearing READ.MATPOWER.INDEXED_ASSIGNMENT warnings; these cases must not be treated as fully interpreted networks. The profile is bounded to 128 tokens per executable statement, 128 scalar bindings, 128 scaling statements, and 16 nested scalar parentheses.

Unchanged same-format emission still returns the exact source bytes, including the original literals and conversion statements. Edited/canonical MATPOWER output and cross-format writers use the interpreted network values and do not append the original conversions, so the conversions are not applied twice.

Canonical MATPOWER output writes aggregate HVDC terminal data as mpc.dcline, including powers, voltage setpoints, limits, and affine loss coefficients. When any line carries a cost, mpc.dclinecost covers every line, with zero-cost rows for lines without a stated cost. Storage is written as an mpc.storage block. These aggregate terminal records do not represent a physical DC network or the PowerModelsACDC extension’s converter model.

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, and a dcline cost travels as the p_cost extension above; storage is 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 states the network’s base_frequency as f_hz, and computes c_nf_per_km at that frequency. A reference bus without a generator gets an ext_grid row, which reads back as a Ref generator. The writer also warns on dropped storage, capability columns, angle limits, rate B/C, nonfinite values (written as JSON null), and costs outside the supported polynomial and piecewise-linear mappings. The reader maps ZIP load composition, line shunt conductance, transformer magnetizing parameters, ratio/ideal and pandapower 2.x tap changers, off-nominal vn_hv_kv/vn_lv_kv, lv-side taps, and shunt vn_kv scaling. Tabular or unrecognized tap changers, reactive cost coefficients, and unsupported nonempty tables are diagnosed with row counts.

The writer emits aggregate HVDC links in a dcline table. It reports unmapped sending-power floors, reactive flows, received powers that disagree with the affine loss model, and DC-line costs; conflicting terminal voltage targets are aligned with the bus controller and diagnosed. This is not full AC/DC support: native DC buses, lines, and converter-station tables are not mapped. Reverse and zero-transfer terminal errors, and the difference between native pandapower PF and OPF loss equations, remain tracked in #843; successful self-round trips do not establish native equivalence for those cases.

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.

MG-RAVENS JSON

One token, two profiles, picked from the document’s classes (see Distribution networks). The balanced profile follows the upstream MATPOWER converter’s conventions, and a bus with base_kv 0 is reported: the SI conversions use 1 kV for it, so the per unit values round trip and the volt and ohm magnitudes are not physical. The multiconductor profile follows opendss2xml. Identifiers are deterministic mRIDs, so a canonical write is byte stable. What the schema has no supported slot for is reported and dropped: passthrough extras, generation costs in the multiconductor profile, a segment with a conductor outside the CIM phase identities, and a bus whose grounded terminals have no phase letter. An unbalanced source becomes one single phase EnergySource per conductor, reported as SOURCE_SPLIT; one shared explicit branch preserves its coupled Thevenin impedance. A split source whose matrix is malformed or asymmetric is refused. Voltage limits are converted between the upstream line-to-line convention and the typed phase-to-ground bounds. Wire/cable asset impedance import remains unsupported and diagnosed; linecode-based segments have a typed projection.

The external schema gate uses the pinned upstream schema unchanged for the distribution profile. The balanced converter profile adds strict definitions for ConnectivityNode.SvVoltage and MySettings, which the upstream MATPOWER converter emits but its own schema omits. The supplement preserves every other upstream constraint; it does not make otherwise unknown properties acceptable. The report identifies this distinction and validates fresh output through IR; it does not equate schema acceptance with electrical equivalence.

PMD MATHEMATICAL JSON

The writer reproduces PMD’s transform_data_model (see Distribution networks), and the tests hold it to PMD v0.16 exports of PMD’s own cases. Findings state what the MATHEMATICAL model does not carry: the winding power rating (the reader restates impedances on the emergency rating), a load’s voltage band transitions and dropout, regulator controls, a load without a nominal voltage (the bus base stands in), and an island no stated base reaches. Storage and objects no map entry claims are kept untyped.

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.

VersionReadWhat the version states differently
1.0XIIDMiTesla namespace. Busbar sections carry the calculated bus v and angle. Three winding transformers have no ratedU0 (leg 1 rated voltage is the impedance base), no leg 1 tap changer, and no phase tap changers. Tie lines state both half lines inline with _1/_2 suffixes and ucteXnodeCode. Shunts state bPerSection, maximumSectionCount, and currentSectionCount and never regulate. Static VAR compensators spell voltageSetPoint and reactivePowerSetPoint. Batteries spell p0 and q0. Ratio tap changers state targetV. Loading limits sit directly on the equipment as the selected DEFAULT group. A switch closing a bus or node onto itself is discarded, as PowSybl does. No minimumValidationLevel.
1.1XIIDMPowSybl namespace. Calculated buses under node breaker topology. Three winding transformer ratedU0, leg 1 tap changers, and phase tap changers.
1.2XIIDMfictitious on every identifiable, targetDeadband on tap changers, ratedS, and shunt voltage regulation.
1.3XIIDMShunt linear and nonlinear models with sectionCount, aliases, and boundary line generation.
1.4XIIDMAlias types.
1.5XIIDMActive and apparent power limits.
1.6XIIDMVoltage levels outside substations and VSC regulating terminals.
1.7XIIDMminimumValidationLevel and the equipment validation namespace.
1.8XIIDMBatteries spell targetP and targetQ. Fictitious bus injections (reported, not retained). Self connected switches are refused.
1.9XIIDMShunt p.
1.10XIIDMTie lines reference two dangling lines. Load models.
1.11XIIDM, JIIDMpairingKey replaces ucteXnodeCode. Subnetworks. Voltage angle limits (reported, not retained).
1.12XIIDM, JIIDMOperational limits groups and ratio tap changer regulationMode/regulationValue.
1.13XIIDM, JIIDMAreas, isCondenser, and active power control 1.2.
1.14XIIDM, JIIDMSolved tap positions and section counts, regulating on static VAR compensators and phase tap changers.
1.15XIIDM, JIIDMDC nodes, grounds, lines, switches, and AC/DC converters.
1.16XIIDM, JIIDMshuntCompensator and boundaryLine element names and multiple selected limit groups.
1.17XIIDM, JIIDMOptional zero conductance and susceptance, retained and lowTapPosition defaults, DC switch resistance. Writers use this version.

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.

Conversion evidence and incremental improvement

The PR matrix and its JSON evidence come from the same test cells and grading rules. Run:

POWERIO_CONVERSION_MATRIX_JSON=target/conversion-matrix.json \
  cargo test -p powerio-cli --test conversion_matrix_report
python3 scripts/conversion-matrix-plan.py target/conversion-matrix.json \
  --output target/conversion-backlog.json

The Conversion Matrix workflow uploads conversion-matrix.json, conversion-backlog.json, and the detailed findings in the conversion-matrix-warning-details artifact. The main-branch Docs deployment publishes matrix evidence and the ranked backlog. A PR artifact describes its exact tested commit, which can be GitHub’s synthetic merge commit; head_commit and base_commit identify the PR inputs separately. Local evidence also states whether the working tree was dirty. Missing provenance is unknown, not success.

The JSON evidence format is schema: "powerio-conversion-matrix", schema_version: 1. It includes provenance, passed, failures, grade counts, and unique cells. Each cell identifies its source, target (null for source parsing), fixture cases, grade, findings, model differences, baseline, and check failures. The grades are lossless, exact, restated, approximate, dropped, and failed. verification.independent_consumer is explicitly not_run_by_this_suite: self round trips do not establish native tool acceptance. These are CI artifact versions, independent of PowerIO IR document versions.

Reading the results

The overview combines lossless and exact as Preserved: no reported loss or typed-model change within the tested coverage. exact also records that the original source can be replayed byte for byte and that a fresh write is lossless. That extra evidence remains in the original grade and verification.byte_echo_exact; combining the display does not remove a check.

DisplayOriginal gradeMeaning
Preservedlossless, exactNo reported loss or typed-model change in the tested projection.
Representation / defaultsrestatedA different representation, generated default, relabeled identifier, or informational remark is reported.
Adjusted / partly checkedapproximateAn adjustment is reported, or some electrical comparison remains unverified. Inspect the findings and limitations to distinguish these.
Data omitteddroppedAt least one piece of source data has no corresponding target field.
Failed checksfailedAn error, invariant failure, or baseline mismatch needs attention.

For example, the PMD source parser can move inline line impedances into reusable internal line-code records; the PMD writer puts them inline again. This representation change produces a remark, not a report of omitted impedance values. An adjustment changes or infers a value; an omission leaves some source data out. A limited comparison is uncertainty about verification and must remain visible separately from a known adjustment.

Each cell reports its most serious finding. A single omitted metadata field can therefore give a cell the same dropped grade as several omitted fields. The grade is not a percentage of the case preserved or a calibrated 1–10 fidelity score. Counts must distinguish conversions from source parses, and comparisons must retain fixture identities and coverage. Native-consumer acceptance is a separate check. Display grouping does not change JSON grades, the baseline, diagnostic severity, or any acceptance rule.

A website can display this evidence, filter by format pair and diagnostic, and link to the exact workflow run. Imported JSON is evidence to inspect, not proof of its origin. Match repository, tested commit, run and artifact identity before calling it authenticated CI. Display failed or stale runs explicitly; preserve source-only findings and distinguish native fields from retained extensions. Do not replace a failed run with the last green run without showing both states.

A bounded repair loop

  1. Run the matrix on a known commit. Rank failing checks first, then dropped, approximate and restated fields by the number of affected cells. The planner’s code groups are triage hints; one diagnostic can describe several unrelated fields, so group size is not a promised improvement count.
  2. Pick one bounded, representable gap. Find the target format’s authoritative semantics and add the smallest reproducer. Prefer an independent target consumer; otherwise identify the specification and the remaining uncertainty.
  3. Implement the mapping and check native units, signs, IDs, optional values, and source retention. Run relevant Rust, Python, C and Julia checks, the matrix, and the repository’s required lint gates.
  4. Compare evidence with --previous previous-matrix.json. Review changed grades and findings and removed cells or fixtures. A smaller test set is not a fidelity improvement. Unsupported target features remain reported.
  5. Only after checking the observed delta, update an intentional baseline with POWERIO_MATRIX_BLESS=1. Open a reviewable PR describing the reproducer, independent evidence, exact delta, limitations and credit. Merge requires review; the planner never edits code, weakens grades or accepts a baseline.
  6. Once the change lands, use the new main evidence to select the next gap.

A scheduled coding agent can perform this bounded cycle with at most one open repair PR. It must stop on ambiguous semantics, failing independent checks or a concurrent branch update. It must not modify its own acceptance rules to obtain more green cells. The goal is preserved electrical meaning, not a target color.

Sienna exchange

A balanced PioModule can be emitted as a SiennaSchemas SystemDocument. Use sienna-json to retain an input document’s version, or to select 0.4.0 for a new module. Explicit targets are sienna-0-1-json, sienna-0-2-json, sienna-0-3-json, and sienna-0-4-json.

import powerio as pio

module = pio.parse("case.raw")
result = pio.emit(module, "sienna-0-4-json", "case.json")
recovered = pio.parse("case.json")

The reader separates component identifiers from bus numbers and converts component bases and natural units into the neutral electrical model. Voltage angles and phase shifts change between Sienna radians and PowerIO degrees. Storage dispatch changes between injection and consumption sign conventions.

JSON cannot state infinity, and both SiennaSchemas and PowerSystems.jl require a numeric Line.rating; PowerSystems also requires each three-winding winding’s rating. An unlimited rating is written as PowerSystems’ INFINITE_BOUND, 10⁶ per unit on the row’s base, which is the value PowerSystems’ own parsers give a zero or absent PSS/E rating. PowerIO reads that value back as unlimited, so the round trip is exact. When PowerSystems validates such a line, it replaces the bound with a rating derived from the line’s parameters and logs a warning. A rating of zero is a real zero bound. Optional ratings that are unlimited are left out.

The adapter maps AC buses, area membership, lines, transformer circuits, two- and three-winding transformers, fixed and switched admittances, constant-power and ZIP loads, static generators, reservoir storage, and generic HVDC lines. Optional source data remains in the module extension org.eigenergy.powerio.sienna, which survives PowerIO IR serialization. Diagnostics identify data that has no active electrical mapping. A same-version write overlays edited electrical values on the retained document. Cross-version writes report source-only fields that require a separate migration.

Sienna’s ext map carries PowerIO identifiers and fields without a native schema counterpart under org.eigenergy.powerio, keyed by component ID. Native schema fields are authoritative. Consumers must handle these keys or list them in their explicit ignore list. A field retained only in ext does not acquire Sienna solver semantics; emission reports electrical constraints that need this handling. A two-winding transformer states one magnetizing shunt, so charging on its secondary terminal is written as a FixedAdmittance on the to bus whose ext names the circuit it belongs to (transformer_circuit, or transformer_uuid in PowerSystems output). A Sienna consumer sees an ordinary bus shunt; the PowerIO reader folds it back into the branch while the shunt and the transformer share one available status. A native edit that gives the shunt a status of its own leaves it a bus shunt with that status, so disabling the generated shunt removes the charging from the branch.

Time-series associations and dynamics records remain available in the retained document. The standalone electrical reader does not acquire a referenced HDF5 companion.

Document and HDF5 bundles

Install powerio[sienna-files] for the Python sienna-bundle transport, or select sienna-0-1-bundle through sienna-0-4-bundle explicitly.

module = pio.parse("system.json", format="sienna-bundle")
pio.serialize(module, "system.pio.json")
pio.emit(module, "sienna-bundle", "exported-system")

A bundle contains system.json and the named HDF5 companion. Input companions must stay within the acquisition root; memory input supplies them through named_buffers. Numeric HDF5 arrays, shapes, and attributes survive IR in org.eigenergy.powerio.sienna.arrays. Bounds cover acquired bytes, expanded arrays, and object counts. External HDF5 links and object arrays are rejected. An existing output directory is never replaced. The electrical value interprets components; retained forecast arrays keep the meaning declared by the Sienna association records. Tests reopen emitted arrays with InfraStore 0.14.1 and validate association records against every released schema. Bundle writes migrate the common time-series associations across releases when their component owners remain in the target. The explicit zoneless declaration keeps its wall-clock meaning: 0.4 writes an offset-free timestamp, while older releases use InfraStore’s legacy Z spelling. The TransitionZero adapter selects 0.2 before handing associations to its pinned InfraStore consumer. Per-unit load series retain their declared device base; other device-base edits that need array rebasing are rejected. Other source-only records still require separate migration.

PowerSystems.jl serialized systems

powersystems-json reads native PowerSystems data formats 4.0.0 and 5.0.0, and writes 5.0.0. This is the serialized Julia System layout, with UUID references and stored device bases. It is distinct from a SiennaSchemas SystemDocument. The format is detected from data_format_version.

pio.emit(module, "powersystems-json", "system.json")

The generated file loads with PowerSystems.System("system.json"). Compatibility checks cover PowerSystems 4.6.2 inputs and 5.9.0/5.12.5 consumers. PowerSystems 5.9 predates native switched-shunt control mode and remote-bus fields. A PowerIO extension preserves these through that runtime; native fields take precedence in newer consumers. The 5.12.5 check verifies those controls directly. PowerNetworkMatrices versions that omit switched admittances from Ybus require the initial injection to be handled separately, as emission diagnostics state.

The native adapter shares the electrical mapping above, including explicit star circuits for three-winding equipment. Parallel devices share their native arc. PowerSystems companion time-series files and masked components remain outside this standalone electrical projection. Unknown native records stay in org.eigenergy.powerio.powersystems in a serialized PowerIO module.

PyPSA binary files

The optional powerio[pypsa-files] extra enables pypsa-netcdf and pypsa-hdf5 through PyPSA’s own container readers and writers. These transports use PowerIO’s existing CSV electrical and temporal mapping, so the same diagnostics apply. The Python package imports the optional dependencies only when a binary transport is used. Input and expanded arrays are bounded to 64 MiB. PyPSA reads HDF5 through pandas and PyTables, which unpickle some attributes, so the reader refuses a file with an attribute whose pickle would call code, and a file with a PyTables 1.x FILTERS attribute, which PyTables rewrites before unpickling.

pio.emit(module, "pypsa-netcdf", "network.nc")
module = pio.parse("network.nc")

TransitionZero pipelines

The Python distribution registers powerio_source and powerio_sink in the interop.sources and interop.sinks entry-point groups. Install tz-oss-interop and the PyPSA file extra in the same environment. The source accepts input_path and an optional PowerIO format; the sink accepts output_path and format (default pio-ir).

Both default to tables: pypsa, matching the PyPSA table layout. The source stages transformers and shunt impedances alongside the other component tables. tables: sienna selects the SiennaSchemas 0.2 tables. A Sienna source refuses component families that the pipeline’s staging helper cannot handle.

The sink accepts PyPSA electrical time series and a single-file target. Sienna temporal staging accepts scalar SingleTimeSeries from any released sienna-bundle version with tables: sienna, converting component bases to the pipeline’s capacity-based series. Forecast arrays remain available in bundles and IR. The Sienna sink preserves its time-series association rows and HDF5 arrays in pio-ir output. A pio-ir sink retains pipeline extension records and their companion columns in the module’s org.eigenergy.powerio.transitionzero extension, including timestamp units and timezones. They return to the pipeline when powerio_source reads that IR. These records do not add planning constraints to the electrical value. Other file targets require the pipeline’s extension sidecar to be emitted separately. PowerIO diagnostics are forwarded to the pipeline’s recorder.

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 drawing layer with supported bus, branch, and substation objects. A drawing with no decoded equipment returns an error.

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(())
}

Rust callers that need the raw display record can still lift a PwdDisplay into a layer with to_geo_layer_from_pwd; 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.

FormatFieldsSpace
PowerWorld PWBValidated bus latitude/longitude fields in supported 425/537 record layoutsgeographic
PowerWorld auxLatitude:1/Longitude:1 bus columns, else the bare Latitude/Longitude pair (SubNum stays in extras: it is identity rather than geometry)geographic
pandapowerbus geo GeoJSON Point stringsgeographic
PyPSAbuses.csv x/ygeographic
DOE GO Challenge 3bus longitude/latitudegeographic
OpenDSSBuscoordsunknown; a diagnostic identifies values within longitude and latitude bounds
BMOPF JSONthe schema’s bus[id].geo Point and line[id].geo LineString with meta.crs; the geo of every other located element as a component location (a switch or transformer LineString reads as the midpoint of its end positions); on read also the extras.geojson FeatureCollection PowerIO 0.11 wrote and pre-schema longitude/latitudedeclared CRS, geographic when omitted

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 document 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 accepts id when kind explicitly identifies a line or branch. An untyped feature counter does not identify equipment. BMOPFTools bus_from/bus_to endpoint names are accepted. A CRS string or a named CRS object retains its identifier; PowerIO does not reproject the coordinates.

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 drawing GeoLayer with decoded bus positions, branch paths, and substation positions. Coordinates remain in drawing units. Unsupported or unmatched bus and branch records produce diagnostics. Read a display with parse, under the same input byte limits as every other source. PowerIO 0.12 removed Python’s parse_display, which returned the raw display record and read the file without those limits.

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().

BMOPF geometry and schema validity

The BMOPF schema declares typed geometry, following BMOPFTools #258 and the shape PowerIO 0.11 already read: bus[id].geo is a GeoJSON Point, line[id].geo a GeoJSON LineString from bus_from through any bends to bus_to, and meta.crs the authority code of the one coordinate reference system every geo field uses. An absent crs means OGC:CRS84, WGS84 longitude then latitude, and coordinates are always x then y whatever the authority’s own axis order, so EPSG:4326 reads the same way. The writer leaves meta.crs out for WGS84. Geometry is descriptive: length stays the electrical length. A malformed vertex invalidates its entire path; PowerIO does not connect the remaining vertices.

BMOPF output writes these slots. A projected system writes its code to meta.crs; WGS84 omits it. A space the schema cannot name (an OpenDSS Buscoords file declares none, a drawing has no earth referent, a projection may lack a code) or coordinates not taken from the source data also write PowerIO’s coordinate metadata as extras.powerio_geo, which the reader prefers over meta.crs, so a read gets the same MulticonductorNetwork::geo back and does not take unknown-space coordinates for WGS84.

Every PowerIO 0.11 BMOPF document stored its geometry as a FeatureCollection in the permitted extras.geojson location: features with kind, id, bus_from, and bus_to, and a powerio_geo member carrying the coordinate metadata. The reader still accepts that layer, but only when no bus or line carries a typed geo field: when both are present the typed slots win, the layer is not merged in, and its features are reported as dropped (READ.BMOPF.FIELD_DROPPED). A geo the reader cannot place, because it is malformed, names no element, or the coordinate metadata is unreadable, is reported the same way. Either form is typed into bus locations and line routes on read and re-emitted from the model in the typed slots, never copied through, so an edit cannot leave a stale copy behind. PowerIO no longer writes the layer.

Same-type source emission preserves the input bytes of a document that states 0.2.0. Editing, or reading a document written against an earlier version, writes the typed coordinates, so a retained source cannot override updated positions. PowerIO IR also retains typed bus locations, line paths, and coordinate metadata.

A RAW revision 33 file does not contain the New England PWB bus-location records. Attach its matching GeoJSON, CSV, AUX, or PWD companion explicitly. PWD positions describe a drawing and must not be interpreted as latitude and longitude.

PSS/E contingency analysis files

A PSS/E contingency analysis reads three text files beside the case: a contingency description file (.con) naming the outages to run, a subsystem description file (.sub) naming the bus groups those outages draw on, and a monitored element file (.mon) naming what the run reports on. Each is a PowerIO value of its own, not a network: ContingencySet, SubsystemSet, and MonitoredSet. Their PowerIO IR structural type names are in the PowerIO IR reference.

CONTINGENCY 'L_000001ODES'
OPEN LINE FROM BUS   1001 TO BUS   1064 CIRCUIT 1
END
SINGLE BRANCH IN SUBSYSTEM 'WOA'
END

parse routes a file by its extension or by a declared token, emit writes it back under that same token, and serialize carries it through PowerIO IR. The tokens are psse-con, psse-sub, and psse-mon; con, sub, mon, contingency, subsystem, and monitored are accepted aliases. No grid exchange format states one of these files, so emitting a .con module as psse or as psse-sub is refused by value type.

Reading and binding

Reading holds what the file states and touches no network. Binding is the separate step.

use powerio::{PioValue, parse};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let case = parse("case.raw")?;
    let PioValue::BalancedNetwork(network) = case.value() else {
        panic!("a .raw parses to a balanced network");
    };

    let module = parse("cases.con")?;
    let PioValue::ContingencySet(set) = module.value() else {
        panic!("a .con parses to a contingency set");
    };

    let resolution = set.resolve(network);
    println!(
        "{} of {} cases bound",
        resolution.resolved,
        resolution.cases.len()
    );
    for note in resolution.diagnostics() {
        eprintln!("{}: {}", note.code(), note.message());
    }

    // An automatic specification expands into one case per element of a
    // subsystem, so the expanded set states every outage explicitly.
    let subsystems = parse("groups.sub")?;
    let PioValue::SubsystemSet(subsystems) = subsystems.value() else {
        panic!("a .sub parses to a subsystem set");
    };
    let expanded = set.expand(network, subsystems);
    print!("{}", expanded.set.to_con());
    Ok(())
}

ContingencySet::resolve returns one ResolvedCase per case: the elements each action bound to, and the actions that bound to nothing with the reason each one did not. Subsystem::select_buses names the buses of one subsystem, and MonitoredSet::resolve binds monitored branches, interfaces, and voltage scopes to table rows against a network and a subsystem set. The binding recomputes the PSS/E machine and circuit identifier of every element with the RAW writer’s own allocation, because a network row’s identity carries neither. A branch statement such as OPEN BRANCH FROM BUS 1 TO BUS 5 CIRCUIT '@1' that names no line or two winding transformer binds to a system switching device on that pair, as component type switch.

Python reaches the same three values and the same two operations:

import powerio

case = powerio.parse("case.raw").value
cases = powerio.parse("cases.con").value

resolution = case.resolve_contingencies(cases.text)
print(resolution["resolved"], "of", resolution["cases"], "cases bound")

groups = powerio.parse("groups.sub").value
expanded, notes = case.expand_contingencies(cases.text, groups.text)
print(expanded)
print(case.select_subsystem_buses(groups.text, "A1"))

C reaches them through pio_value_contingency_set, pio_contingency_set_resolve, and pio_contingency_set_expand, and writes each file back with pio_contingency_set_to_con, pio_subsystem_set_to_sub, and pio_monitored_set_to_mon, so an expanded set reaches a file from C. The C API guide lists the accessors.

What is kept as text

Each reader covers the statements its grammar states and keeps every other line as the source wrote it, under READ.CON.STATEMENT_UNRECOGNIZED, READ.SUB.STATEMENT_UNRECOGNIZED, or READ.MON.STATEMENT_UNRECOGNIZED. A line kept inside a case becomes ContingencyAction::Unrecognized; a line kept at file level becomes a RetainedStatement with the 1-based source line. A tool that writes its own directives into a .con therefore reads completely rather than failing on its first line, and to_con writes those lines back.

The TARA statements among those lines are read at analysis time rather than into new fields, because the three sets’ PowerIO IR layouts are fixed within 0.11. ContingencySet::resolve binds a statement that names buses by quoted name and base kV (BUSNAMES) or one branch by quoted name (BRANCHNAMES): an exact name first, then one equal without regard to letter case and runs of whitespace, and a name matching several elements binds none and is reported as ambiguous. Numeric bus operands keep their identities even when quoted. Named bus operands support the same optional BUS keywords as numbered ones. ContingencySet::calc_default_dispatch and ContingencyAction::calc_dispatched_action read DEFAULT DISPATCH blocks and case actions that close with DISPATCH, and Subsystem::calc_dispatch_rules reads a subsystem’s PARTICIPATE, SCALE, BASELOAD, TURBINETYPE, and EXCEPT lines. Defaults after the file’s END remain inert retained text. Non-finite scaling thresholds also stay retained instead of becoming typed dispatch rules.

Only three shapes are errors: a case that never closes, a case that starts inside another, and a block left open at end of input. The reader’s note budget is sixteen records per file; past it one further note reports the suppression.

A case that does not apply to the network is a BUILD.CON.CASE_UNRESOLVED note naming the case and the first action that bound to nothing, rather than a silent omission. An automatic specification naming a subsystem the .sub file does not state stays unexpanded and earns BUILD.CON.SUBSYSTEM_UNKNOWN.

Emission

A parsed module emits its own file exactly: emit returns the retained source bytes for a same format write. A module that carries no source, such as one read back from PowerIO IR, emits canonical text through to_con, to_sub, or to_mon. Reading canonical text back gives the same set, except that a statement kept from the middle of a source file is written after the cases and so reads back from a later line; writing that second set gives the same text.

Command line

$ powerio contingency resolve case.raw cases.con
$ powerio contingency resolve case.raw cases.con --sub groups.sub --mon watch.mon --json
$ powerio contingency expand case.raw cases.con --sub groups.sub -o expanded.con

resolve prints the case counts, one line per case that bound to nothing with its reason, and, when --mon names a monitored element file, the monitored row counts. --sub is read with --mon, whose statements name the subsystems it states, and resolve refuses --sub without it. --json prints the same counts as one object on stdout. expand writes the expanded .con text to stdout, or to the file -o names.

The grammar

The grammar is established from public contingency files and the example set PSS/E ships, because the manual that defines it is licensed and not public. powerio-tx/src/contingency/FORMAT.md lists each statement with its evidence and gives the writer’s spellings. The case names an expansion generates and the reading of 3WLOWVOLTAGE are PowerIO’s convention, because PSS/E documents neither publicly.

Dynamics and DYR

Representation decision

PSS/E .dyr is a dynamic-model file, not a power-flow network. PowerIO keeps that distinction explicit: .raw is parsed by powerio::parse to a PioValue::BalancedNetwork, while .dyr is parsed by powerio::parse_dyr to a standalone DynamicCase. Pair the two with DynamicStudy; do not insert dynamic records into BalancedNetwork or treat the raw model key as a typed generator reference.

This separate Rust API is intentional. It establishes a stable boundary for loss-preserving DYR records and generic bus association without prematurely committing the cross-language PioValue, PowerIO IR, C ABI, Julia, or Python representations to an incomplete dynamic-model schema.

Parse and pair

The example below is compiled as the dynamic_study Cargo example. Run it in a directory containing case.raw and case.dyr with cargo run -p powerio --example dynamic_study.

use powerio::{DynamicStudy, PioValue, parse, parse_dyr};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let raw = parse("case.raw")?;
    let PioValue::BalancedNetwork(network) = raw.value() else {
        return Err("case.raw did not produce a balanced network".into());
    };

    let dyr_text = std::fs::read_to_string("case.dyr")?;
    let dynamics = parse_dyr(&dyr_text)?;
    let study = DynamicStudy::new(network.clone(), dynamics);

    for unresolved in study.unresolved_buses() {
        eprintln!(
            "line {}: {} references missing bus {}",
            unresolved.line, unresolved.model_name, unresolved.bus_id
        );
    }
    Ok(())
}

DynamicCase::records() returns records in source order. Each record exposes its first-field key, raw model name, optional device key, ordered parameter tokens, source line, and record spelling. An unquoted key is a bus number, returned by bus_id(); a quoted key names a device, as dc line models do ('DC1' 'CDC4T' ... /), and bus_id() returns None for it. DynamicCase::to_dyr_string() returns the original text exactly, including comments and formatting. parse_dyr_bytes rejects invalid UTF-8 rather than replacing bytes.

Linking guarantees and limitations

DynamicStudy::unresolved_buses() verifies only whether each generic DYR bus ID occurs in the paired network, and skips records keyed by a device name. Load models keyed by area, zone, or owner (for example CLODAR) state that number where a bus would be, so the check can report them as unresolved buses. It does not assert that the optional device_id refers to a generator, load, or other particular equipment: the meaning of that field and the association rule depend on the model family. Unknown and user-defined models are preserved rather than rejected or silently dropped. Parameters remain strings on the record; the typed views and model-aware generator linking below read the models with a PSS/E schema.

Typed model views and generator linking

powerio::typed_model reads a record through its PSS/E Model Library parameter schema for GENCLS, GENROU, GENROE, GENSAL, GENSAE, SEXS, ESAC1A, EXST1, TGOV1, GAST, HYGOV and IEEEST (powerio::SUPPORTED_MODELS). Parameters keep PSS/E names, order and the machine base; a Fortran D exponent (1.0D0) reads as E. A record of another model, with the wrong parameter count, a non-numeric token, or an integer code (IEEEST ICS and IB) that is not an integer in range returns a ModelError and stays available raw. Other parameter values pass through without range checks, and some zeros carry PSS/E meaning: a zero time constant bypasses its block, and GENCLS with H = 0 is an infinite bus. The typed view never changes the retained records, so to_dyr_string() still writes the source back byte for byte.

DynamicStudy::machines() (or powerio::link_machines) attaches the typed records to the generators they name by (bus, machine id). The PSS/E reader keeps a machine id only when it differs from the positional default, so powerio::psse_machine_ids rebuilds every generator’s id with the writer’s allocation rule, and powerio::generator_source_impedance returns ZSORCE. A machine id matches exactly; when no generator on the bus has it, the one generator whose id matches ignoring ASCII case is used, and several such are reported as ambiguous. Each generator gets at most one machine, exciter, governor and stabilizer. As in PSS/E, which replaces a model of the same category for a machine when a later DYR record states one, the last record of a role wins and the replacement is reported. Every record that does not attach is reported as a LinkIssue: untyped (naming the generator only for a model known to attach to one), no such generator, out of service, ambiguous id, or replaced.

Not implemented yet: typed views for further models, load and dc-line models, DYR-to-DYD/SWI/PowerWorld AUX conversion, transient simulation (tellegen’s rms module consumes these views), and dynamics exposure through PowerIO IR, C ABI, Julia, or Python. This is the initial public API boundary, not a claim that those features are complete.

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.

MeaningRustPythonJuliaC
name a filepass the name to parsepass a path to parsepass a path string to parsepio_source_open
acquire memorySource::from_memory(name, bytes)pass a file or bytes-like objectpass IO or AbstractVector{UInt8}pio_source_from_memory
parseparse(input), parse_with_options(input, &options)parse(source, format=..., name=...)parse(source; format=..., name=...)pio_parse
module valuemodule.value()module.valuemodule.valuepio_module_value
module diagnosticsmodule.diagnostics()module.diagnosticsmodule.diagnosticspio_module_diagnostics
emit a formatemit(&module, format, destination)emit(module, format, destination=None)emit(module, format, destination=nothing)pio_emit
serialize IRserialize(&module, destination)serialize(module, destination=None)serialize(module, destination=nothing)pio_module_serialize
deserialize IRdeserialize(source)deserialize(source)deserialize(source)pio_module_deserialize
apply updatesapply_updatesapply_updatesapply_updates!pio_apply_updates
resolve contingenciesContingencySet::resolve(&net)network.resolve_contingencies(text)resolve_contingencies(net, set)pio_contingency_set_resolve
expand contingenciesContingencySet::expand(&net, &subsystems)network.expand_contingencies(con, sub)expand_contingencies(net, set, subsystems)pio_contingency_set_expand
select subsystem busesSubsystem::select_buses(&net)network.select_subsystem_buses(sub, name)select_subsystem_buses(net, subsystems, name)pio_balanced_network_select_subsystem_buses
apply a geo layerapply_geo_layer(&module, &layer)network.apply_geo_layer(text)apply_geo_layer(m, layer)pio_module_apply_geo_layer

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.

LanguageA memberA table’s length
Rustaccessor method: module.value(), module.diagnostics(), network.buses()network.buses().len()
Pythonread only property: module.value, module.diagnostics, network.buseslen(network.buses) or network.n_buses
Juliaproperty: module.value, module.diagnostics, net.buseslength(net.buses)
Cone function per member: pio_module_value, pio_module_diagnosticsa _count function

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.

LanguageOperations
Rustlen, iter, checked get
Pythonlen, iteration, series[index], scenarios[id]; TimeSeries is a Sequence and ScenarioSet a Mapping
Julialength, iteration, 1-based getindex
Czero-based length and entry access; scenario lookup by identifier

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")
print(module.type_name)                      # powerio.BalancedNetwork

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

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

records = powerio.diagnostic_records(module.diagnostics)

Diagnostics live on the module rather than on the contained network or solution. Branch on module.value with isinstance; there is no .kind property, kind enum, or typed narrowing helper. module.type_name is the canonical structural name of the value, the same string the C ABI and PowerIO IR use, for messages and machine-readable results.

powerio.diagnostic_records turns those diagnostics into JSON-ready dictionaries, and powerio.diagnostic_record turns one. Each record keeps code, severity, message, and target, and adds id, suggested_action, related, details, and spans when the diagnostic carries them.

A module also carries extensions: JSON values under namespaced keys such as org.eigenergy.powerio.sienna, which PowerIO IR serializes alongside the value. module.extension_keys lists the namespaces, module.extension(key) decodes one value (or returns None), and module.with_extension(key, value) returns a copy carrying value under key. None of the three serializes the typed value, so adding a companion record to a large network costs the record, not the network.

tagged = module.with_extension("org.example.audit", {"reviewed": True})
assert "org.example.audit" in tagged.extension_keys
assert tagged.extension("org.example.audit") == {"reviewed": True}
assert module.extension("org.example.audit") is None   # the original is unchanged

The value classes are BalancedNetwork, dist.MulticonductorNetwork, OperatingPoint, TimeSeries, ScenarioSet, GeoLayer, ContingencySet, SubsystemSet, MonitoredSet, 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 a "version" that names the release whose schema the document follows, such as "0.12.0", and powerio.versions()["powerio_ir"] reports both. The producer record names the software that wrote the document separately. deserialize reads the documents of its own release series and the "version": 2 documents 0.11 wrote; it refuses any other schema or version and reports what it found. PowerIO IR is not a grid exchange format, so it does not appear in format discovery.

PSS/E contingency analysis files

A contingency set is the content of a PSS/E .con file: named cases, each a list of outage actions. A subsystem is PSS/E’s name for a bus selection stated in a .sub file through bus, area, zone, owner and kV range selectors; a .con automatic specification and a .mon statement refer to a subsystem by name, and selecting a subsystem’s buses evaluates its selectors against a network. A monitored set is the content of a .mon file: the elements whose loading and voltage a study reports.

A .con, .sub, or .mon file parses to ContingencySet, SubsystemSet, or MonitoredSet. Each has a text property holding the file. A contingency set and a subsystem set also reach a network through a BalancedNetwork method.

case = powerio.parse("case.raw").value
cases = powerio.parse("cases.con").value
print(cases.text.splitlines()[0])

resolution = case.resolve_contingencies(cases.text)
print(resolution["resolved"], "of", resolution["cases"], "cases bound")
for result in resolution["case_results"]:
    if not result["resolved"]:
        print(result["name"], result["unresolved"][0]["reason"])

groups = powerio.parse("groups.sub").value
expanded, notes = case.expand_contingencies(cases.text, groups.text)
print(expanded)
print(case.select_subsystem_buses(groups.text, "A1"))

resolve_contingencies reports rather than refuses: a case naming an element the network does not hold is counted unresolved and listed in case_results with the reason each action did not bind. Each reason is a fixed name such as no_such_branch; C reports the same names.

Each element a case bound to states its type, which names the table, the row it occupies there, the element’s own in_service flag, and its id. id is None when the network states no identity for that row, and type and row name the element either way.

expand_contingencies turns an automatic specification such as SINGLE BRANCH IN SUBSYSTEM 'A1' into one explicit case per element, and returns the expanded .con text with the readers’ and the expansion’s notes.

MonitoredSet is text only in Python. It carries the file as its text property and has no method that binds it to a network, because binding a monitored element file to a network and a subsystem set is a Rust operation. C reads a monitored set’s statement count with pio_monitored_set_statement_count and its text with pio_monitored_set_to_mon. C selects a subsystem’s buses with pio_balanced_network_select_subsystem_buses, which names the same buses as select_subsystem_buses.

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)

Every DC calculation shares two axes. calc_dc_index_map names them: bus_ids maps a bus row to the source bus id (every bus in table order), branch_rows maps a branch row to its position in the branch table (three winding transformer windings follow the branches), and branch_ids gives the stable identity of that row, the branch uid when the source states one and branches:<row> otherwise. Out of service branches and self loops have no row. A zero impedance branch fails a DC calculation with BUILD.OPERATOR.ZERO_IMPEDANCE; skip_zero_impedance=True drops it and calc_dc_index_map lists it under skipped_branch_rows.

axes = network.calc_dc_index_map(skip_zero_impedance=True)
A = network.calc_incidence_matrix(skip_zero_impedance=True)
assert A.shape == (len(axes["branch_ids"]), len(axes["bus_ids"]))

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.

An OperatingPoint entry of a TimeSeries or ScenarioSet exposes .network, the balanced network with that point’s values applied, so a solver receives the entry without emitting and reparsing it. The property returns the network alone: net bus injection quantities have no balanced network field, so they are dropped and the property reports nothing. emit states that same omission as EMIT.OPERATING_POINT.DATA_OMITTED, so emit the collection when you need the diagnostic.

AC optimal transmission switching

module.to_ac_ots_instance() builds an AcOtsInstance from a balanced network, AC OPF, or AC OTS module. With no argument every initially in-service branch may switch, at zero cost, islanding is forbidden, and there is no budget and no current limit. Any keyword argument makes the options explicit, as the C ABI’s PioAcOtsOptions and PowerIO.jl’s AcOtsOptions do; then an option not given takes its explicit default, and switchable defaults to "all", which includes the initially open branches.

inst = module.to_ac_ots_instance(
    switchable=["branches:0", "branches:1"],   # or "all", "none"
    switching_costs={"branches:0": (4.0, 7.0)},  # (open_cost, close_cost)
    islanding="forbidden",                     # or "allowed"
    max_open=None,
    max_switched=1,
    current_limits="stated",                   # or "skip", "derive_from_rate_a"
    stated_current_limits={"branches:1": (1.25, None)},  # per unit; None is unbounded
).value

inst.options     # the options above, as keyword arguments
inst.branches    # one dict per branch: id, initial_closed, switchable,
                 # switching_cost, stated_current, current

closed = [True] * len(inst.branches)
closed[0] = False
cost = inst.validate_topology(closed)          # 4.0
fixed, diagnostics = inst.fix_topology(closed)  # an AcOpfInstance, and what it drops

solution = powerio.AcOtsSolution.from_ac_opf_solution(inst, closed, ac_solution)
solution.branch_closed, solution.switching_cost
solution.branches_open, solution.branches_switched, solution.objective
solved = solution.solved_network()  # a BalancedNetwork module with the final statuses

inst.options spells the options as the keyword arguments, so module.to_ac_ots_instance(**inst.options) rebuilds the same switching options. validate_topology checks a final status vector, one boolean per branch in table order, against the branches that cannot switch, the budgets, and the islanding policy, and returns the switching cost; it does not check AC feasibility. A refused topology raises PowerIOError with code BUILD.INSTANCE.TOPOLOGY_INVALID, and refused options raise one with BUILD.INSTANCE.SWITCHING_OPTIONS_INVALID. fix_topology returns the AC OPF to solve over that topology and the diagnostics that report the switching data it drops; the instance’s module carries them as well. AcOtsSolution.from_ac_opf_solution attaches an AcOpfSolution of that problem, after checking that it solves exactly the fixed problem and that open branches carry no flow. A solution’s own network keeps the initial statuses; emit solved_network() to write the solved case.

Other functions

FunctionResult
resolve_format(name)the canonical FormatInfo for a token or alias, or None
features()which build features the installed extension carries
versions()the release, the PowerIO IR identity, and the BMOPF schema version
parse_geo(text, name_hint=None)a geographic layer in canonical form with its diagnostics
from_ppc(ppc)a BalancedNetwork from a pandapower or PYPOWER case dictionary
PioModule.from_value(value)a module around a value built in Python
diagnostic_record(diagnostic)one diagnostic as a JSON-ready dictionary
diagnostic_records(diagnostics)every diagnostic as a JSON-ready dictionary, in order
module.to_balanced_report(), module.to_balanced()the multiconductor to balanced transformation

GeoLayer.geojson returns the canonical .geo.json document for a layer, the GeoJSON FeatureCollection with the powerio_geo member that parse_geo reads. C returns the same text from pio_geo_layer_to_geojson.

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 reads and writes default to the directory captured at server startup. POWERIO_MCP_ALLOWED_ROOTS selects explicit directories instead; the compatibility settings POWERIO_MCP_ROOT and POWERIO_MCP_ALLOWED_ROOT follow it in precedence. 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 the C ABI 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.

The exported symbol set is fixed. The gridfm cargo feature adds GridFM Parquet parsing and emission behind the same entry points, and the 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 PowerIO IR schema name and version (powerio_ir with schema and version), the BMOPF schema version, the compiled features, and the diagnostic namespaces and error categories.

The Arrow C export was removed in 0.11.0, and PowerIO 0.12 removed the inert arrow build flag that 0.11 kept for source-build compatibility: a command with --features arrow no longer resolves, so drop the flag (for example cargo build -p powerio-capi --release --features matrix,gridfm,dist,prob). The Arrow record batches and Parquet support behind gridfm are unchanged.

Versions and compatibility

The header states the PowerIO release it was generated from as PIO_VERSION_MAJOR, PIO_VERSION_MINOR, and PIO_VERSION_PATCH, and pio_version_numbers() returns the release of the loaded library as a PioVersionView. pio_version() returns the same release as text. A prerelease such as 1.0.0-rc.1 states its core release, 1.0.0, in the numbers and the whole version in pio_version().

A program compiled against the header of release X.Y.Z works with any library that

  • is in the same release series, as Cargo defines it: the same major and minor numbers before 1.0 (0.12.x), the same major number from 1.0 on (1.x), and
  • is release X.Y.Z or newer.

Within a release series the C ABI only gains symbols: no symbol is removed, and no signature or struct layout changes. A break starts a new release series. Check the library before you use it:

static int library_matches_header(PioVersionView library) {
    if (library.major != PIO_VERSION_MAJOR) {
        return 0;
    }
    if (library.minor != PIO_VERSION_MINOR) {
        return PIO_VERSION_MAJOR > 0 && library.minor > PIO_VERSION_MINOR;
    }
    return library.patch >= PIO_VERSION_PATCH;
}

if (!library_matches_header(pio_version_numbers())) {
    /* the library is from another release series, or older than the header */
}

scripts/check-capi-header.py holds the header to that rule in CI. It compares powerio.h with the header of the newest release tag at or below the workspace version and fails when a function, struct, opaque type, or #define of that header is missing or declared differently; comments and parameter names do not count. A pull request that is meant to break the C ABI before the version moves carries the semver-major label, and once the workspace version starts a new release series the check lists the differences without failing.

Before 0.12 the header carried a separate ABI number; PowerIO 0.12 replaced it with the release. See From 0.11 to 0.12.

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 from a PioSource, opened from a path or built from memory. pio_geo_layer_diagnostics reports what that reader found, and pio_geo_layer_to_geojson writes the layer back as the canonical .geo.json document, the GeoJSON FeatureCollection with the powerio_geo member that pio_geo_layer_parse reads.

PioString *document = pio_geo_layer_to_geojson(layer, &error);
PioStringView geojson = pio_string_view(document); /* release with pio_string_release */

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 document header names the schema ("schema": "pio-ir") and its version, and pio_schema_report reports both under powerio_ir; the producer record names the program that wrote the document. pio_module_deserialize refuses an unsupported schema name or version, or a structural type the library does not implement, and reports what it found. PowerIO IR states which documents a release reads. The C ABI has no module JSON aliases.

PSS/E contingency analysis files

A contingency set is the content of a PSS/E .con file: named cases, each a list of outage actions. A subsystem is PSS/E’s name for a bus selection stated in a .sub file through bus, area, zone, owner and kV range selectors; a .con automatic specification and a .mon statement refer to a subsystem by name, and selecting a subsystem’s buses evaluates its selectors against a network. A monitored set is the content of a .mon file: the elements whose loading and voltage a study reports.

A .con, .sub, or .mon file parses through pio_parse like any other source; pio_value_contingency_set, pio_value_subsystem_set, and pio_value_monitored_set take the typed handle from the module value, and pio_contingency_set_parse reads a contingency file straight from an acquired source with pio_contingency_set_diagnostics for the reader’s notes. pio_emit writes each one back under psse-con, psse-sub, or psse-mon.

A handle from pio_value_contingency_set, pio_value_subsystem_set, or pio_value_monitored_set borrows the module value rather than copying it, and holds the module owner alive, so it stays readable after the module handle is released. A handle from pio_contingency_set_parse or pio_contingency_set_expand owns its set instead.

pio_contingency_set_resolve binds every case to a balanced network and returns a PioContingencyResolution. It reports rather than refuses: a case naming an element the network does not hold is counted unresolved and keeps its reason. pio_contingency_set_expand turns the automatic specifications into explicit cases against a network and a subsystem set.

PioContingencySet *cases = pio_contingency_set_parse(source, &error);
PioContingencyResolution *resolution =
    pio_contingency_set_resolve(cases, network, &error);

printf("%zu of %zu cases bound\n",
       pio_contingency_resolution_resolved_count(resolution),
       pio_contingency_resolution_case_count(resolution));

for (size_t i = 0; i < pio_contingency_resolution_case_count(resolution); i++) {
    size_t bound =
        pio_contingency_resolution_case_component_count(resolution, i);
    for (size_t j = 0; j < bound; j++) {
        PioContingencyComponentView component;
        if (!pio_contingency_resolution_case_component(resolution, i, j,
                                                       &component, &error)) {
            break;
        }
        /* component.id.component_type names the table component.row
           indexes; component.id.local_id is the element's own identity,
           and its len is 0 when the network states none for that row */
    }

    size_t missing =
        pio_contingency_resolution_case_unresolved_count(resolution, i);
    for (size_t j = 0; j < missing; j++) {
        PioStringView statement =
            pio_contingency_resolution_case_unresolved_action(resolution, i, j,
                                                              &error);
        PioStringView reason =
            pio_contingency_resolution_case_unresolved_reason(resolution, i, j,
                                                             &error);
        /* statement is the `.con` line of the action; reason is a fixed name
           such as "no_such_branch", the same name Python reports */
        printf("%.*s: %.*s\n", (int)statement.len, statement.data,
               (int)reason.len, reason.data);
    }
}

PioDiagnostics *notes = NULL;
PioContingencySet *expanded =
    pio_contingency_set_expand(cases, network, subsystems, &notes, &error);
PioString *text = pio_contingency_set_to_con(expanded, &error);
PioStringView view = pio_string_view(text);
printf("%.*s", (int)view.len, view.data);

pio_string_release(text);
pio_diagnostics_release(notes);
pio_contingency_set_release(expanded);
pio_contingency_resolution_release(resolution);
pio_contingency_set_release(cases);

pio_balanced_network_select_subsystem_buses evaluates one named subsystem’s selectors against a network and returns the buses it selects, in ascending order, as an owned PioVector whose values are bus numbers.

PioVector *buses =
    pio_balanced_network_select_subsystem_buses(network, subsystems, "A1", 2, &error);
PioF64View numbers = pio_vector_values(buses); /* release with pio_vector_release */

The set accessors are pio_contingency_set_case_count, pio_contingency_set_case_name, pio_contingency_set_diagnostics, and pio_contingency_set_to_con; pio_subsystem_set_count, pio_subsystem_set_name, and pio_subsystem_set_to_sub; and pio_monitored_set_statement_count and pio_monitored_set_to_mon. Each of the three writers returns owned text, read with pio_string_view and released with pio_string_release, which is how an expanded set reaches a file. pio_balanced_network_select_subsystem_buses reads a network and a subsystem set together and hands back an owned PioVector, read with pio_vector_values and released with pio_vector_release. The resolution accessors are pio_contingency_resolution_case_count, pio_contingency_resolution_resolved_count, pio_contingency_resolution_unresolved_count, pio_contingency_resolution_unrecognized_statement_count, pio_contingency_resolution_case_name, pio_contingency_resolution_case_is_resolved, pio_contingency_resolution_case_component_count, pio_contingency_resolution_case_component, pio_contingency_resolution_case_unresolved_count, pio_contingency_resolution_case_unresolved_reason, and pio_contingency_resolution_case_unresolved_action. Each handle has its own pio_contingency_set_retain and pio_contingency_set_release, pio_subsystem_set_retain and pio_subsystem_set_release, pio_monitored_set_retain and pio_monitored_set_release, and pio_contingency_resolution_retain and pio_contingency_resolution_release.

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.

AC optimal transmission switching has its own entry points.

  • Build an instance.
    • pio_module_to_ac_ots_instance builds one with the default options from a balanced network or AC OPF module.
    • pio_module_to_ac_ots_instance_with_options takes a PioAcOtsOptions, and also reconfigures an AC OTS module. NULL options are the same as pio_module_to_ac_ots_instance.
    • pio_ac_ots_instance_create combines an AC OPF instance handle with options and keeps its objective exactly.
  • Read an instance. pio_value_ac_ots_instance returns the instance view.
    • pio_ac_ots_instance_options reads its stated options and branch count.
    • pio_ac_ots_instance_branch_at reads one branch’s initial status, whether it may switch, its costs, and its current limits.
  • Check and fix a topology. A final topology is one byte per branch: 0 is open and 1 is closed.
    • pio_ac_ots_instance_validate_topology checks it and writes its switching cost.
    • pio_ac_ots_instance_fix_topology returns the AC OPF module over it.
  • Attach and read a solution.
    • pio_ac_ots_solution_create attaches that AC OPF problem’s solution.
    • pio_value_ac_ots_solution returns the solution view.
    • pio_ac_ots_solution_summary reads the open and switched counts, the switching cost, and the objective.
    • pio_ac_ots_solution_branch_closed_at reads one final status.
    • pio_ac_ots_solution_materialize returns the network with the final statuses and solved values, ready for pio_emit.

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.

pio_calc_dc_operators builds the same operators once and returns a PioDcOperators handle whose axes are named: pio_dc_operators_bus_ids maps each bus row to its source bus id, pio_dc_operators_branch_rows maps each branch row to its position in the branch table (three winding transformer windings follow the branches), and pio_dc_operators_branch_identity states the stable identity of one branch row. Out of service branches and self loops have no row. The skip_zero_impedance argument drops a zero impedance branch and lists it under pio_dc_operators_skipped_branch_rows instead of failing the build with BUILD.OPERATOR.ZERO_IMPEDANCE. The eight calculations run over the handle as pio_dc_operators_incidence_matrix, pio_dc_operators_branch_susceptances, pio_dc_operators_bus_susceptance_matrix, pio_dc_operators_branch_flow_matrix, pio_dc_operators_branch_phase_shift_injection, pio_dc_operators_bus_phase_shift_injection, pio_dc_operators_branch_flow_dc, and pio_dc_operators_bus_injection_dc; release the handle with pio_dc_operators_release.

Distribution loads with voltage bands, dropout or current limits use pio_multiconductor_network_load_details_at. Its borrowed voltage-law view keeps nominal voltages, ZIP fractions or exponents, and every transition bound. Presence flags distinguish absent bounds from zero. The existing load view keeps its original layout and rejects laws it cannot describe.

pio_mc_ac_pf_instance_load_details_at returns prescribed power arrays and the same complete law. pio_mc_ac_pf_instance_load_terminal_name_at reads the full terminal map; power channels can have fewer entries than that map when it includes a reference conductor. Keep the network or instance handle alive while using any borrowed string or numeric array. These accessors do not serialize or clone the network.

pio_balanced_network_islands partitions a balanced network into AC islands with the Rust calc_islands rule and returns a PioIslands handle. pio_islands_count and pio_islands_at read one PioIslandView per island, largest first: its bus positions and ids, its reference buses, its in service generators and HVDC ties, and whether a generator supplies it. pio_islands_isolated_bus_ids and pio_islands_isolated_bus_indices list the buses typed isolated, which belong to no island. Release the handle with pio_islands_release.

pio_calc_sensitivities computes the DC PTDF and LODF through the routine the Python binding calls and returns a PioSensitivities handle. The formula is chosen as for the DC operators, and the solver is auto, dense, or sparse. Every reference bus is grounded, one per island, and its PTDF column is zero. pio_sensitivities_ptdf (branches by buses) and pio_sensitivities_lodf (branches by branches) are dense row major spans borrowed from the handle; pio_sensitivities_bus_ids, pio_sensitivities_branch_rows, pio_sensitivities_branch_identity, and pio_sensitivities_reference_bus_indices name the axes, which are the DC operators’ axes. Release the handle with pio_sensitivities_release.

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 verify case.raw --stated-state             # AC bus balance at the stored voltages
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, contingency resolve and contingency expand, which bind PSS/E .con, .sub, and .mon files to a case and expand a .con file’s automatic specifications, as described in PSS/E contingency analysis files, corpus, the private corpus harness described in Corpus harness, and tui. dcopf accepts the alias dc-opf. --from accepts the network and calculation format tokens and aliases in the format table. --to accepts their supported output formats except GridFM; use the gridfm subcommand to write those datasets. iidm and rawx are input spellings only. The geographic layer, PowerWorld display, and PSS/E contingency file tokens are not --from values: the geo and contingency subcommands read those files.

convert, summary, and verify take --merge-buses SPEC, which merges buses before the command runs (see Merging buses). SPEC is switches for closed switches, exact for those and branches with r = 0 and x = 0, psse for those and PSS/E zero impedance lines at the case’s THRSHZ, psse=<x> for the same at threshold x, or impedance=<z> for closed switches and non-transformer branches whose impedance magnitude is at most z. summary adds a bus_merge block with the counts. Its topology.islands block lists the AC islands with their bus counts, reference buses, generators, and HVDC ties to other islands, and counts the unsupplied islands an HVDC line still feeds (see Islands and reference buses).

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

StatusMeaning
0success
1a failure without a PowerIO error category
2request: the arguments name something the request cannot satisfy (a format the writer cannot produce, a missing --from for standard input); clap usage errors also exit 2
3io: a path could not be read or written
4parse: the input is malformed, or a refused include left the output incomplete
5data: valid input that the operation cannot satisfy
6output: the writer could not produce the requested format

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, and about. parse reads a PowerWorld .pwd display to a GeoLayer; the display tool, which returned the raw display record, was removed in 0.12. 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. calc_matrix names both axes of every result: row_ids and col_ids carry bus ids or branch identities, skipped_branch_rows lists the zero impedance branches dropped under skip_zero_impedance, and six of the eight DC calculations (incidence, branch_susceptances, bus_susceptance, branch_flow, branch_phase_shift_injection, bus_phase_shift_injection) join the matrix names, a vector coming back as {"format": "vector", "data": [...]}. The other two, calc_branch_flow_dc and calc_bus_injection_dc, need voltage angles and are not matrix names. Those six take skip_zero_impedance, as do bprime, bdoubleprime, admittance_real, admittance_imag, and lacpf; ptdf, lodf, adjacency, and weighted_laplacian reject it rather than ignoring it. 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 reads and writes default to the directory captured at server startup. POWERIO_MCP_ALLOWED_ROOTS selects explicit directories instead. Remote URI schemes are rejected. A directory input is held to the bounds PowerIO’s own directory listing keeps, counted the same way: no subdirectory may sit 64 levels below it, and the files found plus the subdirectories not yet listed may never pass 4,096 while the server walks it.

Tool arguments come from the client, so the server parses them under smaller byte limits than the 1 GiB library defaults meant for local use. When powerio-mcp or python -m powerio.mcp starts, it sets POWERIO_MAX_PRIMARY_BYTES and POWERIO_MAX_REFERENCED_BYTES to 256 MiB (268435456 bytes) for whichever of the two the host environment leaves unset or empty. That leaves room for a case such as CIM bench’s RealGrid, whose CGMES archive expands to 82.5 MiB of XML. A file named by path may hold at most the primary limit, checked before memory is reserved, and the files a case references or a directory holds share the referenced limit. Inline content and powerio_ir arguments are held to the primary limit in UTF-8 bytes and refused before parsing. The stdio transport reads and decodes each request whole before any tool runs, so these limits bound what the server parses, not the size of a request. To accept larger inputs, set either variable in the server’s environment to a positive decimal byte count; the server keeps any value the operator sets. Importing powerio.mcp changes neither setting.

Outside the server, both limits default to 1 GiB for Rust, C, Python, and Julia path-based acquisition. CGMES XML counts against the referenced limit from a path or from memory, so a CGMES file above 1 GiB needs both settings raised. XIIDM and JIIDM documents keep a fixed 64 MiB limit, and an OpenDSS case stops following includes once they have loaded 64 MiB of script text, unless --dss-max-include-bytes raises that for convert, summary, or serialize. Resource limits lists every limit.

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. Optional Python NetCDF/HDF5 transports use this same profile; see Sienna and pipeline exchange. 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. Distribution CIM support is the CIM100 node breaker profile with per phase equipment and the CIM16 LV feeder profile; controls, distributed energy resources, wire geometry, and limits are reported rather than mapped. A ZIP archive or a folder of related files is read through an input collection.
  • 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.
  • Transient-stability .dyr files parse into a loss-preserving DynamicCase and pair with a steady-state BalancedNetwork through DynamicStudy. The current link check validates bus references only; model-specific device schemas, typed machine/control views, cross-format dynamics conversion, and PowerWorld AUX dynamics views remain future work. See Dynamics and DYR.
  • Balanced to multiconductor construction, load linearized multiconductor admittance from an operating point, and a general multi period planning instance are not part of 0.12.
  • 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, PSS/E RAW, UCTE-DEF, and IEEE CDF 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, one per kind of binding. Rust records, Python dict rows, and PowerIO IR use the data model’s names, derived from MATPOWER (vm, pg, rate_a, tap); the C ABI and Julia spell out the quantity and unit (vm_pu, active_power_mw, rate_a_mva, tap_ratio). Both are stable through 0.12.x.
  • Python tables return dict rows; typed element views like Julia’s are not offered yet.
  • serialize_diagnostics returns the JSON text of a diagnostics array, where serialize returns an EmitResult: a diagnostics array is not a module document and has no artifacts or findings of its own.
  • Public powerio-matrix signatures return sprs::CsMat, and some public coefficient types contain num_complex::Complex64. These dependencies are part of PowerIO’s compatibility guarantees. Their pre-1.0 versions do not inherently prevent PowerIO 1.0, but changing their public types would break consumers. Before 1.0, choose either a documented commitment to those types throughout PowerIO 1.x or owned matrix/complex interfaces with explicit adapters. That decision remains open; updating a lockfile alone does not settle it.

Path to 1.0

The 0.12 API separates source/provenance (PioModule) from electrical values, keeps balanced and conductor-resolved networks distinct, and derives matrices and problem instances explicitly. A new format maps to a shared model instead of requiring pairwise converters. Owner-rooted C/Julia handles and lazy Python access avoid using serialized IR as an internal binding protocol. These are useful stable boundaries; a 1.0 promise still needs evidence for their semantics.

Before the next breaking bump, close the conventions and reference/slack questions (#700, #713), decide the exposed guarantees for numerical types above, and review the public 1.0 milestone’s remaining CGMES difference models, boundary assembly and DGS reader work (#459, #457, #150). A feature can be explicitly deferred by maintainers; it must not silently disappear from the milestone. Require compatibility checks against the last published series, binding parity, archived-schema reads, and independently validated conversion profiles. Unsupported target features need truthful diagnostics, not an all-green matrix.

Keep one release series as the compatibility boundary. Do not introduce another ABI counter or restart an independent IR counter: the C interface uses the release series, and each published schema names that release, even when its payload layout is unchanged. The release check requires the schema identifier to match the core release version; prerelease suffixes remain in producer metadata. Published snapshots remain immutable. This avoids a separately managed schema counter. At 1.0 the stable series becomes 1.x rather than 0.12.x. This is a path to a stable API, not a claim that today’s outstanding decisions are already resolved.

Versions

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

BoundaryValue in 0.12.xChecked whereMoves when
PowerIO release0.12.zthe manifests, powerio::VERSION, powerio.versions(), pio_versionevery release
C ABIthe release series, 0.12.xpio_version_numbers against the header’s PIO_VERSION_* at loada release removes or changes a C symbol, which starts a new series
PowerIO IRthe release whose schema a document follows, "0.12.0"the document header, powerio::IR_VERSIONevery published release; supported types read within the same series, plus 0.11’s 2
Rust toolchain1.89rust-version in the workspace manifest, checked by CIa dependency in the locked graph requires a newer compiler
Python3.11 or laterpyproject.tomla dependency drops a version

Within the 0.12.x series, releases are compatible: the public Rust, Python, and Julia APIs only gain items, the C ABI only gains symbols, and a release reads older documents in the series. An older reader can read newer documents of types it supports and explicitly refuses unknown structural types. A break to an existing type waits for the next series. Before 1.0 a series is one minor release, as Cargo defines it. CI checks the publishable crates against the latest release tag with cargo-semver-checks (scripts/check-semver.sh), and the C header against the latest release header (scripts/check-capi-header.py); a pull request that carries a break is labeled semver-major. See PowerIO IR for the document rule and From 0.11 to 0.12 for what changed.

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)?)?;
0.100.11
parse(Source::open(path)?, None)parse(path)
parse(source, Some(format))parse_with_options(source, &ParseOptions::default().format(format)?)
emit(&module, format, Destination::path(path))emit(&module, format, path)
serialize(&module, Destination::path(path))serialize(&module, path)
deserialize(Source::open(path)?)deserialize(path)
network.to_json()serialize(&PioModule::new(network), destination)
BalancedNetwork::from_json(text)deserialize(Source::from_memory("module.pio.json", text)?)?.into_value()
parse_display(source, from)parse(input), which returns PioValue::GeoLayer; PwdDisplay remains for the raw display record
DisplayData, DisplayFormatremoved from Rust; Python keeps parse_display and DisplayData for the raw PowerWorld display record through 0.11.x, and 0.12 removes them
a layer written by handemit(&module, "geo-json", path)

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 in PowerIO 0.11.1; the producer record names the PowerIO release separately. The reader accepts IR version 2. Documents older than version 2 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. The LinDist3Flow OPF pair arrived in 0.11.1, the LinDist3Flow power flow pair in 0.11.4, and the AC optimal transmission switching pair in 0.11.7.

DcPfInstance              DcPfSolution
AcPfInstance              AcPfSolution
DcOpfInstance             DcOpfSolution
AcOpfInstance             AcOpfSolution
AcOtsInstance             AcOtsSolution
McAcPfInstance            McAcPfSolution
McAcOpfInstance           McAcOpfSolution
LinDist3FlowPfInstance    LinDist3FlowPfSolution
LinDist3FlowOpfInstance   LinDist3FlowOpfSolution
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.

From 0.11 to 0.12

PowerIO 0.12 starts a new release series. From 0.12 on, the release series says what is compatible with what: within 0.12.x, newer readers keep reading older PowerIO IR documents, and the C ABI only gains symbols. Older readers accept newer documents for supported types and refuse unknown structural types. This page lists what changes for code and data written against 0.11.

PowerIO IR documents

The header’s version was the integer 2 in every 0.11 document. From 0.12 it names the release whose schema the document follows, as a string:

{
  "schema": "pio-ir",
  "version": "0.12.0",
  "producer": { "name": "powerio", "version": "0.12.0" }
}

producer is unchanged. It names the software that wrote the document, which need not be PowerIO, and it does not decide whether a document is read.

Reading. PowerIO 0.12.x reads:

  • a document whose version is any 0.12 release, "0.12.0" through "0.12.z", including one later than the reader. A later release can add structural types; a reader refuses a type it does not implement and keeps reading the others.
  • every 0.11 document, "version": 2, with the same meaning. Serializing it again writes "version": "0.12.0".

It refuses everything else with READ.MODULE.UNSUPPORTED, naming the version and producer the document states. A later release series ("0.13.0", "1.0.0") needs a newer PowerIO. An earlier release, the integer 1 of a 0.10 document, or a string that is not a MAJOR.MINOR.PATCH release has to be regenerated from its source data.

0.11 readers. A 0.11 release refuses a 0.12 document. Its message names version "0.12.0" and says to regenerate the document; read it with PowerIO 0.12 instead. A consumer that has to stay on 0.11 needs documents written by 0.11.

Rust. powerio::IR_VERSION is now a &str, "0.12.0", and powerio::IR_MIN_VERSION is gone. Code that compared the integer should compare the release series instead, or leave the decision to deserialize. powerio::IR_SCHEMA_ID is https://powerio.dev/schema/pio-ir/0.12.0/schema.json.

Python. powerio.versions()["powerio_ir"] is now {"schema": "pio-ir", "version": "0.12.0"}, with the version a string.

C. The JSON that pio_schema_report returns states powerio_ir.version as the release string, "0.12.0", instead of the integer 2.

Code that inspects documents. To recognize PowerIO IR, check "schema": "pio-ir" and let deserialize decide whether it reads the version. A check for "version": 2 no longer matches the documents 0.12 writes.

Schema files. Each release publishes its own schema at docs/schema/pio-ir/<release>/schema.json, served from https://powerio.dev/schema/pio-ir/<release>/schema.json, so a document’s version names its schema file directly. Validate a 0.12 document against the file its version names. The 0.11 files under pio-ir/2/ keep their bytes and identifiers, and still describe 0.11 documents. See PowerIO IR for the rule and docs/schema/README.md for every file.

C ABI

PowerIO 0.11 gave the C ABI its own number, 7, which a program compared with the library at load. The number only ever changed when a new release series began, so PowerIO 0.12 removes it and states the release instead.

Removed, with no alias:

  • the PIO_ABI_VERSION macro;
  • pio_abi_version();
  • the abi key of the pio_schema_report document.

Added:

  • PIO_VERSION_MAJOR, PIO_VERSION_MINOR, and PIO_VERSION_PATCH, the release the header was generated from;
  • pio_version_numbers(), which returns the release of the loaded library as a PioVersionView with major, minor, and patch fields.

pio_version() still returns the release as text. A prerelease such as 1.0.0-rc.1 states its core release, 1.0.0, in the numbers and the whole version in pio_version().

A program compiled against the header of release X.Y.Z works with any library that is in the same release series, as Cargo defines it (the same major and minor numbers before 1.0, the same major number from 1.0 on), and is release X.Y.Z or newer. Within a release series the C ABI only gains symbols: no symbol is removed, and no signature or struct layout changes.

0.110.12
pio_abi_version() == PIO_ABI_VERSIONpio_version_numbers() is in the header’s release series, at the header’s release or newer (the check in C)
#if PIO_ABI_VERSION != 7#if PIO_VERSION_MAJOR != 0 || PIO_VERSION_MINOR != 12
"abi" in the pio_schema_report document"powerio_version"

A 0.11 library has no pio_version_numbers. A program that loads the library with dlopen or LoadLibrary can look the symbol up first and treat its absence as a library older than 0.12.

PowerIO.jl applies the same rule. It removes abi_version() and keeps library_version(). Before its first call into a library, PowerIO.jl checks that the library is in the release series of the header it was generated from, at that release or a newer one. It refuses a library from another series, an older library, or one without pio_version_numbers, and names both releases in the error.

Three winding transformer magnetizing admittance

Transformer3W gains magnetizing_connection, which says where mag_g and mag_b connect: StarPoint, between the star point and ground, or Winding1Terminal, between winding 1’s bus and ground outside its ratio. 0.11 placed every three winding magnetizing admittance at the star point, which is what IIDM and CGMES state but not what PSS/E states (#741). For a unit with an off-nominal winding 1 ratio the difference reached |Ym| in Y_bus.

  • The PSS/E RAW and RAWX readers state Winding1Terminal; the XIIDM, JIIDM, and CGMES readers state StarPoint.
  • The star lowering, and so every matrix, puts a Winding1Terminal admittance on winding 1’s branch as from side charging Ym * tap1², so bus 1 sees Ym.
  • A PowerIO IR document states the field only when it is not the star point, so every 0.11 document reads with the meaning it had.
  • PSS/E written from star point data, and XIIDM, JIIDM, or CGMES written from PSS/E data, keep the value and report the moved placement with VALUE_SUBSTITUTED.
  • C: PioBalancedThreeWindingTransformerView ends with a magnetizing_connection string view. Julia: ThreeWindingTransformer ends with magnetizing_connection::String. Python rows carry magnetizing_connection when it is not "star_point".

XIIDM and JIIDM signs

An IIDM battery states targetP, targetQ, and its reactive limits as generation, positive into the network. PowerIO storage states ps and qs as withdrawal, positive when charging. 0.11 copied the battery values into storage unchanged, so a discharging battery read as charging. 0.12 negates them: ps = -targetP, qs = -targetQ, qmin = -maxQ, and qmax = -minQ, and the writers state the inverse.

A converter station’s terminal q is the flow from the bus into the station, while Hvdc::qf and qt are injected into the bus. 0.12 reads the terminal q as the negated qf or qt and writes the inverse; the reactivePowerSetpoint, already an injection, is unchanged (#700).

Storage values or HVDC terminal reactive powers read from XIIDM or JIIDM with 0.11, including PowerIO IR documents 0.11 wrote from those sources, carry the opposite sign. Read the original XIIDM or JIIDM file again with 0.12; do not negate the values by hand in data that mixes sources, because values read from other formats were already correct.

Renamed for consistency

  • SocwrOpfSolution names its branch flows as the other solutions do: branch_from_active_flow, branch_from_reactive_flow, branch_to_active_flow, and branch_to_reactive_flow (they ended in _power), in the Rust values and accessors, the PowerIO IR keys, and the quantity names the C ABI’s solution value accessor takes. The reader still accepts the 0.11 keys. Its bus_order and branch_order return vectors, as every other solution’s do.
  • to_balanced and to_balanced_report are also exported at the facade root, beside the other transformations; powerio::transform keeps them.

Graph data

IndexedNetwork::to_petgraph is removed, and powerio-tx no longer depends on petgraph, a crate before its own 1.0 whose type was in PowerIO’s public API. IndexedNetwork::branch_edges() yields the same topology, one (branch, from, to) per in-service branch over dense bus indices. To keep a petgraph graph, add petgraph to your application’s dependencies. With an existing IndexedNetwork named view, add view.n() nodes and one edge per item:

let mut graph = petgraph::graph::UnGraph::<usize, usize>::with_capacity(view.n(), 0);
let nodes: Vec<_> = (0..view.n()).map(|bus| graph.add_node(bus)).collect();
for (branch, from, to) in view.branch_edges() {
    graph.add_edge(nodes[from], nodes[to], branch);
}

Removed compatibility shims

PowerIO 0.11 kept these only so that 0.11.x code kept working; 0.12 removes them with no alias.

0.110.12
Python powerio.parse_display(path), which returned DisplayData(kind, PwdDisplay(...))powerio.parse(path), which returns a GeoLayer with diagnostics and reads under the input byte limits
Python DisplayData, PwdDisplay, PwdSubstationthe GeoLayer features; Rust keeps PwdDisplay and to_geo_layer_from_pwd
the MCP server’s display toolthe parse tool, which returns the GeoLayer as PowerIO IR
powerio-capi’s inert arrow Cargo featureomit it: cargo build -p powerio-capi --release --features matrix,gridfm,dist,prob

parse refuses a .pwd file whose bus identity tables are ambiguous or repeated, or whose header decodes but places nothing, with PARSE.SOURCE.MALFORMED; parse_display returned the substations of such a file. The display’s save stamp, an undocumented header number the reader uses to recognize drawing records, is not part of the GeoLayer.

Numeric thermal ratings

Branch and winding ratings remain ordinary numbers in Rust, Python, C, and Julia. In 0.12, zero means a zero apparent-power bound and positive infinity means no bound. Neither changes equipment status, impedance, or connectivity. The existing thermal-rating update accepts these same values. Normalization converts MVA to per unit; zero and infinity keep their meaning.

Readers and writers translate format conventions. MATPOWER uses zero for no bound; Egret uses null or an absent field. Egret numeric zero stays zero. Writers report values a target cannot represent rather than silently changing the constraint. Sienna and PowerSystems JSON, which need a number, state no bound as PowerSystems’ INFINITE_BOUND (see Sienna exchange). NaN is not accepted as a usable thermal bound.

PyPSA bounds a passive branch by s_nom * s_max_pu, and the readers now do the same. PyPSA’s default s_nom is 0, so a non-extendable line or transformer that leaves s_nom unset, as power-flow-only networks often do, reads as a zero bound, where 0.11 read it as no bound and ignored s_max_pu. An OPF over such a network holds those flows at zero and is usually infeasible. The read reports the count with READ.PYPSA.THERMAL_BOUND_ZERO. State a positive s_nom, with s_max_pu = inf for no bound. An extendable branch (s_nom_extendable = True) is bounded by s_nom_max * s_max_pu, unbounded by default.

PowerIO IR uses its existing nonfinite encoding: "Infinity" in JSON. The document version distinguishes 0.11 files, where zero meant no bound, from 0.12 files. No thermal-specific record wrappers are needed. See also DC OPF bundles for the corresponding numeric output change.

Python table rows state a nonfinite value as a float in every table, so math.isinf(row["qmaxf"]) holds for an unlimited bound. In 0.11 the hvdc, storage, static_var_compensators, areas, and distribution table rows carried the IR’s "Infinity" and "-Infinity" strings instead; a text field that reads "Infinity" stays text.

PowerIO 0.11.12 and earlier read a native Egret zero as no bound. Regenerate affected data from the original Egret input; an old IR document cannot recover a distinction its producer discarded.

Egret files that PowerIO 0.11.10 or earlier wrote may have a 0 in a mixed rating series where the model meant unlimited; 0.12 reads that 0 as a zero bound. Regenerate them from the original model with 0.11.11 or later, which writes null there.

BMOPF output

There is one BMOPF. PowerIO 0.12 reads and writes the schema proposed in dsopt-schema#2, vendored from the Task Force repository at commit 6796394. Its pin moves to the release tag the schema’s $id names once the Task Force ratifies it.

0.110.12
--to bmopf-json@<version>, emit(module, "bmopf-json@<version>")refused; write bmopf-json
BmopfSchemaVersion, BmopfEmitOptions::with_schema_versionremoved; there is nothing to select
BMOPF_SCHEMA_VERSIONremoved; a written document’s meta.schema_version is the release the schema’s $id names
bmopf::BMOPF_PROPOSAL_URLthe function bmopf::bmopf_proposal_url()
bmopf_schema in pio_schema_report and powerio.versions(), a version numberthe schema’s $id
BmopfEmitOptions::sideload_coordinatesremoved; geometry is in the typed bus.*.geo, line.*.geo and meta.crs slots
bus bounds written as v_min/v_maxwritten as vpg_min/vpg_max
bus neutral to ground cap written as vn_maxwritten as vng_max
meta.$schema stating a PowerIO archive URLno meta.$schema; meta.schema_version, which the schema requires, is the one identifier, and the schema’s $id is in meta.provenance
bus vn_maxvng_max
regulator tap_ratio, tap_ratio_min, tap_ratio_maxvoltage_ratio, voltage_ratio_min, voltage_ratio_max
prime_mover: "DSTATCOM", p_unit/q_unit VA_FRACTION, dc_control: "droop"STATCOM, PU, DROOP
line s_max per phaseone entry per conductor; a per-phase array is dropped on write
an absent meta.crs read as EPSG:4326read as OGC:CRS84; both are WGS84 longitude then latitude

Multiconductor IVR preparation changes three results. A fixed inverter power factor follows the OpenDSS sign convention, pf > 0 putting Q on the same side as P, so McOpfCoil::power_factor_coefficients is [a, -pf] where it was [a, pf], and reactive_slope changes sign. A type-A regulator prepares with the regulated over source ratio and tap_inverse = true, as type B does. An inverter’s energy_cost_rate sets its dispatch cost.

Documents from older BMOPF drafts, PowerIO 0.11 output among them, still read, as BMOPF, with one READ.BMOPF.SCHEMA_LEGACY warning. A consumer that still needs an older draft’s document has to keep its source file: writing such a document, even unchanged, produces the current schema.

Conversion output

No action is needed unless a consumer compares output byte for byte or validates it against a closed schema.

  • PowerModels JSON and egret JSON documents carry more PowerIO keys, which both tools ignore: areas, case metadata, the detailed connectivity hierarchy, the coordinate reference, element identities and rating sets, and typed fields such as transformer and switched shunt controls. Format fidelity lists them. A consumer that rejects unknown keys has to allow them.
  • A MATPOWER branch matrix with the solved flow columns PF, QF, PT, and QT reads them as the branch solution, and the MATPOWER writer states them when every branch has a solution, so such a branch matrix has 17 columns instead of 13.
  • The PMD ENGINEERING writer writes a generator control_mode the source stated.

Toolchain

The Rust MSRV is 1.89 (it was 1.88), because rusqlite 0.41 and uuid 1.27 require it. Python wheels need Python 3.11 or later, as they did in 0.11.9.

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": "0.12.0",
  "producer": { "name": "powerio", "version": "0.12.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, distribution CIM, 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/0.12.3/schema.json and served from https://powerio.dev/schema/pio-ir/0.12.3/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:

fieldmeaning
producerthe software operation that created this module
sourcessource names, sizes, declared formats, and digests
source_mapJSON Pointer paths in value.data mapped to source byte ranges
diagnosticsstructured findings with stable codes and severities
historyordered derivations that produced the current value
extensionsnamespaced data outside the PowerIO core schema

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, PSS/E RAW, UCTE-DEF, and IEEE CDF 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.

A transformer with nondefault per-winding service flags is stored as a nested record in its physical table, with type equal to "powerio.PartialTransformer3W" and the complete transformer body under value. The nested body preserves every original field and all three winding rows; it is not a star expansion or an altered electrical network. Earlier readers reject this new record because its required transformer fields are not at the outer level. Default winding states retain the historical unwrapped representation, including when the whole transformer is off. Malformed wrappers and unwrapped nondefault winding states are rejected, never silently treated as all-on.

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.

Stored collections have two entry bounds. Operating point and solution vectors follow the network’s dimensions: each StoredQuantity’s identities and values, and every bus, branch, generator, terminal, source, and conductor array of a DC, AC, SOCWR, multiconductor, or LinDist3Flow solution, optional arrays included, carries at most 4,194,304 (2^22) entries. A multiconductor solution has one entry per bus terminal, so solutions over up to 4,194,304 bus terminals round trip. The reader refuses the first entry past the bound with READ.MODULE.INVALID, and serialize refuses a longer vector with EMIT.MODULE.RECORD_CAP rather than write a document the reader refuses. Time series and scenario sets carry at most 65,536 entries each, as do the three winding transformer power records of a solution. A stored operating point names at most 64 quantities.

These bounds count entries, not bytes. Byte limits apply when PowerIO reads a source. A file named by path, whether a raw format (including BMOPF) or stored IR, may hold up to 1 GiB; POWERIO_MAX_PRIMARY_BYTES sets a different positive decimal byte count. The files a case references and the files of a directory input share a cumulative limit, POWERIO_MAX_REFERENCED_BYTES, also 1 GiB by default. Both settings come from the process environment. The MCP server sets both to 256 MiB when its operator leaves them unset; see The MCP server.

CGMES XML counts against the referenced limit wherever it comes from. The profiles of one CGMES parse, read from files or expanded from ZIP archives, total at most POWERIO_MAX_REFERENCED_BYTES, and a CGMES XML document or archive larger than that limit is refused whether it comes from a path or from caller-owned memory. A CGMES file above 1 GiB named by path therefore needs both settings raised. An archive may hold at most 4,096 entries, a count read from its end records before the archive is indexed, and at most eight end records. Entries may not share a name or any bytes, and each must lie inside the archive’s entry data. Each file entry may declare at most the referenced limit and at most 200 times its compressed size. An XML entry may declare no more than the budget the profiles before it left, and it must inflate to exactly the size it declares. Nested archives, symbolic link entries, unsafe entry names, document type and entity declarations, and invalid UTF-8 are refused. These archive checks are fixed; only the byte limit is configurable.

Some readers keep limits below these defaults. An XIIDM or JIIDM document holds at most 64 MiB, from a path or from memory. An OpenDSS case follows at most 4,096 includes and stops following them once they have loaded 64 MiB of script text, counting a file again each time the case runs it. It also retains at most 4,194,304 property assignments and edit records across all its objects. A region with several hundred thousand lines and loads passes both the 64 MiB and the property limit; a caller that trusts the case raises them with DssReadLimits in Rust (ParseOptions::dss_limits, or powerio_dist::parse_with_dss_limits), with dss_max_include_bytes and dss_max_properties in Python’s powerio.parse, or with --dss-max-include-bytes and --dss-max-properties in the CLI. The 4,096 include count is fixed.

Apart from CGMES, XIIDM, and JIIDM, caller-owned memory has no whole-document limit; format and record limits still apply. Stored solutions embed their instance and network, so they can exceed the raw input’s size. Consumers should check the actual serialized byte length against their reload limit before saving, and choose a smaller limit for memory-constrained applications. The byte limits do not bound process memory.

Versions and release series

The header’s version names the release whose schema the document follows: "0.12.3" for a document this build writes, described by pio-ir/0.12.3/schema.json. powerio::IR_VERSION is that release and powerio::IR_SCHEMA_ID the $id of its schema file. producer names the software that wrote the document, which need not be PowerIO; the reader reports it and ignores it when deciding whether to read the document.

Compatibility follows the release series as Cargo defines it: one minor release before 1.0 (0.12.x), then one major release (1.x, 2.x). Within a release series, any release reads PowerIO IR documents written by any other release in it, including a later one. A later release in the series can add structural types, add names to a list of allowed values, and add a distinctly tagged alternative to a record; every existing definition keeps its exact text. A reader refuses a document that uses a type or name it does not implement and keeps reading documents that use only the ones it knows. A change that existing readers could not read, such as a new field on an existing record or a different meaning for an existing one, starts a new release series.

PowerIO 0.12 also reads the documents every 0.11 release wrote. Those state the integer "version": 2, and 0.12.0 keeps every record layout they use, so they decode as they did in 0.11. A 0.11 reader refuses a 0.12 document by its string version, whatever its value holds. Its message names the version and says to regenerate the document; upgrading the reader to 0.12 also works.

The reader refuses every other version and reports the schema name, version, and producer the document states, with the remedy: a string from a later release series ("0.13.0", "1.0.0") needs a newer PowerIO, and an earlier release, the integer 1 of a 0.10 document, or a string that is not a MAJOR.MINOR.PATCH release has to be regenerated from its source data.

Every release from 0.12.0 on publishes its own schema file at pio-ir/<release>/schema.json, and no release reuses an earlier one. The 0.11 files under pio-ir/2/, and every earlier file, keep their exact bytes and identifiers. A test compares the current schema with every 0.11 file and with the file of every earlier release in its series, so a definition that a reader of the series understands cannot change. docs/schema/README.md lists every schema file, what each release added, and the document header each describes.

Other intermediate representations answer the versioning question differently. LLVM bitcode records a format version in its MODULE_CODE_VERSION record (0, 1, or 2), which tells the reader how some records are encoded, such as whether instruction operands are absolute or relative value IDs. That number describes the encoding rather than a compatibility window: a newer LLVM reads any bitcode since LLVM 3.0 and upgrades it on load, and an older LLVM is not promised to read newer bitcode. MLIR bytecode carries an explicit version number with per-dialect upgrade hooks. StableHLO ties its compatibility guarantees to its own release version, as PowerIO IR does with the release series. A 0.10 document is refused rather than upgraded; an upgrade path for those documents would be a later addition.

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/0.12.3/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.

structural typeschema definition
powerio.BalancedNetworkBalancedNetwork
powerio.MulticonductorNetworkMulticonductorNetwork
powerio.GeoLayerGeoLayer
powerio.ContingencySetContingencySet
powerio.SubsystemSetSubsystemSet
powerio.MonitoredSetMonitoredSet
powerio.OperatingPoint<powerio.BalancedNetwork>StoredOperatingPoint
powerio.OperatingPoint<powerio.MulticonductorNetwork>StoredOperatingPoint2
powerio.TimeSeries<powerio.BalancedNetwork>StoredTimeSeries
powerio.TimeSeries<powerio.MulticonductorNetwork>StoredTimeSeries2
powerio.TimeSeries<powerio.OperatingPoint<powerio.BalancedNetwork>>StoredOperatingPointTimeSeries
powerio.TimeSeries<powerio.OperatingPoint<powerio.MulticonductorNetwork>>StoredOperatingPointTimeSeries2
powerio.ScenarioSet<powerio.BalancedNetwork>StoredScenarioSet
powerio.ScenarioSet<powerio.MulticonductorNetwork>StoredScenarioSet2
powerio.ScenarioSet<powerio.OperatingPoint<powerio.BalancedNetwork>>StoredOperatingPointScenarioSet
powerio.ScenarioSet<powerio.OperatingPoint<powerio.MulticonductorNetwork>>StoredOperatingPointScenarioSet2
powerio.ScenarioSet<powerio.TimeSeries<powerio.BalancedNetwork>>StoredScenarioSet3
powerio.ScenarioSet<powerio.TimeSeries<powerio.MulticonductorNetwork>>StoredScenarioSet4
powerio.ScenarioSet<powerio.TimeSeries<powerio.OperatingPoint<powerio.BalancedNetwork>>>StoredScenarioSet5
powerio.ScenarioSet<powerio.TimeSeries<powerio.OperatingPoint<powerio.MulticonductorNetwork>>>StoredScenarioSet6
powerio.DcPfInstanceDcPfInstance
powerio.AcPfInstanceAcPfInstance
powerio.DcOpfInstanceDcOpfInstance
powerio.AcOpfInstanceAcOpfInstance
powerio.AcOtsInstanceAcOtsInstance
powerio.McAcPfInstanceMcAcPfInstance
powerio.McAcOpfInstanceMcAcOpfInstance
powerio.LinDist3FlowPfInstanceLinDist3FlowPfInstance
powerio.LinDist3FlowOpfInstanceLinDist3FlowOpfInstance
powerio.AcScucInstanceAcScucInstance
powerio.DcPfSolutionDcPfSolution
powerio.AcPfSolutionAcPfSolution
powerio.DcOpfSolutionDcOpfSolution
powerio.AcOpfSolutionAcOpfSolution
powerio.AcOtsSolutionAcOtsSolution
powerio.SocwrOpfSolutionSocwrOpfSolution
powerio.McAcPfSolutionMcAcPfSolution
powerio.McAcOpfSolutionMcAcOpfSolution
powerio.LinDist3FlowPfSolutionLinDist3FlowPfSolution
powerio.LinDist3FlowOpfSolutionLinDist3FlowOpfSolution
powerio.AcScucSolutionAcScucSolution

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.

fieldtypeunitsigninvariantif absent
namestringrequired
base_mvafloatMVAfinite and positiverequired
base_frequencyfloatHzpositive60
source_formattokenone of the format tokens (matpower, psse, psse-rawx, powermodels-json, egret-json, powerworld, powerworld-pwb, pslf, pandapower-json, pypsa-csv, gridfm, goc3-json, surge-json, opfdata-json, xiidm, jiidm, cgmes, ucte, ieee-cdf, sincal, in-memory, normalized)required
busesarray of Busid uniquerequired
loadsarray of Loadbus names a busrequired
shuntsarray of Shuntbus names a busrequired
branchesarray of Branchfrom and to name busesrequired
generatorsarray of Generatorbus names a busrequired
storagearray of Storagebus names a busrequired
hvdcarray of Hvdcfrom and to name busesrequired
switchesarray of Switchfrom and to name buses[]
transformers_3warray of Transformer3Wevery winding bus names a bus[]
static_var_compensatorsarray of StaticVarCompensatorbus names a bus[]
areasarray of Areanumber unique[]
solverSolverParams or nullnull
case_metadataCaseMetadataevery member null
geoGeoMeta or nullnull
detailed_connectivityDetailedConnectivity or nullnull
generated_uidsarray of stringsubset of component uid values; identifies identities PowerIO assigned because the source stated none[]

Bus

Schema definition: Bus.

fieldtypeunitsigninvariantif absent
ididunique within busesrequired
kindtoken PQ, PV, REF, ISOLATEDMATPOWER type codes 1, 2, 3, 4required
vmfloatp.u.required
vafloatdegreesrequired
base_kvfloatkVnonnegative; 0 when the source states nonerequired
vmaxfloatp.u.vmin <= vmax; Infinity for no boundrequired
vminfloatp.u.required
evhifloat or nullp.u.emergency band, stated only when it differs from vmaxnull (equals vmax)
evlofloat or nullp.u.stated only when it differs from vminnull (equals vmin)
areaintegerrequired
zoneintegerrequired
namestring or nullnull
uidstring or nullunique within busesassigned at serialization
locationLocation or nullnetwork coordinate spacenull
extrasobjectrequired

Load

Schema definition: Load.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
pfloatMWpositive is consumptionrequired
qfloatMVArpositive is inductive consumptionrequired
in_servicebooleanrequired
voltage_modelLoadVoltageModel or nullnull (constant power)
uidstring or nullunique within loadsassigned at serialization
extrasobjectrequired

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.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
gfloatMW at V = 1 p.u.positive is consumptionrequired
bfloatMVAr at V = 1 p.u.positive is capacitive injectionthe initial value of a switched shuntrequired
in_servicebooleanrequired
section_countinteger or nullnull (unset)
controlSwitchedShuntControl or nullnull (fixed shunt)
uidstring or nullunique within shuntsassigned at serialization
extrasobjectrequired

Schema definition: SwitchedShuntControl.

fieldtypeunitsigninvariantif absent
modetoken locked, continuous, discretePSS/E MODSW 0, 2, and 1 or 3 to 6required
vhighfloatp.u.vlow <= vhighrequired
vlowfloatp.u.required
control_busid or nullnames a busnull (the shunt’s own bus)
regulating_terminalTerminalReference or nullnull
rmpctfloatpercentrequired
blocksarray of ShuntBlockrequired

Schema definition: ShuntBlock.

fieldtypeunitsigninvariantif absent
stepsintegerrequired
gfloatMW at V = 1 p.u. per steppositive is consumptionrequired
bfloatMVAr at V = 1 p.u. per steppositive is capacitive injectionrequired

Branch

Ratings use zero for a zero bound and "Infinity" for no bound in 0.12 JSON, using the same nonfinite spelling as other numeric fields. The reader converts zero ratings in 0.11 documents (integer version 2) to infinity; it does not reinterpret zero in a 0.12 document. This also applies to winding and named ratings. The record shapes stay unchanged.

Schema definition: Branch.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
rfloatp.u.required
xfloatp.u.r and x not both zero when a matrix is builtrequired
bfloatp.u.positive is capacitivetotal line charging; half at each end unless charging is presentrequired
chargingBranchCharging or nullcanonical per terminal admittance when presentnull (derive from b)
rate_afloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_bfloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_cfloatMVA0 is a zero bound; +Inf is unboundedrequired
rating_setsarray of BranchRatingSet[]
current_ratingsBranchCurrentRatings or nullnull
tapfloatratio at the from side0 means 1 (a line); otherwise positiverequired
shiftfloatdegreespositive means the from side voltage leads the to siderequired
in_servicebooleanrequired
angminfloatdegreesangmin <= angmax; -360 and 360 mean unconstrainedrequired
angmaxfloatdegreesrequired
controlTransformerControl or nullnull (a line or a fixed ratio transformer)
solutionBranchSolution or nullnull
namestring or nullnull
uidstring or nullunique within branchesassigned at serialization
routearray of Location or nullnetwork coordinate spacenull
extrasobjectrequired

A transformer’s impedance correction table rides in extras. impedance_correction holds {table, variable, points}. variable is ratio or angle (degrees), and each point is {value, factor_re, factor_im}, the complex factor that multiplies the nominal series impedance at that ratio or angle. A three winding transformer keeps three such entries, one per winding or null, and its factor scales that winding’s star impedance. With psse_zcod = 1, entries 0/1/2 instead scale Z12/Z23/Z31, using the sole winding whose control mode is not fixed (regulation may be disabled). Ratio coordinates on a branch are in its effective t1/t2 tap units; three-winding ratio coordinates are bus-base per-unit winding taps. impedance_correction_nominal holds the nominal impedance once apply_impedance_correction has scaled it: [r, x] on a branch and the three pairwise [r, x] on a three winding transformer. impedance_correction_applied holds the corrected impedance that call wrote, in the same layout; a present impedance that differs from it was edited afterward and is the nominal value from then on.

Schema definition: BranchCharging.

fieldtypeunitsigninvariantif absent
g_frfloatp.u.required
b_frfloatp.u.positive is capacitiverequired
g_tofloatp.u.required
b_tofloatp.u.positive is capacitiverequired

Schema definition: BranchRatingSet.

fieldtypeunitsigninvariantif absent
namestringrequired
rate_mvafloatMVA0 is a zero bound; +Inf is unboundedrequired

Schema definition: BranchCurrentRatings.

fieldtypeunitsigninvariantif absent
c_rating_afloatsource units (amperes for PSS/E)required
c_rating_bfloatsource unitsrequired
c_rating_cfloatsource unitsrequired

Schema definition: BranchSolution.

fieldtypeunitsigninvariantif absent
pffloatMWpositive flows into the branch at the from terminalrequired
qffloatMVArpositive flows into the branch at the from terminalrequired
ptfloatMWpositive flows into the branch at the to terminalrequired
qtfloatMVArpositive flows into the branch at the to terminalrequired

Schema definition: TransformerControl.

fieldtypeunitsigninvariantif absent
modetoken fixed, voltage, reactive_flow, active_flow, dc_line_quantity, asymmetric_active_flowPSS/E COD magnitude 0 through 5required
enabledbooleanautomatic adjustment on; the sign of PSS/E CODrequired
controlled_busid or nullnames a busnull
controlled_bus_on_winding_sidebooleanfalse
regulating_terminalTerminalReference or nullnull
band_minfloatp.u. voltage, MVAr, or MW as mode selectsband_min <= band_maxrequired
band_maxfloatas band_minrequired
tap_minfloatratio, or degrees for phase controltap_min <= tap_maxrequired
tap_maxfloatas tap_minrequired
ntpintegernumber of tap positionsrequired
mva_basefloatMVArequired
winding_connection_anglefloat or nulldegreesasymmetric active power flow control onlynull

Generator

Schema definition: Generator.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
pgfloatMWpositive is generationrequired
qgfloatMVArpositive is generationrequired
qmaxfloatMVArqmin <= qmax; Infinity and -Infinity mean unboundedrequired
qminfloatMVArrequired
vgfloatp.u.required
mbasefloatMVApositive when statedrequired
pmaxfloatMWpmin <= pmaxrequired
pminfloatMWrequired
in_servicebooleanrequired
costGenCost or nullnull (no cost curve)
capsmap of string to floatMW, MVAr, MW per minute, or a fraction per keykeys among pc1, pc2, qc1min, qc1max, qc2min, qc2max, ramp_agc, ramp_10, ramp_30, ramp_q, apf, the MATPOWER columns past PMIN{}
energy_sourcetoken hydro, nuclear, wind, thermal, solar, otherother
voltage_regulation_onbooleantrue
regulated_busid or nullnames a busnull (the generator’s own bus)
regulating_terminalTerminalReference or nullnull
active_power_controlActivePowerControl or nullnull
uidstring or nullunique within generatorsassigned at serialization

Schema definition: GenCost.

fieldtypeunitsigninvariantif absent
modelinteger1 is piecewise linear, 2 is polynomialrequired
startupfloatcurrencyrequired
shutdownfloatcurrencyrequired
ncostintegerpolynomial: coeffs.len() == ncost; piecewise: coeffs.len() == 2 * ncostrequired
coeffsarray of floatpolynomial: currency per MW^k per hour, highest order first; piecewise: alternating MW and currency per hour breakpointsrequired

Schema definition: ActivePowerControl.

fieldtypeunitsigninvariantif absent
participatebooleanrequired
droop_percentfloat or nullpercentnull
participation_factorfloat or nullnull
minimum_target_active_power_mwfloat or nullMWnull
maximum_target_active_power_mwfloat or nullMWnull

Storage

The PowerModels storage model.

Schema definition: Storage.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
psfloatMWpositive is withdrawn from the network (charging)required
qsfloatMVArpositive is withdrawn from the networkrequired
energyfloatMWh0 <= energy <= energy_ratingrequired
energy_ratingfloatMWhrequired
charge_ratingfloatMWrequired
discharge_ratingfloatMWrequired
charge_efficiencyfloatfractionin [0, 1]required
discharge_efficiencyfloatfractionin [0, 1]required
thermal_ratingfloatMVArequired
current_ratingfloat or nullamperesnull
qminfloatMVArqmin <= qmaxrequired
qmaxfloatMVArrequired
rfloatp.u.required
xfloatp.u.required
p_lossfloatMWstandby lossrequired
q_lossfloatMVArstandby lossrequired
in_servicebooleanrequired
active_power_controlActivePowerControl or nullnull
uidstring or nullunique within storageassigned at serialization
extrasobjectrequired

Hvdc

A two terminal HVDC line in the MATPOWER dcline convention, whatever the source format. The stored pf, pt, qf, and qt keep these signs throughout 0.11.x: pf is positive from the from bus into the line, and pt, qf, and qt are positive from the line into their bus. The calculations read them through the bus-to-device terminal view (Hvdc::calc_bus_to_device_powers in Rust), positive from each AC bus into the HVDC system: p_from = pf, q_from = -qf, p_to = -pt, q_to = -qt, with p_from + p_to the active power lost. A balanced calculation carries an in service line whose two terminal buses are energized as fixed bus injections, the negatives of its terminal powers: -pf and +qf at the from bus, +pt and +qt at the to bus.

Schema definition: Hvdc.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
in_servicebooleanrequired
pffloatMWpositive flows from the from bus to the to bus, measured at the from endrequired
ptfloatMWpositive flows from the from bus to the to bus, measured at the to endrequired
qffloatMVArpositive is injected into the from busrequired
qtfloatMVArpositive is injected into the to busrequired
vffloatp.u.voltage setpoint at the from busrequired
vtfloatp.u.voltage setpoint at the to busrequired
pminfloatMWbounds on pf; pmin <= pmaxrequired
pmaxfloatMWrequired
qminffloatMVArbounds on qfrequired
qmaxffloatMVArrequired
qmintfloatMVArbounds on qtrequired
qmaxtfloatMVArrequired
loss0floatMWconstant loss termrequired
loss1floatMW per MWlinear loss term in pfrequired
resistance_ohmfloat or nullohmnull
nominal_voltage_kvfloat or nullkVnull
converters_modetoken side1_rectifier_side2_inverter, side1_inverter_side2_rectifier, or nullnull
converter1HvdcConverter or nullnull
converter2HvdcConverter or nullnull
costGenCost or nullusage cost in pfnull
uidstring or nullunique within hvdcassigned at serialization
extrasobjectrequired

Schema definition: HvdcConverter.

fieldtypeunitsigninvariantif absent
componentComponentIdrequired
kindtoken vsc, lccrequired
loss_factor_percentfloatpercent of active powerrequired
power_factorfloat or nullnull
reactive_power_setpoint_mvarfloat or nullMVArnull
regulating_terminalTerminalReference or nullnull
voltage_regulator_onboolean or nullnull
voltage_setpoint_kvfloat or nullkVnull

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.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
closedbooleanrequired
thermal_ratingfloat or nullMVAnull
current_ratingfloat or nullamperesnull
pffloat or nullMWpositive flows into the switch at the from terminalnull
qffloat or nullMVArpositive flows into the switch at the from terminalnull
ptfloat or nullMWpositive flows into the switch at the to terminalnull
qtfloat or nullMVArpositive flows into the switch at the to terminalnull
uidstring or nullunique within switchesassigned at serialization
extrasobjectrequired

Transformer3W

Three windings joined at a star point; the indexed view star-lowers the record for matrix calculations. Default per-winding service states use this body directly. Nondefault states use the tagged record described below, whose nested body has the same physical fields.

Schema definitions: Transformer3W/anyOf/0, PartialTransformer3WFields.

fieldtypeunitsigninvariantif absent
namestring or nullnull
windingsarray of Windingexactly three, in the order primary, secondary, tertiaryrequired
zarray of Impedanceexactly three: z12, z23, z31required
mag_gfloatp.u. on the system baseconnected where magnetizing_connection saysrequired
mag_bfloatp.u. on the system basepositive is capacitiveconnected where magnetizing_connection saysrequired
magnetizing_connection"star_point" or "winding1_terminal"winding1_terminal connects the admittance from winding 1’s bus to ground, outside its ratio"star_point"
star_vmfloatp.u.solved star point voltagerequired
star_vafloatdegreesrequired
in_servicebooleanrequired
uidstring or nullunique within transformers_3wassigned at serialization
extrasobjectrequired

PSS/E connects MAG1 + jMAG2 from winding 1’s bus to ground, outside that winding’s ratio, and its readers state winding1_terminal; IIDM and CGMES state each leg’s admittance at the star point. The star lowering puts a winding1_terminal admittance on winding 1’s branch as from side charging Ym * tap1², which bus 1 sees as Ym, and a star_point one at the star bus. Every 0.11 document omits the field and states the star point. A writer whose format has only the other placement writes the value there and reports it with its VALUE_SUBSTITUTED code.

Two extras entries carry per winding data, in winding order. Each is present only when it differs from its default. winding_in_service holds three booleans; a winding that is out leaves the other two coupled through the star point, and an absent entry means every winding is in service. winding_rating_sets holds three arrays of {name, rate_mva} objects with the MVA ratings beyond rate_a, rate_b, and rate_c, named as in Branch.rating_sets.

PartialTransformer3W

A nondefault winding state uses structural identity "powerio.PartialTransformer3W", including when the whole transformer is off. The nested body requires extras.winding_in_service to contain exactly three booleans, not all true. An explicit all-false state is therefore also tagged. Older IR 2 readers reject this record because its required physical transformer fields are absent at the root. The body preserves all winding rows, identifiers, units, and extension data; no winding is dropped or assigned a fake impedance. Bare nondefault states and malformed tagged records are rejected.

Schema definition: PartialTransformer3WWire/oneOf/0.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.PartialTransformer3W"required
valueobjectcomplete transformer body above with nondefault winding flagsrequired

Schema definition: Winding.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
nominal_kvfloatkV0 defers to the terminal bus base_kvrequired
tapfloatratio1 is nominal (PSS/E WINDV with CW = 1)required
shiftfloatdegreesas Branch.shiftrequired
rate_afloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_bfloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_cfloatMVA0 is a zero bound; +Inf is unboundedrequired
controlTransformerControl or nullnull

Schema definition: Impedance.

fieldtypeunitsigninvariantif absent
rfloatp.u. on the system baserequired
xfloatp.u. on the system baserequired
base_mvafloatMVAthe source’s declared base for the pair; positiverequired

Area

Schema definition: Area.

fieldtypeunitsigninvariantif absent
numberintegerunique within areas; matches Bus.arearequired
namestring or nullnull
net_interchangefloatMWpositive is export out of the arearequired
tolerancefloatMWrequired
slack_busid or nullnames a busnull
area_typestring or nullnull
uidstring or nullnull

StaticVarCompensator

Schema definition: StaticVarCompensator.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
b_min_siemensfloatsiemensb_min_siemens <= b_max_siemensrequired
b_max_siemensfloatsiemensrequired
voltage_setpoint_kvfloatkVrequired
reactive_power_setpoint_mvarfloatMVArpositive is injectionrequired
regulation_modetoken voltage, reactive_powerrequired
regulatingbooleanrequired
regulating_terminalTerminalReference or nullnull
pfloatMWpositive is consumptionrequired
qfloatMVArpositive is consumptionrequired
in_servicebooleanrequired
uidstring or nullnull
extrasobjectrequired

SolverParams

Each member is set only when the source has it.

Schema definition: SolverParams.

fieldtypeunitsigninvariantif absent
newton_tolerancefloat or nullMW and MVAr mismatchnull
max_iterationsinteger or nullnull
zero_impedance_thresholdfloat or nullp.u. reactancenull
adjust_tapsboolean or nullnull
adjust_phase_shiftboolean or nullnull
adjust_dc_tapsboolean or nullnull
adjust_switched_shuntboolean or nullnull
adjust_area_interchangeboolean or nullnull

CaseMetadata

Schema definition: CaseMetadata.

fieldtypeunitsigninvariantif absent
case_datestring or nullnull
forecast_distanceinteger or nullminutes, as the source statesnull
source_model_formatstring or nullnull
minimum_validation_levelstring or nullnull

Coordinates

Schema definition: GeoMeta.

fieldtypeunitsigninvariantif absent
kindtoken source, synthetic, manual, derived, or nulldefault origin of points without their own kindnull

Schema definition: Location.

fieldtypeunitsigninvariantif absent
xfloatnetwork coordinate space; longitude in geographic spacerequired
yfloatnetwork coordinate space; latitude in geographic spacerequired
kindtoken as GeoMeta.kind, or nullnull (the network default)

Component references

Schema definition: ComponentId.

fieldtypeunitsigninvariantif absent
component_typestringthe element table or record kindrequired
local_idstringthe source supplied or assigned identityrequired

Schema definition: TerminalReference.

fieldtypeunitsigninvariantif absent
equipmentComponentIdrequired
terminalinteger1 for single terminal equipment, else the side numberrequired

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.

fieldtypeunitsigninvariantif absent
subnetworksarray of Subnetwork[]
substationsarray of Substation[]
voltage_levelsarray of VoltageLevelkVnominal_kv positive[]
bus_breaker_busesarray of BusBreakerBus[]
calculated_busesarray of CalculatedBus[]
connectivity_nodesarray of ConnectivityNode[]
busbar_sectionsarray of BusbarSection[]
junctionsarray of Junction[]
terminalsarray of Terminal[]
switchesarray of TopologySwitch[]
internal_connectionsarray of InternalConnection[]
operational_limit_groupsarray of OperationalLimitGroupamperes, MW, or MVA per limit kind[]
tap_changersarray of TapChangerlow_tap_position <= tap_position when stated[]
equipment_reactive_limitsarray of EquipmentReactiveLimitsMVAr[]
boundary_linesarray of BoundaryLine[]
tie_linesarray of TieLine[]
component_metadataarray of ComponentMetadata[]
omitted_fieldsarray of OmittedFielda field absent from the source, distinct from a stated zero[]
dc_converter_unitsarray of DcConverterUnit[]
dc_topological_nodesarray of DcTopologicalNode[]
dc_nodesarray of DcNode[]
dc_groundsarray of DcGround[]
dc_busbarsarray of DcBusbar[]
dc_linesarray of DcLine[]
dc_series_devicesarray of DcSeriesDevice[]
dc_switchesarray of DcSwitch[]
voltage_source_convertersarray of VoltageSourceConverter[]
line_commutated_convertersarray of LineCommutatedConverter[]

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.

Without component geography, this is the original network body. The additive located-network alternative below carries typed points without changing these fields or their meanings.

Schema definitions: MulticonductorNetwork/anyOf/0, MulticonductorNetworkBody.

fieldtypeunitsigninvariantif absent
namestring or nullnull
base_frequencyfloatHzpositiverequired
source_formattoken dss, bmopf-json, pmd-json, cim-dist, sincal, ravens-json, pmd-math-json, pandapower-json, or nullnull
busesarray of DistBusid uniquerequired
linecodesarray of DistLineCodename uniquerequired
linesarray of DistLinebus_from, bus_to name buses; linecode names a line coderequired
switchesarray of DistSwitchbus_from, bus_to name busesrequired
transformersarray of DistTransformerevery winding bus names a busrequired
loadsarray of DistLoadbus names a busrequired
shuntsarray of DistShuntbus names a busrequired
capacitorsarray of DistCapacitorbus names a bus[]
generatorsarray of DistGeneratorbus names a busrequired
ibrsarray of DistIbrbus names a bus; control_profile names a profile[]
control_profilesarray of DistControlProfilename unique[]
sourcesarray of VoltageSourceBMOPF carries exactly onerequired
untypedarray of UntypedObjectrequired
commandsarray of [verb, args] string pairssource orderrequired
optionsarray of [name, value] string pairssource orderrequired
extrasobjectrequired
geoDistGeoMeta or nullnull

LocatedMulticonductorNetwork

The powerio.MulticonductorNetwork value can instead contain a nested "powerio.LocatedMulticonductorNetwork" record. It remains the same runtime network family. An older reader rejects the wrapper because its required electrical fields are absent at the root. This representation works wherever the network is stored, including calculation and collection values.

Schema definition: LocatedNetworkWire.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.LocatedMulticonductorNetwork"required
valueLocatedNetworkFieldsrequired

Schema definition: LocatedNetworkFields.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkBodyoriginal electrical network layout aboverequired
locationsarray of DistComponentLocationat most 1,048,576; one point per exact component identityrequired

Schema definition: DistComponentLocation.

fieldtypeunitsigninvariantif absent
targetbus, line, line_code, switch, transformer, load, generator, ibr, shunt, capacitor, sourcenames the component tablerequired
namestringexact existing component id/name; case sensitiverequired
pointDistGeographicPointindependent of drawing positions, routes and electrical lengthrequired
kindsource, synthetic, manual, derived, or nullpoint originnull

Schema definition: DistGeographicPoint.

fieldtypeunitsigninvariantif absent
latitudefloat or nulldecimal degreesnorth positivefinite, in [-90, 90]; at least one axis presentnull
longitudefloat or nulldecimal degreeseast positivefinite, in [-180, 180]; zero is a stated coordinatenull
datumstring or nullnonempty when stated; null means unknown, never implied WGS84null

DistBus

Schema definition: DistBus.

fieldtypeunitsigninvariantif absent
idstringunique within busesrequired
terminalsarray of stringordered, uniquerequired
groundedarray of stringeach names a terminal of this bus; zero impedance to groundrequired
v_minfloat or nullvoltsv_min <= v_maxnull (unbounded)
v_maxfloat or nullvoltsnull (unbounded)
v_min_phasearray of float or nullvoltsphase order excludes neutral and earth; scalar v_min takes precedencenull
v_max_phasearray of float or nullvoltsphase order excludes neutral and earth; scalar v_max takes precedencenull
vpn_minarray of float or nullvoltsper phase to neutral boundnull
vpn_maxarray of float or nullvoltsnull
vpp_minarray of float or nullvoltsper phase to phase boundnull
vpp_maxarray of float or nullvoltsnull
vpos_minfloat or nullvoltspositive sequence boundnull
vpos_maxfloat or nullvoltsnull
vneg_maxfloat or nullvoltsnegative sequence magnitude capnull
vzero_maxfloat or nullvoltszero sequence magnitude capnull
vn_maxfloat or nullvoltsneutral to ground magnitude capnull
locationDistLocation or nullnetwork coordinate spacenull
extrasobjectrequired

DistLineCode

Schema definition: DistLineCode.

fieldtypeunitsigninvariantif absent
namestringunique within linecodesrequired
n_conductorsintegerpositive; the order of every matrixrequired
r_seriesmatrixohm per metern_conductors square, symmetricrequired
x_seriesmatrixohm per metern_conductors square, symmetricrequired
g_frommatrixsiemens per meterhalf of the shunt admittance, at the from endrequired
b_frommatrixsiemens per meterpositive is capacitiverequired
g_tomatrixsiemens per meterhalf of the shunt admittance, at the to endrequired
b_tomatrixsiemens per meterpositive is capacitiverequired
i_maxarray of float or nullamperes per conductornull
s_maxarray of float or nullVA per conductornull
sourcestring or nullorigin of the matrices (BMOPF source)null
extrasobjectrequired

DistLine

Schema definition: DistLine.

fieldtypeunitsigninvariantif absent
namestringunique within linesrequired
bus_fromstringnames a busrequired
bus_tostringnames a busrequired
terminal_map_fromarray of stringn_conductors terminals of bus_fromrequired
terminal_map_toarray of stringn_conductors terminals of bus_torequired
linecodestringnames a line coderequired
lengthfloatmetersnonnegativerequired
i_maxarray of float or nullamperes per conductornull (the line code’s)
s_maxarray of float or nullVA per conductornull (the line code’s)
routearray of DistLocation or nullnetwork coordinate spacenull
extrasobjectrequired

DistSwitch

Schema definition: DistSwitch.

fieldtypeunitsigninvariantif absent
namestringunique within switchesrequired
bus_fromstringnames a busrequired
bus_tostringnames a busrequired
terminal_map_fromarray of stringterminals of bus_from, same length as terminal_map_torequired
terminal_map_toarray of stringterminals of bus_torequired
openbooleanrequired
i_maxarray of float or nullamperes per conductornull
extrasobjectrequired

DistTransformer

Schema definition: DistTransformer.

fieldtypeunitsigninvariantif absent
namestringunique within transformersrequired
phasesinteger1 through 3required
windingsarray of DistWindingtwo or threerequired
xsc_pctarray of floatpercent[xhl] for two windings, [xhl, xht, xlt] for threerequired
extrasobjectrequired

Schema definition: DistWinding.

fieldtypeunitsigninvariantif absent
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
conntoken wye, deltarequired
v_reffloatvolts, line to line for two and three phasespositiverequired
s_ratingfloatVApositiverequired
r_pctfloatpercent of the winding baserequired
tapfloatratio1 is nominalrequired
r_neutralfloat or nullohmnull
x_neutralfloat or nullohmnull

DistLoad

Schema definition: DistLoad.

fieldtypeunitsigninvariantif absent
namestringunique within loadsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
p_nomarray of floatwatts per phasepositive is consumptionone entry per active phaserequired
q_nomarray of floatvars per phasepositive is inductive consumptionsame length as p_nomrequired
voltage_modelDistLoadVoltageModelrequired
extrasobjectrequired

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.

fieldtypeunitsigninvariantif absent
namestringunique within capacitorsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
q_ratedfloatvars, whole bank at v_nompositive is capacitive injectionrequired
v_nomfloatvolts, line to line for the three phase configurationspositiverequired
extrasobjectrequired

DistShunt

Schema definition: DistShunt.

fieldtypeunitsigninvariantif absent
namestringunique within shuntsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of bus, the order of the matricesrequired
gmatrixsiemenssquare in terminal_maprequired
bmatrixsiemenspositive is capacitivesquare in terminal_maprequired
extrasobjectrequired

DistGenerator

Schema definition: DistGenerator.

fieldtypeunitsigninvariantif absent
namestringunique within generatorsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
p_nomarray of floatwatts per phasepositive is generationrequired
q_nomarray of floatvars per phasepositive is generationsame length as p_nomrequired
p_minarray of float or nullwatts per phasep_min <= p_maxnull
p_maxarray of float or nullwatts per phasenull
q_minarray of float or nullvars per phaseq_min <= q_maxnull
q_maxarray of float or nullvars per phasenull
s_maxarray of float or nullVA per conductornull
i_maxarray of float or nullamperes per conductornull
costarray of float or nullcurrency per kWh per phase, or one scalarnull
extrasobjectrequired

DistIbr

Schema definition: DistIbr.

fieldtypeunitsigninvariantif absent
namestringunique within ibrsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
prime_movertoken PV, BATTERY, GENERIC, STATCOM, DSTATCOMrequired
topologytoken SINGLE_PHASE, THREE_LEG, FOUR_LEGrequired
s_maxarray of floatVA per phasenameplaterequired
p_availfloat or nullwattsnull
p_minarray of float or nullwatts per phasenull
p_maxarray of float or nullwatts per phasenull
q_minarray of float or nullvars per phasenull
q_maxarray of float or nullvars per phasenull
i_maxarray of float or nullamperes per conductornull
voltage_aggregationtoken PER_PHASE, AVERAGE, or nullnull
control_profilestring or nullnames a control profilenull
extrasobjectrequired

DistControlProfile

Schema definition: DistControlProfile.

fieldtypeunitsigninvariantif absent
namestringunique within control_profilesrequired
volt_varVoltVarControl or nullnull
volt_wattVoltWattControl or nullnull
power_factorPowerFactorControl or nullnull
extrasobjectrequired

Schema definition: VoltVarControl.

fieldtypeunitsigninvariantif absent
breakpointsarray of floatp.u. voltagefour, [U1, U2, U3, U4], ascendingrequired
q_limitsarray of floatq_unitpositive is injectiontwo, [q_absorb, q_inject]: injects q_inject below U1 and absorbs q_absorb above U4required
voltage_referencetoken PN_PER_PHASE, PP_PER_PHASE, PP_AVERAGED, PG_AVERAGED, PN_AVERAGED, PG_PER_PHASE, or nullnull
q_reftoken VAR_MAX, VAR_AVAILABLE, or nullnull
q_unittoken VA_FRACTION, VAR, or nullnull
p_min_for_qfloat or nullwattsnull
p_min_for_q_maxfloat or nullwattsnull

Schema definition: VoltWattControl.

fieldtypeunitsigninvariantif absent
breakpointsarray of floatp.u. voltagetwo, [U5, U6], ascendingrequired
p_limitsarray of floatp_unittwo, [p_low, p_high] ordered by value: p_high at or below U5, p_low at or above U6; a VA_FRACTION limit is a fraction of the p_ref base, S_MAX when absentrequired
voltage_referencetoken as VoltVarControl.voltage_reference, or nullnull
p_reftoken P_AVAILABLE, P_MAX, S_MAX, or nullnull
p_unittoken VA_FRACTION, W, or nullnull

Schema definition: PowerFactorControl.

fieldtypeunitsigninvariantif absent
pffloatpositive when Q has the same sign as P, negative when opposite (the OpenDSS PVSystem and Storage convention)0 < abs(pf) <= 1required

VoltageSource

An earth-referenced source retains the original record below. A source with an explicit reference terminal uses the separately tagged record described after it; it must not add a bare reference field to this legacy record.

Schema definition: VoltageSource/anyOf/0 (the earth-referenced branch).

fieldtypeunitsigninvariantif absent
namestringunique within sourcesrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
v_magnitudearray of floatvolts per terminal0 on a grounded terminal; same length as terminal_maprequired
v_anglearray of floatradians per terminalsame length as terminal_maprequired
energy_cost_rateoptional array of float$/kWhpositive injection supplies the networkone entry per phase in terminal-map order; excludes neutral terminalsno stated source-price term
extrasobjectrequired

ReferencedVoltageSource

The second source-record alternative has structural identity "powerio.ReferencedVoltageSource". Older IR 2 readers reject this wrapper because the legacy source fields are absent at its root. Existing records remain unchanged. The source can occur anywhere a multiconductor network is stored, including collections and calculation instances.

Schema definition: ReferencedSourceWire/oneOf/0.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.ReferencedVoltageSource"required
valueobjectreferenced source body belowrequired

Schema definition: ReferencedSourceFields.

fieldtypeunitsigninvariantif absent
namestringunique within sourcesrequired
busstringnames a busrequired
terminal_maparray of stringdistinct declared terminals of bus; excludes the referencerequired
v_magnitudearray of floatvolts per terminal-to-reference differencesame length as terminal_map; a grounded phase can have a nonzero differencerequired
v_anglearray of floatradians per terminal-to-reference differencesame length as terminal_maprequired
reference_terminalstringanother declared terminal on bus; does not imply groundingrequired
energy_cost_rateoptional array of float$/kWhpositive injection supplies the networkper phase in terminal-map orderno stated source-price term
extrasobjectrequired

The voltage constraint is V(terminal) - V(reference) = magnitude * exp(i*angle). Every phase-source current has an equal opposite contribution at the reference. Neither an external neutral connection nor an earth path is inferred.

UntypedObject

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

Schema definition: UntypedObject.

fieldtypeunitsigninvariantif absent
classstringrequired
namestringrequired
propsarray of [key, value] string pairssource orderrequired

Distribution coordinates

Schema definition: DistGeoMeta.

fieldtypeunitsigninvariantif absent
kindtoken source, synthetic, manual, derived, or nullnull

Schema definition: DistLocation.

fieldtypeunitsigninvariantif absent
xfloatnetwork coordinate space; longitude in geographic spacerequired
yfloatnetwork coordinate space; latitude in geographic spacerequired
kindtoken as DistGeoMeta.kind, or nullnull (the network default)

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.

fieldtypeunitsigninvariantif absent
spaceCoordinateSpacethe space every feature’s coordinates are inrequired
kindtoken source, synthetic, manual, derived, or nulldefault origin of features without their own kindnull
featuresarray of GeoFeatureempty

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.

fieldtypeunitsigninvariantif absent
widthfloat or nullcanvas unitspositivethe drawing width the source statesnull
heightfloat or nullcanvas unitspositivethe drawing height the source statesnull
unitsstring or nullthe source’s own name for its canvas unitsnull

GeoFeature

Schema definition: GeoFeature.

fieldtypeunitsigninvariantif absent
targettoken bus, branch, or substationthe element family the feature placesrequired
keyElementKeyat least one member names an element, unless a branch states both endpointsrequired
geometryGeoGeometryevery coordinate is finiterequired
fromstring or nulla branch’s endpoint bus, the unordered fallback identitynull
tostring or nullthe other endpoint busnull
kindtoken as GeoLayer.kind, or nullnull (the layer default)

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.

fieldtypeunitsigninvariantif absent
uidstring or nullthe durable identity (buses:3, branches:7)null
idstring or nullthe source’s own element identifiernull
namestring or nullmatched case insensitivelynull
indexinteger or nullpositive1-based row alias, accepted on read and never writtennull

powerio.ContingencySet

One PSS/E contingency description file (.con): the outages a contingency analysis runs. Reading holds what the file states and touches no network; ContingencySet::resolve binds a set to the elements of a network, and ContingencySet::expand turns the automatic specifications into explicit cases over a subsystem set. A statement the grammar does not cover keeps its original line, so a document written back with to_con states everything the source did.

Schema definition: ContingencySet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
casesarray of ContingencyCasein file orderempty
automaticarray of AutomaticSpecin file orderempty
skipsarray of SkipRulethe branches automatic expansion leaves aloneempty
retainedarray of RetainedStatementfile level statements outside the grammarempty

ContingencyCase

Every action of one case applies together.

Schema definition: ContingencyCase.

fieldtypeunitsigninvariantif absent
namestringnonemptyrequired
actionsarray of ContingencyActionin file orderempty

ContingencyAction is one tagged object, keyed by kind. open_branch names from, to, and circuit; open_three_winding names buses, three bus identifiers, and circuit. remove_machine and add_machine name bus and id. remove_shunt and remove_load name bus and an optional id, and a statement with no id names every such element at the bus. remove_switched_shunt and disconnect_bus name bus alone. change_load and change_generation name bus and a Change. unrecognized carries the original text, and a nested dispatch block keeps all of its lines joined with newlines.

Schema definition: Change.

fieldtypeunitsigninvariantif absent
optoken increase, decrease, or setwhether the amount adds to, subtracts from, or replaces the present valuerequired
amountfloatMW or percent, as unit sayspositive is the stated magnitudefiniterequired
unittoken mw or percentrequired

AutomaticSpec

One specification expands into one case per element of a subsystem.

Schema definition: AutomaticSpec.

fieldtypeunitsigninvariantif absent
ordertoken single or doublehow many elements one case outagesrequired
targettoken branch, unit, or tiethe element family the expansion draws from; tie is the branches crossing the subsystem borderrequired
subsystemstringnames a subsystem of the .sub file the expansion runs againstrequired
low_voltage_3wboolean3WLOWVOLTAGE: a branch expansion also takes the low voltage winding of a three winding transformerrequired

Schema definition: SkipRule.

fieldtypeunitsigninvariantif absent
fromidone terminal of the excluded branchrequired
toidthe other terminalrequired
circuitstringthe branch circuit idrequired

RetainedStatement

A statement outside the grammar of its file, kept as the source wrote it. The three contingency analysis files share this record.

Schema definition: RetainedStatement.

fieldtypeunitsigninvariantif absent
lineintegerthe 1-based source line the statement was read from; at least 1required
textstringthe line, with its surrounding whitespace droppedrequired
after_endbooleanthe statement follows the file level END, and the .con writer states it after the END it writes; the .sub and .mon writers state every kept statement before theirs, so it is false therefalse

powerio.SubsystemSet

One PSS/E subsystem description file (.sub): the named bus groups a contingency description file and a monitored element file draw on. Subsystem::select_buses names the buses of one subsystem in a network, and SubsystemSet::to_sub writes the set back.

Schema definition: SubsystemSet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
subsystemsarray of Subsystemin file orderempty
retainedarray of RetainedStatementfile level statements outside the grammarempty

Subsystem

A subsystem is the union of its selector groups.

Schema definition: Subsystem.

fieldtypeunitsigninvariantif absent
namestringnonempty; a .con or .mon statement names it without caserequired
groupsarray of SelectorGroupthe implicit group comes first when it has any selectorempty
retainedarray of RetainedStatementstatements inside this subsystem, and outside any JOIN group, that are outside the grammarempty

Schema definition: SelectorGroup.

fieldtypeunitsigninvariantif absent
joinJoinName or nullhow the file stated the group; null is the implicit group, which holds the selectors stated outside any JOINnull
selectorsarray of SubsystemSelectorbus sets that intersect across selector types within one groupempty
retainedarray of RetainedStatementlines read while this JOIN was open that are outside the grammar; the implicit group holds noneempty

JoinName is one tagged object, keyed by kind: anonymous has no further member and states a JOIN with no name, and named carries the group name. Two groups stated anonymous are two groups, whose bus sets union.

SubsystemSelector is one tagged object, keyed by kind. area, zone, and owner name an inclusive from and to number range; bus names an inclusive range of bus identifiers; kv_range names an inclusive base kV band whose lo is at most its hi. A source statement naming one value reads as a range whose two ends are equal.

powerio.MonitoredSet

One PSS/E monitored element file (.mon): the branch flows, interface flows, and bus voltages a contingency analysis reports on. MonitoredSet::resolve binds the statements to the rows of a network against a subsystem set, and MonitoredSet::to_mon writes the set back.

Schema definition: MonitoredSet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
statementsarray of MonitorStatementin file orderempty
retainedarray of RetainedStatementstatements outside the grammarempty

MonitorStatement is one tagged object, keyed by kind. branches_in_subsystem names a subsystem and low_voltage_3w, and takes every branch with both terminals in it. ties_from_subsystem names a subsystem and takes every branch with exactly one terminal in it. branches carries the branches a MONITOR BRANCHES block lists. interface names the interface name, an optional rating_mw, and the branches whose flows sum over it. Both carry the block’s lines that state no branch as retained. voltage_range names a scope and a vmin at most its vmax, both in per unit. voltage_deviation names a scope, a down limit, and an optional up limit; a source statement naming one value states the downward limit alone.

MonitorScope is one tagged object, keyed by kind: all_buses has no further member, subsystem carries a subsystem name, bus a bus identifier, area, zone, and owner a number under their own name, and kv a base kV value.

Schema definition: BranchRef.

fieldtypeunitsigninvariantif absent
fromidone terminal of the monitored branchrequired
toidthe other terminalrequired
circuitstringthe branch circuit id; an absent id in the source reads as 1required

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.

fieldtypeunitsigninvariantif absent
networkBalancedNetwork or MulticonductorNetwork, as the type name saysthe complete base networkrequired
quantitiesmap of quantity name to StoredQuantityper quantity, belowkeys among the quantity names of the network familyrequired

Schema definition: StoredQuantity.

fieldtypeunitsigninvariantif absent
identitiesarray of stringeach names a component of the network; unique; same length as valuesrequired
valuesarray of floatthe quantity’s unit; a flag is 0 or 1required

identities and values carry at most 4,194,304 entries each; see Resource limits.

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

Schema definition: StoredOperatingPointAssignment.

fieldtypeunitsigninvariantif absent
quantitiesmap of quantity name to StoredQuantityas StoredOperatingPoint.quantitiesrequired

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

quantitykeyed byunitsign
bus_voltage_magnitudebus idp.u.
bus_voltage_anglebus iddegrees
bus_active_injectionbus idMWpositive into the network
bus_reactive_injectionbus idMVArpositive into the network
generator_active_powergenerator uidMWpositive is generation
generator_reactive_powergenerator uidMVArpositive is generation
generator_voltage_setpointgenerator uidp.u.
generator_in_servicegenerator uidflag
load_active_powerload uidMWpositive is consumption
load_reactive_powerload uidMVArpositive is consumption
branch_in_servicebranch uidflag
branch_tap_ratiobranch uidratio
branch_phase_shiftbranch uiddegreesas Branch.shift
switch_closedswitch uidflag

Multiconductor quantities. A terminal quantity is keyed bus_id/terminal, a per phase element quantity element_name/terminal, and a whole element quantity by the element name.

quantitykeyed byunitsign
terminal_voltage_magnitudebus/terminalvolts
terminal_voltage_anglebus/terminalradians
load_active_powerload/terminalwattspositive is consumption
load_reactive_powerload/terminalvarspositive is consumption
generator_active_powergenerator/terminalwattspositive is generation
generator_reactive_powergenerator/terminalvarspositive is generation
transformer_taptransformer nameratio
capacitor_stepscapacitor namecount
switch_closedswitch nameflag

powerio.TimeSeries<T>

Ordered time points and one value of T per point. Labels are the source’s own; PowerIO imposes no calendar meaning.

Schema definitions: StoredTimeSeries, StoredTimeSeries2.

fieldtypeunitsigninvariantif absent
time_pointsarray of TimePointrequired
valuesarray of the element type, each a complete networksame length as time_pointsrequired

A series of operating points gives the shared base network once.

Schema definitions: StoredOperatingPointTimeSeries, StoredOperatingPointTimeSeries2.

fieldtypeunitsigninvariantif absent
networkthe base network, or nullnull only for an empty seriesrequired when values is nonempty
time_pointsarray of TimePointrequired
valuesarray of StoredOperatingPointAssignmentsame length as time_points; identities name components of networkrequired

Schema definition: TimePoint.

fieldtypeunitsigninvariantif absent
labelstringnonempty, boundedrequired
durationDuration or nullthe interval the point coversnull

Schema definition: Duration.

fieldtypeunitsigninvariantif absent
secsintegersecondsrequired
nanosintegernanosecondsbelow one billionrequired

powerio.ScenarioSet<T>

Named alternatives of T with no implied order. Either every scenario has a probability or none does; when present, the probabilities are nonnegative and sum to one within SCENARIO_PROBABILITY_TOLERANCE.

Schema definitions: StoredScenarioSet, StoredScenarioSet2, StoredScenarioSet3, StoredScenarioSet4, StoredScenarioSet5, StoredScenarioSet6.

fieldtypeunitsigninvariantif absent
scenariosarray of the scenario recordid uniquerequired

Schema definitions: StoredScenario, StoredScenario2, StoredScenario3, StoredScenario4, StoredScenario5, StoredScenario6.

fieldtypeunitsigninvariantif absent
idstringnonempty, bounded, unique in the setrequired
probabilityfloat or nullin [0, 1]null
valuethe element type: a network, a network time series, or an operating point time seriesrequired

A scenario set of operating points gives the shared base network once.

Schema definitions: StoredOperatingPointScenarioSet, StoredOperatingPointScenarioSet2.

fieldtypeunitsigninvariantif absent
networkthe base network, or nullnull only for an empty setrequired when scenarios is nonempty
scenariosarray of StoredOperatingPointScenarioid uniquerequired

Schema definition: StoredOperatingPointScenario.

fieldtypeunitsigninvariantif absent
idstringnonempty, bounded, unique in the setrequired
probabilityfloat or nullin [0, 1]null
quantitiesmap of quantity name to StoredQuantityidentities name components of networkrequired

Instances

An instance is the complete input to one named calculation, including the network it runs over. An instance may also include an initial_point, a starting operating assignment a solver may use, whose identities refer to components of the instance’s network.

powerio.DcPfInstance

Schema definition: DcPfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF busrequired
approximationtoken series_susceptance, tap_adjusted_reactance, reactance_only, tap_adjusted_series_susceptance, series_susceptance_no_phase_shiftthe DC branch susceptance formularequired
initial_pointStoredOperatingPointAssignment or nullnull
hvdc_treatmenttoken fixed_injection, ignorehow the specifications treat HVDC lines; written only when not ignoreignore

The bus specifications are derived from the network: a REF bus contributes its stated angle, an ISOLATED bus no equation, and every other bus its net active injection over in service generators and loads. Under fixed_injection each in service HVDC line whose terminal buses are energized adds a fixed injection of -pf at its from bus and +pt at its to bus; under ignore HVDC lines add nothing. A document without hvdc_treatment reads as ignore: a document written before the field existed, when the instance left HVDC lines out, denotes the calculation it did when written, and an ignore instance is written without the field.

powerio.AcPfInstance

Schema definition: AcPfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF busrequired
specificationsarray of AcBusSpecificationone per bus, in bus table orderrequired
initial_pointStoredOperatingPointAssignment or nullnull
hvdc_treatmenttoken fixed_injection, ignorehow specifications derived for a replacement network treat HVDC lines; written only when not ignoreignore

AcBusSpecification is tagged by kind. pq gives p (MW) and q (MVAr), the prescribed net injection; pv gives p and vm (p.u.); reference gives vm and va (degrees); isolated gives nothing. Powers are net injections into the network, positive for generation.

powerio.DcOpfInstance

Schema definition: DcOpfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF bus and one in service generator on a non isolated busrequired
objectiveObjectiverequired
constraintsActiveConstraintsrequired
approximationtoken as DcPfInstance.approximationrequired
initial_pointStoredOperatingPointAssignment or nullnull

powerio.AcOpfInstance

Schema definition: AcOpfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF bus and one in service generator on a non isolated busrequired
objectiveObjectiverequired
constraintsActiveConstraintsrequired
initial_pointStoredOperatingPointAssignment or nullnull

Schema definition: Objective.

fieldtypeunitsigninvariantif absent
termsarray of ObjectiveTermempty is a feasibility problem[]

ObjectiveTerm is tagged by term: network_generator_cost sums the network’s generator cost curves; active_power_dispatch_cost prices active dispatch; branch_switching_cost adds the opening and closing costs of an AC optimal transmission switching instance’s status changes.

Schema definition: ActiveConstraints.

fieldtypeunitsigninvariantif absent
generator_capabilityConstraintSelectionactive and reactive generator limitsrequired
voltage_boundsConstraintSelectionbus voltage magnitude boundsrequired
thermal_limitsConstraintSelectionbranch thermal limitsrequired
angle_boundsConstraintSelectionbranch angle difference boundsrequired

ConstraintSelection is tagged by select: all (every element with a stated limit), none (the family is relaxed), or only with identities, the list of element identities (uid values, or bus ids) the family applies to.

powerio.AcOtsInstance

An AC optimal power flow problem whose branch statuses are decisions. The base network keeps every physical branch, and its in_service bits are the initial topology.

Schema definition: AcOtsInstance.

fieldtypeunitsigninvariantif absent
baseAcOpfInstancethe network, objective, constraint selections, and initial pointrequired
optionsAcOtsOptionsrequired

Schema definition: AcOtsOptions.

fieldtypeunitsigninvariantif absent
switchableBranchSelectionan only identity names one branch, oncerequired
switching_costsarray of BranchSwitchingCostone record per branch at most[]: switching costs nothing
islandingtokenforbidden (no AC island of the initial topology may split; islands that are separate initially stay valid, and closing a branch may join islands) or allowed (islands may split, and each final island gets one reference bus). Under either policy a final topology that leaves buses a generator supplied initially in an island with no in-service generator is refused; no load is shedrequired
max_openinteger or nullbranchesat most the branch count, at least the open branches that cannot switch; counts every open branchnull: no budget
max_switchedinteger or nullbranchesat most the switchable count; counts changes against the initial statusnull: no budget
current_limitstokenskip, stated (the records below), or derive_from_rate_a (PowerModels’ calc_current_limits!)required
stated_current_limitsarray of BranchCurrentLimitone record per branch at most[]

BranchSelection is tagged by select: all (every physical branch, including initially open ones), none, or only with identities, the branch identities (uid values) that may switch.

Schema definition: BranchSwitchingCost.

fieldtypeunitsigninvariantif absent
idstringa branch identityrequired
open_costfloatobjective unitsfinite and nonnegative; charged when an initially closed branch opensrequired
close_costfloatobjective unitsfinite and nonnegative; charged when an initially open branch closesrequired

Schema definition: BranchCurrentLimit.

fieldtypeunitsigninvariantif absent
idstringa branch identityrequired
from_pufloat or nullp.u. on base_mva and the from bus base_kvfinite and positivenull: unbounded
to_pufloat or nullp.u. on base_mva and the to bus base_kvfinite and positivenull: unbounded

powerio.McAcPfInstance

Schema definition: McAcPfInstance.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkat least one voltage sourcerequired
initial_pointStoredOperatingPointAssignment or nullnull

The prescribed terminal powers, source voltages, and active regulator and capacitor controls are derived from the network.

powerio.McAcOpfInstance

Schema definition: McAcOpfInstance.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkat least one voltage sourcerequired
objectiveObjectiverequired
constraintsMulticonductorActiveConstraintsrequired
initial_pointStoredOperatingPointAssignment or nullnull

powerio.LinDist3FlowPfInstance

The fixed-dispatch instance carries the same coefficient formulation as the OPF type, but its objective is empty and conductor limits are monitored after a converged solve rather than enforced as conic constraints.

Schema definition: LinDist3FlowPfInstance.

fieldtypeunitsigninvariantif absent
formulationLinDist3FlowOpfInstancezero objective, fixed generator dispatch, and conductor_limits selected as nonerequired

powerio.LinDist3FlowOpfInstance

Schema definition: LinDist3FlowOpfInstance.

fieldtypeunitsigninvariantif absent
baseMcAcOpfInstancecomplete multiconductor AC OPF instancerequired
optionsLinDist3FlowBuildOptionsfixed reference, unsupported-data, and neutral-provenance policies used to construct the formulationrequired

Schema definition: LinDist3FlowBuildOptions.

fieldtypeunitsigninvariantif absent
reference_policyauto, explicit, or source_propagatedselects the fixed coefficient phasorsrequired
unsupportedreject, lower, approximate, or permissiveselects the audited preparation-policy levelrequired
require_neutral_provenanceboolrequires a recorded neutral-Kron projection when truerequired

Schema definition: MulticonductorActiveConstraints.

fieldtypeunitsigninvariantif absent
terminal_voltage_boundsConstraintSelectionrequired
conductor_limitsConstraintSelectioncurrent or apparent power limitsrequired
generator_capabilityConstraintSelectionper phase boundsrequired

powerio.AcScucInstance

The DOE GO Challenge 3 formulation: one balanced network plus scheduling, reserve, and contingency inputs. Powers in the inputs are per unit on the network’s base_mva, times are hours from the start of the horizon, and costs are dollars or dollars per per unit hour, as the data format gives them.

Schema definition: AcScucInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkrequired
inputsScucInputsidentities name components of network; time varying records match the horizonrequired

Schema definition: ScucInputs.

fieldtypeunitsigninvariantif absent
interval_durationsarray of floathourspositive; chronologicalrequired
devicesarray of ScucDeviceid uniquerequired
active_reserve_zonesarray of ScucActiveReserveZonerequired
reactive_reserve_zonesarray of ScucReactiveReserveZonerequired
contingenciesarray of ScucContingencyrequired
shuntsarray of ScucShuntrequired
transformer_controlsarray of ScucTransformerControlrequired
branch_switching_costsarray of ScucBranchSwitchingCostrequired
violation_costsScucViolationCostsrequired

Schema definition: ScucDevice.

fieldtypeunitsigninvariantif absent
idComponentIdthe generator or load in the networkrequired
kindtoken producer, consumerrequired
on_costfloatdollarsrequired
startup_costfloatdollarsrequired
shutdown_costfloatdollarsrequired
initial_on_statusbooleanrequired
initial_commitmentScucInitialCommitmentrequired
minimum_up_timefloathoursrequired
minimum_down_timefloathoursrequired
ramp_limitsScucRampLimitsrequired
reserve_limitsScucReserveLimitsrequired
reactive_capabilityScucReactiveCapabilityrequired
energy_lower_boundsarray of ScucEnergyRequirementrequired
energy_upper_boundsarray of ScucEnergyRequirementrequired
startup_cost_adjustmentsarray of ScucStartupCostAdjustmentrequired
startup_limitsarray of ScucStartupLimitrequired
periodsarray of ScucDevicePeriodone per interval, chronologicalrequired

ScucReactiveCapability is tagged by kind: none; linear with reactive_power_at_zero_active_power and a slope; bounded with the _max and _min forms of both.

Schema definition: ScucDevicePeriod.

fieldtypeunitsigninvariantif absent
on_status_minbooleanrequired
on_status_maxbooleanrequired
active_power_minfloatp.u.active_power_min <= active_power_maxrequired
active_power_maxfloatp.u.required
reactive_power_minfloatp.u.reactive_power_min <= reactive_power_maxrequired
reactive_power_maxfloatp.u.required
energy_cost_blocksarray of ScucEnergyCostBlockrequired
reserve_costsScucReserveCostsrequired

Schema definition: ScucEnergyCostBlock.

fieldtypeunitsigninvariantif absent
block_sizefloatp.u.nonnegativerequired
marginal_costfloatdollars per p.u. hourrequired

Schema definition: ScucReserveCosts.

fieldtypeunitsigninvariantif absent
regulation_upfloatdollars per p.u. hourrequired
regulation_downfloatdollars per p.u. hourrequired
synchronizedfloatdollars per p.u. hourrequired
nonsynchronizedfloatdollars per p.u. hourrequired
ramping_up_onlinefloatdollars per p.u. hourrequired
ramping_up_offlinefloatdollars per p.u. hourrequired
ramping_down_onlinefloatdollars per p.u. hourrequired
ramping_down_offlinefloatdollars per p.u. hourrequired
reactive_upfloatdollars per p.u. hourrequired
reactive_downfloatdollars per p.u. hourrequired

Schema definition: ScucReserveLimits.

fieldtypeunitsigninvariantif absent
regulation_upfloatp.u.nonnegativerequired
regulation_downfloatp.u.nonnegativerequired
synchronizedfloatp.u.nonnegativerequired
nonsynchronizedfloatp.u.nonnegativerequired
ramping_up_onlinefloatp.u.nonnegativerequired
ramping_up_offlinefloatp.u.nonnegativerequired
ramping_down_onlinefloatp.u.nonnegativerequired
ramping_down_offlinefloatp.u.nonnegativerequired

Schema definition: ScucRampLimits.

fieldtypeunitsigninvariantif absent
upfloatp.u. per hournonnegativerequired
downfloatp.u. per hournonnegativerequired
startupfloatp.u. per hournonnegativerequired
shutdownfloatp.u. per hournonnegativerequired

Schema definition: ScucInitialCommitment.

fieldtypeunitsigninvariantif absent
accumulated_up_timefloathoursnonnegativerequired
accumulated_down_timefloathoursnonnegativerequired

Schema definition: ScucEnergyRequirement.

fieldtypeunitsigninvariantif absent
start_timefloathoursstart_time <= end_timerequired
end_timefloathoursrequired
energyfloatp.u. hourrequired

Schema definition: ScucStartupCostAdjustment.

fieldtypeunitsigninvariantif absent
maximum_down_timefloathoursrequired
costfloatdollarsrequired

Schema definition: ScucStartupLimit.

fieldtypeunitsigninvariantif absent
start_timefloathoursstart_time <= end_timerequired
end_timefloathoursrequired
maximum_startupsintegerrequired

Schema definition: ScucActiveReserveZone.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
busesarray of ComponentIdeach names a bus of the networkrequired
regulation_up_requirement_fractionfloatfraction of zone loadrequired
regulation_down_requirement_fractionfloatfraction of zone loadrequired
synchronized_requirement_fractionfloatfraction of zone loadrequired
nonsynchronized_requirement_fractionfloatfraction of zone loadrequired
ramping_up_requirementarray of floatp.u.one per intervalrequired
ramping_down_requirementarray of floatp.u.one per intervalrequired
regulation_up_violation_costfloatdollars per p.u. hourrequired
regulation_down_violation_costfloatdollars per p.u. hourrequired
synchronized_violation_costfloatdollars per p.u. hourrequired
nonsynchronized_violation_costfloatdollars per p.u. hourrequired
ramping_up_violation_costfloatdollars per p.u. hourrequired
ramping_down_violation_costfloatdollars per p.u. hourrequired

Schema definition: ScucReactiveReserveZone.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
busesarray of ComponentIdeach names a bus of the networkrequired
reactive_up_requirementarray of floatp.u.one per intervalrequired
reactive_down_requirementarray of floatp.u.one per intervalrequired
reactive_up_violation_costfloatdollars per p.u. hourrequired
reactive_down_violation_costfloatdollars per p.u. hourrequired

Schema definition: ScucContingency.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
componentsarray of ComponentIdChallenge 3 requires exactly one AC line, transformer, or DC linerequired

Schema definition: ScucShunt.

fieldtypeunitsigninvariantif absent
idComponentIdthe shunt in the networkrequired
initial_stepintegerstep_min <= initial_step <= step_maxrequired
step_minintegerrequired
step_maxintegerrequired
conductance_per_stepfloatp.u.required
susceptance_per_stepfloatp.u.positive is capacitiverequired

Schema definition: ScucTransformerControl.

fieldtypeunitsigninvariantif absent
idComponentIdthe two winding transformer in the networkrequired
tap_ratio_minfloatp.u.tap_ratio_min <= tap_ratio_maxrequired
tap_ratio_maxfloatp.u.required
phase_shift_minfloatradiansphase_shift_min <= phase_shift_maxrequired
phase_shift_maxfloatradiansrequired

Schema definition: ScucBranchSwitchingCost.

fieldtypeunitsigninvariantif absent
idComponentIdthe branch or transformer in the networkrequired
connection_costfloatdollarsrequired
disconnection_costfloatdollarsrequired

Schema definition: ScucViolationCosts.

fieldtypeunitsigninvariantif absent
active_power_balancefloatdollars per p.u. hourrequired
reactive_power_balancefloatdollars per p.u. hourrequired
branch_thermal_limitfloatdollars per p.u. hourrequired
energy_requirementfloatdollars per p.u. hourrequired

Solutions

A solution contains the instance it solves, and its arrays follow the instance network’s table order: one entry per bus, per branch, or per generator. Injections are net injections into the network at a bus, positive for generation; branch flows are measured into the branch at the named terminal. Each solution says how the calculation ended and what residuals the producer reported. producer is the producer’s free text solver identity, or null. In the DC, AC, SOCWR, multiconductor, and LinDist3Flow solutions, a per bus, branch, generator, terminal, source, or conductor array carries at most 4,194,304 entries; see Resource limits.

Termination is tagged by kind: converged, iteration_limit, infeasible, unbounded, failed, or not_reported, for a source that stores a solved calculation without termination information, as DeepMind OPFData does.

Schema definition: Residuals.

fieldtypeunitsigninvariantif absent
max_active_power_mismatchfloat or nullMWlargest absolute active balance mismatchnull (not reported)
max_reactive_power_mismatchfloat or nullMVArlargest absolute reactive balance mismatchnull (not reported)

Schema definition: GeneratorDispatch.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive is generationone per generatorrequired
q_mvararray of floatMVArpositive is generationone per generator, or emptyrequired

Schema definition: ThreeWindingTransformerTerminalActivePower.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive flows into the transformer at the windingthree entries, winding orderrequired

Schema definition: ThreeWindingTransformerTerminalPower.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive flows into the transformer at the windingthree entries, winding orderrequired
q_mvararray of floatMVArpositive flows into the transformer at the windingthree entries, winding orderrequired

powerio.DcPfSolution

Schema definition: DcPfSolution.

fieldtypeunitsigninvariantif absent
instanceDcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_active_powersarray of ThreeWindingTransformerTerminalActivePowerone per three winding transformerrequired
generator_dispatchGeneratorDispatch or nullnull

powerio.AcPfSolution

Schema definition: AcPfSolution.

fieldtypeunitsigninvariantif absent
instanceAcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_magnitudearray of floatp.u.one per busrequired
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
bus_reactive_injectionarray of floatMVArpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired
generator_dispatchGeneratorDispatch or nullnull

powerio.DcOpfSolution

Multipliers and marginals are the optimizing producer’s optional economic outputs, in the objective’s units per MW; no currency is assumed.

Schema definition: DcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceDcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
three_winding_transformer_terminal_active_powersarray of ThreeWindingTransformerTerminalActivePowerone per three winding transformerrequired
objectivefloatobjective unitsrequired
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
branch_from_limit_multiplierarray of float or nullobjective units per MWone per branch; finite and nonnegativenull
branch_to_limit_multiplierarray of float or nullobjective units per MWone per branch; finite and nonnegativenull

powerio.AcOpfSolution

Schema definition: AcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_magnitudearray of floatp.u.one per busrequired
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
bus_reactive_injectionarray of floatMVArpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
generator_reactive_powerarray of floatMVArpositive is generationone per generatorrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired
objectivefloatobjective unitsrequired
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
bus_reactive_power_marginalarray of float or nullobjective units per MVArone per busnull
branch_from_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull
branch_to_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull

powerio.AcOtsSolution

The final branch statuses of an AC optimal transmission switching instance and the AC optimal power flow solution of the fixed-topology problem they derive. Reading the document checks the topology against the instance and requires ac_solution.instance to state exactly that fixed problem and every open branch to carry zero flow. A NaN flow on an open branch records no flow. Other values follow the AC optimal power flow solution’s own rules, which accept NaN for an out-of-service generator or a non-converged objective. The objective is the AC objective plus the switching cost when the instance’s objective states branch_switching_cost.

Schema definition: AcOtsSolution.

fieldtypeunitsigninvariantif absent
instanceAcOtsInstancerequired
branch_closedarray of booleanone per branch; fixed branches unchanged; within the budgets and islanding policyrequired
ac_solutionAcOpfSolutionsolves the fixed-topology problem; open branches carry zero flowrequired

powerio.SocwrOpfSolution

The PowerModels SOCWR relaxation of an AcOpfInstance. Its objective is a lower bound, and its voltage products make no claim of an AC feasible phasor.

Schema definition: SocwrOpfSolution.

fieldtypeunitsigninvariantif absent
instanceAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
valuesSocwrOpfValuesrequired
dualsSocwrOpfDualsevery member null
objective_lower_boundfloatobjective unitsrequired

Schema definition: SocwrOpfValues.

fieldtypeunitsigninvariantif absent
bus_voltage_magnitude_squaredarray of floatp.u. squaredw[i] = |V_i|^2; one per busrequired
branch_voltage_product_realarray of floatp.u. squaredRe(V_from conj(V_to)); one per branchrequired
branch_voltage_product_imaginaryarray of floatp.u. squaredIm(V_from conj(V_to)); one per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
generator_reactive_powerarray of floatMVArpositive is generationone per generatorrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired

The four branch flow keys were branch_from_active_power, branch_from_reactive_power, branch_to_active_power, and branch_to_reactive_power in 0.11; the reader accepts those spellings in a 0.11 document.

Schema definition: SocwrOpfDuals.

fieldtypeunitsigninvariantif absent
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
bus_reactive_power_marginalarray of float or nullobjective units per MVArone per busnull
branch_from_thermal_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull
branch_to_thermal_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull

powerio.McAcPfSolution

Terminal columns run in bus table order and, within a bus, in the bus’s stated terminal order. Source columns run in source table order and, within a source, in its terminal_map order.

Schema definition: McAcPfSolution.

fieldtypeunitsigninvariantif absent
instanceMcAcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
terminal_voltage_magnitudearray of floatvoltsone per terminalrequired
terminal_voltage_anglearray of floatradiansone per terminalrequired
terminal_current_magnitudearray of float or nullamperesone per terminalnull
terminal_active_powerarray of float or nullwattspositive into the networkone per terminalnull
source_active_injectionarray of floatwattspositive into the networkone per source terminalrequired

powerio.McAcOpfSolution

generator_active_power is per terminal of each generator’s terminal_map. A generator’s cost and bounds are per coil, and generator_coil_active_power is the dispatch in that layout: a WYE generator has one coil per phase terminal in terminal_map order and none for the neutral; a DELTA generator on three terminals has the coils from terminal 1 to 2, 2 to 3, and 3 to 1 of its terminal_map; a DELTA or SINGLE_PHASE generator on two terminals has one coil. The two columns differ for a DELTA generator and for a WYE generator whose neutral voltage is not zero. generator_coil_active_power is written only when the producer reported it, from 0.12.3 on; a release before 0.12.3 refuses a document that states it.

Schema definition: McAcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceMcAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
terminal_voltage_magnitudearray of floatvoltsone per terminalrequired
terminal_voltage_anglearray of floatradiansone per terminalrequired
terminal_current_magnitudearray of float or nullamperesone per terminalnull
terminal_active_powerarray of float or nullwattspositive into the networkone per terminalnull
source_active_injectionarray of floatwattspositive into the networkone per source terminalrequired
generator_active_powerarray of floatwattspositive is generationone per generator terminal: generator table order, each generator’s terminal_map order, neutral includedrequired
generator_coil_active_powerarray of float or nullwattspositive is generationone per generator coil: generator table order, each generator’s coil ordernull
objectivefloatobjective unitsrequired

powerio.LinDist3FlowOpfSolution

The value arrays follow the topology and device channel orders fixed by the embedded instance, independently of a solver’s column ordering.

Schema definition: LinDist3FlowOpfSolution.

fieldtypeunitsigninvariantif absent
instanceLinDist3FlowOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
valuesLinDist3FlowOpfValuesphysical primal valuesrequired
objectivefloatobjective unitsrequired

powerio.LinDist3FlowPfSolution

The value arrays use the same physical axes and SI conventions as the OPF solution. Limit checks exist only for a converged point and report retained line/contact ratings that the fixed-dispatch problem deliberately did not enforce.

Schema definition: LinDist3FlowPfSolution.

fieldtypeunitsigninvariantif absent
instanceLinDist3FlowPfInstancerequired
terminationTerminationnon-converged results have no limit_checksrequired
residualsResidualsrequired
producerstring or nullnull
valuesLinDist3FlowOpfValuesphysical primal valuesrequired
limit_checksarray of LinDist3FlowLimitCheckidentities name retained line conductorsrequired

Schema definition: LinDist3FlowLimitCheck.

fieldtypeunitsigninvariantif absent
linestringretained line identityrequired
conductornonnegative integerposition in that line’s conductor orderrequired
kindline_apparent_power, line_current_from, or line_current_todetermines whether value and limit are VA or Arequired
valuefloatVA or Anonnegativefiniterequired
limitfloatVA or Apositivefiniterequired
loading_ratiofloatper unit of limitnonnegativeequals value / limitrequired
overloadedbooltrue exactly when loading_ratio > 1required
constraint_enforcedboolalways false for fixed dispatchrequired

Schema definition: LinDist3FlowOpfValues.

fieldtypeunitsigninvariantif absent
terminal_voltage_magnitude_squaredarray of floatvolts squarednonnegativetopology node orderrequired
line_active_powerarray of floatwattspositive from parent to childtopology conductor orderrequired
line_reactive_powerarray of floatvarspositive from parent to childtopology conductor orderrequired
generator_active_powerarray of floatwattspositive is generationgenerator table and channel orderrequired
generator_reactive_powerarray of floatvarspositive is generationgenerator table and channel orderrequired
source_active_powerarray of floatwattspositive into the networksource table and terminal-map orderrequired
source_reactive_powerarray of floatvarspositive into the networksource table and terminal-map orderrequired

powerio.AcScucSolution

The GO Challenge 3 output fields. Every series is values[t][row] over the instance’s time points and the corresponding table order; a series a producer did not supply is empty.

Schema definition: AcScucSolution.

fieldtypeunitsigninvariantif absent
instanceAcScucInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
network_outputsScucNetworkOutputsrequired
device_outputsScucDeviceOutputsrequired
objectivefloat or nulldollarsnull

Schema definition: ScucNetworkOutputs.

fieldtypeunitsigninvariantif absent
bus_vmarray of array of floatp.u.one row per time point, one per busrequired
bus_vaarray of array of floatradiansone per busrequired
shunt_steparray of array of integerone per shuntrequired
ac_line_on_statusarray of array of booleanone per AC linerequired
transformer_tmarray of array of floatratioone per two winding transformerrequired
transformer_taarray of array of floatradiansone per two winding transformerrequired
transformer_on_statusarray of array of booleanone per two winding transformerrequired
dc_line_pdc_frarray of array of floatp.u.positive from the from bus to the to busone per DC line[]
dc_line_qdc_frarray of array of floatp.u.positive is injected into the from busone per DC line[]
dc_line_qdc_toarray of array of floatp.u.positive is injected into the to busone per DC line[]

Schema definition: ScucDeviceOutputs.

fieldtypeunitsigninvariantif absent
on_statusarray of array of booleanone row per time point, one per devicerequired
startup_statusarray of array of booleanrequired
shutdown_statusarray of array of booleanrequired
p_onarray of array of floatp.u.positive is production for a producer, consumption for a consumerrequired
qarray of array of floatp.u.as p_onrequired
p_reg_res_uparray of array of floatp.u.nonnegativerequired
p_reg_res_downarray of array of floatp.u.nonnegativerequired
p_syn_resarray of array of floatp.u.nonnegativerequired
p_nsyn_resarray of array of floatp.u.nonnegativerequired
p_ramp_res_up_onlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_up_offlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_down_onlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_down_offlinearray of array of floatp.u.nonnegativerequired
q_res_uparray of array of floatp.u.nonnegativerequired
q_res_downarray of array of floatp.u.nonnegativerequired

Module records

The records beside value in a .pio.json document. .pio.json schema explains what each one is for; the tables here list their fields.

Schema definition: Producer.

fieldtypeunitsigninvariantif absent
namestringnonempty, boundedrequired
versionstringnonempty, boundedrequired

Schema definition: SourceDescriptor.

fieldtypeunitsigninvariantif absent
idstringunique among sources; spans and source map entries name itrequired
namestringa file name, never a local file pathrequired
byte_lengthintegerbytesevery span into this source ends at or before itrequired
formatstring or nulla format tokennull
digestDigest or nullnull

Schema definition: Digest.

fieldtypeunitsigninvariantif absent
algorithmtoken sha256required
valuestring64 lowercase hexadecimal charactersrequired

Schema definition: SourceSpan.

fieldtypeunitsigninvariantif absent
sourcestringnames a source idrequired
byte_startintegerbytes into the retained sourcebyte_start <= byte_end <= byte_lengthrequired
byte_endintegerbytes into the retained sourcehalf openrequired

Schema definition: SourceMapEntry.

fieldtypeunitsigninvariantif absent
targetstringan RFC 6901 pointer into value.datarequired
relationtoken exact, defaulted, inferred, converted_units, aggregated, split, synthetic, transformed, retained_extrarequired
spansarray of SourceSpanempty only for defaulted, synthetic, and transformed[]

Schema definition: Diagnostic.

fieldtypeunitsigninvariantif absent
idstringunique among diagnostics; assigned d0, d1, … at serialization when a record has nonerequired
codestringNAMESPACE.SCOPE.SPECIFICrequired
severitytoken error, warning, remark, noterequired
messagestringone linerequired
targetstring or nullan RFC 6901 pointer into value.datanull
spansarray of SourceSpanthe records the finding is about[]
relatedarray of stringeach names a diagnostic id in the document[]
detailsobject{}
suggested_actionstring or nullnull

Schema definition: HistoryEntry.

fieldtypeunitsigninvariantif absent
idstringunique among historyrequired
kindtoken parse, transform, edit, repair, solverequired
namestringthe operationrequired
input_typestring or nulla structural type namenull
output_typestring or nulla structural type namenull
parametersobject{}
assumptionsarray of string[]
lossesarray of string[]

BMOPF field mapping

This page says what each BMOPF field becomes in PowerIO, in which unit, and which constraint or objective term it enters. It is the authority for the BMOPF converter, so if you find a field that reads or writes differently from what is written here, one of the two has a defect.

The schema comes from the Task Force repository dsopt-schema. There is one BMOPF: PowerIO reads and writes the schema proposed in dsopt-schema#2 at commit 6796394, the Task Force’s schema plus the element classes the IEEE PES Task Force on Benchmarking Multiconductor OPF draft carried. The pin moves to the release tag the schema’s $id names once the Task Force ratifies it; the $id is already the URL of the schema’s bytes at that tag.

A document from an older BMOPF draft (including the bmopf-report drafts and the early draft PowerIO 0.11 wrote) is read as BMOPF: the reader also accepts the older spellings and layouts listed on this page, and reports READ.BMOPF.SCHEMA_LEGACY once. Writing it produces a document in the current schema; the source bytes are echoed only for a document that states a current meta.schema_version and no meta.$schema.

The schema renamed some tokens. The reader takes the earlier spellings, and a current document that uses them gets the same single READ.BMOPF.SCHEMA_LEGACY; a write states the current names:

Earlier spellingCurrentModel value
meta.$schemameta.schema_version onlynone; the $id goes in provenance
bus v_min, v_max, vn_maxvpg_min, vpg_max, vng_maxv_min_phase, v_max_phase, vn_max
regulator tap_ratio, tap_ratio_min, tap_ratio_max (and time_series keys)voltage_ratio, voltage_ratio_min, voltage_ratio_maxwindings[1].tap / windings[0].tap, extras["tap_ratio_min"], extras["tap_ratio_max"]
voltage_source.cost, ibr.costenergy_cost_rateVoltageSource::energy_cost_rate, extras["energy_cost_rate"]
prime_mover DSTATCOMSTATCOMIbrPrimeMover::Statcom (a model Dstatcom writes as STATCOM, reported)
q_unit, p_unit VA_FRACTIONPUVaFraction
dc_control droopDROOPthe string in extras
wire_data.kind overhead, cn_cable, ts_cable; line_geometry.earth_model modified_carson, full_carson, deriUPPER_SNAKEretained source data

The writer never states a value the schema rejects. A field outside its constraint (a tap or ratio that is not strictly positive, a control law of the wrong shape, a bus bound the bus cannot carry, a limit array of the wrong length) is dropped with EMIT.BMOPF.FIELD_DROPPED; a record whose required rating or nominal voltage is not strictly positive is dropped whole with EMIT.BMOPF.RECORD_DROPPED. A network with no voltage source still writes an empty voltage_source table, which the schema rejects; EMIT.BMOPF.SOURCE_COUNT reports it.

Conventions

Every BMOPF quantity is SI and absolute: volts, amperes, watts, vars, volt-amperes, ohms, siemens, metres, radians, hertz, and a cost rate in currency per kilowatt-hour. PowerIO stores the same units with no scaling, so a mapping below gives a unit only where the two names differ.

A matrix element A_k_j is row k, column j, counting from one, and lands in row k - 1, column j - 1 of the corresponding ConductorMatrix. These matrices are symmetric, so the reader fills an unstated transpose cell from its mirror; a stated cell wins over its mirror. A per terminal array has one entry per name in the element’s own terminal map, in that order, and PowerIO keeps that order.

An absent constraint field means no constraint and reads as None; an absent parameter field is zero. A field with no typed slot lands in the element’s extras, and the reader reports it under READ.BMOPF.RETAINED_SOURCE_ONLY. Fields with no typed slot lists every one.

Document level

BMOPFPowerIONote
namePioModule value name
meta.schema_versionidentifies the documentThe document’s one version identifier, which the schema requires. Written as the release the schema’s $id names; any patch release of that line reads as current. An older draft’s release raises READ.BMOPF.SCHEMA_LEGACY, and another value READ.BMOPF.SCHEMA_UNKNOWN. Output records the schema’s $id (BMOPF_SCHEMA_ID), the proposal commit, the schema digest, and the retrieval permalink (bmopf_proposal_url()) under meta.provenance.powerio_bmopf.
meta.$schemaidentifies a document from an older draftRemoved in the current schema and never written. A document without meta.schema_version is identified by it, as the older drafts defined: their identifiers, the bmopf-report draft locations, the early draft permalinks, and the PowerIO archive URLs that 0.11 stamped raise READ.BMOPF.SCHEMA_LEGACY; the current schema’s location reads as current with the key counted as an earlier spelling. A current document carrying it reads too, counted the same way. A $schema and a release number naming different lines raise READ.BMOPF.SCHEMA_MISMATCH. Neither stated raises READ.BMOPF.SCHEMA_ABSENT. Every one parses, read as BMOPF.
meta.crsMulticonductorNetwork::geo coordinate spaceThe authority code of every geo field’s system; absent means OGC:CRS84, WGS84 longitude then latitude, and coordinates are always x then y, so EPSG:4326 reads the same way. Written for a projected or non-WGS84 system, omitted for WGS84. A space the schema cannot name (unknown, diagram, a code-less projection) or coordinates not from the source also travel as extras.powerio_geo, which the reader prefers.
meta.frequencyMulticonductorNetwork::base_frequency, HzAbsent defaults to 60 with READ.BMOPF.VALUE_DEFAULTED.
meta.* (the rest)MulticonductorNetwork::extras["bmopf_meta"]Re-emitted, except the three the writer owns.
terminal_conventionsMulticonductorNetwork::extras["bmopf_terminal_conventions"]Re-emitted verbatim; authored from the terminal names when the source states none, each label classified by calc_terminal_role over the network’s conventions (the CIM wire convention, 4 neutral on every bus, for a network read from distribution CIM or MG-RAVENS).
extrasMulticonductorNetwork::extras["bmopf_extras"]Re-emitted verbatim, minus the tables the reader types out of it.

bus

DistBus, in MulticonductorNetwork::buses().

BMOPFPowerIONote
terminal_namesterminalsOrdered; fixes every per-terminal order on this bus.
perfectly_grounded_terminalsgrounded
vpg_min, vpg_max; read also as v_min, v_max (the first draft)v_min_phase, v_max_phase and scalar v_min, v_maxPhase to ground, one entry per phase terminal. Written as vpg_*. Both spellings read, the current one first; a current document that uses v_* raises one READ.BMOPF.SCHEMA_LEGACY naming the spellings, since that schema rejects them, and both spellings disagreeing raises READ.BMOPF.SEMANTIC_INVALID. Unequal bounds remain ordered phase vectors through IR and bindings. A scalar edit explicitly overrides the vector; balanced lowering rejects unequal phase bounds.
vpn_min, vpn_maxvpn_min, vpn_maxPer phase terminal, kept as arrays.
vpp_min, vpp_maxvpp_min, vpp_maxPer ordered phase pair.
vpos_min, vpos_maxvpos_min, vpos_maxScalars.
vneg_max, vzero_maxvneg_max, vzero_maxMagnitude caps; the lower bound is always zero.
vng_max; read also as vn_max (older drafts)vn_maxNeutral to ground cap. Written as vng_max. A current document that uses vn_max raises the same single READ.BMOPF.SCHEMA_LEGACY as v_*, and both spellings disagreeing raises READ.BMOPF.SEMANTIC_INVALID.
geolocation and MulticonductorNetwork::geoA GeoJSON Point in the system meta.crs names. Written for every bus with a finite location. The reader also accepts the extras.geojson FeatureCollection that PowerIO 0.11 wrote, when no element carries a geo field; it is never written.
longitude, latitudelocation and MulticonductorNetwork::geoThe pre-schema BMOPFTools coordinate fields, outside every schema version. Read into the coordinate space as WGS84; never written back.

line and linecode

DistLine and DistLineCode.

BMOPFPowerIONote
line.bus_from, line.bus_tobus_from, bus_to
line.terminal_map_from, line.terminal_map_toterminal_map_from, terminal_map_toPosition i of the from map fixes matrix index i.
line.linecodelinecode
line.lengthlength, m
line.R_series_i_j, line.X_series_i_ja synthesized DistLineCode named after the line, ohm per metre at unit lengthThe inline branch states the absolute ohms of the whole line, and its length is descriptive. The reader keeps those ohms unscaled in the synthesized line code and sets the line’s length to 1 m, so length times the per metre value is the stated impedance; a stated length other than 1 raises READ.BMOPF.VALUE_DEFAULTED. READ.BMOPF.VALUE_INFERRED names the synthesis. A line that names a linecode takes no inline key.
line.G_from_i_j, line.B_from_i_j, line.G_to_i_j, line.B_to_i_jthe same synthesized line code’s g_from, b_from, g_to, b_to
line.i_max, line.s_maxi_max, s_maxOne entry per conductor of terminal_map_from; override the line code’s. An older draft’s line text said s_max is per phase: a document stating one entry per phase on a map with a neutral reads per conductor with the neutral unbounded (READ.BMOPF.VALUE_INFERRED). A write states s_max only when it has one finite entry per conductor, and otherwise drops it with EMIT.BMOPF.FIELD_DROPPED rather than inventing a limit.
line.georouteA GeoJSON LineString from bus_from through any bends to bus_to, in the system meta.crs names; descriptive, length stays the electrical length. Written for every line with a route of two or more finite vertices.
linecode.R_series_i_j, linecode.X_series_i_jr_series, x_series, ohm per metre
linecode.G_from_i_j, linecode.B_from_i_j, linecode.G_to_i_j, linecode.B_to_i_jg_from, b_from, g_to, b_to, siemens per metreHalf the total shunt at each end.
linecode.i_max, linecode.s_maxi_max, s_maxPer conductor, in matrix row order, applied at both ends. A write drops an s_max of another length.
linecode.sourcesource
linecode.line_geometry, linecode.derivationextrasSchema fields; retained on read, not typed, and not written (EMIT.BMOPF.FIELD_DROPPED).

A line has exactly one impedance source, and the oneOf in both schema versions enforces it: either a linecode with a length, or inline R_series_1_1 and X_series_1_1 with no linecode.

Element geometry

Every located element other than a bus or line may carry a geo: a GeoJSON Point on voltage_source, load, generator, ibr, shunt and capacitor, and a Point or LineString on switch and every transformer subtype. The DC classes take one too and pass through unchanged with the rest of their object.

BMOPFPowerIONote
<element>.geo Pointa DistComponentLocation for that element (MulticonductorNetwork::component_locations)Longitude and latitude in degrees, with meta.crs as the datum (EPSG:4326 when absent).
switch.geo, transformer.<subtype>.<name>.geo LineStringthe same, at the midpoint of the LineString’s two end positionsReported once with READ.BMOPF.VALUE_COLLAPSED; a write states that Point.
bbox on any geonot readNever written.

A component location is geographic, so a geo in a projected document reads nothing and raises READ.BMOPF.FIELD_DROPPED. The writer states a component location as its element’s geo Point when the document’s geometry is WGS84 (no meta.crs) and the point states both axes and a WGS84 datum or none. A point stating no datum, or an origin other than the source data, reads back as WGS84 source coordinates, which EMIT.BMOPF.VALUE_SUBSTITUTED reports. The rest, including component points on buses and lines (whose geo carries the bus location and the line route), raise EMIT.DIST.COMPONENT_COORDINATES_DROPPED.

switch

DistSwitch.

BMOPFPowerIONote
bus_from, bus_to, terminal_map_from, terminal_map_tothe same names
open_switchopen
i_maxi_maxPer conductor. A switch has no shunt, so both ends carry the same magnitude and one array bounds both.

load

DistLoad. Each array has one entry per branch of the load: a phase to neutral branch for WYE, the terminal pair for SINGLE_PHASE, or a line to line branch for DELTA.

BMOPFPowerIONote
bus, terminal_map, configurationthe same namesconfiguration reads case-insensitively; an unrecognized value reads as WYE with READ.BMOPF.VALUE_UNSUPPORTED.
p_nom, q_nomp_nom, q_nom, W and var
modelthe DistLoadVoltageModel variantCONSTANT_POWER, CONSTANT_CURRENT, CONSTANT_IMPEDANCE, ZIP, EXPONENTIAL.
v_nomthe variant’s v_nom
alpha_z, alpha_i, alpha_p, beta_z, beta_i, beta_pthe Zip variant’s fieldsThe three active fractions sum to one, and so do the three reactive.
gamma_p, gamma_qthe Exponential variant’s fields

generator

DistGenerator. Arrays are per phase conductor; WYE is the only configuration the specification supports.

BMOPFPowerIONote
bus, terminal_map, configurationthe same names
p_min, p_max, q_min, q_maxthe same names, W and varWhen a bound pair is equal the dispatch is pinned, and the reader states the same values as p_nom and q_nom so a power flow target has a setpoint.
s_maxs_max, VABounds the sum of squares of that phase’s active and reactive power.
i_maxi_max, APer phase, with an optional trailing entry bounding the neutral return current.
energy_cost_rate, or the deprecated costcost, currency per kWhKept exactly as stated: one entry per phase. A bare scalar reads as a one-entry statement. Written as energy_cost_rate.

voltage_source

VoltageSource. Both versions permit exactly one.

BMOPFPowerIONote
bus, terminal_mapthe same names
v_magnitudev_magnitude, VPer terminal, phase to ground; a grounded terminal states zero.
v_anglev_angle, radPer terminal.
energy_cost_rateenergy_cost_rate, currency per kWhOne entry per phase conductor; neutral terminals have no entry. The schema removed cost here; a document that still states it reads it as energy_cost_rate (with one READ.BMOPF.SCHEMA_LEGACY when it states the current schema), and a write never states cost.
p_min, p_max, q_min, q_maxextrasRetained and re-emitted, not typed.

shunt and capacitor

DistShunt is raw admittance, grounding impedance included. Scalar capacitor ratings use the bank model DistCapacitor; arrays of per-coil ratings are lowered into an exact DistShunt terminal matrix.

BMOPFPowerIONote
shunt.bus, shunt.terminal_mapthe same names
shunt.G_i_j, shunt.B_i_jg, b, total siemens in conductor order
capacitor.bus, capacitor.terminal_map, capacitor.configurationthe same names for a scalar bank; bus, terminal order and matrix incidence for an array
capacitor.q_ratedScalar: q_rated, var; array: terminal shunt b, siemensA scalar rates the whole bank. Array entries rate individual WYE coils or DELTA phase pairs, in var.
capacitor.v_nomScalar: v_nom, V; array: used in q / v_nom²Scalar: line-to-line for three-phase banks, across the pair for SINGLE_PHASE. Array: phase-to-neutral for WYE, phase-to-phase for DELTA, and across the stated pair for SINGLE_PHASE.

transformer

DistTransformer with windings: Vec<DistWinding>. The BMOPF subtype is kept in DistTransformer::extras["bmopf_subtype"], because the winding list alone does not pin down every subtype; a centre tap unit, for example, reads as two secondary windings.

BMOPFPowerIONote
bus_from, bus_towindings[0].bus, windings[1].bus
terminal_map_from, terminal_map_tothe corresponding terminal_mapcenter_tap expands the three to-side terminals into two windings.
v_nom_from, v_nom_towindings[k].v_ref, VFor center_tap, v_nom_to is the per leg voltage.
s_ratingwindings[k].s_rating, VA
r_series_from, r_series_towindings[k].r_pct, percent of that winding’s own baseThe base is n_phases * v_ref^2 / s_rating.
x_series_from, x_series_toxsc_pct, percentThe short-circuit test measures the series sum referred to one side, which is what this field is.
r_series, x_series (three-phase legacy)windings[0].r_pct and xsc_pctThe lumped wye-side spelling; the delta winding is lossless in this model.
tap_ratio; read also as tapwindings[0].tap / windings[1].tapThe multiplier on the nameplate turns ratio.
tap_ratio_min, tap_ratio_maxextrasBounds have no typed winding slot.
r_neutral_from, x_neutral_fromwindings[0].r_neutral, x_neutral, ohmThe winding’s own neutral to earth branch.
r_neutral_to, x_neutral_towindings[1].r_neutral, x_neutral
g_no_load, b_no_loadextrasThe magnetising branch has no typed slot.
i_max_from, i_max_toextrasPer winding conductor of that side, in that side’s own amperes.
n_winding.windings[]one DistWinding eachbus, terminal_map, v_nom, configuration (WYE or DELTA), r_winding, delta_roll, i_max, r_neutral, x_neutral. Both neutral fields are nonnegative; a write drops a negative or nonfinite one with EMIT.BMOPF.TRANSFORMER_NEUTRAL_DROPPED, as the two-winding subtypes do.
n_winding.x_scxsc_pct, ordered 12, 13, ..., 1n, 23, ..., (n-1)nKeyed i_j with i < j in BMOPF, all referred to winding 1.
single_phase_autotransformer, open_delta_regulatorwindings plus extras["bmopf_subtype"]voltage_ratio (read also as the earlier tap_ratio) is the regulated over source voltage ratio, V_to/V_from, for both ANSI types: windings[1].tap / windings[0].tap. Its bounds voltage_ratio_min/voltage_ratio_max, regulator_type and the open delta connection ride in extras; regulator_type records the A/B hardware and does not change the ratio.

The two-winding subtypes declare the tap ratio and its bounds, the four winding neutral fields, and the two no-load fields in place, spelling the ratio tap_ratio, tap_ratio_min, and tap_ratio_max. A document written against an earlier version that carries them under extras.transformer.<subtype>.<name>, or spells the ratio tap, is folded back on read; on a key collision the field already in the subtype object wins.

OpenDSS Xscarray populates every winding-pair reactance in this order. The reader applies scalar XHL/XHT/XLT updates at edit boundaries; regenerated four-or-more-winding records use the complete Xscarray.

ibr and control_profile

DistIbr and DistControlProfile. Both are typed and written as top-level tables. A document written against an earlier version may carry them under extras; on read they come from either place, and the top-level copy wins.

BMOPFPowerIONote
bus, terminal_mapthe same names
topologytopology: SINGLE_PHASE, THREE_LEG, FOUR_LEG
prime_moverprime_mover: PV, BATTERY, GENERIC, STATCOMDSTATCOM, removed from the schema, reads as STATCOM.
s_maxs_max, VA per phase
i_maxi_max, A per conductor
p_availp_avail, W
p_min, p_max, q_min, q_maxthe same names, per phase
control_profilecontrol_profile, an id
voltage_aggregationvoltage_aggregation: PER_PHASE, AVERAGE
energy_cost_rate; read also as costextras["energy_cost_rate"]Retained, not typed. The schema removed ibr.cost; the reader moves a stated cost to energy_cost_rate (with one READ.BMOPF.SCHEMA_LEGACY when the document states the current schema), a write states only energy_cost_rate, and the IVR objective prices the inverter from it.
dc_bus, dc_terminal_map, dc_control, dc_v_set, dc_p_ref, dc_droop, dc_deadband, dc_link_coupled, p_dc_min, p_dc_maxextrasThe DC coupling fields; retained, not typed.
r_filter, x_filter, b_filter_shunt, grid_forming, v_ref_internalextrasRetained, not typed.
control_profile.power_factor.pfPowerFactorControl
control_profile.volt_var.*VoltVarControl: voltage_reference, breakpoints, q_limits, q_unit, q_ref, and the two active-power thresholds
control_profile.volt_watt.*VoltWattControl: voltage_reference, breakpoints, p_limits, p_unit, p_ref

Fields with no typed slot

The classes below read into MulticonductorNetwork::untyped() by class and name, with their properties kept as text, and are written back to the top-level table the schema declares. A time series profile whose meaning BMOPF’s multiplicative profiles cannot carry stays under extras.time_series. Reading each one reports READ.BMOPF.RETAINED_SOURCE_ONLY.

dc_bus, dc_branch, dc_grounding, dc_load, dc_source, time_series, wire_data, line_geometry, and a per-element time_series reference map.

The DC classes, the time series and the reference maps pass through and re-emit unchanged. wire_data and line_geometry are retained on read but not written, each reported with EMIT.BMOPF.RECORD_DROPPED. Nothing reads their values into a calculation, so if a case’s behaviour depends on them, the instance PowerIO builds from it does not represent that case. The reader says so per class rather than leaving you to discover it.

The calculation

powerio::to_mc_ac_opf_instance builds a McAcOpfInstance through McAcOpfInstance::from_network. The instance shares the network rather than copying it: it selects which of the network’s stated limits are active constraints and which objective terms are summed, and reads the numbers from the network.

Objective. There is one term, ObjectiveTerm::ActivePowerDispatchCost, which is the specification’s default objective: the sum over every dispatchable element and every phase of that phase’s cost rate against the active power the element injects into the network. A positive cost minimises the element’s injection and a negative cost maximises it, and that holds the same way for a generator, the voltage source, and an IBR. The rate comes from the element’s own per phase rate: a generator reads it from DistGenerator::cost (BMOPF energy_cost_rate, or its deprecated alias cost), a voltage source from VoltageSource::energy_cost_rate, and an IBR from its extras["energy_cost_rate"] (the earlier cost spelling when only that is stated). ObjectiveTerm::NetworkGeneratorCost is the term for a balanced network and is not part of a BMOPF instance.

Constraints. MulticonductorActiveConstraints selects three families, each ConstraintSelection::All by default, which matches the specification’s rule that constraints are active for the elements present.

FamilyThe BMOPF fields it activates
terminal_voltage_boundsbus.vpg_min, vpg_max, vpn_min, vpn_max, vpp_min, vpp_max, vpos_min, vpos_max, vneg_max, vzero_max, vng_max
conductor_limitsline.i_max, line.s_max, linecode.i_max, linecode.s_max, switch.i_max, transformer.i_max_from, transformer.i_max_to
generator_capabilitygenerator.p_min, p_max, q_min, q_max, s_max, i_max, and the same bounds on an IBR

A family selects by stable element identity, so a study that relaxes one line’s thermal limit refers to that line instead of restating the bound. ConstraintSelection::None relaxes a whole family, and Only lists the elements whose limits stay active.

Equipment behaviour has no selection family, because there is no limit to relax: a closed switch equates its two ends conductor by conductor, an open switch carries no current, the ideal winding pair relates its two coil voltages by the turns ratio and balances ampere-turns, and the voltage source fixes its terminal voltage with a free current. Those hold in every instance built from a network that includes them.

The solution

Solved values stay in McAcOpfSolution and are not written back into the network, so the network still describes the case and the solution describes one result of it.

McAcOpfSolutionUnit and order
terminal_voltage_magnitudeV, resolved terminal order
terminal_voltage_anglerad, resolved terminal order
terminal_current_magnitudeA, resolved terminal order, when the solver reports it
terminal_active_powerW, resolved terminal order, when the solver reports it
source_active_injectionW, per source terminal
generator_active_powerW, per generator terminal: generator table order with each generator’s terminal map order, neutral included
generator_coil_active_powerW, per generator coil, when the solver reports it: generator table order with each generator’s coil order, the order of its p_min, p_max and energy_cost_rate entries
objectivethe optimised objective value
termination, residuals, producerhow the solve ended, its residuals, and what produced it

Checked against what

The reference data is the two published example networks, vendored at tests/data/dist/bmopf/. powerio-dist/tests/bmopf.rs checks that each one parses, that writing the result validates against the schema of the version written, that a second write is identical to the first, and that parsing the written document reproduces the model. The equations above were checked against the specification pages of math-and-data-model-specifications rather than inferred from the data.

BMOPFTools.jl is publicly available and is identified as the generator of example_ieee13.json. The PowerIO 0.11 compatibility change exercises the typed module API, explicit legacy schema version, retained diagnostics, transformer core-shunt locations and nominal n-winding imports. Its numerical suite compares power-flow voltages and transformer admittance with OpenDSS, including independently prepared BMOPF cases and native OpenDSS conversions.

PowerIO’s structural tests additionally check triangular matrix completion, conductor order, regulator fields, proposal provenance and rejected malformed records. These checks distinguish data preservation from the equations a particular solver supports; retaining a regulator or n-winding record does not imply that PowerIO’s own matrix compiler implements it.

Explicit terminal-coil no-load admittance

transformer.<subtype>.<id>.no_load_shunt holds {winding, g, b} in transformer extras and in PowerIO IR. The one-based winding index fixes its physical location, and g + j b is siemens per coil at the terminal voltage. It cannot coexist with the existing from-side g_no_load and b_no_load fields.

OpenDSS and PMD exciting-branch percentages map to winding 2 with a negative magnetizing susceptance. Conversion uses the actual tapped WYE phase-to-neutral or DELTA phase-to-phase coil voltage and divides total transformer VA by the phase count. A winding-2 shunt converts back to those percentages; other locations report that this target parameterization cannot represent them. Legacy BMOPF output preserves the object under extras.transformer and reports the relocation. Nonzero core shunts reject the limited PowerIO passive transformer matrix profile before execution.

The independent check evals/validation/validate_bmopf_core_shunts.py compares six transformer topologies with OpenDSS Yprim through an intermediate PowerIO IR document. BMOPFTools’ 0.11 adapter uses an equivalent bus-shunt matrix and retains the original coil object in provenance. Successful parsing alone does not establish support for a transformer calculation.

Per-coil capacitor arrays and regulator edits

BMOPF capacitor q_rated arrays state vars per coil at the stated coil voltage v_nom. The reader lowers these arrays exactly into a DistShunt terminal susceptance matrix: each coil contributes q / v_nom² to its two diagonal entries and the negative value to the two cross entries. WYE coils use the last mapped terminal as the return; DELTA uses the ordered cyclic pairs (one pair for a two-terminal device). A lone WYE terminal connects to ground.

The generated name starts with __bmopf_capacitor_ and receives a suffix if needed to avoid a declared shunt. READ.BMOPF.CAPACITOR_LOWERED records this exact representation change. Canonical emission writes the shunt; source-preserving module emission still preserves the retained source bytes. Invalid array shapes, negative/nonfinite ratings, nonpositive voltage, repeated terminals, and more than 64 terminals fail parsing rather than approximating a bank. Scalar bank capacitors continue to use DistCapacitor.

No hidden capacitor metadata carries electrical coefficients. Editing the canonical shunt changes the emitted electrical data directly. Y-bus assembly, LinDist3Flow lowering, and IVR preparation consume the same terminal matrix. Open-delta regulators retain their original map only while it agrees with both canonical winding maps; otherwise emission writes separate regulator legs and reports the loss of the original grouping. N-winding s_max remains on its original winding axis in the existing winding metadata.

Scalar single-coil IBR bounds

The reader accepts scalar p_min, p_max, q_min, q_max, s_max and i_max as one-entry vectors, matching the reference engine’s single-coil convention. In particular, p_max: 0 is an enforced zero-availability bound, not an absent field. Scalars are not broadcast across multiple coils; downstream cardinality validation still applies. Malformed scalar values remain nonfinite and invalid, rather than disappearing from the prepared problem.

Integrated transmission/distribution modeling

powerio-tnd owns the relationship between BalancedNetwork and MulticonductorNetwork. Its Rust API is also available through powerio::tnd. The component crates remain independently usable. Cross-model transformations live in tnd; facade transformations add the common module record handling.

IntegratedNetwork::new takes a transmission PioModule, a map of named feeder modules, and explicit interfaces. Each interface identifies a transmission bus, a feeder voltage source, and its A/B/C terminals. Names stay scoped to each component, and the original modules retain their source bytes and records. Construction checks references, shared frequency, competing source constraints, phase maps, and the load replacement policy. Closed ideal switches join terminals by their terminal maps, so a source, ground, or other interface reached through them counts as competing at the terminal it reaches. Its validated contents are immutable.

An interface states a positive voltage ratio, which Interface::new requires, and an angle displacement in radians. Construction checks the selected source’s stated phase voltages against it: each magnitude must lie within 0.5 to 2 times the bus phase voltage times the ratio, and the stated angles must rotate A, B, C in the phase map’s order. A wrong ratio or a swapped phase map therefore fails before any coupled equation uses it. boundary_voltages converts transmission positive-sequence per-unit voltage using the bus line-to-line kV base into feeder phase-to-earth volts, in A/B/C order. boundary_power sums V times conjugate(I) and returns MW + j MVAr, positive into the feeder. Each current is measured in amperes with the same phase order. The interface is lossless. A consumer supplies any substation transformer losses inside a component model; different component MVA bases do not alter these SI boundary quantities.

The consumer replaces the selected source’s three phase voltage equations with coupled equations. Additional zero-volt source terminals remain earth clamps. Floating-reference sources are refused by this initial interface rules. TransmissionDemand::Additional adds the feeder demand at the transmission bus; ReplaceLoads names the active load UIDs to substitute when assembling coupled equations. Keeping this choice explicit prevents double-counting feeder demand. The retained standalone component records are unchanged, so a consumer must apply these substitutions when building an integrated calculation.

Formats and migration

SINCAL is the first adapter under powerio_tnd::formats::sincal. Enable the sincal feature to acquire and retain native projects, parse explicit balanced or multiconductor profiles, and author the supported experimental outputs. Storage internals remain hidden from normal rustdoc. The existing powerio format names, CLI behavior, Python API, and C ABI remain available. Direct Rust users of the unreleased SINCAL adapters move from the tx/dist crates to tnd. powerio::dist::parse_sincal remains available as a facade convenience. The published powerio-sincal-tables transport identity remains unchanged.

powerio_tnd::formats::pandapower reads three-phase pandapower JSON into a MulticonductorNetwork and hands every other pandapower document to the balanced reader. See pandapower three-phase JSON.

SINCAL profile parsing produces a component module. An integrated case requires explicit interfaces; voltage levels alone cannot establish a network partition or determine which transmission load a feeder replaces. Existing MATPOWER and OpenDSS modules can be composed through the same generic API.

Extension points

A future native integrated format should store component references and an interface manifest, with a versioned boundary schema and retained source records. A PowerModelsITD.jl adapter can map its component files and boundary definitions into this composition. Both adapters should reuse the component parsers and checked interface constructor.

The initial integration API is Rust-only. PowerIO IR and the facade’s PioValue variants are unchanged. A future integrated IR variant and binding accessors need a separate compatibility design. Coupled calculation instances belong in powerio-prob, while sparse coupled operators belong in powerio-matrix. Solver algorithms remain downstream.

Crate graph and architecture map

The workspace is layered. Shared infrastructure sits below every parser and a thin facade sits on top; no lower crate depends on the facade, and the two network crates do not depend on each other.

powerio-core          Source, FormatId, Diagnostic, Error, PioModule<T>,
                      TimePoint, TimeSeries<T>, ScenarioSet<T>, Destination
├── powerio-archive   bounded ZIP indexing and verified reads; no case discovery
├── powerio-tx        BalancedNetwork and the balanced readers and writers
└── powerio-dist      MulticonductorNetwork and the OpenDSS, PMD, BMOPF, and CIM converters

powerio-tnd          IntegratedNetwork, cross-model transformations, and
                      optional SINCAL adapters; depends on core, tx, and dist

powerio-prob          operating points, updates, the nine instances, the ten
                      solutions, and GO Challenge 3, OPFData, and BMOPF assembly;
                      depends on core, tx, and dist; matrix free
powerio-synth        deterministic topology-only network generators;
                      depends on tx
powerio-matrix        sparse matrices and graph data for both network families;
                      depends on core, tx, dist, prob, and synth
powerio               PioValue, parse, emit, serialize, deserialize, and the
                      re-exports; depends on core, tx, dist, prob, tnd, and on matrix
                      behind the `matrix` feature
powerio-cli, powerio-capi, powerio-py, powerio-wasm    over the facade

A change has to keep that shape. powerio-core owns no electrical type, parser, matrix, instance, or IR record layout. powerio-tx and powerio-dist stay usable on their own, so a distribution consumer pulls in neither the balanced model nor the matrix stack. powerio-prob does not depend on powerio-matrix. The facade re-exports the component crates, which is why cargo add powerio gets you everything, and its matrix feature adds the matrix crate without creating a cycle. CI checks these edges against cargo metadata, so the map below and the manifests cannot drift apart.

The powerio-tnd crate composes the independent network models through checked interfaces and owns cross-model transformations. SINCAL is its first optional format module. The facade enables powerio-tnd/sincal by default; disabling that feature keeps SQLite out of the dependency graph. The architecture gate requires the model crates to remain independent of tnd and each other. See Integrated transmission/distribution modeling for the interface rules and planned extensions.

Components

The PowerIO component map: powerio-core at the bottom; powerio-tx and powerio-dist as independent siblings above it; powerio-prob over both networks; powerio-matrix over the networks and prob; the powerio facade over the component crates with an optional matrix feature edge; powerio-cli, powerio-capi, powerio-py, and powerio-wasm over the facade; solvers consume instances from powerio-prob and the GridFM pipeline reads Parquet datasets from powerio-matrix.

The facade does not force a consumer to depend on every component crate, and the two network crates are siblings with no edge between them. Solvers consume instances but sit outside PowerIO, and their workspaces and numerical caches stay outside with them.

Data flow

The PowerIO data flow: a Source of named immutable bytes enters parse, which produces a PioModule holding the typed value, retained source, diagnostics, and history; time series and scenario sets expose owner rooted typed entries through indexing and iteration; to_balanced derives a balanced module from a multiconductor module with reported assumptions and losses; calc operations return matrices and vectors with element mappings; emit produces grid exchange formats; serialize and deserialize connect the module to PowerIO IR.

Every arrow out of the module is an explicit call that returns diagnostics; nothing is transformed as a side effect of something else.

The diagram sources are in docs/diagrams/*.dot. scripts/check-architecture-map.py checks the drawn crate edges against cargo metadata and, with --render, regenerates the images.

Why powerio-archive is separate

The shared-collection plan #774 introduced this boundary in #776. It owns model-neutral ZIP transport: bounded metadata indexing, normalized entry names, overlap and descriptor checks, and size/CRC-verified entry reads. It never extracts files or decides which electrical model a file contains. The facade owns case discovery, manifests, dependency observations, and nested collection selection. CGMES and SINCAL also reuse the crate’s bounded reading primitives; they do not yet use its complete collection inventory.

This separation keeps ZIP dependencies out of powerio-core, and lets lower format adapters share the same transport primitives without depending on the facade. It also makes the hostile-input tests usable independently of network parsing. Moving these functions into the facade would introduce a dependency cycle; moving them into core would add archive concerns to every core consumer. A separate crate is not a requirement of the file format, but it is a useful boundary for the current dependency graph. Its cost is another published crate and release bootstrap step. An inventory is not a certificate that every unread entry has passed CRC validation, nor a bound on subsequent electrical model allocations; callers still inspect diagnostics and apply model limits.

LLVM and MLIR lessons

PowerIO’s design borrows from LLVM and MLIR where their problems overlap with reading, transforming, and writing power system data. This page goes through each lesson taken and where the shipped design applies it, then the mechanisms left out on purpose. Primary references: the MLIR language reference, diagnostics, interfaces, pass management, and dialect definition documents.

Adopted

A small shared foundation under acyclic higher layers. LLVM’s library layering puts Support under IR under the producers. PowerIO’s powerio-core owns sources, diagnostics, errors, the module, and the generic containers; the network crates, the calculation crate, and the matrix crate stack over it in one direction, and CI asserts the edges from cargo metadata (Crate graph).

Source ownership that survives parsing. MLIR’s source manager keeps buffers alive so locations mean something after parsing. A PioModule retains its source, and same format emission returns those bytes unchanged. A diagnostic has a source identifier plus a byte range into those exact bytes, end to end, and the MATPOWER, PSS/E RAW, UCTE-DEF, and IEEE CDF readers attach the range of the record a finding is about, for the failure that ends a read and for warnings alike; the other readers attach no span yet.

Deterministic serialization. serialize is a function of the module alone, so one module serializes to identical text every time, and serializing the module that text deserializes to reproduces the text. Members are written in a fixed order (record fields in declaration order, map keys sorted), diagnostic IDs are minted d0, d1, … in record order for records that have none, and every float is written in the shortest decimal form that reads back to the same value. Two equal modules therefore compare equal as documents, which is what a cache key, a golden file, or a content digest needs.

Entry points that acquire their own input, with configuration as a value. MLIR reads a module through one operation with three input kinds: parseSourceFile(filename, block, config) opens the named file itself, parseSourceFile(sourceMgr, ...) takes a source manager the caller built, and parseSourceString(text, block, config, sourceName) takes content whose name supplies diagnostic locations. LLVM’s object::createBinary has the same pair of a path and a buffer and “autodetect[s] the file type” rather than taking a format argument. PowerIO’s parse, emit, serialize, and deserialize take their input or output through IntoSource and IntoDestination, which accept a file or directory name, content already in memory, and a built Source or Destination, so the ordinary read is parse("case.raw") with one call and one failure point, and detection is the default. Optional configuration is a documented value, as in writeBytecodeToFile(op, os, config = {}) and spirv::serialize(module, binary, options = {}); Rust has no default arguments, so each operation is a pair, parse with parse_with_options.

Its own representation read separately from foreign formats. MLIR reads its own text and bytecode through parseSourceFile, which detects the encoding, and reaches foreign formats through the mlir-translate registry of named translations. PowerIO does the same. serialize and deserialize handle PowerIO IR, parse and emit translate grid exchange formats, and parse refuses a .pio.json by naming deserialize. A future binary IR encoding therefore goes behind deserialize, detected from its own leading bytes, rather than behind a new operation. The naming lines up as well. MLIR spells its own binary encoding spirv::serialize and spirv::deserialize, and LLVM reserves emit for producing a target file from IR (TargetMachine::addPassesToEmitFile).

One value set, so which value a format produces is data. MLIR has one IR and reads foreign formats through registered translations whose result is that IR, rather than a reading operation per category of input. PowerIO’s PioValue is that one set, so a geographic layer is a value in it, powerio.GeoLayer, and the canonical .geo.json, GeoJSON, aliased CSV or JSON records, headerless buscoords CSV, and a PowerWorld .pwd display all reach it through parse. There is no second reading path beside parse, so a document that is not a grid case still parses, serializes, and emits like every other value.

Structured diagnostics with stable severities and attached context. The four severities (error, warning, remark, note) are MLIR’s, with the same meanings: a remark reports on success, a note attaches context to another finding. PowerIO adds a stable dotted code, which is what you branch on, plus targets, related records, and suggested actions.

Typed representations at more than one abstraction level. The value families span reusable networks, calculation instances, and solutions the way a compiler holds IR at several levels; nothing forces the richer levels through the poorer ones.

Explicit transformations with testable boundaries. Each transformation names its input and output types, returns diagnostics, and refuses what it cannot represent; balanced lowering exposes powerio::transform::to_balanced_report so you can inspect its assumptions and refusals before you transform a value. Nothing rewrites as a side effect, and format loss diagnostics belong to the EmitResult returned by emit.

Verification at representation boundaries. Parsers and transformations verify what they produce and report findings rather than repairing silently; repairs are explicit operations that leave history records.

Shared operations instead of per format switches. The parse and emission dispatchers route once, at the facade; matrix calculations, serializers, and inspectors consume the concrete typed values, so a new format adds one parser and one serializer rather than a case in every consumer.

Analysis caches. Factorizations and prepared solver arrays are derived data behind the public results, invalidated when their inputs change, the way pass manager analyses are; IndexedNetwork, the derived index view, stays public in 0.11 because downstream consumers build matrices through it directly.

Registries checked mechanically where tables drift. Structural type names, format tokens, diagnostic codes, and drawn architecture edges are each held to one source by a CI gate, which is the maintainable slice of MLIR’s declarative dialect definitions.

Serialization specified apart from memory. Each PowerIO release publishes an explicit schema and validation rules for its documents, and the Rust structs do not define the public document layout. As in MLIR bytecode, the document has a version and a separate producer string, and the reader checks the version and structural type. The version names the release whose schema the document follows, and, as StableHLO ties compatibility to its own release version, a reader accepts the documents of its own release series; later releases in a series add structural types without changing existing ones. PowerIO IR reference defines every structural type field by field, the way the MLIR language reference defines its types, and a test holds the page to the generated schema. PowerIO makes no LLVM or MLIR compatibility promise by analogy.

Scrutiny proportional to permanence. A new core concept (a value family or common module record) needs a registered structural type name, an exact IR representation, and binding coverage. A new format adapter needs none of that.

Not adopted

PowerIO 0.11 has no SSA values, no generic operation tree, no region nesting, no global context, no open runtime dialect registry, no generic pass manager, and no bytecode. The existing Rust types describe power system data more directly than an operation tree would, and none of those mechanisms has a PowerIO use with measured benefit. Public names stay power system names. A bus is a bus, a lowering is named for its concrete result, and no Rust struct is renamed to an operation so it resembles MLIR. A PioContext would be justified only by measured interning or shared allocation needs, and none has appeared.

Two MLIR bytecode mechanisms are also left out while one version covers the whole document. Per dialect versions would let one value family evolve on its own schedule; PowerIO adopts them only when a family needs a representation change the others do not. Writer back deployment (setDesiredBytecodeVersion) would let a newer build write a document an older release reads for a consumer pinned to it; PowerIO adopts it only when such a consumer appears.

DC OPF bundle

powerio dcopf <case>.m -o <out> assembles a DcOpfInstance and writes <out>/<case>_dcopf/. Rust callers pass an assembled instance to powerio_matrix::emit_dcopf_bundle. The directory contains Matrix Market files and dcopf_meta.json.

The bundle writes the DC problem in the solver’s positive form, where b.mtx holds the positive susceptance magnitude of each branch and A.mtx is bus by branch. The public calculations in Matrices and graphs use the PowerModels form instead, where calc_branch_susceptances is negative for an inductive branch and calc_incidence_matrix is branch by bus. So the bundle’s b is the negated public b, and A.mtx is the transposed public A.

Definitions

  • Format. Matrix Market. Matrices are coordinate real; square symmetric ones (L, L_grounded) use the symmetric header and store the lower triangle only. Vectors are array real general, one value per line.
  • Index base. .mtx row and column indices are 1-based, as Matrix Market requires. reference_buses in the manifest are 0-based dense bus indices.
  • Sign convention. The DC bus susceptance matrix \(L\) uses the positive M-matrix form: stored nonzero off-diagonal entries are negative, diagonals are nonnegative, and \(L_{ii} = \sum_j \lvert L_{ij} \rvert\). An off-diagonal entry is \(L_{ij} = -b_e\) for the branch between \(i\) and \(j\), so a consumer recovers the branch susceptance as \(-L_{ij} > 0\).
  • Units. The default PerUnit divides power by base_mva and rescales cost so it is a function of per unit power, \(q \leftarrow 2c_2 \cdot \mathrm{base}^2\) and \(c \leftarrow c_1 \cdot \mathrm{base}\). Native keeps MW and native cost. The manifest records which one you chose.
  • Generator costs. The default export policy for costs is require, so an in service generator without cost data is an error. Pass --missing-gen-cost to fill the missing rows for a feasibility test.
  • Reference buses. reference_buses in the manifest lists every grounded bus as a 0-based dense index. Each in service island needs at least one reference. If several references lie in one island, the bundle fixes all of those voltage angles to zero; it is not a participation factor slack model.
  • Branch susceptance formula. b.mtx holds \(b_e\), positive for an inductive branch, the coefficient on \(\theta_f - \theta_t\). The complete flow is \(f_e = b_e(\theta_f - \theta_t) - b_e\delta_e\), where \(\delta_e\) is the phase shift in shift.mtx. The default, SeriesSusceptance, uses \(b_e = x/(r^2 + x^2)\) plus the phase shift terms, with no tap scaling. TapAdjustedReactance uses \(b_e = 1/(x \tau)\) plus p_shift. ReactanceOnly (\(b_e = 1/x\), taps and shifts ignored) is kept because it is the textbook DC linearization, and reproducing a published result needs it exactly as written. The manifest records the formula.

Matrices

fileshapewhat
A.mtx\(n \times m\)signed incidence matrix; column \(e\) has \(+1\) at from-bus, \(-1\) at to-bus
L.mtx\(n \times n\)DC bus susceptance matrix \(L = A \operatorname{diag}(b) A^\mathsf{T}\); with positive branch weights, its rank is \(n-c\) for \(c\) connected components
L_grounded.mtx\((n-k) \times (n-k)\)\(L\) with \(k\) reference rows and columns removed; SPD when every island is grounded
BAt.mtx\(m \times n\)branch flow matrix \(B A^\mathsf{T}\) over the bundle’s positive susceptance magnitudes; complete flow adds flow_offset. In PowerModels signs the same flow is \(p_\text{branch} = -B_f,v_a + b \odot \text{shift}\) with negated susceptances
Cg.mtx\(n \times n_{\mathrm{gen}}\)generator-to-bus incidence, one \(1\) per column

Vectors

The bus indexed vectors, of length \(n\), are pd (load), gs (shunt conductance, the constant real power a shunt draws at one per unit voltage; a nodal balance subtracts it beside pd), q, c, and c0 (the diagonal, linear, and constant cost terms), pmax and pmin (generation bounds), e_r (reference indicator: \(1\) at every reference bus, else \(0\)), p_shift (phase shift injection; zero only under ReactanceOnly, which ignores shifts, or when the case has no phase shifter), p_hvdc (the fixed injection of in service HVDC lines: -pf at each line’s from bus and +pt at its to bus; all zero under --hvdc ignore), and fixed_withdrawal, equal to pd + gs + p_shift - p_hvdc.

The branch indexed vectors, of length \(m\), are b (susceptances), shift (radians), flow_offset (equal to -b * shift elementwise), fmax (per unit thermal limits: \(0\) is a zero flow bound and inf is no bound, see the 0.12 note below), and the radian limits angle_min and angle_max on \(\theta_{\mathrm{from}} - \theta_{\mathrm{to}}\), the MATPOWER and PowerModels convention, which is not net of the branch’s phase shift. By default they carry PowerModels’ ±60 degree pad (AngleDifferenceBounds::PowerModelsPad, exactly its correct_voltage_angle_differences!): a side the case leaves unconstrained, as PSS/E and other formats with no angle limits always do, or unusable (at or beyond ±90 degrees, or the MATPOWER 0/0 spelling) becomes ±60 degrees. A branch that shifts phase by more than 60 degrees cannot meet that window, so with_angle_difference_bounds on the assembly options, and powerio dcopf --angle-difference-bounds, select another rule: ShiftCenteredPad (shift-centered-pad) centers the same pad on each branch’s phase shift, Stated (stated) keeps the bounds the case states and reads an absent side as negative or positive infinity, and None (none) removes both bounds for every branch. The MATPOWER 0/0 pair denotes no bounds; a lower side at or below −360 degrees and an upper side at or above 360 degrees denote absent sides. Other stated sides remain unchanged, so a single zero side, as in 0/30, stays a bound at zero; MATPOWER’s makeAang reads each zero side as absent instead. Unwrapped DC angle differences can exceed a full turn, so ±360 degrees is not a substitute for no constraint. Bundle vectors spell infinities -inf and inf; consumers must omit the corresponding inequality side. Preparation JSON uses the strings "-Infinity" and "Infinity", retaining numeric values for finite limits. The default padded policy and the C ABI remain unchanged.

The generator space vectors, of length \(n_{\mathrm{gen}}\), are q_gen, c_gen, c0_gen, pmax_gen, and pmin_gen.

The bundle schema only represents polynomial generator costs. If a generator has a piecewise linear cost, preparation returns a typed error instead of writing zero polynomial coefficients; the in memory generator space preparation keeps those breakpoints exactly.

The constant cost terms c0 and c0_gen do not move the argmin. They are there so that a consumer reporting objective values can reconstruct the full cost.

Generator space is canonical. The nodal q, c, c0, pmax, and pmin files aggregate the generators at each bus: the bounds are the sums of the generator bounds, and the cost curves combine by the parallel rule \(q = 1 / \sum_i 1/q_i\), which is the curve of the split that costs least. That aggregate agrees with generator space only while the cheapest split stays inside the bound of each generator. A bus with one generator keeps that generator’s curve.

Manifest (dcopf_meta.json)

Starting in 0.12, fmax.mtx uses zero for a zero flow bound and positive infinity for no bound, including inactive constraints. Zero never changes branch status. Earlier bundles used zero for no bound; check powerio_version when reading those files.

The manifest has schema powerio.dcopf and is stamped with the writing release in powerio_version. It describes the Matrix Market files with structured metadata:

  • dimensions: n_buses, n_source_branches, n_branch_columns, n_generators, n_reference_buses, and n_grounded_buses.
  • index_base: dense = 0 for manifest bus, branch, generator, and reference indices; matrix_market = 1 for .mtx coordinates.
  • branch_susceptance_formula, units, build_options, and zero_impedance. build_options records skip_zero_impedance, synthesize_unrated_limits, angle_difference_bounds (power_models_pad, shift_centered_pad, stated, or none), and hvdc_treatment (fixed_injection or ignore). The zero impedance block records the skip flag, denominator rule, skipped count, and skipped source branch rows.
  • grounding: reference buses, removed rows and columns, the grounded operator (L_grounded), and the reference selector (e_r).
  • operators[]: one entry per emitted operator with name, file, kind, rows, cols, index_space, and units.

cost_policy, synthesized_gen_costs, patched_gen_costs, files[], and powerio_version are top level fields.

Solving with it

The complete affine equations are \[ f = B A^\mathsf{T}\theta + \texttt{flow_offset} \] and \[ L\theta = C_g p_g - \texttt{fixed_withdrawal}. \] Factor the grounded system, since L_grounded is SPD when every island has a reference. Drop all reference_buses entries from the right hand side, solve the reduced system, and set each reference angle to \(0\). e_r identifies the grounded buses without parsing the manifest. You can use the full singular \(L\) instead when the right hand side sums to zero within each connected component.

An interior point DC OPF solver builds reweighted bus Laplacians at each Newton step from the same A and b (only the edge weights change), so A is the durable operator to hand over.

Corpus harness

powerio corpus runs the conversion matrix’s properties against a private case corpus without letting a byte of it into the repository. The vendored fixtures cover the readers and writers on a handful of public cases, and real corpora hold the tail: dialect quirks, fields no fixture uses, and records at scales no fixture reaches. Much of that data is confidential, so it cannot become a fixture, appear in a warning quoted in a commit, or fingerprint itself through a numeric constant in a test.

powerio corpus ingest <corpus-dir> --work <scratch-dir> [--max-bytes N]
powerio corpus compare --work <scratch-dir>
powerio corpus walk --work <scratch-dir> [--walks N] [--hops N] [--seed N] [--settle N]
powerio corpus report --work <scratch-dir> -o findings.jsonl --summary summary.md

The corpus directory is only ever read. The work directory holds raw values and is disposable, so keep it on the machine that owns the corpus. findings.jsonl is the boundary: before report writes a byte, it audits its own output against every string the corpus taught it. The tool and the conversion matrix test in powerio-cli/tests/conversion_matrix_report.rs run the same code, the invariants module of powerio-cli, so the CI gate and the harness cannot drift apart.

Ingest and bucketing

Every readable file is parsed into the typed model and given an electrical fingerprint: element counts, base MVA, the sorted degree sequence of the bus graph, and quantized multisets of impedances and injections. Siblings of one case in different formats share a fingerprint even when all their names differ, so they land in one bucket, and every other file gets a bucket of its own. Bucket identifiers are ordinals assigned in fingerprint order, so nothing about a bucket identifier, path, or report row comes from a source file name. An unparseable file is a finding rather than an error, and a parser panic is reported by code location plus a tool minimized token level mutation distance, not by file content.

Compare

compare runs every leg from the pristine case: the four matrix properties in both directions for every sibling pair, and as a PowerIO round trip for every sibling on its own. The properties are warning accounting on read and write, core survival, Y_bus entry for entry and per bus injections, and the canonicalized typed model diff. Each typed model diff path is paired against the warnings that leg emitted, and a diff with no covering warning becomes an undeclared loss finding.

Walk

walk converts each bucket’s case through random cycles of formats and grades the chain properties: the route must not change the destination (converting A to B to C must land where A to C does), conversion must settle (a second pass through a format changes nothing), and an emptied table must stay empty (rows reappearing means a writer made up data no reader gave it). compare already grades each hop’s own loss, so walk findings carry only the chain properties, each with the format path and the seed that replays it.

The run learns as it goes. A ledger in the work directory keeps, per directed format pair, every distinct signature that edge has produced, and the next path is drawn toward the pairs that have taught the least. The run ends when --settle consecutive walks teach the ledger nothing. The ledger persists across runs; delete it to start over.

The anonymization boundary

The tool enforces the boundary itself rather than relying on the care of whoever reads the report:

  • Identifiers: every name in a case is replaced with its element class ordinal (bus#12, gen#3) in every emitted string, warning texts included.
  • Values: findings give relative deltas, ratios, and quantized magnitudes. A field’s exact value appears only when it is a format constant such as a mode flag or a column count, and not when it is grid data.
  • Text: no line of a source file is echoed, and comments in decks are not echoed either.
  • Findings are property shaped: format, record type, field path, expected behavior, observed behavior, and structural preconditions. That is enough to reproduce the problem without any of the case.

From a finding to a fix

  1. Triage by severity: crash, silent value change, silent drop, undeclared loss, miscounted warning, declared loss confirmed.
  2. Restate the finding as a falsifiable sentence about the format, using the findings file alone.
  3. Build a minimal synthetic reproducer from an existing vendored fixture, from powerio gen, or by hand as a case of two to four buses with canonical values. The test must fail before the fix and pass after. A finding you cannot reproduce synthetically is not actionable; it goes into the report as open and does not go into a commit.
  4. Fix under the existing decision order: carry the data, stop retaining restatements, warn only on losses. Then run the full gate, including the conversion matrix. If a cell changes on purpose, regenerate powerio-cli/tests/conversion_matrix.baseline with POWERIO_MATRIX_BLESS=1 and check each changed line.
  5. Commit one property per commit, and describe the property rather than the run that found it. Rerun the tool to confirm the finding class closed and no other bucket regressed.

A fixture added this way comes with its generation script or handwritten provenance, recorded in the fixture README. Corpus paths do not belong in a diff.

Performance

PowerIO has five benchmark tiers, listed below. They answer different questions, so keep their numbers separate when you publish them.

tiercommandwhat it answers
Rust microbenchmarkscargo bench -p powerio-tx --bench parse and --bench large_caseparser, writer, and PowerWorld reader timing inside one process, and the PSS/E reader and indexed view on a continental-size case
Matrix microbenchmarkscargo bench -p powerio-matrix --bench matrixsparse matrix, DC OPF component, and dense sensitivity builder timing after parse/indexing
Cross tool parser and matrix comparisonjulia --project=evals/validation evals/performance/bench_julia.jl --jsonpowerio through the C ABI against ExaPowerIO.jl and PowerModels.jl, including parse plus Y bus construction
Python parser comparison.venv/bin/python evals/performance/bench_parse.py --json <cases>Python package parse and matrix path against pandapower reader paths
C ABI release sizetwo cargo build -p powerio-capi --release builds plus statbinary size without and with the gridfm feature, the only feature that changes the binary

large_case generates a PSS/E revision 35 case of about 100,000 buses in memory, with 29,000 transformers and 13,000 generators, and times the reader and IndexedNetwork::new on it. Point POWERIO_PGLIB_CASE78484 at PGLib’s pglib_opf_case78484_epigrids.m to time the same two steps on that case, and POWERIO_LARGE_CASE_WRITE at a path to keep the generated text for profiling.

The published tables come from evals/performance/render_tables.py, which renders the JSON the harnesses write, and this page is the reference for how those numbers are made. Each refresh also records the snapshot environment: machine model, chip, core count, memory, OS, Rust, C compiler, Julia, Python, and the package versions of the comparison harnesses. Regenerate the JSON inputs first, then render:

bash evals/validation/fetch_cases.sh
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 evals/performance/bench_julia.jl --json
.venv/bin/python evals/performance/bench_parse.py --json \
  tests/data/case2869pegase.m \
  tests/data/large/case9241pegase.m \
  tests/data/large/case13659pegase.m \
  tests/data/large/case193k.m
# tests/data/large/ is not in the repository; evals/validation/fetch_cases.sh fills it.
python3 evals/performance/render_tables.py
python3 evals/performance/render_tables.py --check

The Julia benchmark writes rows for parse only and matrix_rows for parse plus Y bus construction. Each tool is timed on its own path: PowerIO on C ABI parsing and typed network access, PowerModels on parse_file, make_per_unit!, and calc_admittance_matrix, and ExaPowerIO on parse_matpower plus a sparse Y bus assembled from its parsed branch admittance rows.

The Rust Criterion benchmarks measure PowerWorld .pwb and .aux parse timings. Fetch the public fixtures, run cargo bench -p powerio-tx --bench parse -- "parse_aux_|parse_pwb_", then run python3 evals/performance/extract_powerworld_bench.py before you render the tables. If you are publishing the Texas7k local row, pass its aux and pwb paths through POWERIO_BENCH_AUX and POWERIO_BENCH_PWB during the Criterion run.

Matrix builder timings do not include parsing. The matrix benchmark parses each fixture once, builds IndexedNetwork once, and times only the derived matrix construction. Its pipeline row measures Pipeline::run for the paired \(Y_{\mathrm{bus}}\) export, including MTX, shunt, and metadata writes:

cargo bench -p powerio-matrix --bench matrix
python3 evals/performance/extract_matrix_bench.py
python3 evals/performance/render_tables.py

While you work on one builder, filter the run down to the benchmarks you care about, for example:

cargo bench -p powerio-matrix --bench matrix -- 'matrix_bprime|matrix_ybus|dcopf_'

Criterion compares each run against whatever baseline is in your local target/criterion, so treat a Performance has regressed line as a reason to investigate rather than as a publishable claim by itself. A number that goes into a release note or benchmark page needs the commit, tree cleanliness, machine, toolchain, command, fixtures, and whether the optional large cases were present.

Before you publish a C ABI change, measure the release binary size. The C ABI exports one symbol set and only the gridfm feature changes the binary, so two builds cover the range (the library is libpowerio_capi.so on Linux, libpowerio_capi.dylib on macOS, and powerio_capi.dll on Windows):

cargo build -p powerio-capi --release --no-default-features
cp target/release/libpowerio_capi.so /tmp/libpowerio_capi-core.so
cargo build -p powerio-capi --release --no-default-features --features gridfm
cp target/release/libpowerio_capi.so /tmp/libpowerio_capi-gridfm.so
stat -c '%s %n' /tmp/libpowerio_capi-core.so /tmp/libpowerio_capi-gridfm.so

Testing and release checks

If your change alters numerical semantics, it needs tests and a short note in code or docs saying why. If it is a performance change, it needs before and after measurements.

Baseline checks

scripts/ci-mirror.sh runs the Linux side of the Rust, Docs, and Python workflows in the feature combinations CI uses: format, clippy, the terminology and symbol gates, header parity and regeneration, every crate’s tests in each gated feature set, the C smoke and header programs, schema generation, packaging checks, the book, and the Python lint, stub, and test lanes. Run it before you mark a larger implementation change ready for review, rather than assembling your own subset, because a hand assembled subset misses feature configurations. cargo test --workspace, for example, tests one configuration: Cargo unifies features across the workspace, so powerio-cli turns gridfm on in the facade and matrix crates for the whole build, a build without it is never checked, and nothing turns on the facade’s matrix feature or the C ABI’s gridfm feature. It builds powerio-capi with default features only, so the C ABI release-feature diagnostic tests are skipped, and it does not test each crate’s opt-in features in isolation. CI runs separate commands to exercise each configuration it supports, minimal builds included. The deprecated C ABI arrow compatibility flag adds no code or tests. Legacy commands remain accepted in 0.11.x, but maintained source-build commands omit it; #673 tracks its eventual breaking removal.

The script needs cbindgen for the header regeneration, and skips the wasm check, the semver check, and the book when wasm32-unknown-unknown, cargo-semver-checks, or mdbook is missing. It leaves to CI the MSRV build, cargo deny, Miri, the sanitizer and Go client builds, the macOS, Windows, and FreeBSD jobs, and the Julia binding, validation, PowSybl, and fuzz workflows. A PowerIO.jl checkout at ../PowerIO.jl, or wherever POWERIO_JL points, adds the check that every C entry point is bound or exempted there; the script runs without one. To run the Julia tests themselves, see the Julia binding row below.

The Python binding tests need a wheel built into a virtual environment. Build it from the repository root, where pyproject.toml lives:

python3 -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin build --release -o dist
pip install dist/*.whl
python -m pytest python/tests

Install the built wheel rather than an editable one. When pytest runs from the repository root, the powerio/ crate directory there shadows a maturin develop install.

Route changes

Pick the smallest set of gates that covers what you changed, then run the release gates before you claim a release.

changed surfaceextra gates
parser or writer semanticsbash evals/validation/run_validation.sh; format round trip tests; affected cargo +nightly fuzz run <target> -- -runs=1 harnesses
MG-RAVENS or PMD MATHEMATICALthe RAVENS schema workflow; cargo test -p powerio-dist --test pmd_math --test ravens --test ravens_physics --test format_input_robustness; the PowSybl RAVENS routes in evals/powsybl/run.sh
rich model fieldsbash evals/validation/run_rich_validation.sh
matrix calculationscargo test -p powerio-matrix; cargo bench -p powerio-matrix --bench matrix
problem instances or DC OPF bundlescargo test -p powerio-prob --no-default-features; cargo test -p powerio --features matrix
SINCAL readers, writers, or the sincal featurecargo test -p powerio -p powerio-tx -p powerio-dist -p powerio-tnd --no-default-features; bash scripts/ci-clippy.sh no-sincal; cargo check -p powerio --no-default-features --features matrix --target wasm32-unknown-unknown
PowerWorld binary readerPowerWorld parser tests plus `cargo bench -p powerio-tx –bench parse – “parse_aux_
C ABIscripts/capi-header-parity.sh; python3 scripts/check-capi-header.py; scripts/capi-smoke.sh; cargo test -p powerio-capi --no-default-features; cargo test -p powerio-capi --features matrix,gridfm,dist,prob; bash scripts/ci-clippy.sh capi-no-default; bash scripts/ci-clippy.sh capi-release
Python package metadata or extrasmaturin build --release --out /tmp/powerio-wheel-check; inspect wheel METADATA
Julia binding compatibilitybuild powerio-capi --features matrix,gridfm,dist,prob, then run PowerIO.jl tests with POWERIO_CAPI
shared surface with PowerIO.jlpush a same-named PowerIO.jl companion branch; the tandem CI job tests against it
public Rust APIbash scripts/check-semver.sh (needs cargo install cargo-semver-checks --locked)
CLI behaviorcargo test -p powerio-cli --test cli
documentation or websitemdbook build docs; mdbook test docs; RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps; regenerate schemas and the C header when their source rustdoc changes; run scripts/capi-header-parity.sh; check links to retired guide outputs

evals/validation/run_validation.sh needs the Python oracle stack in the same Python 3.11+ venv as the local wheel, and treats a missing PyPSA, pandapower, or egret as a setup failure. evals/validation/run_rich_validation.sh treats the committed PowerModels rich oracle as strict, so missing Julia is a setup failure there too.

Release gates

Before you publish a release claim, run the full set below on top of the baseline checks:

cargo test -p powerio-capi --no-default-features
cargo test -p powerio-capi --features matrix,gridfm,dist,prob
bash scripts/ci-clippy.sh capi-no-default
bash scripts/ci-clippy.sh capi-release
cargo build -p powerio-capi --release --features matrix,gridfm,dist,prob
scripts/capi-header-parity.sh
python3 scripts/check-capi-header.py
scripts/capi-smoke.sh
POWERIO_CAPI=$PWD/target/release/libpowerio_capi.so \
  julia --project=../PowerIO.jl -e 'using Pkg; Pkg.test()'   # .dylib on macOS
cargo bench -p powerio-matrix --bench matrix -- 'matrix_bprime|matrix_ybus|dcopf_'
(cd evals/performance/asv && ../../../.venv/bin/asv check -E existing:../../../.venv/bin/python)
(cd evals/performance/asv && ../../../.venv/bin/asv run --quick --show-stderr -E existing:../../../.venv/bin/python --dry-run)
for target in $(cd fuzz && ls fuzz_targets | sed 's/\.rs$//'); do
  cargo +nightly fuzz run "$target" -- -runs=1
done
bash evals/validation/run_validation.sh
bash evals/validation/run_rich_validation.sh

run_validation.sh checks the classic transmission paths against PowerModels.jl, ExaPowerIO.jl, egret, pandapower, and PyPSA, the distribution fixtures against OpenDSS and the BMOPF schema, and runs the reader to writer conversion matrix; run_rich_validation.sh covers fields outside the MATPOWER row shape (branch terminal admittance, switches, current ratings, solution values, HVDC costs, load voltage models). GOC3 has its own goc3-reference CI job, which pins the GO-3 data model, C3DataUtilities, and the D1, D2, and D3 files from GOC3Benchmark.jl. That job validates PowerIO’s problem and solution documents with the GO-3 data model, parses all three benchmark problems as AcScucInstance, runs the Challenge 3 data checks on them, and runs the same checks on a PowerIO AcScucSolution output document. Surge has no external validator in this harness, so its current evidence is its Rust parser, writer, routing, stored module, and round trip tests. The format chapter says what the independent checks prove for each format.

The gates do not prove that every field of every source format survives. Known losses are part of the public behavior and show up as warnings.

Benchmark updates

Regenerate the benchmark JSON before you change a published table:

julia --project=evals/validation evals/performance/bench_julia.jl --json
.venv/bin/python evals/performance/bench_parse.py --json <cases>
cargo bench -p powerio-tx --bench parse -- "parse_aux_|parse_pwb_"
python3 evals/performance/extract_powerworld_bench.py
cargo bench -p powerio-matrix --bench matrix
python3 evals/performance/extract_matrix_bench.py
python3 evals/performance/render_tables.py
python3 evals/performance/render_tables.py --check

The ASV suite tracks Python wheel parse and matrix timing across git history. To smoke test it on an uncommitted worktree, point it at the local venv:

cd evals/performance/asv
../../../.venv/bin/asv check -E existing:../../../.venv/bin/python
../../../.venv/bin/asv run --quick --show-stderr -E existing:../../../.venv/bin/python --dry-run

Do not edit generated benchmark tables by hand. When you publish new numbers, update the snapshot environment described on the performance page as well: commit, tree cleanliness, machine, OS, toolchain, Python stack, Julia stack, commands, fixtures, and optional local data.

Broad local corpora stay local. Pass them in through the documented environment variables or --root flags, review the reports the run writes under evals/validation/results/, and do not commit corpus paths or generated outputs.

Multiconductor IVR preparation

powerio_matrix::build_mc_ac_opf_preparation converts an McAcOpfInstance into solver-independent rectangular voltage/current coefficients. It occupies exactly the same boundary as balanced AC and DC OPF preparation: powerio-dist owns the electrical network, powerio-prob owns the instance and selections, and powerio-matrix derives indexed numerical data. The powerio::matrix facade exposes the same API. No optimizer, AD library, or expression type crosses this boundary.

Choose explicit voltage and per-coil power bases with McAcOpfAssemblyOptions::new, then pass the instance and bases to build_mc_ac_opf_preparation. The API example shows the call and is compiled by the crate’s documentation tests.

DELTA loads, generators, capacitors and transformer windings, and THREE_LEG inverters, must connect only phase terminals. Preparation rejects neutral and earth endpoints with BUILD.MULTI.OPF_INVALID, using explicit terminal conventions when supplied. A two-terminal DELTA is one phase-to-phase coil; three-terminal DELTA coils follow the declared cyclic order. Grounding a phase does not by itself change its terminal role. WYE and SINGLE_PHASE return connections retain their existing semantics.

Fixed inverter PF uses McOpfCoil::power_factor_coefficients: bounded [a,b] for a*P + b*Q = 0, with a = sqrt((1 - |pf|) * (1 + |pf|)) and b = -pf. The sign follows OpenDSS PVSystem and Storage and BMOPF: pf > 0 gives Q/P = +tan(acos |pf|), Q with the same sign as P, and pf < 0 the opposite sign. PowerIO 0.11 used b = pf, the reverse. The signed input domain remains 0 < |pf| <= 1; even subnormal inputs keep a finite row. Solvers should use these coefficients, not the legacy reactive_slope ratio. That ratio is computed without trigonometric cancellation when representable and is None if division would overflow; None therefore does not imply absence of PF control when bounded coefficients are present. Hard P/Q/S/I limits still intersect the control equation. Absolute residual tolerance on this bounded row does not certify relative PF accuracy, especially near zero PF or zero apparent-power dispatch.

Units and axes

Canonical inputs are SI. Explicit bases are voltage in V and power in VA per coil. Current base is S_base / V_base; impedance base is V_base² / S_base. The output stores per-unit voltages, currents, powers, impedance, and admittance. Cost coefficients are currency/hour per per-unit active injection, including the instance objective weight. Angle bounds and offsets are radians. Complex values are [real, imaginary]; magnitude bounds are not squared.

The terminal axis follows canonical bus storage order and each bus’s terminal order. Every terminal carries its original bus/name identity. Branch matrices are local square conductor matrices; from and to map those axes into the global terminal axis. Device coils follow their connection incidence, while terminals retains the source map including a neutral. source_row indexes the canonical table identified by the device kind. Transformer current indices are local to coils; equation voltage indices are global. Ports reconstruct rated physical currents and voltages and need not coincide with internal coil axes.

Star-device current ratings follow terminal_map, including a neutral at any position. Preparation maps each rating to its physical terminal before forming phase coils. A two-wire coil uses the tighter outgoing/return rating; delta ratings remain coil ordered. Missing or infinite caps remain unbounded, and zero remains an exact zero-current bound.

Load power is positive consumption; generator, IBR and source power is positive injection. All limits distinguish absent from exact zero. Deselecting a bound does not remove a physical device law or infer an unprovided bound. Voltage selections use bus names, conductor selections use line:name, switch:name, and transformer:name, and capability selections use generator names and ibr:name.

Supported exact profile

Preparation retains mutual line impedance and both end shunts, explicit neutral conductors, shunts, capacitor matrices, and ideal switches/sources. Currents remain explicit at exact-zero or singular impedance. There is no neutral reduction, impedance inversion, epsilon impedance, or ideal-switch contraction.

Voltage-bounded ZIP, exponential and constant-power laws, including those read from ordinary OpenDSS loads, remain intact in the network and PF/OPF instance. The current IVR preparation profile refuses them explicitly because its power-law terms cannot represent their piecewise transitions, dropout or current limits. It does not silently approximate them by their nominal laws.

A caller that accepts that approximation opts in explicitly: McAcOpfAssemblyOptions::with_bounded_load_laws(BoundedLoadLawPolicy::ProjectToNominal) replaces each bounded law by its nominal (middle-band) law. The low-voltage transitions, high-voltage continuation and dropout are then not modeled. The preparation lists one McOpfLoadLawProjection per load in load_law_projections, and McAcOpfPreparation::diagnostics() returns one BUILD.MULTI.LOAD_LAW_PROJECTED warning for each. The default, BoundedLoadLawPolicy::Refuse, is unchanged. Ordinary OpenDSS feeders, whose default model=1 loads read as bounded laws, need this opt-in to reach OPF preparation. LinDist3Flow has the same choice through its unsupported policy: reject and lower refuse these loads, while approximate and permissive project them and record a load_approximated preparation action.

Supported devices include WYE/DELTA/two-terminal P/I/Z/ZIP/exponential loads, generator capability and linear dispatch cost, single-phase/center-tapped/Yd/Dy and fixed n-winding transformers, type-A/B regulators, and supported open-delta banks. A regulator’s tap_ratio is the regulated over source voltage ratio, V_to/V_from, for both ANSI types, as BMOPF defines it; regulator_type records the A/B hardware and does not change the ratio. PowerIO 0.11 read a type-A ratio as V_from/V_to. Winding descriptors preserve neutral/core paths and physical current/VA port limits. Ordinary two-sided transformer and regulator taps can be continuous; arbitrary n-winding optimized taps are outside this profile.

Supported IBR profiles include single-phase, three-leg and four-leg topology, PQ/current/apparent-power bounds, signed fixed PF, supported PG/PN/PP volt-var and volt-watt curves (per-phase or averaged), and isolated DC-link active balance. Prepared control knots and load power-law terms describe the laws without choosing a derivative implementation. Scalar canonical capacitor nameplates follow DistCapacitor; BMOPF per-coil capacitor arrays arrive as exact terminal shunts, shared with other preparation and matrix consumers.

Fixed-PF and volt-var laws intersect the selected reactive-power capability box. Preparation retains both even when their intersection is infeasible; it does not silently relax the capability or clamp the control law. Deselecting generator capability removes the box while preserving the physical control law.

Formulation restrictions and downstream responsibility

This builder rejects initial points, terminal-referenced voltage sources, floating source neutrals, unreferenced islands, ideal conductor cycles/paths between fixed references, and angle windows outside the strict (-pi/2, pi/2) domain. Those are preparation-profile restrictions, not canonical network invalidity or proofs of infeasibility.

Earth-referenced source phasors prescribe absolute terminal voltages. A source with an explicit reference terminal prescribes a voltage difference; this IVR profile rejects it through the shared source-reference readiness check rather than interpreting it as an absolute voltage.

Explicit DC networks, uninterpreted electrical extras, conflicting or unsupported IBR policies, and unimplemented tap profiles also fail explicitly. The builder checks finite dimensions, units, source identities, and selections before returning data. Public records are derived arrays, not a new portable IR value or a stable serialized solver model; reconstruct them from the canonical instance.

Transformer rows are equations[k] + t * tap_equations[k] = 0, with nominal multiplier t = 1. The physical tap is tap_nominal * t, or tap_nominal / t for a regulator (tap_inverse). Fixed taps have no multiplier rows. Initial voltage seeds are suggestions; a free common mode in a seed is not a physical reference imposed on the optimization problem. With transformers present, the seeds come from a sparse solve of the no-load voltage equations (source voltages, closed conductors, and the transformer voltage rows at nominal tap). Each free common mode, such as a floating delta secondary, is seeded at zero. Memory follows the number of stored coefficients, a few per terminal on radial and meshed feeders, rather than the square of the terminal count.

The downstream solver owns expression construction, objective/constraint scaling, sparse Jacobians/Hessians, optimization, status acceptance, and independent physical residual validation. Polynomial rows admit exact affine/quadratic coefficients; nonpolynomial control/load laws may use the solver’s existing AD. PowerIO does not prescribe or depend on that choice, return an optimum, or expose prices or solution sensitivities.

Verification

Preparation tests check hand-computed SI/per-unit values, explicit incidence, zero/absent bounds, disabled selections, malformed metadata, canonical edits, source coverage and unsupported profile boundaries. Converter tests independently check capacitor susceptance, custom open-delta maps and winding limits. Y-bus, LinDist3Flow and IVR consumers have separate capacitor witnesses.

The companion Tellegen suite checks equation residuals, analytical/AD/finite- difference derivatives, feasibility, dispatch changes under reversed costs, and 64 frozen solves against pinned BMOPFTools IVR. These are downstream evidence; ordinary PowerIO tests require neither Julia nor an optimizer. Matching an objective alone does not establish correct physics or a global optimum.