Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 PowerIO component map: powerio-core at the bottom; powerio-tx and powerio-dist as independent siblings above it; powerio-prob over both networks; powerio-matrix over the networks and prob; the powerio facade over the component crates with an optional matrix feature edge; powerio-cli, powerio-capi, powerio-py, and powerio-wasm over the facade; solvers consume instances from powerio-prob and the GridFM pipeline reads Parquet datasets from powerio-matrix.

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

The PowerIO data flow: a Source of named immutable bytes enters parse, which produces a PioModule holding the typed value, retained source, diagnostics, and history; time series and scenario sets expose owner rooted typed entries through indexing and iteration; to_balanced derives a balanced module from a multiconductor module with reported assumptions and losses; calc operations return matrices and vectors with element mappings; emit produces grid exchange formats; serialize and deserialize connect the module to PowerIO IR.

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.