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:
| Source | Value |
|---|---|
| MATPOWER, PSS/E, XIIDM, CGMES, UCTE-DEF, and the other balanced formats | BalancedNetwork |
| OpenDSS, PowerModelsDistribution JSON, BMOPF JSON, distribution CIM | MulticonductorNetwork |
| a PyPSA directory whose inputs vary by snapshot | TimeSeries<BalancedNetwork> |
| a GridFM Parquet dataset | ScenarioSet<BalancedNetwork> |
| a DOE GO Challenge 3 problem file | AcScucInstance |
| that problem file beside its solution file | AcScucSolution |
| a DeepMind OPFData file | AcOpfSolution |
a geographic layer document or a PowerWorld .pwd display | GeoLayer |
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
- What each source parses to and what a module contains: Core concepts.
- Balanced transmission cases: Transmission networks.
- Conductor level distribution cases: Distribution networks.
- Matrices, signs, units, and index mappings: Matrices and graphs.
- What each reader keeps and each writer reports: Formats and fidelity.
- The same operations in each language: Rust, Python, Julia, and C.
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.
- Choose files, drop a folder, or select ZIP projects. PowerIO identifies each input format, including mixed transmission and distribution cases.
- Choose one or more output formats. Transmission defaults to MATPOWER; distribution defaults to PMD engineering JSON. Each case can override those choices.
- 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
| Type | Meaning |
|---|---|
BalancedNetwork | A self contained balanced case: equipment identities, terminals, physical parameters, ratings, limits, costs, and the source’s operating assignment. |
MulticonductorNetwork | The 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. |
*Instance | The complete input of one named calculation: fixed inputs, unknowns, bounds, objectives, horizon, contingencies, and formulation choices. |
*Solution | The result of one calculation: computed quantities, termination, residuals, multipliers, and the objective or bound. |
GeoLayer | Coordinates and routes for the elements of a case, as a document of its own. |
ContingencySet, SubsystemSet, MonitoredSet | The 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:
SelectedMembersexports only the primary or named document group. It makes no claim that a DSS primary alone is a complete editable project.Projectexports 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.
| Rule | Merges |
|---|---|
| closed switches | the two buses of every closed switch |
| exact | branches with r = 0 and x = 0 (a transformer only at nominal ratio with no shift) |
| PSS/E threshold | non-transformer branches with r = 0 and abs(x) at most the threshold, by default the THRSHZ the case states |
| impedance magnitude | non-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
pmaxin-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-RAVENS | Model |
|---|---|
ConnectivityNode, Terminal.phases | buses, with the terminals the equipment uses; a Ground at a node grounds the conductors its phase code names |
ACLineSegment with ACLineSegmentPhase | lines, 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 |
PerLengthPhaseImpedance | line codes in ohm/m and S/m |
EnergyConsumer with EnergyConsumerPhase | loads; 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) |
LinearShuntCompensator | shunt banks; Yn is a wye bank whose neutral is grounded, Y one on an ungrounded neutral |
the Switch classes with SwitchPhase | switches with their state |
PowerTransformer, TransformerTank, TransformerTankEnd, TransformerEndInfo with its tests | transformers, 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) |
EnergySource | voltage sources; a source whose phasors are not one balanced set is written as one single phase EnergySource per conductor with the same phasors |
RotatingMachine, PowerElectronicsConnection | generators 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.
| CIM | Model |
|---|---|
ConnectivityNode, Terminal | buses, with the terminals the equipment uses |
ACLineSegment with ACLineSegmentPhase | lines, conductors in sequenceNumber order; each phase’s sequenceNumber names its PhaseImpedanceData row and column |
PerLengthPhaseImpedance, PerLengthSequenceImpedance, segment r/x totals | line codes in ohm/m and S/m |
EnergyConsumer with EnergyConsumerPhase | loads, per phase power |
LinearShuntCompensator with its phases | shunts; sections multiply the per section admittance |
the Switch classes with SwitchPhase | switches with their state and rating |
PowerTransformer with PowerTransformerEnd, TransformerMeshImpedance, RatioTapChanger | transformers of any winding count, with taps |
TransformerTank with TransformerTankEnd | one transformer per tank, grouped by its PowerTransformer in the cim_power_transformer extra |
Asset linking a tank to TransformerTankInfo, with TransformerEndInfo | winding ratings, connections, and resistances |
ShortCircuitTest | short circuit reactances between winding pairs, and winding resistances when no end info states one |
NoLoadTest, TransformerCoreAdmittance | the %noloadloss and %imag extras |
EnergySource | voltage sources, with the series impedance in rs/xs extras |
WireInfo.ratedCurrent of a segment’s PowerSystemResource.AssetDatasheet | the segment’s ampacity, i_max on each conductor |
Diagram with its DiagramObjects and DiagramObjectPoints | coordinates: 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 olderCIM-schema-cimNNnamespaces; 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 thecim-disttoken “CIM distribution (CIM100 cim17v40, GridAPPS-D profile)”. - Input. One document, or the top level
.xmldocuments of a directory, read through the sameSourceacquisition as every directory format: thePOWERIO_MAX_REFERENCED_BYTESbudget 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_2021profile classes CIM-Graph generates (evals/validation/cim_dist); PowerIO output has no vocabulary errors.evals/validation/validate_cim_tanks.pycompares 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, andLoadResponseCharacteristicare reported on read (READ.CIM_DIST.CLASS_UNMAPPED,READ.CIM_DIST.FIELD_UNMAPPED). A document that connects equipment throughTopologicalNode(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-distis 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:
- Parse a
MulticonductorNetworkmodule and apply explicit neutral Kron projection when needed. Keep the projection report and reject unsupported equipment through the instance constructor’s diagnostics. - Construct
LinDist3FlowOpfInstanceand callpowerio_matrix::build_lindist3flow_standard_form(instance.value()). The result supplies CSC matricespanda, vectorsqandb, and ordered zero, nonnegative, and second-order cone blocks formin 1/2 x' P x + q' xsubject toA x + s = b,s in K. - 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. - Decode the primal vector with
lindist3flow_values_from_standard_primal, then constructLinDist3FlowOpfSolutionwith the retained instance, termination, decoded values, and objective. Store the result in a module and callpowerio::serializefor 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 profile | PF instance preparation | Ordinary target emission and reparse |
|---|---|---|
| CSIRO19 / balanced, noon snapshot | Pass | MATPOWER pass, with loss diagnostics |
| Truong12 / multiconductor | Pass | DSS, PMD JSON and BMOPF JSON pass, with loss diagnostics |
| CSIRO09 / multiconductor, noon snapshot | Refused: unsourced native islands | Refused: reference-terminal voltage sources |
| CSIRO12 / multiconductor, noon snapshot, compatibility opt-in | Pass | Refused: 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.
| Source | Parses to |
|---|---|
| PyPSA CSV directory, snapshot axis with varying inputs | TimeSeries<BalancedNetwork> |
| PyPSA CSV directory, fixed network with electrical assignments per snapshot | TimeSeries<OperatingPoint<BalancedNetwork>> |
Egret JSON with system.time_keys in the scalar profile | TimeSeries<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:
| Source | Parses to |
|---|---|
| DOE GO Challenge 3 problem file | AcScucInstance |
| that problem file beside its solution file | AcScucSolution |
| DeepMind OPFData JSON | AcOpfSolution |
| BMOPF JSON or distribution CIM | MulticonductorNetwork; 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:
| Token | Flow |
|---|---|
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
| matrix | shape | calculation | notes |
|---|---|---|---|
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_matrix | full 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_matrix | row \(e\) has \(+1\) at the from bus, \(-1\) at the to bus |
| DC branch susceptances \(b\) | \(m\) | DcOperators::calc_branch_susceptances | one 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_matrix | positive solver susceptance magnitudes times \(C^\mathsf{T}\); internal solver data |
| Per-island PTDF | one matrix per component | calc_ptdf_by_island | partitions one global PTDF solve and returns source bus/branch index mappings |
| PTDF | \(m \times n\) | calc_ptdf | routes through Auto solver selection; calc_ptdf_lodf_with_options exposes the choice |
| LODF | \(m \times m\) | calc_lodf | routes 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_columns | one 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_jacobian | polar or rectangular voltage coordinates |
| multiconductor admittance | conductor by conductor | calc_multiconductor_admittance_matrix | from a MulticonductorNetwork; Rust only in 0.11 |
| adjacency | \(n \times n\) | calc_adjacency_matrix | sparse graph adjacency |
| graph edges | one per in-service branch | IndexedNetwork::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
pgandqg, 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 unlessHvdcTreatment::Ignoreis 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), unlessLccReactivePower::Statedkeeps 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 aBUILD.STATED_STATE.LCC_MODEL_UNAVAILABLEwarning. The active powers stay the reader’spfandpt, which price the DC current differently from the bridge model (seepowerio_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
newtonpfdrives to zero. An injection equal to it closes the bus, andclosure_injections(mask)returns that injection at every bus carrying a flag inmask. - Flags. Each bus carries
StatedBusFlagsnaming 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, andlow_impedance_branch(a branch belowlow_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_klargest 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 withBUILD.SWITCH.CLOSED, as the PTDF and LODF builders refuse it. Merge the buses either joins first:BalancedNetwork::merge_busesin Rust, or--merge-buses switches(closed switches) or--merge-buses exact(and zero impedance branches) withpowerio 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)\), returningNonefor an unknown source ID. The matrix builders turn that intoError::UnknownBusat 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). MATPOWERBpclears bus shunts and line charging, sets tap magnitudes to one, and keeps phase shifts. MATPOWERBppkeeps 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::chargingis the stored per terminal admittance when present:g_fr,b_fr,g_to, andb_toare already per unit on the system base.Branch::bis the legacy MATPOWERBR_Btotal projection for formats that carry only one charging value. Matrix builders useBranch::calc_terminal_charging(), so terminal values feed \(Y_{\mathrm{bus}}\) even when the legacy total is zero or stale. -
FDPF scheme.
Schemeselects between the two MATPOWER fast decoupled forms.Xbclears resistance forBp;Bxclears resistance forBpp. The default isBx. -
Zero impedance branches.
BuildOptions::skip_zero_impedancecontrols the builders whose branch denominator can be zero. The defaultfalsereturnsError::ZeroImpedance;trueskips the branch and records the skipped source branch rows inMatrixStatsasskipped_zero_impedanceandskipped_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 recordsdropped_zero_impedanceingridfm_meta.json.BalancedNetwork::merge_busesresolves them explicitly instead, together with closed switches (see Merging buses). -
Reference coverage.
IndexedNetwork::check_reference_coverageverifies 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 (
ClosedSwitchPolicyonNormalizeSettingskeeps or refuses them instead), andmerge_busesmerges them on request (see Merging buses).IndexedNetwork::check_closed_switchesrefuses a network that skipped both withBUILD.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. ExplicitKeepremains for consumers that model switches themselves. -
Branch susceptance formulas.
BranchSusceptanceFormulaselects the branch susceptance vector \(b\) and, for formulas that include phase shifts, the phase shift injection. In the PowerModels form,DcOperators::calc_incidence_matrixreturns 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
SeriesSusceptanceuses \(b = -x/(r^2 + x^2)\), which takes the whole series impedance into account, plus the phase shift injection vectorp_shift. A tap does not scale it. It reduces to \(b = -1/x\) when the branch has no resistance.SeriesSusceptanceNoPhaseShiftuses 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.TapAdjustedSeriesSusceptancedivides that series coefficient by the effective transformer tap and includes phase shifts. It is the ignore-conductance convention; see the formula table.TapAdjustedReactancereproduces MATPOWER’smakeBdc: \(b = -1/(x\tau)\) for a transformer with tap ratio \(\tau\), plusp_shift.ReactanceOnlyis the textbook \(b = -1/x\) with resistance, taps, and shifts ignored. The resulting \(-B\) matches MATPOWERBpunderScheme::Xbwhen 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:
| Quantity | Convention | Reference | powerio |
|---|---|---|---|
| Bus type codes | \(1 = \mathrm{PQ}\), \(2 = \mathrm{PV}\), \(3 = \mathrm{ref}\), \(4 = \mathrm{isolated}\) | MATPOWER idx_bus | network::BusType |
| Impedance, susceptance | per unit on baseMVA, never rescaled | MATPOWER idx_brch (BR_B already per unit) | matpower |
| Branch terminal admittance | MATPOWER 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 projection | PowerModels matpower.jl; MATPOWER idx_brch | network::BranchCharging, Branch::calc_terminal_charging |
| Tap ratio | 0 means a line (treated as 1); nonzero is a transformer | MATPOWER idx_brch TAP | Branch::calc_effective_tap |
| Phase shift, angle | degrees in the model; PowerModels JSON carries radians | PowerModels make_per_unit! | powermodels-json |
| Angle limits | angmin/angmax default ±360 (unconstrained) | MATPOWER idx_brch ANGMIN/ANGMAX | Branch::has_angle_limits |
| pandapower/PyPSA impedance | line 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 siemens | pandapower PPC conversion, PyPSA static components | pandapower-json, pypsa-csv |
dcline Pt/Qf/Qt | sign flips vs MATPOWER | PowerModels matpower.jl | powermodels-json |
| Generator cost | \(c_2 p^2 + c_1 p\) maps to \(q = 2c_2\), \(c = c_1\); coefficients high order first | MATPOWER idx_cost, egret matpower_parser | GenCost::calc_quadratic |
source_id | ["bus", id] for bus-tied elements | PowerModels matpower.jl | powermodels-json |
| PSLF shunts | EPC pu_mw/pu_mvar are per unit on sbase; Shunt stores MW/MVAr at \(V = 1\) | paired EPC/RAW case checks | pslf |
| DOE GO Challenge 3 | an 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 BalancedNetwork | pinned GO-3 data model, C3DataUtilities, and GOC3Benchmark.jl D1/D2/D3 files | powerio::parse, powerio::emit |
| Surge angles | Surge JSON carries voltage angles, phase shifts, and angle limits in radians; BalancedNetwork stores degrees | Rust Surge round trip tests | surge-json |
| DeepMind OPFData JSON | DeepMind 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 IDs | Paper Appendix A, the PyG loader, the smallest complete official fixture, and size independent FullTop and N-1 property tests | opfdata-json |
| UCTE-DEF units and signs | ohm, 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 Hz | PowSybl Core UcteImporter and UcteNode.fix | ucte |
| IEEE CDF shunts and taps | bus 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 sign | MATPOWER cdf2mpc, PowSybl IeeeCdfBusReader and IeeeCdfBranchReader, the vendored 14 and 30 bus cases against case14.m and case30.m | ieee-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:
| Data | PowerModels JSON | egret JSON |
|---|---|---|
| area records | top-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.areas | one 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 format | top-level case_metadata | system.case_metadata |
| system frequency | top-level base_frequency | system.base_frequency |
| a source-assigned element identity | uid in the element row | uid in the element entry |
| branch rating sets beyond the three ratings | rating_sets (name, rate_mva) | rating_sets (name, rate_mva) |
fields no typed slot holds (extras) | the element row’s own keys | the element entry’s own keys |
| MATPOWER generator capability and ramp columns | standard PowerModels fields | the MATPOWER column names |
| a dcline cost | standard PowerModels fields | p_cost, as a generator states it |
| detailed connectivity (substations, voltage levels, node breaker topology) | top-level detailed_connectivity | system.detailed_connectivity |
| the coordinate reference of locations and routes | top-level geo | system.geo |
bus location; branch name, route, and transformer control; switched shunt section_count and control | the element row, under the PowerIO IR name | the element entry, under the PowerIO IR name |
generator energy_source, voltage_regulation_on, regulating_terminal, regulated_bus, active_power_control | the generator row | the generator entry |
HVDC resistance_ohm, nominal_voltage_kv, converters_mode, converter1, converter2 | the dcline row | the dc_branch entry |
storage active_power_control | the storage row | egret 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 withegret.data.model_data.ModelDataand 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 transformers_nombase. 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.
| Version | Read | What the version states differently |
|---|---|---|
| 1.0 | XIIDM | iTesla 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.1 | XIIDM | PowSybl namespace. Calculated buses under node breaker topology. Three winding transformer ratedU0, leg 1 tap changers, and phase tap changers. |
| 1.2 | XIIDM | fictitious on every identifiable, targetDeadband on tap changers, ratedS, and shunt voltage regulation. |
| 1.3 | XIIDM | Shunt linear and nonlinear models with sectionCount, aliases, and boundary line generation. |
| 1.4 | XIIDM | Alias types. |
| 1.5 | XIIDM | Active and apparent power limits. |
| 1.6 | XIIDM | Voltage levels outside substations and VSC regulating terminals. |
| 1.7 | XIIDM | minimumValidationLevel and the equipment validation namespace. |
| 1.8 | XIIDM | Batteries spell targetP and targetQ. Fictitious bus injections (reported, not retained). Self connected switches are refused. |
| 1.9 | XIIDM | Shunt p. |
| 1.10 | XIIDM | Tie lines reference two dangling lines. Load models. |
| 1.11 | XIIDM, JIIDM | pairingKey replaces ucteXnodeCode. Subnetworks. Voltage angle limits (reported, not retained). |
| 1.12 | XIIDM, JIIDM | Operational limits groups and ratio tap changer regulationMode/regulationValue. |
| 1.13 | XIIDM, JIIDM | Areas, isCondenser, and active power control 1.2. |
| 1.14 | XIIDM, JIIDM | Solved tap positions and section counts, regulating on static VAR compensators and phase tap changers. |
| 1.15 | XIIDM, JIIDM | DC nodes, grounds, lines, switches, and AC/DC converters. |
| 1.16 | XIIDM, JIIDM | shuntCompensator and boundaryLine element names and multiple selected limit groups. |
| 1.17 | XIIDM, JIIDM | Optional 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.
| Display | Original grade | Meaning |
|---|---|---|
| Preserved | lossless, exact | No reported loss or typed-model change in the tested projection. |
| Representation / defaults | restated | A different representation, generated default, relabeled identifier, or informational remark is reported. |
| Adjusted / partly checked | approximate | An adjustment is reported, or some electrical comparison remains unverified. Inspect the findings and limitations to distinguish these. |
| Data omitted | dropped | At least one piece of source data has no corresponding target field. |
| Failed checks | failed | An 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
- 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.
- 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.
- 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.
- 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. - 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. - 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.
| Format | Fields | Space |
|---|---|---|
| PowerWorld PWB | Validated bus latitude/longitude fields in supported 425/537 record layouts | geographic |
| PowerWorld aux | Latitude:1/Longitude:1 bus columns, else the bare Latitude/Longitude pair (SubNum stays in extras: it is identity rather than geometry) | geographic |
| pandapower | bus geo GeoJSON Point strings | geographic |
| PyPSA | buses.csv x/y | geographic |
| DOE GO Challenge 3 | bus longitude/latitude | geographic |
| OpenDSS | Buscoords | unknown; a diagnostic identifies values within longitude and latitude bounds |
| BMOPF JSON | the 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/latitude | declared 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.
| Meaning | Rust | Python | Julia | C |
|---|---|---|---|---|
| name a file | pass the name to parse | pass a path to parse | pass a path string to parse | pio_source_open |
| acquire memory | Source::from_memory(name, bytes) | pass a file or bytes-like object | pass IO or AbstractVector{UInt8} | pio_source_from_memory |
| parse | parse(input), parse_with_options(input, &options) | parse(source, format=..., name=...) | parse(source; format=..., name=...) | pio_parse |
| module value | module.value() | module.value | module.value | pio_module_value |
| module diagnostics | module.diagnostics() | module.diagnostics | module.diagnostics | pio_module_diagnostics |
| emit a format | emit(&module, format, destination) | emit(module, format, destination=None) | emit(module, format, destination=nothing) | pio_emit |
| serialize IR | serialize(&module, destination) | serialize(module, destination=None) | serialize(module, destination=nothing) | pio_module_serialize |
| deserialize IR | deserialize(source) | deserialize(source) | deserialize(source) | pio_module_deserialize |
| apply updates | apply_updates | apply_updates | apply_updates! | pio_apply_updates |
| resolve contingencies | ContingencySet::resolve(&net) | network.resolve_contingencies(text) | resolve_contingencies(net, set) | pio_contingency_set_resolve |
| expand contingencies | ContingencySet::expand(&net, &subsystems) | network.expand_contingencies(con, sub) | expand_contingencies(net, set, subsystems) | pio_contingency_set_expand |
| select subsystem buses | Subsystem::select_buses(&net) | network.select_subsystem_buses(sub, name) | select_subsystem_buses(net, subsystems, name) | pio_balanced_network_select_subsystem_buses |
| apply a geo layer | apply_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.
| Language | A member | A table’s length |
|---|---|---|
| Rust | accessor method: module.value(), module.diagnostics(), network.buses() | network.buses().len() |
| Python | read only property: module.value, module.diagnostics, network.buses | len(network.buses) or network.n_buses |
| Julia | property: module.value, module.diagnostics, net.buses | length(net.buses) |
| C | one function per member: pio_module_value, pio_module_diagnostics | a _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.
| Language | Operations |
|---|---|
| Rust | len, iter, checked get |
| Python | len, iteration, series[index], scenarios[id]; TimeSeries is a Sequence and ScenarioSet a Mapping |
| Julia | length, iteration, 1-based getindex |
| C | zero-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
| Function | Result |
|---|---|
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, ¬es, &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_instancebuilds one with the default options from a balanced network or AC OPF module.pio_module_to_ac_ots_instance_with_optionstakes aPioAcOtsOptions, and also reconfigures an AC OTS module. NULL options are the same aspio_module_to_ac_ots_instance.pio_ac_ots_instance_createcombines an AC OPF instance handle with options and keeps its objective exactly.
- Read an instance.
pio_value_ac_ots_instancereturns the instance view.pio_ac_ots_instance_optionsreads its stated options and branch count.pio_ac_ots_instance_branch_atreads 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_topologychecks it and writes its switching cost.pio_ac_ots_instance_fix_topologyreturns the AC OPF module over it.
- Attach and read a solution.
pio_ac_ots_solution_createattaches that AC OPF problem’s solution.pio_value_ac_ots_solutionreturns the solution view.pio_ac_ots_solution_summaryreads the open and switched counts, the switching cost, and the objective.pio_ac_ots_solution_branch_closed_atreads one final status.pio_ac_ots_solution_materializereturns the network with the final statuses and solved values, ready forpio_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
| Status | Meaning |
|---|---|
| 0 | success |
| 1 | a failure without a PowerIO error category |
| 2 | request: 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 |
| 3 | io: a path could not be read or written |
| 4 | parse: the input is malformed, or a refused include left the output incomplete |
| 5 | data: valid input that the operation cannot satisfy |
| 6 | output: 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
AcScucSolutiondoes emit the official GO Challenge 3 solution file. - PowerIO does not solve anything; instances feed external solvers.
- Transient-stability
.dyrfiles parse into a loss-preservingDynamicCaseand pair with a steady-stateBalancedNetworkthroughDynamicStudy. 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
convertin the library; you composeparsewithemit. The command line does havepowerio 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_diagnosticsreturns the JSON text of a diagnostics array, whereserializereturns anEmitResult: a diagnostics array is not a module document and has no artifacts or findings of its own.- Public
powerio-matrixsignatures returnsprs::CsMat, and some public coefficient types containnum_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:
| Boundary | Value in 0.12.x | Checked where | Moves when |
|---|---|---|---|
| PowerIO release | 0.12.z | the manifests, powerio::VERSION, powerio.versions(), pio_version | every release |
| C ABI | the release series, 0.12.x | pio_version_numbers against the header’s PIO_VERSION_* at load | a release removes or changes a C symbol, which starts a new series |
| PowerIO IR | the release whose schema a document follows, "0.12.0" | the document header, powerio::IR_VERSION | every published release; supported types read within the same series, plus 0.11’s 2 |
| Rust toolchain | 1.89 | rust-version in the workspace manifest, checked by CI | a dependency in the locked graph requires a newer compiler |
| Python | 3.11 or later | pyproject.toml | a 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.10 | 0.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, DisplayFormat | removed 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 hand | emit(&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_fileparse_textparse_strparse_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_towrite_stringwrite_fileto_format- module JSON read and write names
BalancedNetwork::to_json,from_json, andto_json_with_diagnostics- the
model-jsonJSON classification family - the
pio-jsonformat 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
versionis 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_VERSIONmacro; pio_abi_version();- the
abikey of thepio_schema_reportdocument.
Added:
PIO_VERSION_MAJOR,PIO_VERSION_MINOR, andPIO_VERSION_PATCH, the release the header was generated from;pio_version_numbers(), which returns the release of the loaded library as aPioVersionViewwithmajor,minor, andpatchfields.
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.11 | 0.12 |
|---|---|
pio_abi_version() == PIO_ABI_VERSION | pio_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 stateStarPoint. - The star lowering, and so every matrix, puts a
Winding1Terminaladmittance on winding 1’s branch as from side chargingYm * tap1², so bus 1 seesYm. - 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:
PioBalancedThreeWindingTransformerViewends with amagnetizing_connectionstring view. Julia:ThreeWindingTransformerends withmagnetizing_connection::String. Python rows carrymagnetizing_connectionwhen 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
SocwrOpfSolutionnames its branch flows as the other solutions do:branch_from_active_flow,branch_from_reactive_flow,branch_to_active_flow, andbranch_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. Itsbus_orderandbranch_orderreturn vectors, as every other solution’s do.to_balancedandto_balanced_reportare also exported at the facade root, beside the other transformations;powerio::transformkeeps 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.11 | 0.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, PwdSubstation | the GeoLayer features; Rust keeps PwdDisplay and to_geo_layer_from_pwd |
the MCP server’s display tool | the parse tool, which returns the GeoLayer as PowerIO IR |
powerio-capi’s inert arrow Cargo feature | omit 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.11 | 0.12 |
|---|---|
--to bmopf-json@<version>, emit(module, "bmopf-json@<version>") | refused; write bmopf-json |
BmopfSchemaVersion, BmopfEmitOptions::with_schema_version | removed; there is nothing to select |
BMOPF_SCHEMA_VERSION | removed; a written document’s meta.schema_version is the release the schema’s $id names |
bmopf::BMOPF_PROPOSAL_URL | the function bmopf::bmopf_proposal_url() |
bmopf_schema in pio_schema_report and powerio.versions(), a version number | the schema’s $id |
BmopfEmitOptions::sideload_coordinates | removed; geometry is in the typed bus.*.geo, line.*.geo and meta.crs slots |
bus bounds written as v_min/v_max | written as vpg_min/vpg_max |
bus neutral to ground cap written as vn_max | written as vng_max |
meta.$schema stating a PowerIO archive URL | no meta.$schema; meta.schema_version, which the schema requires, is the one identifier, and the schema’s $id is in meta.provenance |
bus vn_max | vng_max |
regulator tap_ratio, tap_ratio_min, tap_ratio_max | voltage_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 phase | one entry per conductor; a per-phase array is dropped on write |
an absent meta.crs read as EPSG:4326 | read 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, andQTreads 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_modethe 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:
| field | meaning |
|---|---|
producer | the software operation that created this module |
sources | source names, sizes, declared formats, and digests |
source_map | JSON Pointer paths in value.data mapped to source byte ranges |
diagnostics | structured findings with stable codes and severities |
history | ordered derivations that produced the current value |
extensions | namespaced 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:
floatis a JSON number or one of the strings"Infinity","-Infinity", and"NaN";nullis refused at a float position.float or nullis a float the source may leave unstated.idis a bus identifier: a nonnegative integer, the source’s own bus number.matrixis an array of equal length float arrays.tokenis one of the listed strings. - unit: the physical unit.
p.u.is per unit on the network’sbase_mvaand the busbase_kvunless 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:
requiredwhen 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 type | schema definition |
|---|---|
powerio.BalancedNetwork | BalancedNetwork |
powerio.MulticonductorNetwork | MulticonductorNetwork |
powerio.GeoLayer | GeoLayer |
powerio.ContingencySet | ContingencySet |
powerio.SubsystemSet | SubsystemSet |
powerio.MonitoredSet | MonitoredSet |
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.DcPfInstance | DcPfInstance |
powerio.AcPfInstance | AcPfInstance |
powerio.DcOpfInstance | DcOpfInstance |
powerio.AcOpfInstance | AcOpfInstance |
powerio.AcOtsInstance | AcOtsInstance |
powerio.McAcPfInstance | McAcPfInstance |
powerio.McAcOpfInstance | McAcOpfInstance |
powerio.LinDist3FlowPfInstance | LinDist3FlowPfInstance |
powerio.LinDist3FlowOpfInstance | LinDist3FlowOpfInstance |
powerio.AcScucInstance | AcScucInstance |
powerio.DcPfSolution | DcPfSolution |
powerio.AcPfSolution | AcPfSolution |
powerio.DcOpfSolution | DcOpfSolution |
powerio.AcOpfSolution | AcOpfSolution |
powerio.AcOtsSolution | AcOtsSolution |
powerio.SocwrOpfSolution | SocwrOpfSolution |
powerio.McAcPfSolution | McAcPfSolution |
powerio.McAcOpfSolution | McAcOpfSolution |
powerio.LinDist3FlowPfSolution | LinDist3FlowPfSolution |
powerio.LinDist3FlowOpfSolution | LinDist3FlowOpfSolution |
powerio.AcScucSolution | AcScucSolution |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | required | |||
base_mva | float | MVA | finite and positive | required | |
base_frequency | float | Hz | positive | 60 | |
source_format | token | one 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 | ||
buses | array of Bus | id unique | required | ||
loads | array of Load | bus names a bus | required | ||
shunts | array of Shunt | bus names a bus | required | ||
branches | array of Branch | from and to name buses | required | ||
generators | array of Generator | bus names a bus | required | ||
storage | array of Storage | bus names a bus | required | ||
hvdc | array of Hvdc | from and to name buses | required | ||
switches | array of Switch | from and to name buses | [] | ||
transformers_3w | array of Transformer3W | every winding bus names a bus | [] | ||
static_var_compensators | array of StaticVarCompensator | bus names a bus | [] | ||
areas | array of Area | number unique | [] | ||
solver | SolverParams or null | null | |||
case_metadata | CaseMetadata | every member null | |||
geo | GeoMeta or null | null | |||
detailed_connectivity | DetailedConnectivity or null | null | |||
generated_uids | array of string | subset of component uid values; identifies identities PowerIO assigned because the source stated none | [] |
Bus
Schema definition: Bus.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | id | unique within buses | required | ||
kind | token PQ, PV, REF, ISOLATED | MATPOWER type codes 1, 2, 3, 4 | required | ||
vm | float | p.u. | required | ||
va | float | degrees | required | ||
base_kv | float | kV | nonnegative; 0 when the source states none | required | |
vmax | float | p.u. | vmin <= vmax; Infinity for no bound | required | |
vmin | float | p.u. | required | ||
evhi | float or null | p.u. | emergency band, stated only when it differs from vmax | null (equals vmax) | |
evlo | float or null | p.u. | stated only when it differs from vmin | null (equals vmin) | |
area | integer | required | |||
zone | integer | required | |||
name | string or null | null | |||
uid | string or null | unique within buses | assigned at serialization | ||
location | Location or null | network coordinate space | null | ||
extras | object | required |
Load
Schema definition: Load.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
p | float | MW | positive is consumption | required | |
q | float | MVAr | positive is inductive consumption | required | |
in_service | boolean | required | |||
voltage_model | LoadVoltageModel or null | null (constant power) | |||
uid | string or null | unique within loads | assigned at serialization | ||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
g | float | MW at V = 1 p.u. | positive is consumption | required | |
b | float | MVAr at V = 1 p.u. | positive is capacitive injection | the initial value of a switched shunt | required |
in_service | boolean | required | |||
section_count | integer or null | null (unset) | |||
control | SwitchedShuntControl or null | null (fixed shunt) | |||
uid | string or null | unique within shunts | assigned at serialization | ||
extras | object | required |
Schema definition: SwitchedShuntControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
mode | token locked, continuous, discrete | PSS/E MODSW 0, 2, and 1 or 3 to 6 | required | ||
vhigh | float | p.u. | vlow <= vhigh | required | |
vlow | float | p.u. | required | ||
control_bus | id or null | names a bus | null (the shunt’s own bus) | ||
regulating_terminal | TerminalReference or null | null | |||
rmpct | float | percent | required | ||
blocks | array of ShuntBlock | required |
Schema definition: ShuntBlock.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
steps | integer | required | |||
g | float | MW at V = 1 p.u. per step | positive is consumption | required | |
b | float | MVAr at V = 1 p.u. per step | positive is capacitive injection | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
from | id | names a bus | required | ||
to | id | names a bus | required | ||
r | float | p.u. | required | ||
x | float | p.u. | r and x not both zero when a matrix is built | required | |
b | float | p.u. | positive is capacitive | total line charging; half at each end unless charging is present | required |
charging | BranchCharging or null | canonical per terminal admittance when present | null (derive from b) | ||
rate_a | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
rate_b | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
rate_c | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
rating_sets | array of BranchRatingSet | [] | |||
current_ratings | BranchCurrentRatings or null | null | |||
tap | float | ratio at the from side | 0 means 1 (a line); otherwise positive | required | |
shift | float | degrees | positive means the from side voltage leads the to side | required | |
in_service | boolean | required | |||
angmin | float | degrees | angmin <= angmax; -360 and 360 mean unconstrained | required | |
angmax | float | degrees | required | ||
control | TransformerControl or null | null (a line or a fixed ratio transformer) | |||
solution | BranchSolution or null | null | |||
name | string or null | null | |||
uid | string or null | unique within branches | assigned at serialization | ||
route | array of Location or null | network coordinate space | null | ||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
g_fr | float | p.u. | required | ||
b_fr | float | p.u. | positive is capacitive | required | |
g_to | float | p.u. | required | ||
b_to | float | p.u. | positive is capacitive | required |
Schema definition: BranchRatingSet.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | required | |||
rate_mva | float | MVA | 0 is a zero bound; +Inf is unbounded | required |
Schema definition: BranchCurrentRatings.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
c_rating_a | float | source units (amperes for PSS/E) | required | ||
c_rating_b | float | source units | required | ||
c_rating_c | float | source units | required |
Schema definition: BranchSolution.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
pf | float | MW | positive flows into the branch at the from terminal | required | |
qf | float | MVAr | positive flows into the branch at the from terminal | required | |
pt | float | MW | positive flows into the branch at the to terminal | required | |
qt | float | MVAr | positive flows into the branch at the to terminal | required |
Schema definition: TransformerControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
mode | token fixed, voltage, reactive_flow, active_flow, dc_line_quantity, asymmetric_active_flow | PSS/E COD magnitude 0 through 5 | required | ||
enabled | boolean | automatic adjustment on; the sign of PSS/E COD | required | ||
controlled_bus | id or null | names a bus | null | ||
controlled_bus_on_winding_side | boolean | false | |||
regulating_terminal | TerminalReference or null | null | |||
band_min | float | p.u. voltage, MVAr, or MW as mode selects | band_min <= band_max | required | |
band_max | float | as band_min | required | ||
tap_min | float | ratio, or degrees for phase control | tap_min <= tap_max | required | |
tap_max | float | as tap_min | required | ||
ntp | integer | number of tap positions | required | ||
mva_base | float | MVA | required | ||
winding_connection_angle | float or null | degrees | asymmetric active power flow control only | null |
Generator
Schema definition: Generator.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
pg | float | MW | positive is generation | required | |
qg | float | MVAr | positive is generation | required | |
qmax | float | MVAr | qmin <= qmax; Infinity and -Infinity mean unbounded | required | |
qmin | float | MVAr | required | ||
vg | float | p.u. | required | ||
mbase | float | MVA | positive when stated | required | |
pmax | float | MW | pmin <= pmax | required | |
pmin | float | MW | required | ||
in_service | boolean | required | |||
cost | GenCost or null | null (no cost curve) | |||
caps | map of string to float | MW, MVAr, MW per minute, or a fraction per key | keys among pc1, pc2, qc1min, qc1max, qc2min, qc2max, ramp_agc, ramp_10, ramp_30, ramp_q, apf, the MATPOWER columns past PMIN | {} | |
energy_source | token hydro, nuclear, wind, thermal, solar, other | other | |||
voltage_regulation_on | boolean | true | |||
regulated_bus | id or null | names a bus | null (the generator’s own bus) | ||
regulating_terminal | TerminalReference or null | null | |||
active_power_control | ActivePowerControl or null | null | |||
uid | string or null | unique within generators | assigned at serialization |
Schema definition: GenCost.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
model | integer | 1 is piecewise linear, 2 is polynomial | required | ||
startup | float | currency | required | ||
shutdown | float | currency | required | ||
ncost | integer | polynomial: coeffs.len() == ncost; piecewise: coeffs.len() == 2 * ncost | required | ||
coeffs | array of float | polynomial: currency per MW^k per hour, highest order first; piecewise: alternating MW and currency per hour breakpoints | required |
Schema definition: ActivePowerControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
participate | boolean | required | |||
droop_percent | float or null | percent | null | ||
participation_factor | float or null | null | |||
minimum_target_active_power_mw | float or null | MW | null | ||
maximum_target_active_power_mw | float or null | MW | null |
Storage
The PowerModels storage model.
Schema definition: Storage.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
ps | float | MW | positive is withdrawn from the network (charging) | required | |
qs | float | MVAr | positive is withdrawn from the network | required | |
energy | float | MWh | 0 <= energy <= energy_rating | required | |
energy_rating | float | MWh | required | ||
charge_rating | float | MW | required | ||
discharge_rating | float | MW | required | ||
charge_efficiency | float | fraction | in [0, 1] | required | |
discharge_efficiency | float | fraction | in [0, 1] | required | |
thermal_rating | float | MVA | required | ||
current_rating | float or null | amperes | null | ||
qmin | float | MVAr | qmin <= qmax | required | |
qmax | float | MVAr | required | ||
r | float | p.u. | required | ||
x | float | p.u. | required | ||
p_loss | float | MW | standby loss | required | |
q_loss | float | MVAr | standby loss | required | |
in_service | boolean | required | |||
active_power_control | ActivePowerControl or null | null | |||
uid | string or null | unique within storage | assigned at serialization | ||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
from | id | names a bus | required | ||
to | id | names a bus | required | ||
in_service | boolean | required | |||
pf | float | MW | positive flows from the from bus to the to bus, measured at the from end | required | |
pt | float | MW | positive flows from the from bus to the to bus, measured at the to end | required | |
qf | float | MVAr | positive is injected into the from bus | required | |
qt | float | MVAr | positive is injected into the to bus | required | |
vf | float | p.u. | voltage setpoint at the from bus | required | |
vt | float | p.u. | voltage setpoint at the to bus | required | |
pmin | float | MW | bounds on pf; pmin <= pmax | required | |
pmax | float | MW | required | ||
qminf | float | MVAr | bounds on qf | required | |
qmaxf | float | MVAr | required | ||
qmint | float | MVAr | bounds on qt | required | |
qmaxt | float | MVAr | required | ||
loss0 | float | MW | constant loss term | required | |
loss1 | float | MW per MW | linear loss term in pf | required | |
resistance_ohm | float or null | ohm | null | ||
nominal_voltage_kv | float or null | kV | null | ||
converters_mode | token side1_rectifier_side2_inverter, side1_inverter_side2_rectifier, or null | null | |||
converter1 | HvdcConverter or null | null | |||
converter2 | HvdcConverter or null | null | |||
cost | GenCost or null | usage cost in pf | null | ||
uid | string or null | unique within hvdc | assigned at serialization | ||
extras | object | required |
Schema definition: HvdcConverter.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
component | ComponentId | required | |||
kind | token vsc, lcc | required | |||
loss_factor_percent | float | percent of active power | required | ||
power_factor | float or null | null | |||
reactive_power_setpoint_mvar | float or null | MVAr | null | ||
regulating_terminal | TerminalReference or null | null | |||
voltage_regulator_on | boolean or null | null | |||
voltage_setpoint_kv | float or null | kV | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
from | id | names a bus | required | ||
to | id | names a bus | required | ||
closed | boolean | required | |||
thermal_rating | float or null | MVA | null | ||
current_rating | float or null | amperes | null | ||
pf | float or null | MW | positive flows into the switch at the from terminal | null | |
qf | float or null | MVAr | positive flows into the switch at the from terminal | null | |
pt | float or null | MW | positive flows into the switch at the to terminal | null | |
qt | float or null | MVAr | positive flows into the switch at the to terminal | null | |
uid | string or null | unique within switches | assigned at serialization | ||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string or null | null | |||
windings | array of Winding | exactly three, in the order primary, secondary, tertiary | required | ||
z | array of Impedance | exactly three: z12, z23, z31 | required | ||
mag_g | float | p.u. on the system base | connected where magnetizing_connection says | required | |
mag_b | float | p.u. on the system base | positive is capacitive | connected where magnetizing_connection says | required |
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_vm | float | p.u. | solved star point voltage | required | |
star_va | float | degrees | required | ||
in_service | boolean | required | |||
uid | string or null | unique within transformers_3w | assigned at serialization | ||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
type | string | exactly "powerio.PartialTransformer3W" | required | ||
value | object | complete transformer body above with nondefault winding flags | required |
Schema definition: Winding.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
nominal_kv | float | kV | 0 defers to the terminal bus base_kv | required | |
tap | float | ratio | 1 is nominal (PSS/E WINDV with CW = 1) | required | |
shift | float | degrees | as Branch.shift | required | |
rate_a | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
rate_b | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
rate_c | float | MVA | 0 is a zero bound; +Inf is unbounded | required | |
control | TransformerControl or null | null |
Schema definition: Impedance.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
r | float | p.u. on the system base | required | ||
x | float | p.u. on the system base | required | ||
base_mva | float | MVA | the source’s declared base for the pair; positive | required |
Area
Schema definition: Area.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
number | integer | unique within areas; matches Bus.area | required | ||
name | string or null | null | |||
net_interchange | float | MW | positive is export out of the area | required | |
tolerance | float | MW | required | ||
slack_bus | id or null | names a bus | null | ||
area_type | string or null | null | |||
uid | string or null | null |
StaticVarCompensator
Schema definition: StaticVarCompensator.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | id | names a bus | required | ||
b_min_siemens | float | siemens | b_min_siemens <= b_max_siemens | required | |
b_max_siemens | float | siemens | required | ||
voltage_setpoint_kv | float | kV | required | ||
reactive_power_setpoint_mvar | float | MVAr | positive is injection | required | |
regulation_mode | token voltage, reactive_power | required | |||
regulating | boolean | required | |||
regulating_terminal | TerminalReference or null | null | |||
p | float | MW | positive is consumption | required | |
q | float | MVAr | positive is consumption | required | |
in_service | boolean | required | |||
uid | string or null | null | |||
extras | object | required |
SolverParams
Each member is set only when the source has it.
Schema definition: SolverParams.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
newton_tolerance | float or null | MW and MVAr mismatch | null | ||
max_iterations | integer or null | null | |||
zero_impedance_threshold | float or null | p.u. reactance | null | ||
adjust_taps | boolean or null | null | |||
adjust_phase_shift | boolean or null | null | |||
adjust_dc_taps | boolean or null | null | |||
adjust_switched_shunt | boolean or null | null | |||
adjust_area_interchange | boolean or null | null |
CaseMetadata
Schema definition: CaseMetadata.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
case_date | string or null | null | |||
forecast_distance | integer or null | minutes, as the source states | null | ||
source_model_format | string or null | null | |||
minimum_validation_level | string or null | null |
Coordinates
Schema definition: GeoMeta.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
kind | token source, synthetic, manual, derived, or null | default origin of points without their own kind | null |
Schema definition: Location.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
x | float | network coordinate space; longitude in geographic space | required | ||
y | float | network coordinate space; latitude in geographic space | required | ||
kind | token as GeoMeta.kind, or null | null (the network default) |
Component references
Schema definition: ComponentId.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
component_type | string | the element table or record kind | required | ||
local_id | string | the source supplied or assigned identity | required |
Schema definition: TerminalReference.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
equipment | ComponentId | required | |||
terminal | integer | 1 for single terminal equipment, else the side number | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
subnetworks | array of Subnetwork | [] | |||
substations | array of Substation | [] | |||
voltage_levels | array of VoltageLevel | kV | nominal_kv positive | [] | |
bus_breaker_buses | array of BusBreakerBus | [] | |||
calculated_buses | array of CalculatedBus | [] | |||
connectivity_nodes | array of ConnectivityNode | [] | |||
busbar_sections | array of BusbarSection | [] | |||
junctions | array of Junction | [] | |||
terminals | array of Terminal | [] | |||
switches | array of TopologySwitch | [] | |||
internal_connections | array of InternalConnection | [] | |||
operational_limit_groups | array of OperationalLimitGroup | amperes, MW, or MVA per limit kind | [] | ||
tap_changers | array of TapChanger | low_tap_position <= tap_position when stated | [] | ||
equipment_reactive_limits | array of EquipmentReactiveLimits | MVAr | [] | ||
boundary_lines | array of BoundaryLine | [] | |||
tie_lines | array of TieLine | [] | |||
component_metadata | array of ComponentMetadata | [] | |||
omitted_fields | array of OmittedField | a field absent from the source, distinct from a stated zero | [] | ||
dc_converter_units | array of DcConverterUnit | [] | |||
dc_topological_nodes | array of DcTopologicalNode | [] | |||
dc_nodes | array of DcNode | [] | |||
dc_grounds | array of DcGround | [] | |||
dc_busbars | array of DcBusbar | [] | |||
dc_lines | array of DcLine | [] | |||
dc_series_devices | array of DcSeriesDevice | [] | |||
dc_switches | array of DcSwitch | [] | |||
voltage_source_converters | array of VoltageSourceConverter | [] | |||
line_commutated_converters | array 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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string or null | null | |||
base_frequency | float | Hz | positive | required | |
source_format | token dss, bmopf-json, pmd-json, cim-dist, sincal, ravens-json, pmd-math-json, pandapower-json, or null | null | |||
buses | array of DistBus | id unique | required | ||
linecodes | array of DistLineCode | name unique | required | ||
lines | array of DistLine | bus_from, bus_to name buses; linecode names a line code | required | ||
switches | array of DistSwitch | bus_from, bus_to name buses | required | ||
transformers | array of DistTransformer | every winding bus names a bus | required | ||
loads | array of DistLoad | bus names a bus | required | ||
shunts | array of DistShunt | bus names a bus | required | ||
capacitors | array of DistCapacitor | bus names a bus | [] | ||
generators | array of DistGenerator | bus names a bus | required | ||
ibrs | array of DistIbr | bus names a bus; control_profile names a profile | [] | ||
control_profiles | array of DistControlProfile | name unique | [] | ||
sources | array of VoltageSource | BMOPF carries exactly one | required | ||
untyped | array of UntypedObject | required | |||
commands | array of [verb, args] string pairs | source order | required | ||
options | array of [name, value] string pairs | source order | required | ||
extras | object | required | |||
geo | DistGeoMeta or null | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
type | string | exactly "powerio.LocatedMulticonductorNetwork" | required | ||
value | LocatedNetworkFields | required |
Schema definition: LocatedNetworkFields.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | MulticonductorNetworkBody | original electrical network layout above | required | ||
locations | array of DistComponentLocation | at most 1,048,576; one point per exact component identity | required |
Schema definition: DistComponentLocation.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
target | bus, line, line_code, switch, transformer, load, generator, ibr, shunt, capacitor, source | names the component table | required | ||
name | string | exact existing component id/name; case sensitive | required | ||
point | DistGeographicPoint | independent of drawing positions, routes and electrical length | required | ||
kind | source, synthetic, manual, derived, or null | point origin | null |
Schema definition: DistGeographicPoint.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
latitude | float or null | decimal degrees | north positive | finite, in [-90, 90]; at least one axis present | null |
longitude | float or null | decimal degrees | east positive | finite, in [-180, 180]; zero is a stated coordinate | null |
datum | string or null | nonempty when stated; null means unknown, never implied WGS84 | null |
DistBus
Schema definition: DistBus.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | unique within buses | required | ||
terminals | array of string | ordered, unique | required | ||
grounded | array of string | each names a terminal of this bus; zero impedance to ground | required | ||
v_min | float or null | volts | v_min <= v_max | null (unbounded) | |
v_max | float or null | volts | null (unbounded) | ||
v_min_phase | array of float or null | volts | phase order excludes neutral and earth; scalar v_min takes precedence | null | |
v_max_phase | array of float or null | volts | phase order excludes neutral and earth; scalar v_max takes precedence | null | |
vpn_min | array of float or null | volts | per phase to neutral bound | null | |
vpn_max | array of float or null | volts | null | ||
vpp_min | array of float or null | volts | per phase to phase bound | null | |
vpp_max | array of float or null | volts | null | ||
vpos_min | float or null | volts | positive sequence bound | null | |
vpos_max | float or null | volts | null | ||
vneg_max | float or null | volts | negative sequence magnitude cap | null | |
vzero_max | float or null | volts | zero sequence magnitude cap | null | |
vn_max | float or null | volts | neutral to ground magnitude cap | null | |
location | DistLocation or null | network coordinate space | null | ||
extras | object | required |
DistLineCode
Schema definition: DistLineCode.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within linecodes | required | ||
n_conductors | integer | positive; the order of every matrix | required | ||
r_series | matrix | ohm per meter | n_conductors square, symmetric | required | |
x_series | matrix | ohm per meter | n_conductors square, symmetric | required | |
g_from | matrix | siemens per meter | half of the shunt admittance, at the from end | required | |
b_from | matrix | siemens per meter | positive is capacitive | required | |
g_to | matrix | siemens per meter | half of the shunt admittance, at the to end | required | |
b_to | matrix | siemens per meter | positive is capacitive | required | |
i_max | array of float or null | amperes per conductor | null | ||
s_max | array of float or null | VA per conductor | null | ||
source | string or null | origin of the matrices (BMOPF source) | null | ||
extras | object | required |
DistLine
Schema definition: DistLine.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within lines | required | ||
bus_from | string | names a bus | required | ||
bus_to | string | names a bus | required | ||
terminal_map_from | array of string | n_conductors terminals of bus_from | required | ||
terminal_map_to | array of string | n_conductors terminals of bus_to | required | ||
linecode | string | names a line code | required | ||
length | float | meters | nonnegative | required | |
i_max | array of float or null | amperes per conductor | null (the line code’s) | ||
s_max | array of float or null | VA per conductor | null (the line code’s) | ||
route | array of DistLocation or null | network coordinate space | null | ||
extras | object | required |
DistSwitch
Schema definition: DistSwitch.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within switches | required | ||
bus_from | string | names a bus | required | ||
bus_to | string | names a bus | required | ||
terminal_map_from | array of string | terminals of bus_from, same length as terminal_map_to | required | ||
terminal_map_to | array of string | terminals of bus_to | required | ||
open | boolean | required | |||
i_max | array of float or null | amperes per conductor | null | ||
extras | object | required |
DistTransformer
Schema definition: DistTransformer.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within transformers | required | ||
phases | integer | 1 through 3 | required | ||
windings | array of DistWinding | two or three | required | ||
xsc_pct | array of float | percent | [xhl] for two windings, [xhl, xht, xlt] for three | required | |
extras | object | required |
Schema definition: DistWinding.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
conn | token wye, delta | required | |||
v_ref | float | volts, line to line for two and three phases | positive | required | |
s_rating | float | VA | positive | required | |
r_pct | float | percent of the winding base | required | ||
tap | float | ratio | 1 is nominal | required | |
r_neutral | float or null | ohm | null | ||
x_neutral | float or null | ohm | null |
DistLoad
Schema definition: DistLoad.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within loads | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
configuration | token wye, delta, single_phase | required | |||
p_nom | array of float | watts per phase | positive is consumption | one entry per active phase | required |
q_nom | array of float | vars per phase | positive is inductive consumption | same length as p_nom | required |
voltage_model | DistLoadVoltageModel | required | |||
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within capacitors | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
configuration | token wye, delta, single_phase | required | |||
q_rated | float | vars, whole bank at v_nom | positive is capacitive injection | required | |
v_nom | float | volts, line to line for the three phase configurations | positive | required | |
extras | object | required |
DistShunt
Schema definition: DistShunt.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within shunts | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus, the order of the matrices | required | ||
g | matrix | siemens | square in terminal_map | required | |
b | matrix | siemens | positive is capacitive | square in terminal_map | required |
extras | object | required |
DistGenerator
Schema definition: DistGenerator.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within generators | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
configuration | token wye, delta, single_phase | required | |||
p_nom | array of float | watts per phase | positive is generation | required | |
q_nom | array of float | vars per phase | positive is generation | same length as p_nom | required |
p_min | array of float or null | watts per phase | p_min <= p_max | null | |
p_max | array of float or null | watts per phase | null | ||
q_min | array of float or null | vars per phase | q_min <= q_max | null | |
q_max | array of float or null | vars per phase | null | ||
s_max | array of float or null | VA per conductor | null | ||
i_max | array of float or null | amperes per conductor | null | ||
cost | array of float or null | currency per kWh per phase, or one scalar | null | ||
extras | object | required |
DistIbr
Schema definition: DistIbr.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within ibrs | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
prime_mover | token PV, BATTERY, GENERIC, STATCOM, DSTATCOM | required | |||
topology | token SINGLE_PHASE, THREE_LEG, FOUR_LEG | required | |||
s_max | array of float | VA per phase | nameplate | required | |
p_avail | float or null | watts | null | ||
p_min | array of float or null | watts per phase | null | ||
p_max | array of float or null | watts per phase | null | ||
q_min | array of float or null | vars per phase | null | ||
q_max | array of float or null | vars per phase | null | ||
i_max | array of float or null | amperes per conductor | null | ||
voltage_aggregation | token PER_PHASE, AVERAGE, or null | null | |||
control_profile | string or null | names a control profile | null | ||
extras | object | required |
DistControlProfile
Schema definition: DistControlProfile.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within control_profiles | required | ||
volt_var | VoltVarControl or null | null | |||
volt_watt | VoltWattControl or null | null | |||
power_factor | PowerFactorControl or null | null | |||
extras | object | required |
Schema definition: VoltVarControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
breakpoints | array of float | p.u. voltage | four, [U1, U2, U3, U4], ascending | required | |
q_limits | array of float | q_unit | positive is injection | two, [q_absorb, q_inject]: injects q_inject below U1 and absorbs q_absorb above U4 | required |
voltage_reference | token PN_PER_PHASE, PP_PER_PHASE, PP_AVERAGED, PG_AVERAGED, PN_AVERAGED, PG_PER_PHASE, or null | null | |||
q_ref | token VAR_MAX, VAR_AVAILABLE, or null | null | |||
q_unit | token VA_FRACTION, VAR, or null | null | |||
p_min_for_q | float or null | watts | null | ||
p_min_for_q_max | float or null | watts | null |
Schema definition: VoltWattControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
breakpoints | array of float | p.u. voltage | two, [U5, U6], ascending | required | |
p_limits | array of float | p_unit | two, [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 absent | required | |
voltage_reference | token as VoltVarControl.voltage_reference, or null | null | |||
p_ref | token P_AVAILABLE, P_MAX, S_MAX, or null | null | |||
p_unit | token VA_FRACTION, W, or null | null |
Schema definition: PowerFactorControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
pf | float | positive when Q has the same sign as P, negative when opposite (the OpenDSS PVSystem and Storage convention) | 0 < abs(pf) <= 1 | required |
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).
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within sources | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | terminals of bus | required | ||
v_magnitude | array of float | volts per terminal | 0 on a grounded terminal; same length as terminal_map | required | |
v_angle | array of float | radians per terminal | same length as terminal_map | required | |
energy_cost_rate | optional array of float | $/kWh | positive injection supplies the network | one entry per phase in terminal-map order; excludes neutral terminals | no stated source-price term |
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
type | string | exactly "powerio.ReferencedVoltageSource" | required | ||
value | object | referenced source body below | required |
Schema definition: ReferencedSourceFields.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | unique within sources | required | ||
bus | string | names a bus | required | ||
terminal_map | array of string | distinct declared terminals of bus; excludes the reference | required | ||
v_magnitude | array of float | volts per terminal-to-reference difference | same length as terminal_map; a grounded phase can have a nonzero difference | required | |
v_angle | array of float | radians per terminal-to-reference difference | same length as terminal_map | required | |
reference_terminal | string | another declared terminal on bus; does not imply grounding | required | ||
energy_cost_rate | optional array of float | $/kWh | positive injection supplies the network | per phase in terminal-map order | no stated source-price term |
extras | object | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
class | string | required | |||
name | string | required | |||
props | array of [key, value] string pairs | source order | required |
Distribution coordinates
Schema definition: DistGeoMeta.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
kind | token source, synthetic, manual, derived, or null | null |
Schema definition: DistLocation.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
x | float | network coordinate space; longitude in geographic space | required | ||
y | float | network coordinate space; latitude in geographic space | required | ||
kind | token as DistGeoMeta.kind, or null | null (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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
space | CoordinateSpace | the space every feature’s coordinates are in | required | ||
kind | token source, synthetic, manual, derived, or null | default origin of features without their own kind | null | ||
features | array of GeoFeature | empty |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
width | float or null | canvas units | positive | the drawing width the source states | null |
height | float or null | canvas units | positive | the drawing height the source states | null |
units | string or null | the source’s own name for its canvas units | null |
GeoFeature
Schema definition: GeoFeature.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
target | token bus, branch, or substation | the element family the feature places | required | ||
key | ElementKey | at least one member names an element, unless a branch states both endpoints | required | ||
geometry | GeoGeometry | every coordinate is finite | required | ||
from | string or null | a branch’s endpoint bus, the unordered fallback identity | null | ||
to | string or null | the other endpoint bus | null | ||
kind | token as GeoLayer.kind, or null | null (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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
uid | string or null | the durable identity (buses:3, branches:7) | null | ||
id | string or null | the source’s own element identifier | null | ||
name | string or null | matched case insensitively | null | ||
index | integer or null | positive | 1-based row alias, accepted on read and never written | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
header | array of string | the comment lines ahead of the first statement, as written | empty | ||
cases | array of ContingencyCase | in file order | empty | ||
automatic | array of AutomaticSpec | in file order | empty | ||
skips | array of SkipRule | the branches automatic expansion leaves alone | empty | ||
retained | array of RetainedStatement | file level statements outside the grammar | empty |
ContingencyCase
Every action of one case applies together.
Schema definition: ContingencyCase.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | nonempty | required | ||
actions | array of ContingencyAction | in file order | empty |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
op | token increase, decrease, or set | whether the amount adds to, subtracts from, or replaces the present value | required | ||
amount | float | MW or percent, as unit says | positive is the stated magnitude | finite | required |
unit | token mw or percent | required |
AutomaticSpec
One specification expands into one case per element of a subsystem.
Schema definition: AutomaticSpec.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
order | token single or double | how many elements one case outages | required | ||
target | token branch, unit, or tie | the element family the expansion draws from; tie is the branches crossing the subsystem border | required | ||
subsystem | string | names a subsystem of the .sub file the expansion runs against | required | ||
low_voltage_3w | boolean | 3WLOWVOLTAGE: a branch expansion also takes the low voltage winding of a three winding transformer | required |
Schema definition: SkipRule.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
from | id | one terminal of the excluded branch | required | ||
to | id | the other terminal | required | ||
circuit | string | the branch circuit id | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
line | integer | the 1-based source line the statement was read from; at least 1 | required | ||
text | string | the line, with its surrounding whitespace dropped | required | ||
after_end | boolean | the 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 there | false |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
header | array of string | the comment lines ahead of the first statement, as written | empty | ||
subsystems | array of Subsystem | in file order | empty | ||
retained | array of RetainedStatement | file level statements outside the grammar | empty |
Subsystem
A subsystem is the union of its selector groups.
Schema definition: Subsystem.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | nonempty; a .con or .mon statement names it without case | required | ||
groups | array of SelectorGroup | the implicit group comes first when it has any selector | empty | ||
retained | array of RetainedStatement | statements inside this subsystem, and outside any JOIN group, that are outside the grammar | empty |
Schema definition: SelectorGroup.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
join | JoinName or null | how the file stated the group; null is the implicit group, which holds the selectors stated outside any JOIN | null | ||
selectors | array of SubsystemSelector | bus sets that intersect across selector types within one group | empty | ||
retained | array of RetainedStatement | lines read while this JOIN was open that are outside the grammar; the implicit group holds none | empty |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
header | array of string | the comment lines ahead of the first statement, as written | empty | ||
statements | array of MonitorStatement | in file order | empty | ||
retained | array of RetainedStatement | statements outside the grammar | empty |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
from | id | one terminal of the monitored branch | required | ||
to | id | the other terminal | required | ||
circuit | string | the branch circuit id; an absent id in the source reads as 1 | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork or MulticonductorNetwork, as the type name says | the complete base network | required | ||
quantities | map of quantity name to StoredQuantity | per quantity, below | keys among the quantity names of the network family | required |
Schema definition: StoredQuantity.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
identities | array of string | each names a component of the network; unique; same length as values | required | ||
values | array of float | the quantity’s unit; a flag is 0 or 1 | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
quantities | map of quantity name to StoredQuantity | as StoredOperatingPoint.quantities | required |
Balanced quantities. A bus quantity is keyed by the bus id’s decimal
spelling; an element quantity by the element’s uid.
| quantity | keyed by | unit | sign |
|---|---|---|---|
bus_voltage_magnitude | bus id | p.u. | |
bus_voltage_angle | bus id | degrees | |
bus_active_injection | bus id | MW | positive into the network |
bus_reactive_injection | bus id | MVAr | positive into the network |
generator_active_power | generator uid | MW | positive is generation |
generator_reactive_power | generator uid | MVAr | positive is generation |
generator_voltage_setpoint | generator uid | p.u. | |
generator_in_service | generator uid | flag | |
load_active_power | load uid | MW | positive is consumption |
load_reactive_power | load uid | MVAr | positive is consumption |
branch_in_service | branch uid | flag | |
branch_tap_ratio | branch uid | ratio | |
branch_phase_shift | branch uid | degrees | as Branch.shift |
switch_closed | switch uid | flag |
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.
| quantity | keyed by | unit | sign |
|---|---|---|---|
terminal_voltage_magnitude | bus/terminal | volts | |
terminal_voltage_angle | bus/terminal | radians | |
load_active_power | load/terminal | watts | positive is consumption |
load_reactive_power | load/terminal | vars | positive is consumption |
generator_active_power | generator/terminal | watts | positive is generation |
generator_reactive_power | generator/terminal | vars | positive is generation |
transformer_tap | transformer name | ratio | |
capacitor_steps | capacitor name | count | |
switch_closed | switch name | flag |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
time_points | array of TimePoint | required | |||
values | array of the element type, each a complete network | same length as time_points | required |
A series of operating points gives the shared base network once.
Schema definitions: StoredOperatingPointTimeSeries, StoredOperatingPointTimeSeries2.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | the base network, or null | null only for an empty series | required when values is nonempty | ||
time_points | array of TimePoint | required | |||
values | array of StoredOperatingPointAssignment | same length as time_points; identities name components of network | required |
Schema definition: TimePoint.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
label | string | nonempty, bounded | required | ||
duration | Duration or null | the interval the point covers | null |
Schema definition: Duration.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
secs | integer | seconds | required | ||
nanos | integer | nanoseconds | below one billion | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
scenarios | array of the scenario record | id unique | required |
Schema definitions: StoredScenario, StoredScenario2, StoredScenario3, StoredScenario4, StoredScenario5, StoredScenario6.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | nonempty, bounded, unique in the set | required | ||
probability | float or null | in [0, 1] | null | ||
value | the element type: a network, a network time series, or an operating point time series | required |
A scenario set of operating points gives the shared base network once.
Schema definitions: StoredOperatingPointScenarioSet, StoredOperatingPointScenarioSet2.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | the base network, or null | null only for an empty set | required when scenarios is nonempty | ||
scenarios | array of StoredOperatingPointScenario | id unique | required |
Schema definition: StoredOperatingPointScenario.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | nonempty, bounded, unique in the set | required | ||
probability | float or null | in [0, 1] | null | ||
quantities | map of quantity name to StoredQuantity | identities name components of network | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork | at least one REF bus | required | ||
approximation | token series_susceptance, tap_adjusted_reactance, reactance_only, tap_adjusted_series_susceptance, series_susceptance_no_phase_shift | the DC branch susceptance formula | required | ||
initial_point | StoredOperatingPointAssignment or null | null | |||
hvdc_treatment | token fixed_injection, ignore | how the specifications treat HVDC lines; written only when not ignore | ignore |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork | at least one REF bus | required | ||
specifications | array of AcBusSpecification | one per bus, in bus table order | required | ||
initial_point | StoredOperatingPointAssignment or null | null | |||
hvdc_treatment | token fixed_injection, ignore | how specifications derived for a replacement network treat HVDC lines; written only when not ignore | ignore |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork | at least one REF bus and one in service generator on a non isolated bus | required | ||
objective | Objective | required | |||
constraints | ActiveConstraints | required | |||
approximation | token as DcPfInstance.approximation | required | |||
initial_point | StoredOperatingPointAssignment or null | null |
powerio.AcOpfInstance
Schema definition: AcOpfInstance.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork | at least one REF bus and one in service generator on a non isolated bus | required | ||
objective | Objective | required | |||
constraints | ActiveConstraints | required | |||
initial_point | StoredOperatingPointAssignment or null | null |
Schema definition: Objective.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
terms | array of ObjectiveTerm | empty 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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
generator_capability | ConstraintSelection | active and reactive generator limits | required | ||
voltage_bounds | ConstraintSelection | bus voltage magnitude bounds | required | ||
thermal_limits | ConstraintSelection | branch thermal limits | required | ||
angle_bounds | ConstraintSelection | branch angle difference bounds | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
base | AcOpfInstance | the network, objective, constraint selections, and initial point | required | ||
options | AcOtsOptions | required |
Schema definition: AcOtsOptions.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
switchable | BranchSelection | an only identity names one branch, once | required | ||
switching_costs | array of BranchSwitchingCost | one record per branch at most | []: switching costs nothing | ||
islanding | token | forbidden (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 shed | required | ||
max_open | integer or null | branches | at most the branch count, at least the open branches that cannot switch; counts every open branch | null: no budget | |
max_switched | integer or null | branches | at most the switchable count; counts changes against the initial status | null: no budget | |
current_limits | token | skip, stated (the records below), or derive_from_rate_a (PowerModels’ calc_current_limits!) | required | ||
stated_current_limits | array of BranchCurrentLimit | one 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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | a branch identity | required | ||
open_cost | float | objective units | finite and nonnegative; charged when an initially closed branch opens | required | |
close_cost | float | objective units | finite and nonnegative; charged when an initially open branch closes | required |
Schema definition: BranchCurrentLimit.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | a branch identity | required | ||
from_pu | float or null | p.u. on base_mva and the from bus base_kv | finite and positive | null: unbounded | |
to_pu | float or null | p.u. on base_mva and the to bus base_kv | finite and positive | null: unbounded |
powerio.McAcPfInstance
Schema definition: McAcPfInstance.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | MulticonductorNetwork | at least one voltage source | required | ||
initial_point | StoredOperatingPointAssignment or null | null |
The prescribed terminal powers, source voltages, and active regulator and capacitor controls are derived from the network.
powerio.McAcOpfInstance
Schema definition: McAcOpfInstance.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | MulticonductorNetwork | at least one voltage source | required | ||
objective | Objective | required | |||
constraints | MulticonductorActiveConstraints | required | |||
initial_point | StoredOperatingPointAssignment or null | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
formulation | LinDist3FlowOpfInstance | zero objective, fixed generator dispatch, and conductor_limits selected as none | required |
powerio.LinDist3FlowOpfInstance
Schema definition: LinDist3FlowOpfInstance.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
base | McAcOpfInstance | complete multiconductor AC OPF instance | required | ||
options | LinDist3FlowBuildOptions | fixed reference, unsupported-data, and neutral-provenance policies used to construct the formulation | required |
Schema definition: LinDist3FlowBuildOptions.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
reference_policy | auto, explicit, or source_propagated | selects the fixed coefficient phasors | required | ||
unsupported | reject, lower, approximate, or permissive | selects the audited preparation-policy level | required | ||
require_neutral_provenance | bool | requires a recorded neutral-Kron projection when true | required |
Schema definition: MulticonductorActiveConstraints.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
terminal_voltage_bounds | ConstraintSelection | required | |||
conductor_limits | ConstraintSelection | current or apparent power limits | required | ||
generator_capability | ConstraintSelection | per phase bounds | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
network | BalancedNetwork | required | |||
inputs | ScucInputs | identities name components of network; time varying records match the horizon | required |
Schema definition: ScucInputs.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
interval_durations | array of float | hours | positive; chronological | required | |
devices | array of ScucDevice | id unique | required | ||
active_reserve_zones | array of ScucActiveReserveZone | required | |||
reactive_reserve_zones | array of ScucReactiveReserveZone | required | |||
contingencies | array of ScucContingency | required | |||
shunts | array of ScucShunt | required | |||
transformer_controls | array of ScucTransformerControl | required | |||
branch_switching_costs | array of ScucBranchSwitchingCost | required | |||
violation_costs | ScucViolationCosts | required |
Schema definition: ScucDevice.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | the generator or load in the network | required | ||
kind | token producer, consumer | required | |||
on_cost | float | dollars | required | ||
startup_cost | float | dollars | required | ||
shutdown_cost | float | dollars | required | ||
initial_on_status | boolean | required | |||
initial_commitment | ScucInitialCommitment | required | |||
minimum_up_time | float | hours | required | ||
minimum_down_time | float | hours | required | ||
ramp_limits | ScucRampLimits | required | |||
reserve_limits | ScucReserveLimits | required | |||
reactive_capability | ScucReactiveCapability | required | |||
energy_lower_bounds | array of ScucEnergyRequirement | required | |||
energy_upper_bounds | array of ScucEnergyRequirement | required | |||
startup_cost_adjustments | array of ScucStartupCostAdjustment | required | |||
startup_limits | array of ScucStartupLimit | required | |||
periods | array of ScucDevicePeriod | one per interval, chronological | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
on_status_min | boolean | required | |||
on_status_max | boolean | required | |||
active_power_min | float | p.u. | active_power_min <= active_power_max | required | |
active_power_max | float | p.u. | required | ||
reactive_power_min | float | p.u. | reactive_power_min <= reactive_power_max | required | |
reactive_power_max | float | p.u. | required | ||
energy_cost_blocks | array of ScucEnergyCostBlock | required | |||
reserve_costs | ScucReserveCosts | required |
Schema definition: ScucEnergyCostBlock.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
block_size | float | p.u. | nonnegative | required | |
marginal_cost | float | dollars per p.u. hour | required |
Schema definition: ScucReserveCosts.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
regulation_up | float | dollars per p.u. hour | required | ||
regulation_down | float | dollars per p.u. hour | required | ||
synchronized | float | dollars per p.u. hour | required | ||
nonsynchronized | float | dollars per p.u. hour | required | ||
ramping_up_online | float | dollars per p.u. hour | required | ||
ramping_up_offline | float | dollars per p.u. hour | required | ||
ramping_down_online | float | dollars per p.u. hour | required | ||
ramping_down_offline | float | dollars per p.u. hour | required | ||
reactive_up | float | dollars per p.u. hour | required | ||
reactive_down | float | dollars per p.u. hour | required |
Schema definition: ScucReserveLimits.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
regulation_up | float | p.u. | nonnegative | required | |
regulation_down | float | p.u. | nonnegative | required | |
synchronized | float | p.u. | nonnegative | required | |
nonsynchronized | float | p.u. | nonnegative | required | |
ramping_up_online | float | p.u. | nonnegative | required | |
ramping_up_offline | float | p.u. | nonnegative | required | |
ramping_down_online | float | p.u. | nonnegative | required | |
ramping_down_offline | float | p.u. | nonnegative | required |
Schema definition: ScucRampLimits.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
up | float | p.u. per hour | nonnegative | required | |
down | float | p.u. per hour | nonnegative | required | |
startup | float | p.u. per hour | nonnegative | required | |
shutdown | float | p.u. per hour | nonnegative | required |
Schema definition: ScucInitialCommitment.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
accumulated_up_time | float | hours | nonnegative | required | |
accumulated_down_time | float | hours | nonnegative | required |
Schema definition: ScucEnergyRequirement.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
start_time | float | hours | start_time <= end_time | required | |
end_time | float | hours | required | ||
energy | float | p.u. hour | required |
Schema definition: ScucStartupCostAdjustment.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
maximum_down_time | float | hours | required | ||
cost | float | dollars | required |
Schema definition: ScucStartupLimit.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
start_time | float | hours | start_time <= end_time | required | |
end_time | float | hours | required | ||
maximum_startups | integer | required |
Schema definition: ScucActiveReserveZone.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | unique | required | ||
buses | array of ComponentId | each names a bus of the network | required | ||
regulation_up_requirement_fraction | float | fraction of zone load | required | ||
regulation_down_requirement_fraction | float | fraction of zone load | required | ||
synchronized_requirement_fraction | float | fraction of zone load | required | ||
nonsynchronized_requirement_fraction | float | fraction of zone load | required | ||
ramping_up_requirement | array of float | p.u. | one per interval | required | |
ramping_down_requirement | array of float | p.u. | one per interval | required | |
regulation_up_violation_cost | float | dollars per p.u. hour | required | ||
regulation_down_violation_cost | float | dollars per p.u. hour | required | ||
synchronized_violation_cost | float | dollars per p.u. hour | required | ||
nonsynchronized_violation_cost | float | dollars per p.u. hour | required | ||
ramping_up_violation_cost | float | dollars per p.u. hour | required | ||
ramping_down_violation_cost | float | dollars per p.u. hour | required |
Schema definition: ScucReactiveReserveZone.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | unique | required | ||
buses | array of ComponentId | each names a bus of the network | required | ||
reactive_up_requirement | array of float | p.u. | one per interval | required | |
reactive_down_requirement | array of float | p.u. | one per interval | required | |
reactive_up_violation_cost | float | dollars per p.u. hour | required | ||
reactive_down_violation_cost | float | dollars per p.u. hour | required |
Schema definition: ScucContingency.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | unique | required | ||
components | array of ComponentId | Challenge 3 requires exactly one AC line, transformer, or DC line | required |
Schema definition: ScucShunt.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | the shunt in the network | required | ||
initial_step | integer | step_min <= initial_step <= step_max | required | ||
step_min | integer | required | |||
step_max | integer | required | |||
conductance_per_step | float | p.u. | required | ||
susceptance_per_step | float | p.u. | positive is capacitive | required |
Schema definition: ScucTransformerControl.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | the two winding transformer in the network | required | ||
tap_ratio_min | float | p.u. | tap_ratio_min <= tap_ratio_max | required | |
tap_ratio_max | float | p.u. | required | ||
phase_shift_min | float | radians | phase_shift_min <= phase_shift_max | required | |
phase_shift_max | float | radians | required |
Schema definition: ScucBranchSwitchingCost.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | ComponentId | the branch or transformer in the network | required | ||
connection_cost | float | dollars | required | ||
disconnection_cost | float | dollars | required |
Schema definition: ScucViolationCosts.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
active_power_balance | float | dollars per p.u. hour | required | ||
reactive_power_balance | float | dollars per p.u. hour | required | ||
branch_thermal_limit | float | dollars per p.u. hour | required | ||
energy_requirement | float | dollars per p.u. hour | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
max_active_power_mismatch | float or null | MW | largest absolute active balance mismatch | null (not reported) | |
max_reactive_power_mismatch | float or null | MVAr | largest absolute reactive balance mismatch | null (not reported) |
Schema definition: GeneratorDispatch.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
p_mw | array of float | MW | positive is generation | one per generator | required |
q_mvar | array of float | MVAr | positive is generation | one per generator, or empty | required |
Schema definition: ThreeWindingTransformerTerminalActivePower.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
p_mw | array of float | MW | positive flows into the transformer at the winding | three entries, winding order | required |
Schema definition: ThreeWindingTransformerTerminalPower.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
p_mw | array of float | MW | positive flows into the transformer at the winding | three entries, winding order | required |
q_mvar | array of float | MVAr | positive flows into the transformer at the winding | three entries, winding order | required |
powerio.DcPfSolution
Schema definition: DcPfSolution.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | DcPfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
bus_voltage_angle | array of float | degrees | one per bus | required | |
bus_active_injection | array of float | MW | positive into the network | one per bus | required |
branch_from_active_flow | array of float | MW | positive into the branch at the from terminal | one per branch | required |
branch_to_active_flow | array of float | MW | positive into the branch at the to terminal | one per branch | required |
three_winding_transformer_terminal_active_powers | array of ThreeWindingTransformerTerminalActivePower | one per three winding transformer | required | ||
generator_dispatch | GeneratorDispatch or null | null |
powerio.AcPfSolution
Schema definition: AcPfSolution.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | AcPfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
bus_voltage_magnitude | array of float | p.u. | one per bus | required | |
bus_voltage_angle | array of float | degrees | one per bus | required | |
bus_active_injection | array of float | MW | positive into the network | one per bus | required |
bus_reactive_injection | array of float | MVAr | positive into the network | one per bus | required |
branch_from_active_flow | array of float | MW | positive into the branch at the from terminal | one per branch | required |
branch_from_reactive_flow | array of float | MVAr | positive into the branch at the from terminal | one per branch | required |
branch_to_active_flow | array of float | MW | positive into the branch at the to terminal | one per branch | required |
branch_to_reactive_flow | array of float | MVAr | positive into the branch at the to terminal | one per branch | required |
three_winding_transformer_terminal_powers | array of ThreeWindingTransformerTerminalPower | one per three winding transformer | required | ||
generator_dispatch | GeneratorDispatch or null | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | DcOpfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
bus_voltage_angle | array of float | degrees | one per bus | required | |
bus_active_injection | array of float | MW | positive into the network | one per bus | required |
branch_from_active_flow | array of float | MW | positive into the branch at the from terminal | one per branch | required |
branch_to_active_flow | array of float | MW | positive into the branch at the to terminal | one per branch | required |
generator_active_power | array of float | MW | positive is generation | one per generator | required |
three_winding_transformer_terminal_active_powers | array of ThreeWindingTransformerTerminalActivePower | one per three winding transformer | required | ||
objective | float | objective units | required | ||
bus_active_power_marginal | array of float or null | objective units per MW | one per bus | null | |
branch_from_limit_multiplier | array of float or null | objective units per MW | one per branch; finite and nonnegative | null | |
branch_to_limit_multiplier | array of float or null | objective units per MW | one per branch; finite and nonnegative | null |
powerio.AcOpfSolution
Schema definition: AcOpfSolution.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | AcOpfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
bus_voltage_magnitude | array of float | p.u. | one per bus | required | |
bus_voltage_angle | array of float | degrees | one per bus | required | |
bus_active_injection | array of float | MW | positive into the network | one per bus | required |
bus_reactive_injection | array of float | MVAr | positive into the network | one per bus | required |
branch_from_active_flow | array of float | MW | positive into the branch at the from terminal | one per branch | required |
branch_from_reactive_flow | array of float | MVAr | positive into the branch at the from terminal | one per branch | required |
branch_to_active_flow | array of float | MW | positive into the branch at the to terminal | one per branch | required |
branch_to_reactive_flow | array of float | MVAr | positive into the branch at the to terminal | one per branch | required |
generator_active_power | array of float | MW | positive is generation | one per generator | required |
generator_reactive_power | array of float | MVAr | positive is generation | one per generator | required |
three_winding_transformer_terminal_powers | array of ThreeWindingTransformerTerminalPower | one per three winding transformer | required | ||
objective | float | objective units | required | ||
bus_active_power_marginal | array of float or null | objective units per MW | one per bus | null | |
bus_reactive_power_marginal | array of float or null | objective units per MVAr | one per bus | null | |
branch_from_limit_multiplier | array of float or null | objective units per MVA | one per branch; finite and nonnegative | null | |
branch_to_limit_multiplier | array of float or null | objective units per MVA | one per branch; finite and nonnegative | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | AcOtsInstance | required | |||
branch_closed | array of boolean | one per branch; fixed branches unchanged; within the budgets and islanding policy | required | ||
ac_solution | AcOpfSolution | solves the fixed-topology problem; open branches carry zero flow | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | AcOpfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
values | SocwrOpfValues | required | |||
duals | SocwrOpfDuals | every member null | |||
objective_lower_bound | float | objective units | required |
Schema definition: SocwrOpfValues.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus_voltage_magnitude_squared | array of float | p.u. squared | w[i] = |V_i|^2; one per bus | required | |
branch_voltage_product_real | array of float | p.u. squared | Re(V_from conj(V_to)); one per branch | required | |
branch_voltage_product_imaginary | array of float | p.u. squared | Im(V_from conj(V_to)); one per branch | required | |
generator_active_power | array of float | MW | positive is generation | one per generator | required |
generator_reactive_power | array of float | MVAr | positive is generation | one per generator | required |
branch_from_active_flow | array of float | MW | positive into the branch at the from terminal | one per branch | required |
branch_from_reactive_flow | array of float | MVAr | positive into the branch at the from terminal | one per branch | required |
branch_to_active_flow | array of float | MW | positive into the branch at the to terminal | one per branch | required |
branch_to_reactive_flow | array of float | MVAr | positive into the branch at the to terminal | one per branch | required |
three_winding_transformer_terminal_powers | array of ThreeWindingTransformerTerminalPower | one per three winding transformer | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus_active_power_marginal | array of float or null | objective units per MW | one per bus | null | |
bus_reactive_power_marginal | array of float or null | objective units per MVAr | one per bus | null | |
branch_from_thermal_limit_multiplier | array of float or null | objective units per MVA | one per branch; finite and nonnegative | null | |
branch_to_thermal_limit_multiplier | array of float or null | objective units per MVA | one per branch; finite and nonnegative | null |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | McAcPfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
terminal_voltage_magnitude | array of float | volts | one per terminal | required | |
terminal_voltage_angle | array of float | radians | one per terminal | required | |
terminal_current_magnitude | array of float or null | amperes | one per terminal | null | |
terminal_active_power | array of float or null | watts | positive into the network | one per terminal | null |
source_active_injection | array of float | watts | positive into the network | one per source terminal | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | McAcOpfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
terminal_voltage_magnitude | array of float | volts | one per terminal | required | |
terminal_voltage_angle | array of float | radians | one per terminal | required | |
terminal_current_magnitude | array of float or null | amperes | one per terminal | null | |
terminal_active_power | array of float or null | watts | positive into the network | one per terminal | null |
source_active_injection | array of float | watts | positive into the network | one per source terminal | required |
generator_active_power | array of float | watts | positive is generation | one per generator terminal: generator table order, each generator’s terminal_map order, neutral included | required |
generator_coil_active_power | array of float or null | watts | positive is generation | one per generator coil: generator table order, each generator’s coil order | null |
objective | float | objective units | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | LinDist3FlowOpfInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
values | LinDist3FlowOpfValues | physical primal values | required | ||
objective | float | objective units | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | LinDist3FlowPfInstance | required | |||
termination | Termination | non-converged results have no limit_checks | required | ||
residuals | Residuals | required | |||
producer | string or null | null | |||
values | LinDist3FlowOpfValues | physical primal values | required | ||
limit_checks | array of LinDist3FlowLimitCheck | identities name retained line conductors | required |
Schema definition: LinDist3FlowLimitCheck.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
line | string | retained line identity | required | ||
conductor | nonnegative integer | position in that line’s conductor order | required | ||
kind | line_apparent_power, line_current_from, or line_current_to | determines whether value and limit are VA or A | required | ||
value | float | VA or A | nonnegative | finite | required |
limit | float | VA or A | positive | finite | required |
loading_ratio | float | per unit of limit | nonnegative | equals value / limit | required |
overloaded | bool | true exactly when loading_ratio > 1 | required | ||
constraint_enforced | bool | always false for fixed dispatch | required |
Schema definition: LinDist3FlowOpfValues.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
terminal_voltage_magnitude_squared | array of float | volts squared | nonnegative | topology node order | required |
line_active_power | array of float | watts | positive from parent to child | topology conductor order | required |
line_reactive_power | array of float | vars | positive from parent to child | topology conductor order | required |
generator_active_power | array of float | watts | positive is generation | generator table and channel order | required |
generator_reactive_power | array of float | vars | positive is generation | generator table and channel order | required |
source_active_power | array of float | watts | positive into the network | source table and terminal-map order | required |
source_reactive_power | array of float | vars | positive into the network | source table and terminal-map order | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
instance | AcScucInstance | required | |||
termination | Termination | required | |||
residuals | Residuals | required | |||
producer | string or null | null | |||
network_outputs | ScucNetworkOutputs | required | |||
device_outputs | ScucDeviceOutputs | required | |||
objective | float or null | dollars | null |
Schema definition: ScucNetworkOutputs.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
bus_vm | array of array of float | p.u. | one row per time point, one per bus | required | |
bus_va | array of array of float | radians | one per bus | required | |
shunt_step | array of array of integer | one per shunt | required | ||
ac_line_on_status | array of array of boolean | one per AC line | required | ||
transformer_tm | array of array of float | ratio | one per two winding transformer | required | |
transformer_ta | array of array of float | radians | one per two winding transformer | required | |
transformer_on_status | array of array of boolean | one per two winding transformer | required | ||
dc_line_pdc_fr | array of array of float | p.u. | positive from the from bus to the to bus | one per DC line | [] |
dc_line_qdc_fr | array of array of float | p.u. | positive is injected into the from bus | one per DC line | [] |
dc_line_qdc_to | array of array of float | p.u. | positive is injected into the to bus | one per DC line | [] |
Schema definition: ScucDeviceOutputs.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
on_status | array of array of boolean | one row per time point, one per device | required | ||
startup_status | array of array of boolean | required | |||
shutdown_status | array of array of boolean | required | |||
p_on | array of array of float | p.u. | positive is production for a producer, consumption for a consumer | required | |
q | array of array of float | p.u. | as p_on | required | |
p_reg_res_up | array of array of float | p.u. | nonnegative | required | |
p_reg_res_down | array of array of float | p.u. | nonnegative | required | |
p_syn_res | array of array of float | p.u. | nonnegative | required | |
p_nsyn_res | array of array of float | p.u. | nonnegative | required | |
p_ramp_res_up_online | array of array of float | p.u. | nonnegative | required | |
p_ramp_res_up_offline | array of array of float | p.u. | nonnegative | required | |
p_ramp_res_down_online | array of array of float | p.u. | nonnegative | required | |
p_ramp_res_down_offline | array of array of float | p.u. | nonnegative | required | |
q_res_up | array of array of float | p.u. | nonnegative | required | |
q_res_down | array of array of float | p.u. | nonnegative | required |
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.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
name | string | nonempty, bounded | required | ||
version | string | nonempty, bounded | required |
Schema definition: SourceDescriptor.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | unique among sources; spans and source map entries name it | required | ||
name | string | a file name, never a local file path | required | ||
byte_length | integer | bytes | every span into this source ends at or before it | required | |
format | string or null | a format token | null | ||
digest | Digest or null | null |
Schema definition: Digest.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
algorithm | token sha256 | required | |||
value | string | 64 lowercase hexadecimal characters | required |
Schema definition: SourceSpan.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
source | string | names a source id | required | ||
byte_start | integer | bytes into the retained source | byte_start <= byte_end <= byte_length | required | |
byte_end | integer | bytes into the retained source | half open | required |
Schema definition: SourceMapEntry.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
target | string | an RFC 6901 pointer into value.data | required | ||
relation | token exact, defaulted, inferred, converted_units, aggregated, split, synthetic, transformed, retained_extra | required | |||
spans | array of SourceSpan | empty only for defaulted, synthetic, and transformed | [] |
Schema definition: Diagnostic.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | unique among diagnostics; assigned d0, d1, … at serialization when a record has none | required | ||
code | string | NAMESPACE.SCOPE.SPECIFIC | required | ||
severity | token error, warning, remark, note | required | |||
message | string | one line | required | ||
target | string or null | an RFC 6901 pointer into value.data | null | ||
spans | array of SourceSpan | the records the finding is about | [] | ||
related | array of string | each names a diagnostic id in the document | [] | ||
details | object | {} | |||
suggested_action | string or null | null |
Schema definition: HistoryEntry.
| field | type | unit | sign | invariant | if absent |
|---|---|---|---|---|---|
id | string | unique among history | required | ||
kind | token parse, transform, edit, repair, solve | required | |||
name | string | the operation | required | ||
input_type | string or null | a structural type name | null | ||
output_type | string or null | a structural type name | null | ||
parameters | object | {} | |||
assumptions | array of string | [] | |||
losses | array 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 spelling | Current | Model value |
|---|---|---|
meta.$schema | meta.schema_version only | none; the $id goes in provenance |
bus v_min, v_max, vn_max | vpg_min, vpg_max, vng_max | v_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_max | windings[1].tap / windings[0].tap, extras["tap_ratio_min"], extras["tap_ratio_max"] |
voltage_source.cost, ibr.cost | energy_cost_rate | VoltageSource::energy_cost_rate, extras["energy_cost_rate"] |
prime_mover DSTATCOM | STATCOM | IbrPrimeMover::Statcom (a model Dstatcom writes as STATCOM, reported) |
q_unit, p_unit VA_FRACTION | PU | VaFraction |
dc_control droop | DROOP | the string in extras |
wire_data.kind overhead, cn_cable, ts_cable; line_geometry.earth_model modified_carson, full_carson, deri | UPPER_SNAKE | retained 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
| BMOPF | PowerIO | Note |
|---|---|---|
name | PioModule value name | |
meta.schema_version | identifies the document | The 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.$schema | identifies a document from an older draft | Removed 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.crs | MulticonductorNetwork::geo coordinate space | The 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.frequency | MulticonductorNetwork::base_frequency, Hz | Absent defaults to 60 with READ.BMOPF.VALUE_DEFAULTED. |
meta.* (the rest) | MulticonductorNetwork::extras["bmopf_meta"] | Re-emitted, except the three the writer owns. |
terminal_conventions | MulticonductorNetwork::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). |
extras | MulticonductorNetwork::extras["bmopf_extras"] | Re-emitted verbatim, minus the tables the reader types out of it. |
bus
DistBus, in MulticonductorNetwork::buses().
| BMOPF | PowerIO | Note |
|---|---|---|
terminal_names | terminals | Ordered; fixes every per-terminal order on this bus. |
perfectly_grounded_terminals | grounded | |
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_max | Phase 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_max | vpn_min, vpn_max | Per phase terminal, kept as arrays. |
vpp_min, vpp_max | vpp_min, vpp_max | Per ordered phase pair. |
vpos_min, vpos_max | vpos_min, vpos_max | Scalars. |
vneg_max, vzero_max | vneg_max, vzero_max | Magnitude caps; the lower bound is always zero. |
vng_max; read also as vn_max (older drafts) | vn_max | Neutral 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. |
geo | location and MulticonductorNetwork::geo | A 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, latitude | location and MulticonductorNetwork::geo | The 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.
| BMOPF | PowerIO | Note |
|---|---|---|
line.bus_from, line.bus_to | bus_from, bus_to | |
line.terminal_map_from, line.terminal_map_to | terminal_map_from, terminal_map_to | Position i of the from map fixes matrix index i. |
line.linecode | linecode | |
line.length | length, m | |
line.R_series_i_j, line.X_series_i_j | a synthesized DistLineCode named after the line, ohm per metre at unit length | The 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_j | the same synthesized line code’s g_from, b_from, g_to, b_to | |
line.i_max, line.s_max | i_max, s_max | One 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.geo | route | A 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_j | r_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_j | g_from, b_from, g_to, b_to, siemens per metre | Half the total shunt at each end. |
linecode.i_max, linecode.s_max | i_max, s_max | Per conductor, in matrix row order, applied at both ends. A write drops an s_max of another length. |
linecode.source | source | |
linecode.line_geometry, linecode.derivation | extras | Schema 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.
| BMOPF | PowerIO | Note |
|---|---|---|
<element>.geo Point | a 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 LineString | the same, at the midpoint of the LineString’s two end positions | Reported once with READ.BMOPF.VALUE_COLLAPSED; a write states that Point. |
bbox on any geo | not read | Never 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.
| BMOPF | PowerIO | Note |
|---|---|---|
bus_from, bus_to, terminal_map_from, terminal_map_to | the same names | |
open_switch | open | |
i_max | i_max | Per 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.
| BMOPF | PowerIO | Note |
|---|---|---|
bus, terminal_map, configuration | the same names | configuration reads case-insensitively; an unrecognized value reads as WYE with READ.BMOPF.VALUE_UNSUPPORTED. |
p_nom, q_nom | p_nom, q_nom, W and var | |
model | the DistLoadVoltageModel variant | CONSTANT_POWER, CONSTANT_CURRENT, CONSTANT_IMPEDANCE, ZIP, EXPONENTIAL. |
v_nom | the variant’s v_nom | |
alpha_z, alpha_i, alpha_p, beta_z, beta_i, beta_p | the Zip variant’s fields | The three active fractions sum to one, and so do the three reactive. |
gamma_p, gamma_q | the Exponential variant’s fields |
generator
DistGenerator. Arrays are per phase conductor; WYE is the only
configuration the specification supports.
| BMOPF | PowerIO | Note |
|---|---|---|
bus, terminal_map, configuration | the same names | |
p_min, p_max, q_min, q_max | the same names, W and var | When 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_max | s_max, VA | Bounds the sum of squares of that phase’s active and reactive power. |
i_max | i_max, A | Per phase, with an optional trailing entry bounding the neutral return current. |
energy_cost_rate, or the deprecated cost | cost, currency per kWh | Kept 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.
| BMOPF | PowerIO | Note |
|---|---|---|
bus, terminal_map | the same names | |
v_magnitude | v_magnitude, V | Per terminal, phase to ground; a grounded terminal states zero. |
v_angle | v_angle, rad | Per terminal. |
energy_cost_rate | energy_cost_rate, currency per kWh | One 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_max | extras | Retained 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.
| BMOPF | PowerIO | Note |
|---|---|---|
shunt.bus, shunt.terminal_map | the same names | |
shunt.G_i_j, shunt.B_i_j | g, b, total siemens in conductor order | |
capacitor.bus, capacitor.terminal_map, capacitor.configuration | the same names for a scalar bank; bus, terminal order and matrix incidence for an array | |
capacitor.q_rated | Scalar: q_rated, var; array: terminal shunt b, siemens | A scalar rates the whole bank. Array entries rate individual WYE coils or DELTA phase pairs, in var. |
capacitor.v_nom | Scalar: 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.
| BMOPF | PowerIO | Note |
|---|---|---|
bus_from, bus_to | windings[0].bus, windings[1].bus | |
terminal_map_from, terminal_map_to | the corresponding terminal_map | center_tap expands the three to-side terminals into two windings. |
v_nom_from, v_nom_to | windings[k].v_ref, V | For center_tap, v_nom_to is the per leg voltage. |
s_rating | windings[k].s_rating, VA | |
r_series_from, r_series_to | windings[k].r_pct, percent of that winding’s own base | The base is n_phases * v_ref^2 / s_rating. |
x_series_from, x_series_to | xsc_pct, percent | The 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_pct | The lumped wye-side spelling; the delta winding is lossless in this model. |
tap_ratio; read also as tap | windings[0].tap / windings[1].tap | The multiplier on the nameplate turns ratio. |
tap_ratio_min, tap_ratio_max | extras | Bounds have no typed winding slot. |
r_neutral_from, x_neutral_from | windings[0].r_neutral, x_neutral, ohm | The winding’s own neutral to earth branch. |
r_neutral_to, x_neutral_to | windings[1].r_neutral, x_neutral | |
g_no_load, b_no_load | extras | The magnetising branch has no typed slot. |
i_max_from, i_max_to | extras | Per winding conductor of that side, in that side’s own amperes. |
n_winding.windings[] | one DistWinding each | bus, 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_sc | xsc_pct, ordered 12, 13, ..., 1n, 23, ..., (n-1)n | Keyed i_j with i < j in BMOPF, all referred to winding 1. |
single_phase_autotransformer, open_delta_regulator | windings 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.
| BMOPF | PowerIO | Note |
|---|---|---|
bus, terminal_map | the same names | |
topology | topology: SINGLE_PHASE, THREE_LEG, FOUR_LEG | |
prime_mover | prime_mover: PV, BATTERY, GENERIC, STATCOM | DSTATCOM, removed from the schema, reads as STATCOM. |
s_max | s_max, VA per phase | |
i_max | i_max, A per conductor | |
p_avail | p_avail, W | |
p_min, p_max, q_min, q_max | the same names, per phase | |
control_profile | control_profile, an id | |
voltage_aggregation | voltage_aggregation: PER_PHASE, AVERAGE | |
energy_cost_rate; read also as cost | extras["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_max | extras | The DC coupling fields; retained, not typed. |
r_filter, x_filter, b_filter_shunt, grid_forming, v_ref_internal | extras | Retained, not typed. |
control_profile.power_factor.pf | PowerFactorControl | |
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.
| Family | The BMOPF fields it activates |
|---|---|
terminal_voltage_bounds | bus.vpg_min, vpg_max, vpn_min, vpn_max, vpp_min, vpp_max, vpos_min, vpos_max, vneg_max, vzero_max, vng_max |
conductor_limits | line.i_max, line.s_max, linecode.i_max, linecode.s_max, switch.i_max, transformer.i_max_from, transformer.i_max_to |
generator_capability | generator.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.
McAcOpfSolution | Unit and order |
|---|---|
terminal_voltage_magnitude | V, resolved terminal order |
terminal_voltage_angle | rad, resolved terminal order |
terminal_current_magnitude | A, resolved terminal order, when the solver reports it |
terminal_active_power | W, resolved terminal order, when the solver reports it |
source_active_injection | W, per source terminal |
generator_active_power | W, per generator terminal: generator table order with each generator’s terminal map order, neutral included |
generator_coil_active_power | W, 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 |
objective | the optimised objective value |
termination, residuals, producer | how 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 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
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 thesymmetricheader and store the lower triangle only. Vectors arearray real general, one value per line. - Index base.
.mtxrow and column indices are 1-based, as Matrix Market requires.reference_busesin 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
PerUnitdivides power bybase_mvaand 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}\).Nativekeeps 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-costto fill the missing rows for a feasibility test. - Reference buses.
reference_busesin 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.mtxholds \(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 inshift.mtx. The default,SeriesSusceptance, uses \(b_e = x/(r^2 + x^2)\) plus the phase shift terms, with no tap scaling.TapAdjustedReactanceuses \(b_e = 1/(x \tau)\) plusp_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
| file | shape | what |
|---|---|---|
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, andn_grounded_buses.index_base:dense = 0for manifest bus, branch, generator, and reference indices;matrix_market = 1for.mtxcoordinates.branch_susceptance_formula,units,build_options, andzero_impedance.build_optionsrecordsskip_zero_impedance,synthesize_unrated_limits,angle_difference_bounds(power_models_pad,shift_centered_pad,stated, ornone), andhvdc_treatment(fixed_injectionorignore). 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 withname,file,kind,rows,cols,index_space, andunits.
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
- Triage by severity: crash, silent value change, silent drop, undeclared loss, miscounted warning, declared loss confirmed.
- Restate the finding as a falsifiable sentence about the format, using the findings file alone.
- 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. - 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.baselinewithPOWERIO_MATRIX_BLESS=1and check each changed line. - 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.
| tier | command | what it answers |
|---|---|---|
| Rust microbenchmarks | cargo bench -p powerio-tx --bench parse and --bench large_case | parser, writer, and PowerWorld reader timing inside one process, and the PSS/E reader and indexed view on a continental-size case |
| Matrix microbenchmarks | cargo bench -p powerio-matrix --bench matrix | sparse matrix, DC OPF component, and dense sensitivity builder timing after parse/indexing |
| Cross tool parser and matrix comparison | julia --project=evals/validation evals/performance/bench_julia.jl --json | powerio 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 size | two cargo build -p powerio-capi --release builds plus stat | binary 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 surface | extra gates |
|---|---|
| parser or writer semantics | bash evals/validation/run_validation.sh; format round trip tests; affected cargo +nightly fuzz run <target> -- -runs=1 harnesses |
| MG-RAVENS or PMD MATHEMATICAL | the 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 fields | bash evals/validation/run_rich_validation.sh |
| matrix calculations | cargo test -p powerio-matrix; cargo bench -p powerio-matrix --bench matrix |
| problem instances or DC OPF bundles | cargo test -p powerio-prob --no-default-features; cargo test -p powerio --features matrix |
SINCAL readers, writers, or the sincal feature | cargo 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 reader | PowerWorld parser tests plus `cargo bench -p powerio-tx –bench parse – “parse_aux_ |
| C ABI | scripts/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 extras | maturin build --release --out /tmp/powerio-wheel-check; inspect wheel METADATA |
| Julia binding compatibility | build powerio-capi --features matrix,gridfm,dist,prob, then run PowerIO.jl tests with POWERIO_CAPI |
| shared surface with PowerIO.jl | push a same-named PowerIO.jl companion branch; the tandem CI job tests against it |
| public Rust API | bash scripts/check-semver.sh (needs cargo install cargo-semver-checks --locked) |
| CLI behavior | cargo test -p powerio-cli --test cli |
| documentation or website | mdbook 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.