Struct NetworkPackage 

#[non_exhaustive]
pub struct NetworkPackage {

    pub schema_version: String,
    pub producer: Producer,
    pub package_id: Option<String>,
    pub created_at: Option<String>,
    pub model_kind: ModelKind,
    pub model: ModelPayload,
    pub operating_points: Option<OperatingPointSeries>,
    pub study: Option<StudyBlock>,
    pub origin: Origin,
    pub sources: Vec<SourceDescriptor>,
    pub source_maps: Vec<SourceMapEntry>,
    pub diagnostics: Vec<StructuredDiagnostic>,
    pub validation: ValidationSummary,
    pub summary: ObjectSummary,
    pub lowering_history: Vec<LoweringRecord>,
    pub derived: DerivedMetadata,
}

A versioned package containing one model payload, provenance, diagnostics, validation results, and lowering history. Serializes to .pio.json.

model_kind is stored explicitly and is authoritative; the payload is also self-describing (tagged by kind). NetworkPackage::kind_is_consistent asserts the two agree. The reader ignores unknown top level fields from a newer producer.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

schema_version: String

The .pio.json format version (semver); see PIO_PACKAGE_SCHEMA_VERSION.

Required. It used to default to the current version when absent, which let a document opt out of the lineage gate by dropping the field: a 0.1-era payload then read under 0.2 rules, and a field the two spell differently arrived as its serde default with no error and no warning. That is the misreading the gate exists to stop, so a document must now state its lineage.

producer: Producer

package_id: Option<String>

Stable content id, e.g. "sha256:...". The scaffold leaves it None.

created_at: Option<String>

RFC 3339 build timestamp. Left None by default for deterministic, round-trip-stable output; set explicitly when a timestamp is wanted.

model_kind: ModelKind

Explicit model kind. Authoritative; never inferred from field presence.

model: ModelPayload

operating_points: Option<OperatingPointSeries>

Replayable operating states over the static payload. The package constructors and setters omit empty series for static single state cases.

study: Option<StudyBlock>

Cumulative interactive edits over the package payload.

origin: Origin

sources: Vec<SourceDescriptor>

source_maps: Vec<SourceMapEntry>

diagnostics: Vec<StructuredDiagnostic>

validation: ValidationSummary

summary: ObjectSummary

lowering_history: Vec<LoweringRecord>

derived: DerivedMetadata

Implementations

impl NetworkPackage

pub fn from_balanced(net: BalancedNetwork) -> Self

Wrap a balanced network. Origin is inferred from its source format: InMemory / Derived (normalized) / File (a parsed text format, recording whether source was retained; the path is not captured here).

pub fn from_parsed_balanced(parsed: Parsed) -> Self

Wrap the result of a balanced case reader. Reader adapters can attach source data that is not part of the balanced network model; an operating point series derives from the reader’s own parse, handed forward as powerio::Parsed::document.

