Module format 

Readers and writers for supported case formats, all meeting at BalancedNetwork.

Each format module owns its reader and/or writer: MATPOWER .m, PowerModels JSON, PSS/E .raw, PowerWorld .aux, egret ModelData JSON, pandapower JSON, PyPSA CSV folders, PSLF .epc, GO Challenge 3 JSON, and Surge JSON, and DeepMind OPFData JSON. PowerWorld .pwb cases, GO Challenge 3 and OPFData JSON canonical output, and PowerWorld .pwd displays are read only. Case input and output formats meet here, so adding a writable format is one module plus one hub registration. parse_file reads BalancedNetwork cases, detecting the format from its extension; parse_display_file reads display artifacts such as PowerWorld .pwd. write_as serializes a BalancedNetwork to text targets. Directory formats, such as PyPSA CSV folders, use explicit filesystem helpers. Non-finite numeric values, such as MATPOWER Inf/NaN angle limits, are written as JSON null.

Fidelity behavior

Conversion is two-tier:

• Same format writes return the original text. A reader keeps its source text (see BalancedNetwork), so writing back to the same format returns every field, comment, and numeric token.
• Cross-format keeps maximal fidelity with itemized loss. Whatever the target format cannot represent is reported in the Conversion warnings, never dropped silently. On the read side, readers itemize what they ignore in Parsed warnings.

Modules

powerworld

Read and write PowerWorld auxiliary .aux files.

routing

Shared format alias and JSON shape routing for the powerio crate.

Structs

Conversion

Output of a conversion: the serialized text plus any fidelity warnings: data the target can’t represent, defaults synthesized, or blocks mapped best effort. An empty warnings means a faithful conversion. For convert_file and convert_str, warnings carries the read side (Parsed warnings) too, ahead of the write side.

Parsed

Output of a parse: the network plus the reader’s fidelity warnings, tables and columns the model cannot carry, reported instead of dropped silently. Empty for readers that don’t report read warnings (currently readers that do not need to reduce any source fields).

PwdDisplay

Decoded PowerWorld display file content.

PwdSubstation

One substation symbol from a display file: the identity row joined with its drawing record, in identity table (display) order. x and y are diagram coordinates as stored, y north positive (see the module docs).

PypsaCsvOutputs

WriteOptions

Optional write-time policies layered on top of the neutral BalancedNetwork.

Enums

DisplayData

Output of a display parse. PowerWorld .pwd produces DisplayData::PowerWorld; a geographic sidecar produces DisplayData::Geo.

DisplayFormat

A display artifact format. These files are not power network cases and do not parse to BalancedNetwork.

SourceDocument

A format’s source document, parsed once by the reader and handed forward so downstream adapters derive their data from the same parse instead of reparsing the retained source text. Today that is the GOC3 document, which the operating point extractor in powerio-pkg consumes.

TargetFormat

A target interchange format. See write_as.

Functions

convert_file

Convert a case file to to, optionally forcing the source format with from.

convert_file_with_options

Convert a case file with write-time cost policies.

convert_str

Convert in-memory case text of the named format (see target_format_from_name) to to.

convert_str_with_options

Convert in-memory case text with write-time cost policies.

display_format_from_name

Map a display format name to a DisplayFormat, or None if unrecognized. Accepts pwd, powerworld-pwd, and powerworld-display; geojson, geo-json, and geo name the geographic layer.

parse_bytes

Parse in-memory case bytes of the named format. Accepts every name parse_str does, plus pwb: PowerWorld binary has no text form, so this is the only in-memory entry point that reaches it. Text formats decode as UTF-8 and take the parse_str path from there.

parse_bytes_with_name

parse_bytes with a name hint, as parse_str_with_name is to parse_str.

parse_deepmind_opfdata_json

Parse one raw FullTop or N-1 DeepMind OPFData JSON document as a solved snapshot. The reader does not assume a case name or fixed element counts.

parse_display_bytes

Parse display bytes in the named display format.

parse_display_file

Parse the display file at path, choosing the reader from from or, when None, from the extension. A .pwd extension selects PowerWorld display data.

parse_egret_json

Parse egret ModelData JSON into a BalancedNetwork.

parse_file

