Crate powerio_capi 

C ABI for powerio: ABI v4.

Parse any supported power system case format into an opaque handle, query it, convert it to another format, and pull out the numeric tables a downstream solver needs to assemble matrices. Every entry point is extern "C", catches panics at the boundary, and returns error text into a caller-provided buffer.

The surface follows a fixed grammar, written out in the header preamble (include/powerio.h, generated by cbindgen, never hand-edit):

• Verb-led names are operations and the verb fixes the return family: parse/read/normalize return a new handle, write has a filesystem effect, convert transcodes without keeping a handle, free destroys.
• to_ marks a representation change of the same network; the target is a format string (pio_to_format) unless the output type differs (pio_to_arrow fills Arrow C Data Interface structs).
• Format names never appear in symbols: formats are strings, so a new format never changes this ABI. The canonical snapshot is the powerio-json format name.
• Array extractors share the cap/count convention: write up to cap values, return the total available, NULL out is a pure count query.
• Vocabulary: a bus is a named connection point (this surface is bus granular); a node is one conductor’s point at a bus, reserved for the multiconductor surface; a branch is any two-terminal series element, lines and transformers alike.

Structs

PioDistNetwork

Opaque parsed distribution network handle (the multiconductor wire-coordinate model). Distinct from PioNetwork (the positive-sequence transmission model); none of the pio_n_*/extractor functions accept it. Only built with the dist cargo feature.

PioNetwork

Opaque parsed network handle. Carries the parsed Network, the IndexCore derived from it once at parse time (so every indexed query reuses the same bus-id map and per-bus aggregates instead of rebuilding them), and the reader’s fidelity warnings (pio_warnings).

PioPackage

Opaque .pio.json compiler package handle. A package owns one powerio_pkg::NetworkPackage, which wraps either a balanced PioNetwork payload or a multiconductor PioDistNetwork payload.

Constants

PIO_ABI_VERSION

ABI version of this C interface. Bump on any breaking change to an existing pio_* signature or to the powerio-json snapshot schema (new additive symbols don’t require a bump). A consumer compares pio_abi_version against the value it was built against (the PIO_ABI_VERSION macro in powerio.h) and refuses a mismatched library instead of calling in blind.

PIO_ARROW_TABLE_BRANCH

PIO_ARROW_TABLE_BUS

Table selectors for pio_to_arrow; the C header mirrors these as PIO_ARROW_TABLE_*.

PIO_ARROW_TABLE_GEN

PIO_ARROW_TABLE_LOAD

PIO_ARROW_TABLE_SHUNT

PIO_ARROW_TABLE_SOLVER_ARC

PIO_ARROW_TABLE_SOLVER_BRANCH

PIO_ARROW_TABLE_SOLVER_BUS

PIO_ARROW_TABLE_SOLVER_GEN

PIO_ARROW_TABLE_SOLVER_HVDC

PIO_ARROW_TABLE_SOLVER_LOAD

PIO_ARROW_TABLE_SOLVER_SHUNT

PIO_ARROW_TABLE_SOLVER_STORAGE

PIO_ARROW_TABLE_SOLVER_SWITCH

PIO_ARROW_TABLE_SWITCH

PIO_DIST_ABI_VERSION

ABI version of the optional pio_dist_* C surface. This is separate from PIO_ABI_VERSION so distribution C entry points can evolve without forcing a core ABI bump. Version 1 is the supported dist surface with conversion order (input, from, to, ...).

PIO_ERRBUF_MIN

A comfortable error-buffer size: pass a char[PIO_ERRBUF_MIN] to any errbuf/warnbuf parameter and a message always fits without truncation.

Functions

pio_abi_version

The ABI version the library was built with (see PIO_ABI_VERSION). Lets a consumer detect a stale or incompatible library at load time. Infallible.

pio_base_mva^⚠

pio_branch_charging^⚠

Write the branch terminal charging table as parallel arrays, each up to cap entries, and return the total branch count. Columns are p.u.

pio_branches^⚠

Write the branch table as parallel arrays, each up to cap entries, and return the total branch count. A branch is any two-terminal series element lines and transformers alike (a transformer has tap != 0). from/to are 1-based bus IDS (the pio_bus_ids id space, not dense indices); map them to dense matrix rows with the pio_bus_ids ordering. Any output pointer may be NULL to skip that column; all NULL is the count query.

