Crate graph and architecture map
The workspace is layered. Shared infrastructure sits below every parser and a thin facade sits on top; no lower crate depends on the facade, and the two network crates do not depend on each other.
powerio-core Source, FormatId, Diagnostic, Error, PioModule<T>,
TimePoint, TimeSeries<T>, ScenarioSet<T>, Destination
├── powerio-archive bounded ZIP indexing and verified reads; no case discovery
├── powerio-tx BalancedNetwork and the balanced readers and writers
└── powerio-dist MulticonductorNetwork and the OpenDSS, PMD, BMOPF, and CIM converters
powerio-tnd IntegratedNetwork, cross-model transformations, and
optional SINCAL adapters; depends on core, tx, and dist
powerio-prob operating points, updates, the nine instances, the ten
solutions, and GO Challenge 3, OPFData, and BMOPF assembly;
depends on core, tx, and dist; matrix free
powerio-synth deterministic topology-only network generators;
depends on tx
powerio-matrix sparse matrices and graph data for both network families;
depends on core, tx, dist, prob, and synth
powerio PioValue, parse, emit, serialize, deserialize, and the
re-exports; depends on core, tx, dist, prob, tnd, and on matrix
behind the `matrix` feature
powerio-cli, powerio-capi, powerio-py, powerio-wasm over the facade
A change has to keep that shape. powerio-core owns no electrical type,
parser, matrix, instance, or IR record layout. powerio-tx and powerio-dist
stay usable on their own, so a distribution consumer pulls in neither the
balanced model nor the matrix stack. powerio-prob does not depend on
powerio-matrix. The facade re-exports the component crates, which is why
cargo add powerio gets you everything, and its matrix feature adds the
matrix crate without creating a cycle. CI checks these edges against
cargo metadata, so the map below and the manifests cannot drift apart.
The powerio-tnd crate composes the independent network models through checked
interfaces and owns cross-model transformations. SINCAL is its first optional
format module. The facade enables powerio-tnd/sincal by default; disabling
that feature keeps SQLite out of the dependency graph. The architecture gate
requires the model crates to remain independent of tnd and each other.
See Integrated transmission/distribution modeling for the interface
rules and planned extensions.
Components
The facade does not force a consumer to depend on every component crate, and the two network crates are siblings with no edge between them. Solvers consume instances but sit outside PowerIO, and their workspaces and numerical caches stay outside with them.
Data flow
Every arrow out of the module is an explicit call that returns diagnostics; nothing is transformed as a side effect of something else.
The diagram sources are in docs/diagrams/*.dot.
scripts/check-architecture-map.py checks the drawn crate edges against
cargo metadata and, with --render, regenerates the images.
Why powerio-archive is separate
The shared-collection plan #774 introduced this boundary in #776. It owns model-neutral ZIP transport: bounded metadata indexing, normalized entry names, overlap and descriptor checks, and size/CRC-verified entry reads. It never extracts files or decides which electrical model a file contains. The facade owns case discovery, manifests, dependency observations, and nested collection selection. CGMES and SINCAL also reuse the crate’s bounded reading primitives; they do not yet use its complete collection inventory.
This separation keeps ZIP dependencies out of powerio-core, and lets lower
format adapters share the same transport primitives without depending on the
facade. It also makes the hostile-input tests usable independently of network
parsing. Moving these functions into the facade would introduce a dependency
cycle; moving them into core would add archive concerns to every core consumer.
A separate crate is not a requirement of the file format, but it is a useful
boundary for the current dependency graph. Its cost is another published crate
and release bootstrap step. An inventory is not a certificate that every
unread entry has passed CRC validation, nor a bound on subsequent electrical
model allocations; callers still inspect diagnostics and apply model limits.