Parse the case file at path, choosing the reader from from (the target_format_from_name names plus pypsa-csv/pypsa, pwb, pslf, and epc) or, when None, from the path: a directory containing network.csv parses as a PyPSA CSV folder (any other directory fails: Error::UnknownFormat when its name maps to no extension, the I/O error otherwise), and a file maps by extension (m/json/raw/aux/pwb/epc), case insensitively (issue #97: .RAW is as common as .raw in the wild). A .json file is classified by top level shape markers: pandapower ("_class": "pandapowerNet"), egret (elements and system), GO Challenge 3 (network plus time_series_input/reliability), Surge JSON (format: "surge-json"), OPFData (grid, solution, and metadata), powerio-json (buses plus network keys), and PowerModels JSON (baseMVA, branch, gen, or gencost). JSON matching distribution markers, ambiguous markers, or no known markers returns Error::UnknownFormat. Pass from to force a transmission format. PowerWorld .pwb is a binary read only format with no retained source; PSLF .epc is text and has a writer. Returns Parsed: the network plus the reader’s fidelity warnings.

parse_goc3_json

Parse a GO Challenge 3 JSON input file.

parse_matpower

Parse the MATPOWER case in content into a BalancedNetwork.

parse_matpower_file

Parse the MATPOWER case at path, using the file stem as the network name.

parse_pandapower_json

Parse pandapower pandapowerNet JSON content. Returns Parsed: the network plus the reader’s fidelity warnings.

parse_powermodels_json

Parse PowerModels.jl network data JSON into a BalancedNetwork. Loads and shunts are read as separate elements and the raw text is retained, so writing back to PowerModels JSON is a byte-exact echo. per_unit = true input (powerio’s own output, and PowerModels’ own export) is converted to the neutral MW/degree convention (powers ×baseMVA, angles to degrees, cost coefficients un-scaled), following PowerModels’ own exceptions (storage ps/qs stay raw, dcline pt/qf/qt flip sign); per_unit = false is read as-is.

parse_powerworld

Parse a PowerWorld .aux into a BalancedNetwork, reading the Bus/Load/Shunt/ Gen/Branch DATA blocks by their declared field lists.

parse_pslf

Parse a PSLF .epc case into a BalancedNetwork.

parse_psse

Parse a PSS/E .raw (revisions 33-35) into a BalancedNetwork. Reads bus/load/ fixed-shunt/generator/branch/2- and 3-winding transformer; skips the advanced sections.

parse_str

Parse in-memory case text of the named format (see target_format_from_name). Returns Parsed: the network plus the reader’s fidelity warnings.

parse_str_with_name

parse_str with a name hint for formats that carry no name of their own (the role the file stem plays in parse_file). Lets a caller that already read a file’s text keep the stem-derived case name without going back through the filesystem.

parse_surge_json

read_pypsa_csv_folder

Read a PyPSA CSV folder at path. Returns Parsed: the network plus the reader’s fidelity warnings.

target_format_from_name

Map a format name (with the common aliases) to a TargetFormat, or None if unrecognized. Accepts matpower/m, powermodels-json/powermodels/pm, egret-json/egret, pandapower-json/pandapower/pp, psse/raw, powerworld/aux, pslf/epc, goc3-json/goc3, and surge-json/surge, and opfdata-json/opfdata/gridopt. The powerio-json/powerio/json names remain compatibility aliases for the model JSON methods. Case-insensitive. The one place the bindings (Python, C ABI) share, so a new text format means one new arm here, not three. PyPSA CSV folders, GridFM datasets, and PowerWorld .pwb are directory or read only inputs with no text target; they are routed by crate::format::routing.

write_as

Convert a BalancedNetwork to format. Writing back to the source format returns the retained source text; otherwise the network is serialized into the target.

write_as_with_options

Convert a BalancedNetwork with write-time cost policies. The old write_as behavior is preserved when options is default.

write_dir

Write net into out_dir as the named directory format. This function dispatches directory format names for the bindings. PyPSA CSV (pypsa-csv/pypsa) is the one such format today; a text format name is rejected by name, pointing at write_as. Returns the write’s fidelity warnings.

write_egret_json

write_matpower

Serialize net to MATPOWER .m text. Echoes the retained source verbatim when net came from MATPOWER; otherwise emits canonical .m.

write_pandapower_json

write_powermodels_json

write_powerworld

write_pslf

Serialize net to PSLF .epc text.

write_psse

Serialize net to PSS/E .raw at the default revision (33).

write_psse_rev

Serialize net to PSS/E .raw at rev (33, 34, or 35).

write_pypsa_csv_folder

write_surge_json