pio_bus_demand^⚠

Write the per-bus demand aggregates (active pd, reactive qd, summed over each bus’s loads, dense pio_bus_ids order), each up to cap entries, and return the total bus count. Either pointer may be NULL.

pio_bus_ids^⚠

Write the 1-based external bus ids, in dense order, into out, up to cap entries, and return the total bus count. This ordering DEFINES the dense index space every other per-bus array shares. Call once with (NULL, 0) to size, allocate, then call again to fill. Ids are int64 in 1..2^63-1 (a v4 invariant); a source id that is a string or exceeds that range is mapped to dense int64 at read, never passed through raw.

pio_bus_shunt^⚠

Write the per-bus shunt aggregates (conductance gs, susceptance bs, dense pio_bus_ids order), each up to cap entries, and return the total bus count. Either pointer may be NULL.

pio_convert_file^⚠

Convert the case file at path from format from (NULL to infer from the path, as pio_parse_file) to format to, without keeping a handle. Returns the converted text as an owned C string (free with pio_string_free), NULL on error. Fidelity warnings, read side first, are written \n-joined into warnbuf.

pio_convert_str^⚠

Convert in-memory case text from format from (required; there is no path to infer from) to format to, without keeping a handle: the in-memory sibling of pio_convert_file. Returns the converted text as an owned C string (free with pio_string_free), NULL on error. Fidelity warnings, read side first, are written \n-joined into warnbuf.

pio_dist_abi_version

The ABI version of the optional pio_dist_* surface. Only linked when the dist feature is compiled in; probe that first with pio_has_feature("dist") if loading dynamically.

pio_dist_convert_file^⚠

Convert distribution case path from optional source format from to format to; see pio_dist_parse_file for the inference rules. Returns the converted text as an owned C string (free with pio_string_free), NULL on error. The warnings written \n-joined into warnbuf carry both the parse warnings and the writer’s fidelity losses (there is no handle to query them).

pio_dist_convert_str^⚠

Convert in-memory distribution case text of format from to format to (both required; dss, pmd, or bmopf). The parameter order is input, source, target, matching pio_dist_convert_file. Returns the converted text as an owned C string (free with pio_string_free), NULL on error. The warnings written \n-joined into warnbuf carry both the parse warnings and the writer’s fidelity losses (there is no handle to query them).

pio_dist_network_free^⚠

Free a distribution network handle from pio_dist_parse_file or pio_dist_parse_str. NULL is a no-op; free exactly once.

pio_dist_parse_file^⚠

Parse a distribution case file into a PioDistNetwork handle. The format comes from from if non-NULL (dss, pmd, or bmopf), else from the file itself: .dss is OpenDSS, and .json holding the ENGINEERING data_model key is PMD JSON, otherwise BMOPF JSON. Returns NULL on error and writes the message into errbuf. Free the handle with pio_dist_network_free.

pio_dist_parse_str^⚠

Parse in-memory distribution case text of the named format (dss, pmd, or bmopf; required, since there is no path to infer from). An OpenDSS Redirect/Compile in text resolves against the current working directory. Returns NULL on error and writes the message into errbuf. Free the handle with pio_dist_network_free.

pio_dist_to_format^⚠

Serialize net to distribution format to (dss, pmd, or bmopf). Writing back to the format the handle was parsed from echoes the source text byte for byte; a cross-format write reports every fidelity loss in warnbuf (\n-joined). Returns the text as an owned C string (free with pio_string_free), NULL on error.

pio_dist_warnings^⚠

Parse warnings retained on the handle (everything the reader could not represent or had to assume), \n-joined and written into the caller warnbuf (truncated to fit, always NUL-terminated). Returns the total byte length of the joined message; call with NULL/0 to size first, then fill — the same idiom as pio_warnings. Returns 0 for a NULL handle.

pio_gens^⚠

Write the generator table as parallel arrays, each up to cap entries, and return the total generator count. bus is the 1-based bus id (the pio_bus_ids id space). Any output pointer may be NULL to skip.

pio_has_feature^⚠