pub fn from_balanced_with_read_warnings<I, S>( net: BalancedNetwork, code: &str, warnings: I, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Wrap a balanced network and lift reader warnings into structured diagnostics under code.

pub fn record_read_warnings<I, S>(&mut self, code: &str, warnings: I)

where I: IntoIterator<Item = S>, S: Into<String>,

Append reader warnings to package diagnostics.

pub fn from_multiconductor(net: MulticonductorNetwork) -> Self

Wrap a multiconductor network. Parse warnings are lifted into structured diagnostics, and defaulted fields are lifted into source maps with mapping_kind = defaulted, so the package surfaces that provenance even though those parser-side fields are not part of the IR payload.

pub fn model_kind(&self) -> ModelKind

The explicit model kind.

pub fn kind_is_consistent(&self) -> bool

Whether the explicit model_kind agrees with the payload variant. A reader should reject a package where this is false.

pub fn as_balanced(&self) -> Option<&BalancedNetwork>

The balanced payload, if this package carries one.

pub fn as_multiconductor(&self) -> Option<&MulticonductorNetwork>

The multiconductor payload, if this package carries one.

pub fn operating_points(&self) -> Option<&OperatingPointSeries>

Replayable operating states over the static payload, when present.

pub fn with_operating_points( self, operating_points: OperatingPointSeries, ) -> Self

Attach a format neutral operating point series to this package.

pub fn set_operating_points(&mut self, operating_points: OperatingPointSeries)

Attach or replace operating points in place. Empty series are omitted.

pub fn clear_operating_points(&mut self)

Remove operating points from this package.

pub fn study(&self) -> Option<&StudyBlock>

Cumulative study edits over the static payload, when present.

pub fn with_study(self, study: StudyBlock) -> Self

Attach a study block to this package. Empty blocks are omitted.

pub fn set_study(&mut self, study: StudyBlock)

Attach or replace the study block in place. Empty blocks are omitted.

pub fn clear_study(&mut self)

Remove the study block from this package.

pub fn materialize_operating_point(&self, index: usize) -> Result<Self>

Materialize one operating point into a static package.

The returned package has the same metadata and model kind, with its payload updated for index, operating_points cleared, and sane validation recomputed for the updated payload.

pub fn materialize_balanced_operating_point( &self, index: usize, ) -> Result<Option<BalancedNetwork>>

Materialize one operating point and return the balanced payload if this is a balanced package.

pub fn materialize_multiconductor_operating_point( &self, index: usize, ) -> Result<Option<MulticonductorNetwork>>

Materialize one operating point and return the multiconductor payload if this is a multiconductor package.

pub fn materialize_study_commit(&self, commit_index: usize) -> Result<Self>

Materialize a study commit into a static package.

The returned package folds commits 0..=commit_index, clears operating_points and study, and records the replay pass in lowering_history.

pub fn materialize_balanced_study_commit( &self, commit_index: usize, ) -> Result<Option<BalancedNetwork>>

Materialize a study commit and return the balanced payload.

pub fn to_json(&self) -> Result<String>

Serialize to compact .pio.json.

pub fn to_json_pretty(&self) -> Result<String>

Serialize to pretty .pio.json.

pub fn from_json(text: &str) -> Result<Self>

Deserialize from .pio.json.

pub fn supports_schema_version(version: &str) -> bool

Whether this reader accepts the document’s schema_version.

The .pio.json compatibility rule: unknown top level fields from a newer producer are ignored, versions in the reader’s lineage load, and anything else is rejected before payload use. The lineage is the major version once it reaches 1, and the exact major.minor pair while the major is 0 (cargo 0.x semantics: a 0.x minor bump is incompatible).

pub fn with_origin(self, origin: Origin) -> Self

pub fn with_package_id(self, id: impl Into<String>) -> Self

pub fn with_created_at(self, created_at: impl Into<String>) -> Self

pub fn with_sources(self, sources: Vec<SourceDescriptor>) -> Self

pub fn with_source_maps(self, source_maps: Vec<SourceMapEntry>) -> Self

pub fn push_lowering(&mut self, record: LoweringRecord)

Append a lowering record to the history.

pub fn attach_normalized_solver_table_metadata(&mut self) -> Result<bool, Error>

Attach compact metadata for the normalized dense solver table lowering.

Returns Ok(false) for non-balanced packages. The full table rows stay outside the package payload; this records the pass name, row counts, units, dense identities, and source row provenance a compiler cache needs to validate external table artifacts.

pub fn with_normalized_solver_table_metadata(self) -> Result<Self, Error>

Return a package with normalized solver table metadata attached.

pub fn check_multiconductor_to_balanced_lowering( &self, ) -> Option<MulticonductorToBalancedReadiness>

Check whether this package’s multiconductor payload is ready for the explicit multiconductor to balanced lowering pass.

pub fn lower_multiconductor_to_balanced( &self, options: MulticonductorToBalancedOptions, ) -> Result<Self, MulticonductorToBalancedError>

Explicitly lower a multiconductor package to a derived balanced package.

This method only accepts packages whose payload is ModelKind::Multiconductor. It does not mutate the input package.

pub fn run_sane_validation(&mut self)

Run the package semantic validation profile and record its findings.

This pass leaves the payload untouched: it reports structural and semantic issues, but never repairs or rewrites the model. It does rewrite the package’s own diagnostics and validation, so it needs &mut self.

Trait Implementations

impl Clone for NetworkPackage

fn clone(&self) -> NetworkPackage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NetworkPackage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NetworkPackage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for NetworkPackage

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for NetworkPackage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.