Struct Network 

pub struct Network {
    pub name: String,
    pub base_mva: f64,
    pub buses: Vec<Bus>,
    pub loads: Vec<Load>,
    pub shunts: Vec<Shunt>,
    pub branches: Vec<Branch>,
    pub generators: Vec<Generator>,
    pub storage: Vec<Storage>,
    pub hvdc: Vec<Hvdc>,
    pub source_format: SourceFormat,
    pub source: Option<Arc<String>>,
}

A format-neutral power network.

Fields

name: String

base_mva: f64

buses: Vec<Bus>

loads: Vec<Load>

shunts: Vec<Shunt>

branches: Vec<Branch>

generators: Vec<Generator>

storage: Vec<Storage>

hvdc: Vec<Hvdc>

source_format: SourceFormat

source: Option<Arc<String>>

Raw source text, when read from a textual format; enables a byte-exact same-format round-trip. Arc<String> (not Arc<str>) is deliberate: a reader that already owns the buffer (the MATPOWER file path) moves it in with no second copy of the whole file. The trade is one extra indirection per access; don’t “simplify” it back to Arc<str>, which would reintroduce the copy this avoids.

Skipped in JSON: the structured tables are the transport, not the raw echo, and skipping also keeps serde’s rc feature out of the build. A from_json round-trip returns this as None.

Implementations

impl Network

pub fn in_memory( name: impl Into<String>, base_mva: f64, buses: Vec<Bus>, branches: Vec<Branch>, ) -> Network

A network assembled in memory from buses and branches, with no loads, shunts, generators, storage, HVDC, or retained source document. Synthetic topology generators and tests use it instead of repeating the struct literal. The caller owns reference integrity (run check_references if the ids might be inconsistent).

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

Serialize the structured tables to JSON — the transport the C ABI (pio_to_json) and the Julia bridge consume. The retained source text is excluded (see the field’s #[serde(skip)]), so the byte-exact echo stays on the same-format write path; a from_json round-trip reproduces every field except source, which returns None.

pub fn to_format(&self, format: TargetFormat) -> Conversion

Serialize this network to format, preserving the retained source text on same-format writes and reporting any target-format fidelity warnings.

pub fn to_matpower(&self) -> String

Serialize this network to MATPOWER .m text.

This is byte-exact when the network was parsed from MATPOWER and still carries its retained source text.

pub fn from_json(text: &str) -> Result<Network, Error>

Rebuild a Network from JSON produced by to_json.

Validates the result (no buses, unique bus ids, no dangling references) before returning, so the JSON transport — the C ABI and Julia bridge ride on it — can’t hand back a network the file readers would have rejected (the same no-buses guard read_source applies to every parse path).

pub fn is_normalized(&self) -> bool

Whether this is a normalized (per-unit, radian, filtered) derived product from to_normalized, rather than a raw network at the file’s unit basis. Unit-sensitive code that takes a &Network can check this instead of silently assuming MW.

pub fn check_base_mva(&self) -> Result<(), Error>

Error unless base_mva is a positive, finite number. It is every per-unit divisor, so a malformed base would otherwise silently poison downstream values with NaN/Inf or flipped signs. The per-unit consumers (to_normalized, the gridfm export) call this; any other unit-sensitive consumer should too.

pub fn validate(&self) -> Result<(), Error>

Check structural integrity: bus ids are unique and every element references an existing bus. The file readers and from_json run this; a Network built by hand (or mutated, e.g. by a scenario generator) should call it before handing the network to IndexedNetwork, whose dense indexing assumes it.

impl Network

pub fn to_normalized(&self) -> Result<Network, Error>

A normalized, computation-ready copy of this network. The raw Network is kept lossless (MATPOWER units, 1-based sparse ids, out-of-service elements retained); to_normalized derives the form a solver or ML pipeline wants:

• Per unit (÷base_mva): gen pg/qg/pmax/pmin/qmax/qmin and the ramp caps (GEN_PU_KEYS); load p/q; shunt g/b; branch rate_a/b/c; storage energy/ratings/limits/losses; HVDC pf/pt/qf/qt, reactive limits, loss0; gen-cost coefficients (cost_to_pu). Storage ps/qs and HVDC aggregate pmin/pmax stay raw, matching the PowerModels per-unit convention. Voltages, impedances, tap, and loss1 are already dimensionless.
• Radians: bus va; branch shift/angmin/angmax.
• Tap: 0 → 1.0 (an explicit 1 is kept).
• Filtered: drop buses typed isolated (BusType::Isolated) and every out-of-service element, then drop any element left referencing a dropped bus. A bus orphaned by the out-of-service filter (no in-service branch, but not typed isolated) is kept — its load is real — and surfaces as its own island, which the grounding check reports if it has no reference.
• IDs: kept buses retain their source bus ids, and every surviving endpoint stays in the same id space. Consumers that need dense rows should use IndexedNetwork, which derives [0, n) indices without destroying source ids.
• Bus types: a bus hosting a surviving generator keeps REF if the file marked it REF, otherwise becomes PV; a generator-less bus is PQ (so a generator-less REF is demoted). The file’s REF buses are kept, several included, and the consumer picks the slack. Only when no reference bus survives is the largest-pmax in-service generator’s bus promoted to REF.

This is a derived product, not a source for write-back: source is dropped and source_format is SourceFormat::Normalized, so writing it serializes the per-unit/radian model instead of echoing the raw bytes, and a consumer can tell it apart from a raw in-memory network.

Scope is the universal canonicalization only. It does not pad angle bounds, synthesize a missing rate_a, or restrict the gen-cost model — those are solver-prep choices a consumer applies on top. The cost rescale is universal and lives here; the model restriction does not.

Errors

Error::InvalidBaseMva if base_mva is not a positive, finite number (every per-unit divisor), so a malformed base can’t silently poison the whole network with NaN/Inf or sign-flipped values. Error::ReferenceBusCount if no reference bus can be established — no REF survives and there is no in-service generator to anchor one.

Trait Implementations

impl Clone for Network

fn clone(&self) -> Network

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Network

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Network

fn deserialize<__D>( __deserializer: __D, ) -> Result<Network, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Network

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

where __S: Serializer,

Serialize this value into the given Serde serializer.