Crate powerio_capi

Expand description

C ABI for powerio.

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. Strings handed back are owned by the library; free them with pio_string_free. Array extractors fill caller-allocated buffers (length = the matching pio_n_* count); pass NULL to skip one.

Naming: every symbol is prefixed pio_. The header is include/powerio.h.

Structs§

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 nodal aggregates instead of rebuilding them), and the reader’s fidelity warnings (pio_parse_warnings).

Constants§

PIO_ABI_VERSION: ABI version of this C interface. Bump on any breaking change to an existing pio_* signature or to the JSON transport 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_export_arrow; the C header mirrors these as PIO_ARROW_TABLE_*.
PIO_ARROW_TABLE_GEN
PIO_ARROW_TABLE_LOAD
PIO_ARROW_TABLE_SHUNT
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_branches^⚠: Fill the branch tables (each length pio_n_branches). from/to are the 1-based bus ids (the same id space as pio_bus_ids, not dense indices); map them to dense matrix rows with the pio_bus_ids ordering. Any pointer may be NULL to skip.
pio_bus_ids^⚠: Fill out (length pio_n_buses) with the 1-based bus ids in dense order.
pio_convert_file^⚠: Convert path to format to (optionally forcing the source via from). Returns the converted text as an owned C string (free with pio_string_free), NULL on error. Fidelity warnings, if any, are written \n-joined into warnbuf.
pio_export_arrow^⚠: Export one raw network table over the Arrow C Data Interface.
pio_from_json^⚠: Rebuild a network handle from JSON produced by pio_to_json. Returns a new handle (free with pio_network_free), or NULL on error (message into errbuf). The handle has no retained source, so pio_to_matpower reformats it rather than echoing a byte-exact original.
pio_gens^⚠: Fill the generator tables (each length pio_n_gens; bus is the 1-based bus id, the same id space as pio_bus_ids). Any pointer may be NULL to skip.
pio_gridfm_scenario_ids^⚠: Write a gridfm dataset’s distinct scenario ids (ascending) into out, up to cap entries, and return the total count. Call once with cap == 0 (or out NULL) to size, allocate, then call again to fill — the standard count/buffer pattern of pio_bus_ids. Returns -1 on error and writes the message into errbuf. Built --features gridfm.
pio_is_radial^⚠: 1 if the in-service topology is a forest, else 0.
pio_n_branches^⚠
pio_n_buses^⚠
pio_n_components^⚠
pio_n_gens^⚠
pio_n_reference_buses^⚠: Number of reference (slack) buses. 0 means none; > 1 means one reference per island or several fixed reference buses in one island. A normalized case always reports >= 1.
pio_network_free^⚠: Free a network handle from pio_parse_file, pio_parse_str, pio_to_normalized, or pio_from_json.
pio_nodal_demand^⚠: Fill nodal aggregates (each length pio_n_buses, dense order): active and reactive demand summed per bus. Any pointer may be NULL.
pio_nodal_shunt^⚠: Fill nodal shunt aggregates (each length pio_n_buses, dense order).
pio_parse_file^⚠: Parse path (format from extension, or from if non-NULL) into a case handle. from accepts the pio_parse_str format names plus pypsa-csv/pypsa; 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_parse_warnings). Returns NULL on error and writes the message into errbuf.
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 (see TargetFormat::from_str). 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_parse_warnings). Returns NULL on error and writes the message into errbuf. Free the handle with pio_network_free.
pio_parse_warnings^⚠: Read fidelity warnings attached at parse time, \n-joined into warnbuf (truncated to fit; NULL/0 to skip). Returns the warning count; 0 for a NULL handle. Empty for formats whose readers are total.
pio_read_gridfm^⚠: Read one scenario of a gridfm-datakit Parquet dataset into a network handle — the inverse of the gridfm writer. dir resolves leniently: the raw/ leaf holding the parquet files, a <case>/ directory with a raw/ child, or a parent holding exactly one such case. Returns NULL on error and writes the message into errbuf; the lossy read’s fidelity warnings (what the gridfm schema couldn’t round-trip) are written \n-joined into warnbuf. Free the handle with pio_network_free. Built --features gridfm.
pio_reference_bus^⚠: Dense [0, n) index of the single reference bus, or -1 if not exactly one (also -1 if the index is too large for isize). A network may carry several references (one per island, or a normalized case that kept the file’s multiple REF buses); use pio_n_reference_buses to tell zero from many, and pio_reference_buses to read them all.
pio_reference_buses^⚠: Fill out (length pio_n_reference_buses) with the dense [0, n) indices of the reference buses, ascending.
pio_string_free^⚠: Free a string returned by pio_to_matpower, pio_to_format, pio_convert_file, or pio_to_json.
pio_to_format^⚠: Serialize net to format to.
pio_to_json^⚠: Serialize the case to JSON: the structured-table transport every Julia bridge consumes. Carries the whole [Network] (buses, loads, shunts, branches, generators, storage, HVDC, extras) but not the retained source text, so it is structured data, not the byte-exact echo. Returns an owned C string (free with pio_string_free), NULL on error (message into errbuf).
pio_to_matpower^⚠: Serialize net to MATPOWER .m text (byte-exact echo when parsed from MATPOWER). Returns an owned C string; free with pio_string_free. Returns NULL on error and writes the message into errbuf.
pio_to_normalized^⚠: Normalize net into a NEW per-unit network handle: per unit, radians, out-of-service filtered, source bus ids preserved, bus types canonicalized (see Network::to_normalized). The result is independent of net; free both with pio_network_free. Every extractor and pio_to_json 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_version: The crate version string (e.g. "0.0.1"), 'static and NUL-terminated. Do NOT free it. Informational; pair it with pio_abi_version for the actual compatibility check.
pio_write_pypsa_csv_folder^⚠: Write net as a PyPSA CSV folder at out_dir. Returns 0 on success and -1 on error (the message is written into errbuf), the same convention as the other fallible int returns in this ABI. Fidelity warnings, if any, are written \n-joined into warnbuf.