Module format 

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

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. PowerWorld .pwb cases, GO Challenge 3 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 Network cases, detecting the format from its extension; parse_display_file reads display artifacts such as PowerWorld .pwd. write_as serializes a Network 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 Network), 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

goc3_bridge

Document-walking helpers shared with powerio-pkg’s operating point extractor, which must interpret a GOC3 document exactly as this parser does: same section ordering, same device row assignment, same cost mapping. Hidden: not part of the public format API.

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

Enums

DisplayData

Output of a display parse. v0.2.2 supports PowerWorld .pwd; future display formats can add variants without changing the parse entry point.

DisplayFormat

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

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.

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. v0.2.2 infers PowerWorld .pwd.

parse_egret_json

Parse egret ModelData JSON into a Network.

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"), 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 Network.

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 Network. Loads and shunts are read as first-class 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 Network, reading the Bus/Load/Shunt/ Gen/Branch DATA blocks by their declared field lists.

parse_pslf

Parse a PSLF .epc case into a Network.

parse_psse

Parse a PSS/E .raw (revisions 33-35) into a Network. 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_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, powerio-json/powerio/json (the canonical snapshot; plain json means this one, the foreign JSON dialects are namespaced), pslf/epc, goc3-json/goc3, and surge-json/surge. 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 Network 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 Network with write-time cost policies. The old write_as behavior is preserved when options is default.

write_dir

Write net into the directory out_dir as the named directory-shaped format: the directory sibling of write_as, sharing its name-dispatch role 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