Whether an optional build feature is compiled in: pass "arrow", "gridfm", "dist", or "pkg". Returns 1 if present, 0 otherwise (and 0 for a NULL or unknown name). The optional surfaces (pio_to_arrow, the pio_read_dir/ gridfm path, the pio_dist_* block, and the pio_package_* block) are only linked when their feature is built, so a consumer that loaded the library at runtime probes for them here instead of resolving symbols blind. Feature names are strings like format names, so a new feature never changes this signature. Infallible.

pio_is_radial^⚠

1 if the in-service topology is radial (every island a tree), else 0.

pio_n_branches^⚠

pio_n_buses^⚠

pio_n_gens^⚠

pio_n_islands^⚠

Number of islands: connected components of the in-service topology.

pio_n_switches^⚠

pio_network_free^⚠

Free a network handle from pio_parse_file, pio_parse_str, pio_read_dir, or pio_normalize.

pio_normalize^⚠

Normalize net into a NEW network handle: per unit, radians, out-of-service filtered, source bus ids preserved, bus types canonicalized (see Network::to_normalized). A value transform, not a serialization, hence the verb, while the to_* family re-encodes unchanged data. The result is independent of net; free both with pio_network_free. Every extractor and serializer works on it unchanged (the handle is per unit, not MW). Returns NULL on error (no reference bus can be chosen, or a non-positive base MVA) and writes the message into errbuf.

pio_package_diagnostics_json^⚠

Return the package structured diagnostics array as JSON. The returned string is owned by the library; free it with pio_string_free.

pio_package_free^⚠

Free a package handle returned by pio_package_*. NULL is a no-op; free exactly once.

pio_package_from_balanced_network^⚠

Wrap a balanced PioNetwork handle in a .pio.json package. The C handle name is historical; the payload is powerio::BalancedNetwork. include_solver_metadata != 0 attaches compact normalized solver table metadata.

pio_package_from_multiconductor_network^⚠

Wrap a multiconductor PioDistNetwork handle in a .pio.json package. The C handle name is historical; the payload is powerio_dist::MulticonductorNetwork.

pio_package_lower_multiconductor_to_balanced^⚠

Lower a multiconductor package to a new balanced package. Call pio_package_multiconductor_to_balanced_preflight_json first when the caller needs structured blockers for unsupported inputs. base_mva is the three phase system power base used for the balanced per-unit projection.

pio_package_materialize_operating_point^⚠

Materialize one operating point into a new static package.

pio_package_multiconductor_to_balanced_preflight_json^⚠

Return the multiconductor-to-balanced lowering preflight report as JSON. base_mva is the three phase system power base used for the balanced per-unit projection. Returns NULL if the package is not multiconductor.

pio_package_operating_points_json^⚠

Return the package operating point series as JSON, or null when absent. The returned string is owned by the library; free it with pio_string_free.

pio_package_parse_file^⚠

Parse a .pio.json package file into an opaque package handle. This reads only the package envelope; case format names still enter through pio_parse_file / pio_dist_parse_file and package constructors. Returns NULL on error and writes the message into errbuf. Free the handle with pio_package_free.

pio_package_parse_str^⚠

Parse in-memory .pio.json text into an opaque package handle. Returns NULL on error and writes the message into errbuf. Free the handle with pio_package_free.

pio_package_to_json^⚠

Serialize a package handle to compact .pio.json. Returns an owned C string (free with pio_string_free) or NULL on error.

pio_package_validate^⚠

Run the package semantic validation profile in place. Returns 0 on success, -1 on error.

pio_package_validation_json^⚠

Return the package validation summary as JSON. The returned string is owned by the library; free it with pio_string_free.

pio_parse_file^⚠

Parse path (format from extension, or from if non-NULL) into a network handle. from accepts the pio_parse_str format names plus pypsa-csv/pypsa, goc3-json/goc3, surge-json/surge, and pwb; that includes pslf/epc, and .epc is inferred by extension. A PyPSA CSV folder is a directory, so it can only enter through this function, with from = "pypsa-csv" (or NULL when the directory holds a network.csv). Read fidelity warnings attach to the handle (pio_warnings). Returns NULL on error and writes the message into errbuf. Free the handle with pio_network_free.

pio_parse_str^⚠

