Struct BalancedNetwork 

pub struct BalancedNetwork { /* private fields */ }

A balanced network with stable source bus IDs and separate element tables: an immutable cheap to clone owning handle over private shared tables.

Cloning the handle bumps one reference count and clones no table allocation. Reads go through the per field accessors; the *_mut accessors copy the shared tables once on first write to a shared handle (copy on write), so no other handle ever observes a mutation. The choice of whole value sharing is private: clone stays zero allocation because the handle wraps its tables in one Arc.

Implementations

impl BalancedNetwork

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 BalancedNetwork

pub fn to_geo_layer(&self) -> GeoLayer

Transform this network’s coordinates to a standalone GeoLayer: one point per located bus, one route per routed branch. The layer carries the network’s coordinate space and default origin.

pub fn apply_geo_layer(&mut self, layer: &GeoLayer) -> GeoApplyReport

Apply a GeoLayer onto this network: matched bus points land in Bus.location, matched branch routes in Branch.route, and the layer’s space becomes the network’s GeoMeta when anything matched. Matching follows ElementKey. Substation features are not applied here; join them through super::apply_substation_points.

impl BalancedNetwork

pub fn name(&self) -> &String

The case name.

pub fn name_mut(&mut self) -> &mut String

Mutable access to the same table; a shared handle copies its tables once here, so no other handle observes the change.

pub fn geo(&self) -> &Option<GeoMeta>

The geographic metadata when the source carries any.

pub fn geo_mut(&mut self) -> &mut Option<GeoMeta>

Mutable access to the same table; a shared handle copies its tables once here, so no other handle observes the change.

pub fn case_metadata(&self) -> &CaseMetadata

Source neutral case metadata when the source records it.

pub fn case_metadata_mut(&mut self) -> &mut CaseMetadata

Mutable access to the same table; a shared handle copies its tables once here, so no other handle observes the change.

pub fn solver(&self) -> &Option<SolverParams>

Solver / solution-control metadata when the source carries it.

pub fn solver_mut(&mut self) -> &mut Option<SolverParams>

Mutable access to the same table; a shared handle copies its tables once here, so no other handle observes the change.

impl BalancedNetwork

pub fn detailed_connectivity(&self) -> &Option<Arc<DetailedConnectivity>>

Authoritative hierarchy and detailed connectivity when present.

pub fn detailed_connectivity_mut( &mut self, ) -> &mut Option<Arc<DetailedConnectivity>>

Mutable access to detailed connectivity. Taking mutable access clears source field omission records because a caller can change any of the corresponding values through this reference.

impl BalancedNetwork

pub fn share_equal_tables(&mut self, donor: &BalancedNetwork)

Replace each element table’s allocation with donor’s wherever the contents are equal, so equal tables across derived networks (the scenarios of one dataset, the points of one series) are stored once. No value changes; a table that differs anywhere keeps its own allocation.

impl BalancedNetwork

pub fn buses(&self) -> &Vec<Bus>

pub fn buses_mut(&mut self) -> &mut Vec<Bus>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn static_var_compensators(&self) -> &Vec<StaticVarCompensator>

pub fn static_var_compensators_mut(&mut self) -> &mut Vec<StaticVarCompensator>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn branches(&self) -> &Vec<Branch>

pub fn branches_mut(&mut self) -> &mut Vec<Branch>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn switches(&self) -> &Vec<Switch>

pub fn switches_mut(&mut self) -> &mut Vec<Switch>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn hvdc(&self) -> &Vec<Hvdc>

pub fn hvdc_mut(&mut self) -> &mut Vec<Hvdc>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn transformers_3w(&self) -> &Vec<Transformer3W>

Three-winding transformers, kept as typed records.

pub fn transformers_3w_mut(&mut self) -> &mut Vec<Transformer3W>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

pub fn areas(&self) -> &Vec<Area>

Area records: scheduled interchange and per-area swing bus.

pub fn areas_mut(&mut self) -> &mut Vec<Area>

