Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.