Language APIs

PowerIO uses the same IO vocabulary across Rust, Python, Julia, and the C ABI, with language-specific spelling where needed. A new format or dataset appears as a format string or convenience wrapper rather than a new naming scheme.

Verb taxonomy:

• parse_*: bytes, paths, or text to typed parsed values. Transmission parsers return a balanced network handle; distribution parsers return a multiconductor network handle; display parsers return display data.
• to_*: BalancedNetwork to a new value
• convert_file: path to target text convenience
• write_*: filesystem outputs (write_gridfm, write_pypsa_csv_folder, write_dcopf_bundle); the Rust hub also keeps write_as and per-format write_* text builders, the internals behind to_format and the to_* writers, which the bindings do not mirror
• read_*: filesystem dataset inputs (read_gridfm, read_pypsa_csv_folder), the inverse of write_*. Datasets are multi-file directories, so they read and write; single documents parse and serialize (parse_*/to_*)
• export_*: handoff to external memory or interface protocols

Note: the C ABI carries no per-format symbols: matpower, powerio-json, PyPSA CSV directories, and gridfm datasets are all format strings into pio_to_format / pio_parse_str / pio_write_dir / pio_read_dir. Removing or changing a documented format token is a C behavior change even though the C signature stays the same. The language APIs keep their per-format conveniences (to_matpower, from_json, …) as wrappers over the same paths.

C ABI and binding compatibility

The C ABI is the stable boundary for non Rust callers. Handles own parsed networks. PioPackage handles own .pio.json documents. Callers free network handles with pio_network_free, package handles with pio_package_free, and SCOPF handles with pio_scopf_instance_free. They free returned text with pio_string_free, size output buffers before filling them, and treat every format name as a string routed through the same parser and writer hub.

C ABI review points:

• null handles must return documented defaults or errors and must never crash;
• optional output buffers must be safe to pass as null; required output structs such as Arrow exports must report an error when null;
• returned text and warning buffers must be NUL terminated when capacity permits;
• reported lengths must let callers allocate exact buffers;
• header declarations and exported Rust symbols must match;
• feature gated exports such as Arrow, GridFM, distribution, packages, and problem instances must be additive;
• ownership rules must be documented in the header, README, and binding code.

Julia’s PowerIO.jl uses the C ABI for handles, dense extractors, Arrow, GridFM, PyPSA CSV folders, distribution conversion, and .pio.json document construction. Programmatic whole-network JSON remains available through powerio-json; file handoffs should use .pio.json. The Julia binding checks pio_abi_version() against PIO_ABI_VERSION on first use. Distribution calls also check pio_dist_abi_version().

GOC3 document construction is the first .pio.json operating point path backed by a source format. The static balanced model JSON carries the first interval; the replayable series is exposed through the package APIs above.

During development, test the Julia binding against the local C ABI instead of a release artifact:

cargo build -p powerio-capi --release --features arrow,matrix,gridfm,dist,pkg,prob
POWERIO_CAPI=$PWD/target/release/libpowerio_capi.dylib \
  julia --project=../PowerIO.jl -e 'using Pkg; Pkg.test()'

Binding compatibility checks:

Distribution surface (powerio-dist)

The multiconductor distribution model follows the same taxonomy under its own handle type; the two families do not mix. The C distribution surface ships behind the optional dist feature (PIO_DIST); a consumer probes it with pio_has_feature("dist"), then checks pio_dist_abi_version() against PIO_DIST_ABI_VERSION. PowerIO.jl uses the same runtime check before calling the distribution C conversion helpers.