Struct Network 

pub struct Network {

    pub name: String,
    pub base_mva: f64,
    pub freq_hz: f64,
    pub buses: Vec<Bus>,
    pub branches: Vec<Branch>,
    pub generators: Vec<Generator>,
    pub loads: Vec<Load>,
    pub controls: NetworkControlData,
    pub hvdc: HvdcModel,
    pub area_schedules: Vec<AreaSchedule>,
    pub facts_devices: Vec<FactsDevice>,
    pub metadata: NetworkMetadata,
    pub cim: NetworkCimData,
    pub interfaces: Vec<Interface>,
    pub flowgates: Vec<Flowgate>,
    pub nomograms: Vec<OperatingNomogram>,
    pub topology: Option<NodeBreakerTopology>,
    pub induction_machines: Vec<InductionMachine>,
    pub conditional_limits: BranchConditionalRatings,
    pub breaker_ratings: Vec<BreakerRating>,
    pub fixed_shunts: Vec<FixedShunt>,
    pub power_injections: Vec<PowerInjection>,
    pub market_data: NetworkMarketData,
}

A complete power system network model.

Holds all electrical equipment (buses, branches, generators, loads) and supplementary data (HVDC links, FACTS devices, flowgates, topology, etc.) needed to run power flow, OPF, contingency analysis, and dispatch.

Typically constructed by a parser in surge-io (MATPOWER, PSS/E RAW, CGMES, XIIDM) rather than built by hand. After parsing, call validate() to check invariants before passing the network to any solver.

Fields

name: String

System name.

base_mva: f64

System base power in MVA.

freq_hz: f64

Nominal system frequency in Hz. Defaults to 60 Hz (North America / Korea). Set to 50 Hz for Europe / most of Asia.

buses: Vec<Bus>

All buses in the network.

branches: Vec<Branch>

All branches (lines and transformers) in the network.

generators: Vec<Generator>

All generators in the network.

loads: Vec<Load>

All loads in the network.

controls: NetworkControlData

Discrete voltage control devices: switched shunts, OLTCs, and PARs.

hvdc: HvdcModel

Canonical HVDC namespace: point-to-point links and explicit DC grids.

area_schedules: Vec<AreaSchedule>

Area interchange records parsed from PSS/E RAW “AREA INTERCHANGE DATA”.

Metadata only — does not affect the Newton-Raphson solve directly.

facts_devices: Vec<FactsDevice>

FACTS device records parsed from PSS/E RAW “FACTS DEVICE DATA”.

Processed by surge_ac::facts_expansion::expand_facts() before solving to convert them into Generator and Branch modifications.

metadata: NetworkMetadata

Supplementary metadata: regions, owners, impedance corrections, and other reference data.

cim: NetworkCimData

CIM/CGMES supplementary data — metadata, assets, measurements, protection, grounding, geographic locations, and operational data.

Not used by power flow or OPF solvers. Populated by the CGMES parser and preserved for round-tripping and specialized analysis tools.

interfaces: Vec<Interface>

Transmission interfaces — sets of branches defining flow boundaries between areas. Enforced in DC-OPF as linear constraints on bus angles.

flowgates: Vec<Flowgate>

Flowgates — monitored elements under specific contingencies. All in-service flowgates are enforced in DC-OPF/SCED/SCUC as linear constraints on base-case monitored-element flow. Contingency flowgates carry pre-computed OTDF-adjusted limits in limit_mw. Dynamic OTDF constraint generation belongs in SCOPF.

nomograms: Vec<OperatingNomogram>

Operating nomograms: piecewise-linear inter-flowgate limit dependencies.

Each nomogram restricts the MW limit of one flowgate based on the real-time flow measured on a second “index” flowgate. Applied iteratively in SCED/SCUC (see DispatchOptions::max_nomogram_iter).

topology: Option<NodeBreakerTopology>

Physical node-breaker topology model.

When present, the network was built from a node-breaker source (CGMES, XIIDM node-breaker). The model retains the full physical hierarchy (substations, voltage levels, bays, connectivity nodes, switches) and the mapping from connectivity nodes to bus-branch buses.

When absent, the network is purely bus-branch (MATPOWER, PSS/E, XIIDM bus-breaker). All existing workflows are unaffected.

induction_machines: Vec<InductionMachine>