Mutable access to the same table. A shared handle copies the table set spine and this one table here, so no other handle observes the change and untouched tables stay shared.

impl BalancedNetwork

pub fn loads(&self) -> &Vec<Load>

pub fn loads_mut(&mut self) -> &mut Vec<Load>

Mutable load access makes source omission metadata conservative: a subsequent emission writes the numeric active and reactive power values.

pub fn generators(&self) -> &Vec<Generator>

pub fn generators_mut(&mut self) -> &mut Vec<Generator>

Mutable generator access makes source omission metadata conservative: a subsequent emission writes all numeric generator assignments.

pub fn storage(&self) -> &Vec<Storage>

pub fn storage_mut(&mut self) -> &mut Vec<Storage>

Mutable storage access makes source omission metadata conservative: a subsequent emission writes both numeric power assignments.

pub fn shunts(&self) -> &Vec<Shunt>

pub fn shunts_mut(&mut self) -> &mut Vec<Shunt>

Mutable shunt access makes source omission metadata conservative: a subsequent emission writes conductance per section.

impl BalancedNetwork

pub fn base_mva(&self) -> f64

System MVA base.

pub fn base_mva_mut(&mut self) -> &mut f64

pub fn base_frequency(&self) -> f64

System base frequency in hertz (50 or 60).

pub fn base_frequency_mut(&mut self) -> &mut f64

pub fn source_format(&self) -> SourceFormat

The format the case was parsed from.

pub fn source_format_mut(&mut self) -> &mut SourceFormat

pub fn assign_missing_component_ids(&mut self)

Assign persistent identities to records whose source format supplied none.

Source supplied identities are preserved. Generated identities use electrical identifiers such as a bus number or branch terminals and are stored on the record, so later table reordering does not change them. A suffix distinguishes several records attached to the same bus or terminal pair.

The identities are unique across the whole network, not only within one table: a load and a generator at bus 3 are two records, and formats that index every element by one identifier (XIIDM, CGMES) reject the same identifier twice. The first record to claim a stem keeps it and the next takes a numeric suffix.

Callers that assemble a network by pushing records can call this once after construction. PowerIO parsers call it before returning a module.

pub fn uid_is_generated(&self, uid: Option<&str>) -> bool

True when PowerIO generated this identity to make records addressable.

impl BalancedNetwork

pub fn new(name: impl Into<String>, base_mva: f64) -> BalancedNetwork

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

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 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 &BalancedNetwork 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, as coded VALIDATE.BALANCED.VALUE_DOMAIN findings. Each record targets the element and carries the field, the current value, the value a repair would set, and why in details.

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; repair_values applies the fixes to a parsed module and records them.

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

Check structural integrity: bus ids are unique and every element references an existing bus. File readers run this; a BalancedNetwork 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 BalancedNetwork

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

A normalized, computation-ready copy of this network. The raw BalancedNetwork 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 synthesize a missing rate_a or restrict the gen-cost model — those are solver preparation choices a consumer applies on top. Use BalancedNetwork::to_normalized_with_options for the opt in PowerModels angle bound repair. 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::NoReferenceBus if no reference bus can be established — no REF survives and there is no in-service generator to anchor one.

pub fn to_normalized_with_options( &self, options: &NormalizeOptions, ) -> Result<NormalizedNetwork, Error>

Like BalancedNetwork::to_normalized, with opt in solver preparation repairs that report fidelity warnings.

impl BalancedNetwork

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

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.

Trait Implementations

impl Clone for BalancedNetwork

fn clone(&self) -> BalancedNetwork

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BalancedNetwork

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for BalancedNetwork

fn deserialize<D>( deserializer: D, ) -> Result<BalancedNetwork, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<BalancedNetwork> for PioValue

fn from(value: BalancedNetwork) -> Self

Converts to this type from the input type.

impl JsonSchema for BalancedNetwork

Available on crate feature schema only.

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 BalancedNetwork

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.