Struct Network 

#[non_exhaustive]
pub struct Network {

    pub name: String,
    pub base_mva: f64,
    pub base_frequency: f64,
    pub buses: Vec<Bus>,
    pub loads: Vec<Load>,
    pub shunts: Vec<Shunt>,
    pub branches: Vec<Branch>,
    pub switches: Vec<Switch>,
    pub generators: Vec<Generator>,
    pub storage: Vec<Storage>,
    pub hvdc: Vec<Hvdc>,
    pub transformers_3w: Vec<Transformer3W>,
    pub areas: Vec<Area>,
    pub solver: Option<SolverParams>,
    pub source_format: SourceFormat,
    pub source: Option<Arc<String>>,
}

A format-neutral power network.

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.

name: String

base_mva: f64

base_frequency: f64

System base frequency in hertz (50 or 60). Threaded through the formats that record it (PSS/E BASFRQ, pandapower f_hz) and defaulted to DEFAULT_BASE_FREQUENCY for the rest. Load-bearing for any reactance↔henry conversion (pandapower line charging) and reported as a fidelity loss when a non-default value writes to a format with no frequency field.

buses: Vec<Bus>

loads: Vec<Load>

shunts: Vec<Shunt>

branches: Vec<Branch>

switches: Vec<Switch>

generators: Vec<Generator>

storage: Vec<Storage>

hvdc: Vec<Hvdc>

transformers_3w: Vec<Transformer3W>

Three-winding transformers, kept as typed records rather than folded into branches, so a star point and the per-winding data survive a round trip. #[serde(default)] so JSON written before the field existed still deserializes. IndexedNetwork lowers each in-service record into a star bus plus three branches (via Transformer3W::star_expansion) before building any matrix, so a 3-winding transformer does appear in Y_bus/connectivity; the canonical model keeps the typed record for round-trip fidelity.

areas: Vec<Area>

Area records: scheduled interchange and per-area swing bus. Distinct from the bare area number on each Bus; this is the area’s metadata, which every conversion dropped before. #[serde(default)] so older JSON still deserializes.

solver: Option<SolverParams>

Solver / solution-control metadata when the source carries it, else None. #[serde(default)] so older JSON still deserializes.

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 apply_gen_cost_policy( &mut self, patches: &[GenCostPatch], policy: MissingGenCostPolicy, ) -> Result<GenCostPolicyReport, Error>

Apply explicit cost patches, then a missing-cost policy.

Patches replace the existing cost for the named generator. The missing-cost fill policy only touches generators still missing a cost after patching.

impl Network

pub fn new(name: impl Into<String>, base_mva: f64) -> 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 (the powerio-json format) 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.

JSON has no Inf/NaN: serde_json writes a non-finite field as null, which from_json rejects on the way back (null is not an f64). The write stays total, the bindings materialize every parsed network through this transport, and readers legitimately produce Inf limits, but such a snapshot does not round trip; write_as reports the degradation as a fidelity warning naming the field.

Errors

A serde_json serialization failure (none arise from this model today).

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

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

Errors

As write_as: only a PowerioJson serialization failure.

pub fn to_format_with_options( &self, format: TargetFormat, options: &WriteOptions, ) -> Result<Conversion, Error>

Serialize this network with write-time cost policies.

The network itself is not mutated. Default options preserve to_format behavior.

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_values(&self) -> Vec<Diagnostic>

Report element fields whose values fall outside their physical domain, without changing anything. Each Diagnostic names the element, the field, the current value, the value repair would set, and why.

This generalizes the per-reader value clamps (a bus voltage magnitude outside [0, 2], an angle past ±2000°, a zero generator MVA base or voltage setpoint) into one pass any consumer can run, separate from the structural validate (which only checks ids and references). It is non-mutating; call repair to apply the fixes.

pub fn repair(&mut self) -> Vec<Diagnostic>

Clamp every out-of-domain value to its repaired value (the same rules validate_values reports), returning the list of changes made. A second call returns an empty list (the values are now in domain).

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.

impl Network

pub fn subset(&self, sel: &Selector, keep_boundary: bool) -> Network

Carve out the sub-network whose buses match sel.

In-scope buses keep their loads, shunts, generators, and storage; a branch, HVDC line, or 3-winding transformer is kept when every bus it touches is kept. With keep_boundary, a branch or HVDC line straddling the selection edge pulls its out-of-scope endpoint in as a tie bus (tagged extras["tie_bus"] = true) so the carved island has no dangling branch ends; without it, a straddling branch is dropped. A tie bus is a stub: its own loads/generators are not pulled in. A control reference (regulated bus) that falls outside the kept set is cleared so the result is reference-consistent.

The result is a fresh SourceFormat::InMemory network (no retained source); an empty Selector returns a clone-equivalent of the whole case, and a selector matching no bus returns an empty network.

pub fn merge_bus(&mut self, into: BusId, from: BusId)

Merge bus from into bus into: re-home every element on from (loads, shunts, generators, storage, branch/HVDC/transformer endpoints, and control references) onto into, drop the branches and HVDC lines that ran directly between the two (now self-loops), and remove the from bus. The surviving bus keeps the stronger of the two bus kinds (a slack is not demoted).

A no-op when into == from. The other attributes of from (its voltage, limits, name) are discarded; the topology and injections are what move.

pub fn reduce_zero_impedance(&mut self, threshold: f64) -> usize

Collapse every in-service, non-transformer branch whose series impedance magnitude is at or below threshold by merging its endpoints (the to-bus into the from-bus), returning the number of branches removed. Parallel jumpers between the same pair go in the same step.

Zero-impedance branches (bus ties, breakers modeled as jumpers) carry no power flow drop, so collapsing them shrinks the network without changing its electrical behavior. An out-of-service jumper is an open switch whose endpoints are not electrically joined, so it is left in place. Transformers are never collapsed (a unity-ratio transformer is a real device, not a jumper); a jumper between two windings of the same 3-winding transformer is also skipped, since merging would collapse that transformer onto one node.

pub fn reduce_passthrough_buses(&mut self) -> usize

Collapse degree-2 passthrough buses, returning the number removed. A passthrough bus carries nothing but two in-service line sections, so it is an electrically inert junction: the two sections fold into one equivalent branch between their outer endpoints and the middle bus is deleted.

This is the multi-section-line reduction. Exporters often split one circuit into segments joined at dummy buses; folding them back recovers the single branch. A bus qualifies only when it carries no load, generator, shunt, or storage, is not a control reference, area swing, HVDC endpoint, or 3-winding winding bus, is not the system slack, and is touched by exactly two ordinary branches (never transformers) that are both in service and run to two distinct other buses. The equivalent branch sums the series impedance and line charging, takes the more limiting thermal rating of the two sections, and intersects their angle limits. Chains of dummy buses collapse fully, one bus per step.

pub fn retype_isolated_buses(&mut self) -> usize

Retype to BusType::Isolated every bus with no in-service electrical connection — no in-service incident branch, HVDC line, or 3-winding transformer — returning the number retyped.

A stranded bus (retired or not-yet-built equipment, or the residue of a topology edit) otherwise keeps a PQ/PV/slack kind that tells a solver to include it, leaving an ungrounded singleton in the system. This only demotes a disconnected bus; it never promotes a connected one, and a bus the source already marks isolated is left untouched. Connectivity is judged on in-service equipment only, so opening the last branch into a bus makes it eligible.

impl Network

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

Lower this balanced network into normalized dense solver tables.

Errors

Propagates Network::to_normalized errors and reports Error::UnknownBus if the derived normalized network contains an internal dangling bus reference.

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.