Induction machine (motor load) records from PSS/E RAW v35+ “INDUCTION MACHINE DATA”.

Stores steady-state equivalent-circuit parameters for each motor load. Empty for MATPOWER, IEEE-CDF, and PSS/E v33 cases.

conditional_limits: BranchConditionalRatings

Conditional thermal limits from CGMES ConditionalLimit objects.

Keyed by branch index. Each entry holds one or more condition-dependent ratings that override rate_a/rate_c when the user activates the matching condition via Network::apply_conditional_limits.

breaker_ratings: Vec<BreakerRating>

Circuit breaker ratings for fault duty comparison.

fixed_shunts: Vec<FixedShunt>

Fixed shunt equipment (preserves identity lost when baked into Bus.shunt_susceptance_mvar).

power_injections: Vec<PowerInjection>

Explicit fixed P/Q injections that must survive topology remap.

market_data: NetworkMarketData

Market and dispatch data: dispatchable loads, reserves, combined-cycle plants, outage schedules, and system-wide policies.

Implementations

impl Network

pub fn new(name: &str) -> Self

Create an empty network with the given name and default settings (base_mva = 100, freq_hz = 60).

pub fn apply_conditional_limits(&mut self, active_conditions: &[String])

Apply conditional thermal limits for the given active conditions.

For each branch that has conditional ratings matching any of the active_conditions, overwrites rate_a/rate_c with the most restrictive matching conditional value. Snapshots original ratings on first call so reset_conditional_limits can restore them.

pub fn reset_conditional_limits(&mut self)

Reset all conditional limits back to base thermal ratings.

pub fn storage_generators(&self) -> impl Iterator<Item = (usize, &Generator)>

Iterator over generators that have storage capability.

pub fn n_buses(&self) -> usize

Number of buses in the network.

pub fn n_branches(&self) -> usize

Number of branches in the network.

pub fn max_bus_number(&self) -> u32

Maximum external bus number in the network, or 0 if empty.

pub fn n_generators(&self) -> usize

Number of generators in the network (total, including out-of-service).

pub fn n_generators_in_service(&self) -> usize

Number of in-service generators.

pub fn validate_structure(&self) -> Result<(), NetworkError>

Validate the structural integrity of the network graph and identity references.

This checks that the model is internally connected the way the solver code expects, but does not try to prove solve-time numeric readiness.

pub fn validate_for_solve(&self) -> Result<(), NetworkError>

Validate the network for solver readiness.

This is the release-grade contract that callers should rely on before invoking power flow, OPF, or contingency analysis. Explicit unbounded optimization limits are permitted where the runtime already models them as open-ended bounds.

pub fn validate_for_dc_solve(&self) -> Result<(), NetworkError>

Validate the network for DC solver readiness.

DC studies do not consume the full AC voltage/reactive-control state, so this contract intentionally checks only the structural and numeric fields that the DC formulation actually uses.

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

Validate network invariants required before any solver is invoked.

This now means “solve-ready” rather than merely structurally coherent.

pub fn canonicalize_branch_circuit_ids(&mut self)

Fill missing canonical generator IDs with deterministic network-local IDs.

Existing non-empty IDs are preserved (after trimming surrounding whitespace). Only missing IDs are synthesized, and the generated values are stable for a fixed generator ordering.

pub fn canonicalize_generator_ids(&mut self)

pub fn canonicalize_load_ids(&mut self)

Fill missing load identifiers with deterministic network-local IDs.

Existing non-empty IDs are preserved after trimming surrounding whitespace. Generated IDs are stable for a fixed load ordering.

pub fn canonicalize_shunt_ids(&mut self)

Fill missing fixed-shunt identifiers with deterministic network-local IDs.

Existing non-empty IDs are preserved after trimming surrounding whitespace. Generated IDs are stable for a fixed shunt ordering.

pub fn canonicalize_switched_shunt_ids(&mut self)

Fill missing switched-shunt identifiers with deterministic network-local IDs.

pub fn canonicalize_hvdc_converter_ids(&mut self)

Fill missing explicit-DC converter identifiers with deterministic grid-local IDs.

pub fn canonicalize_dispatchable_load_ids(&mut self)

Fill missing dispatchable-load identifiers with deterministic network-local IDs.

Existing non-empty IDs are preserved after trimming surrounding whitespace. Generated IDs are stable for a fixed resource ordering and use the external bus number.

