powerio_pkg/
lib.rs

1//! `powerio-pkg`: the `.pio.json` compiler package.
2//!
3//! PowerIO has no single flattened "universal network" struct. It has two
4//! concrete static-grid IR families that stay distinct:
5//!
6//! - [`powerio::BalancedNetwork`] (the scalar positive-sequence transmission
7//!   model, historically `powerio::Network`);
8//! - [`powerio_dist::MulticonductorNetwork`] (the wire-coordinate distribution
9//!   model, historically `powerio_dist::DistNetwork`).
10//!
11//! A [`NetworkPackage`] is the readable envelope that wraps exactly one of
12//! those payloads at a time, alongside the metadata a compiler artifact needs
13//! to be trustworthy: an explicit [`ModelKind`], producer and origin metadata,
14//! source maps, structured diagnostics, a validation summary, and lowering
15//! history. It can also carry optional operating points that replay state
16//! updates over the static payload. GOC3 packages use that block for the source
17//! time series: the payload holds one static interval, and
18//! [`NetworkPackage::materialize_operating_point`] derives another static
19//! package from a selected period. It serializes to `.pio.json`. See
20//! `docs/src/compiler-ir.md` for the architecture and
21//! `docs/src/pio-json-schema.md` for the field reference.
22//!
23//! The package always carries [`NetworkPackage::model_kind`] explicitly; a
24//! reader must never infer whether the payload is balanced or multiconductor
25//! from which field is present. [`NetworkPackage::kind_is_consistent`] asserts
26//! the explicit kind agrees with the payload variant.
27//!
28//! ```
29//! use powerio_pkg::{NetworkPackage, ModelKind};
30//!
31//! let net = powerio::BalancedNetwork::in_memory("demo", 100.0, vec![], vec![]);
32//! let pkg = NetworkPackage::from_balanced(net);
33//! assert_eq!(pkg.model_kind(), ModelKind::Balanced);
34//! assert!(pkg.kind_is_consistent());
35//! let json = pkg.to_json_pretty().unwrap();
36//! let back = NetworkPackage::from_json(&json).unwrap();
37//! assert_eq!(back.model_kind(), ModelKind::Balanced);
38//! ```
39//!
40//! Binary `.pio` is out of scope until the JSON package stabilizes; this crate
41//! is JSON only.
42
43pub mod diagnostics;
44pub mod lowering;
45pub mod model;
46pub mod operating;
47pub mod package;
48pub mod provenance;
49pub mod summary;
50pub mod validation;
51
52pub use diagnostics::{DiagnosticCode, DiagnosticSeverity, DiagnosticStage, StructuredDiagnostic};
53pub use lowering::{
54    LoweringRecord, MulticonductorToBalancedError, MulticonductorToBalancedLowering,
55    MulticonductorToBalancedOptions, MulticonductorToBalancedReadiness,
56    SequenceTransformConvention, check_multiconductor_to_balanced_lowering,
57    lower_multiconductor_to_balanced,
58};
59pub use model::{ModelKind, ModelPayload};
60pub use operating::{ElementRef, ElementUpdate, OperatingPoint, OperatingPointSeries, TimeAxis};
61pub use package::{
62    DerivedMetadata, NetworkPackage, NormalizedSolverTableMetadata, NormalizedSolverTableRowCounts,
63    NormalizedSolverTableSourceRows, PIO_PACKAGE_SCHEMA_URL, PIO_PACKAGE_SCHEMA_VERSION,
64    PIO_PAYLOAD_BALANCED_SCHEMA_URL, PIO_PAYLOAD_BALANCED_SCHEMA_VERSION,
65    PIO_PAYLOAD_MULTICONDUCTOR_SCHEMA_URL, PIO_PAYLOAD_MULTICONDUCTOR_SCHEMA_VERSION,
66};
67pub use provenance::{
68    Confidence, MappingKind, Origin, Producer, SourceDescriptor, SourceMapEntry, SourceRef,
69};
70pub use summary::{ObjectSummary, ObjectTopology, ObjectUnits};
71pub use validation::{ValidationCounts, ValidationPass, ValidationStatus, ValidationSummary};
powerio_pkg/lib.rs

powerio_pkg/
lib.rs