Parse in-memory case text of the named format into a network handle. Unlike pio_parse_file there is no path to infer from, so format is required: one of matpower/m, powermodels/pm, egret, pandapower-json/pandapower/pp, psse/raw, powerworld/aux, pslf/epc, goc3-json/goc3, surge-json/surge, or powerio-json/json (the canonical snapshot pio_to_format writes, validated on read). PyPSA CSV folders are directories, not text; parse them with pio_parse_file and from = "pypsa-csv". Read fidelity warnings attach to the handle (pio_warnings). Returns NULL on error and writes the message into errbuf. Free the handle with pio_network_free.

pio_read_dir^⚠

Read one scenario of a dataset directory in the named from format into a network handle: the directory sibling of pio_parse_file. gridfm (the gridfm-datakit Parquet layout; dir resolves leniently: the raw/ leaf, a <case>/ directory with a raw/ child, or a parent holding exactly one such case) is the one dataset format today. scenario selects within a multi-scenario dataset (pio_scenario_ids enumerates them); formats without scenarios take 0. Read fidelity warnings attach to the handle (pio_warnings). Returns NULL on error and writes the message into errbuf. Free the handle with pio_network_free. Built --features gridfm.

pio_ref_bus_index^⚠

Dense [0, n) index of the single reference (slack) bus, or -1 if not exactly one. An INDEX into the pio_bus_ids ordering, not a bus id; pio_branches from/to carry ids, so the unit is in the name. A network may carry several references (one per island, or a normalized case that kept the file’s multiple REF buses); pio_ref_bus_indices reads them all, and its count (NULL out) tells zero from many.

pio_ref_bus_indices^⚠

Write the dense [0, n) indices of the reference (slack) buses, ascending, into out, up to cap entries, and return the total count: the cap/count convention of pio_bus_ids. 0 means none; > 1 means one reference per island or several fixed references in one island (a normalized case always reports >= 1).

pio_scenario_ids^⚠

Write the distinct scenario ids (ascending) of the dataset directory dir in the named from format into out, up to cap entries, and return the total count: the cap/count convention of pio_bus_ids. gridfm is the one dataset format today. Returns -1 on error and writes the message into errbuf (unlike the handle extractors, this reads the filesystem and can fail). Built --features gridfm.

pio_string_free^⚠

Free a string returned by pio_to_format, pio_convert_file, or pio_convert_str.

pio_switches^⚠

Write the switch table as parallel arrays, each up to cap entries, and return the total switch count. from/to are external bus ids.

pio_to_arrow^⚠

Export one network table over the Arrow C Data Interface: the to_ conversion whose output type is Arrow structs rather than a string, and the bulk plane this ABI evolves on. Tables 0..5 are raw network tables; tables 6 and up are normalized solver tables with per unit/radian values and dense zero based row ids. New or richer columns arrive in the Arrow schema, leaving the C signatures fixed.

pio_to_format^⚠

Serialize net to the named format to: the one text serializer; every format is named by a string. Accepts the pio_parse_str names: matpower is a byte-exact echo when the handle was parsed from MATPOWER, and powerio-json is the canonical snapshot (validated by pio_parse_str on the way back; the retained source text is the one field it omits). The snapshot is lossless except for a non-finite f64 (Inf/NaN), which JSON cannot represent: it is written as null, named in a fidelity warning, and then fails to read back; pass warnbuf to detect it.

pio_version

The crate version string (a semver string), 'static and NUL-terminated. Do NOT free it. Informational; pair it with pio_abi_version for the actual compatibility check.

pio_warnings^⚠

The fidelity warnings attached to the handle at construction (by whichever of pio_parse_file, pio_parse_str, pio_read_dir, or pio_normalize built it), \n-joined into warnbuf (truncated to fit on a UTF-8 boundary; NULL/0 to skip). Returns the byte length of the full joined text, excluding the NUL; call once with (NULL, 0) to size, then pass a char[len + 1]. 0 means no warnings (or a NULL handle); readers that are total attach none.

pio_write_dir^⚠

Write net into the directory out_dir as the named directory-shaped format to: the directory sibling of pio_to_format. PyPSA CSV (pypsa-csv/pypsa) is the one such format today; a text format name is an error pointing back at pio_to_format. Returns 0 on success and -1 on error (message into errbuf). Fidelity warnings, if any, are written \n-joined into warnbuf.