pub fn canonicalize_runtime_identities(&mut self)

Canonicalize source-facing identities that must be unambiguous at runtime.

This keeps solver and study code agnostic to source-format quirks such as reverse-direction duplicate branch records, stale PV bus tags on buses without an in-service regulating generator, or missing explicit generator / DC-converter identifiers.

pub fn bus_index_map(&self) -> HashMap<u32, usize>

Build a mapping from external bus number to internal 0-based index.

pub fn gen_index_by_id(&self) -> HashMap<String, usize>

Build a mapping from canonical generator ID to generator array index.

Duplicate IDs are deduplicated: only the first occurrence is kept.

pub fn find_gen_index_by_id(&self, id: &str) -> Option<usize>

Find the internal array index of the generator matching a canonical ID.

pub fn gen_index_map(&self) -> HashMap<(u32, Option<String>), usize>

Build a mapping from (bus, machine_id) to generator array index.

This is a source-format convenience lookup, not the canonical generator identity contract. Multiple generators at the same bus with the same machine ID are deduplicated: only the first occurrence is kept.

pub fn find_gen_index( &self, bus: u32, machine_id: Option<&str>, ) -> Option<usize>

Find the internal array index of the generator matching (bus, machine_id).

This is a source-format convenience lookup. When machine_id is None, the first generator (in array order) at that bus is returned regardless of its machine_id field.

pub fn branch_index_map(&self) -> HashMap<(u32, u32, String), usize>

Build a mapping from (from_bus, to_bus, circuit) to branch array index.

Parallel branches (same terminal buses, different circuit IDs) are all included. The first occurrence wins for duplicate keys.

pub fn find_branch_index( &self, from_bus: u32, to_bus: u32, circuit: &str, ) -> Option<usize>

Find the internal array index of the branch matching (from, to, circuit).

Matches either direction, preserving the circuit identifier.

pub fn load_index_by_id(&self) -> HashMap<String, usize>

Build a mapping from canonical load ID to load array index.

Duplicate IDs are deduplicated: only the first occurrence is kept.

pub fn find_load_index_by_id(&self, id: &str) -> Option<usize>

Find the internal array index of the load matching a canonical ID.

pub fn find_load_index(&self, bus: u32, id: Option<&str>) -> Option<usize>

Find the internal array index of the first load matching (bus, id).

When id is None, returns the first load at the bus.

pub fn shunt_index_by_id(&self) -> HashMap<String, usize>

Build a mapping from canonical fixed-shunt ID to shunt array index.

Duplicate IDs are deduplicated: only the first occurrence is kept.

pub fn find_shunt_index_by_id(&self, id: &str) -> Option<usize>

Find the internal array index of the fixed shunt matching a canonical ID.

pub fn find_shunt_index(&self, bus: u32, id: Option<&str>) -> Option<usize>

Find the internal array index of the first fixed shunt matching (bus, id).

When id is None, returns the first shunt at the bus.

pub fn find_hvdc_link_index_by_name(&self, name: &str) -> Option<usize>

Find the internal array index of the HVDC link matching its stable name.

pub fn find_pumped_hydro_index_by_name(&self, name: &str) -> Option<usize>

Find the internal array index of the pumped-hydro unit matching its stable name.

pub fn find_dispatchable_load_index( &self, resource_id: &str, bus: Option<u32>, ) -> Option<usize>

Find the internal array index of the dispatchable load matching (resource_id, bus).

pub fn find_combined_cycle_index_by_name(&self, name: &str) -> Option<usize>

Find the internal array index of the combined-cycle plant matching its stable name.

pub fn slack_bus_index(&self) -> Option<usize>

Find the internal index of the first slack bus in bus-array order.

All DC/PTDF/OPF solvers use this as the single angle reference — only the first slack bus is removed from the B’ matrix. AC NR excludes ALL slack buses from the Jacobian. Use slack_buses() to enumerate all of them; call validate_for_solve to enforce one slack bus per connected component.

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

Return references to all slack buses in the network.

For systems with distributed slack or multiple slack buses, this returns all of them. For single-slack systems, the returned Vec has one element. Use slack_bus_index when only the first (reference) bus is needed.

pub fn agc_participation_by_bus(&self) -> Vec<(usize, f64)>

Aggregate generator AGC participation factors by internal bus index.

Returns (internal_bus_index, total_participation_factor) pairs for buses that have at least one in-service generator with a positive agc_participation_factor. Weights are not normalized (the caller should normalize to sum to 1.0 if needed).

pub fn bus_load_p_mw(&self) -> Vec<f64>

Compute per-bus real power demand (MW) by summing in-service Load objects and subtracting in-service PowerInjection objects.

pub fn bus_load_q_mvar(&self) -> Vec<f64>

Compute per-bus reactive power demand (MVAr) by summing in-service Load objects and subtracting in-service PowerInjection objects.

pub fn bus_load_p_mw_with_map(&self, bus_map: &HashMap<u32, usize>) -> Vec<f64>

Compute per-bus real power demand (MW) with a pre-built bus index map.

pub fn bus_load_q_mvar_with_map( &self, bus_map: &HashMap<u32, usize>, ) -> Vec<f64>

Compute per-bus reactive power demand (MVAr) with a pre-built bus index map.

pub fn bus_p_injection_pu(&self) -> Vec<f64>

Compute real power injection at each bus in per-unit. P_inject[i] = (sum of Pg at bus i - Pd at bus i) / base_mva

Demand is computed from in-service Load objects (and PowerInjection objects, which act as negative load). Generator output is summed from in-service generators.

pub fn bus_p_injection_pu_with_map( &self, bus_map: &HashMap<u32, usize>, ) -> Vec<f64>

Compute real power injection at each bus in per-unit with a pre-built bus index map.

pub fn bus_q_injection_pu(&self) -> Vec<f64>

Compute reactive power injection at each bus in per-unit.

Demand is computed from in-service Load objects (and PowerInjection objects, which act as negative load). Generator output is summed from in-service generators.

pub fn bus_q_injection_pu_with_map( &self, bus_map: &HashMap<u32, usize>, ) -> Vec<f64>

Compute reactive power injection at each bus in per-unit with a pre-built bus index map.

pub fn total_generation_mw(&self) -> f64

Total real power generation (MW).

pub fn total_load_mw(&self) -> f64

Total real power demand (MW) from in-service Load objects.

pub fn rebuild_bus_state_from_explicit_equipment(&mut self)

Rebuild bus-level fixed shunt aggregates from explicit equipment.

This is the canonical path for node-breaker-backed networks where topology-sensitive state must survive bus splits and merges. Dynamic control overlays such as switched shunts or AC/DC controller injections are intentionally excluded; they are applied by solver/control loops.

Load demand is not stored on Bus; it lives exclusively on Load objects and is computed at solve time via bus_load_p_mw.

pub fn rebuild_bus_state_from_explicit_equipment_with_map( &mut self, bus_map: &HashMap<u32, usize>, )

Rebuild bus-level fixed shunt aggregates with a pre-built bus index map.

pub fn scale_loads(&mut self, factor: f64, area: Option<u32>)

Scale all loads by a factor. If area is Some, only loads in that area are affected.

Scales Load objects only. Real and reactive power are both multiplied by factor.

pub fn scale_loads_with_map( &mut self, factor: f64, area: Option<u32>, bus_map: &HashMap<u32, usize>, )

Scale all loads by a factor with a pre-built bus index map.

pub fn scale_generation(&mut self, factor: f64, area: Option<u32>)

Scale all in-service generator real power output by a factor.

Each generator’s p is multiplied by factor and then clamped to [pmin, pmax]. If area is Some, only generators connected to buses in that area are affected.

pub fn scale_generation_with_map( &mut self, factor: f64, area: Option<u32>, bus_map: &HashMap<u32, usize>, )

Scale all in-service generator real power output with a pre-built bus index map.

pub fn set_branch_sequence( &mut self, from_bus: u32, to_bus: u32, circuit: &str, r0: f64, x0: f64, b0: f64, ) -> bool

Set zero-sequence impedance for a branch identified by (from, to, circuit).

Returns true if the branch was found and updated, false otherwise.

pub fn get_branch_sequence( &self, from_bus: u32, to_bus: u32, circuit: &str, ) -> Option<(f64, f64, f64)>

Get zero-sequence impedance for a branch identified by (from, to, circuit).

Returns Some((r0, x0, b0)) if the branch exists and has zero-sequence data, None otherwise.

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

Formats the value using the given formatter.

impl Default for Network

fn default() -> Self

Returns the “default value” for a type.

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

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::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::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.