powerio_tx/

operations.rs

//! Model operations: deriving or rewriting a [`BalancedNetwork`].
//!
//! These are model-level transforms, distinct from the format readers/writers and
//! from the per unit [`to_normalized`](BalancedNetwork::to_normalized) form.
//! [`subset`](BalancedNetwork::subset) selects a subnetwork from a larger case;
//! [`merge_bus`](BalancedNetwork::merge_bus) collapses two buses into one (re-homing the
//! incident elements), and [`reduce_zero_impedance`](BalancedNetwork::reduce_zero_impedance)
//! removes jumper branches through [`merge_buses`](BalancedNetwork::merge_buses).
//! [`reduce_passthrough_buses`](BalancedNetwork::reduce_passthrough_buses) folds dummy-bus
//! line sections back into one equivalent branch.

use std::collections::HashSet;

mod subset;
pub use subset::BusSubset;
pub(crate) use subset::filter_connectivity;
use subset::filter_rows;

use serde_json::Value;

use crate::diagnostics::Diagnostic;
use crate::merge::{BusMergeRule, MergeSurvivor, ZeroImpedanceRule, kind_priority};
use crate::network::{
    BalancedNetwork, BalancedNetworkTables, Branch, Bus, BusId, BusType, Extras,
    IMPEDANCE_CORRECTION_APPLIED_EXTRA, IMPEDANCE_CORRECTION_NOMINAL_EXTRA,
    ImpedanceCorrectionVariable, SourceFormat, current_correction_nominal,
};

/// The nominal impedance an earlier impedance correction recorded in `extras`
/// for the present impedance `current`, or `current`, recorded there now. An
/// impedance edited since the correction wrote it is the new nominal.
fn recorded_nominal<T>(extras: &mut Extras, current: T) -> T
where
    T: PartialEq + serde::Serialize + serde::de::DeserializeOwned,
{
    if let Some(nominal) = current_correction_nominal(extras, &current) {
        return nominal;
    }
    let value = serde_json::to_value(&current).expect("an impedance serializes to JSON");
    extras.insert(IMPEDANCE_CORRECTION_NOMINAL_EXTRA.to_owned(), value);
    current
}

/// Record the corrected impedance an impedance correction wrote, so a later
/// edit of it is recognized.
fn record_applied<T: serde::Serialize>(extras: &mut Extras, applied: &T) {
    let value = serde_json::to_value(applied).expect("an impedance serializes to JSON");
    extras.insert(IMPEDANCE_CORRECTION_APPLIED_EXTRA.to_owned(), value);
}

/// `(a.0 + j·a.1)·(b.0 + j·b.1)`.
fn complex_product(a: (f64, f64), b: (f64, f64)) -> (f64, f64) {
    (a.0 * b.0 - a.1 * b.1, a.0 * b.1 + a.1 * b.0)
}

/// The endpoint of `b` other than `m` (assumes `m` is an endpoint).
fn other_end(b: &Branch, m: BusId) -> BusId {
    if b.from == m { b.to } else { b.from }
}

/// Combine two thermal ratings into the equivalent for a series pair. `0` means
/// "no limit" in the MATPOWER convention, so it yields to a finite rating; two
/// finite ratings give the more limiting (smaller) one.
fn combine_rate(a: f64, b: f64) -> f64 {
    match (a == 0.0, b == 0.0) {
        (true, _) => b,
        (_, true) => a,
        _ => a.min(b),
    }
}

/// What [`reduce_zero_impedance_with_report`](BalancedNetwork::reduce_zero_impedance_with_report)
/// did: the number of branches it removed and the merge's diagnostics, or
/// the error that left the network unchanged.
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct ZeroImpedanceReduction {
    /// Branches removed, the jumpers and any branch they shorted. Zero when
    /// the merge failed.
    pub removed: usize,
    /// What the merge changed, or the error that stopped it.
    pub diagnostics: Vec<Diagnostic>,
}

/// Which buses a [`subset`](BalancedNetwork::subset) keeps: inclusive ranges over area,
/// zone, base kV, and bus number, ANDed together. An unset (`None`) filter
/// matches every bus, so [`Selector::default`] selects the whole network.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Selector {
    /// Inclusive `(low, high)` area-number range.
    pub area: Option<(usize, usize)>,
    /// Inclusive `(low, high)` zone-number range.
    pub zone: Option<(usize, usize)>,
    /// Inclusive `(low, high)` base-kV range.
    pub base_kv: Option<(f64, f64)>,
    /// Inclusive `(low, high)` bus-number range.
    pub bus: Option<(usize, usize)>,
}

impl Selector {
    /// Whether `bus` satisfies every set filter.
    fn matches(&self, bus: &Bus) -> bool {
        fn in_usize(range: Option<(usize, usize)>, v: usize) -> bool {
            range.is_none_or(|(lo, hi)| lo <= v && v <= hi)
        }
        fn in_f64(range: Option<(f64, f64)>, v: f64) -> bool {
            range.is_none_or(|(lo, hi)| lo <= v && v <= hi)
        }
        in_usize(self.area, bus.area)
            && in_usize(self.zone, bus.zone)
            && in_f64(self.base_kv, bus.base_kv)
            && in_usize(self.bus, bus.id.0)
    }
}

impl 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. Detailed connectivity is filtered with the electrical
    /// tables; unassigned source topology remains, and an emptied voltage level
    /// is removed when no retained topology uses it.
    ///
    /// The result preserves normalized units for normalized input; otherwise it
    /// is a fresh [`SourceFormat::InMemory`] network. An empty `Selector` returns
    /// a clone-equivalent of the whole case,
    /// and a selector matching no bus returns an empty network.
    #[must_use]
    pub fn subset(&self, sel: &Selector, keep_boundary: bool) -> BalancedNetwork {
        let in_scope: HashSet<BusId> = self
            .buses()
            .iter()
            .filter(|b| sel.matches(b))
            .map(|b| b.id)
            .collect();
        self.subset_scope(&in_scope, keep_boundary, &HashSet::new())
            .network
    }

    /// Carve out the sub-network and source-to-result row maps on `buses`, such as one island of
    /// [`calc_islands`](BalancedNetwork::calc_islands): the
    /// [`subset`](BalancedNetwork::subset) rules with no boundary buses, so a
    /// branch, switch, HVDC line, or 3-winding transformer is kept when every
    /// bus it touches is in the set. Ids the network does not declare are
    /// ignored.
    ///
    /// A 3-winding transformer with a winding in the set is also kept when
    /// each of its other windings is dead: its bus is typed isolated, or the
    /// winding is out of service ([`crate::Transformer3W::winding_in_service`]).
    /// That winding's bus comes along as an isolated stub (tagged
    /// `extras["tie_bus"]`), so an island that such a transformer joins stays
    /// one island. The returned [`BusSubset`] maps every source table row to
    /// its result row, including stub buses and excluded injections.
    #[must_use]
    pub fn subset_buses(&self, buses: &std::collections::BTreeSet<BusId>) -> BusSubset {
        let in_scope: HashSet<BusId> = buses.iter().copied().collect();
        let isolated: HashSet<BusId> = self
            .buses()
            .iter()
            .filter(|bus| bus.kind == BusType::Isolated)
            .map(|bus| bus.id)
            .collect();
        let mut stubs = HashSet::new();
        for transformer in self.transformers_3w().iter().filter(|t| t.in_service) {
            let windings = || {
                transformer
                    .windings
                    .iter()
                    .zip(transformer.winding_in_service())
            };
            let touches = windings().any(|(w, _)| in_scope.contains(&w.bus));
            let dead_outside = windings().all(|(w, connected)| {
                in_scope.contains(&w.bus) || !connected || isolated.contains(&w.bus)
            });
            if touches && dead_outside {
                stubs.extend(
                    windings()
                        .map(|(w, _)| w.bus)
                        .filter(|bus| !in_scope.contains(bus)),
                );
            }
        }
        self.subset_scope(&in_scope, false, &stubs)
    }

    /// [`subset`](BalancedNetwork::subset) over a bus set already chosen.
    /// `stubs` are out-of-scope buses kept as isolated tie buses.
    // A flat filter pipeline, one stanza per element table; splitting it would add
    // indirection without clarity.
    #[expect(clippy::too_many_lines)]
    fn subset_scope(
        &self,
        in_scope: &HashSet<BusId>,
        keep_boundary: bool,
        stubs: &HashSet<BusId>,
    ) -> BusSubset {
        // Boundary: the out-of-scope endpoint of any branch/HVDC with exactly one
        // endpoint in scope, plus the stubs.
        let mut boundary: HashSet<BusId> = stubs.clone();
        if keep_boundary {
            let mut edge = |a: BusId, b: BusId| match (in_scope.contains(&a), in_scope.contains(&b))
            {
                (true, false) => {
                    boundary.insert(b);
                }
                (false, true) => {
                    boundary.insert(a);
                }
                _ => {}
            };
            for br in self.branches() {
                edge(br.from, br.to);
            }
            for d in self.hvdc() {
                edge(d.from, d.to);
            }
        }
        let kept: HashSet<BusId> = in_scope.union(&boundary).copied().collect();

        let (mut buses, bus_rows) = filter_rows(self.buses(), |b| kept.contains(&b.id));
        for bus in &mut buses {
            if boundary.contains(&bus.id) {
                bus.extras.insert("tie_bus".into(), Value::Bool(true));
            }
            if stubs.contains(&bus.id) {
                bus.kind = BusType::Isolated;
            }
        }

        // Build the source-to-result maps in the same pass that selects rows.
        // Injections on retained boundary/stub buses are deliberately excluded.
        let (loads, load_rows) = filter_rows(self.loads(), |v| in_scope.contains(&v.bus));
        let (mut shunts, shunt_rows) = filter_rows(self.shunts(), |v| in_scope.contains(&v.bus));
        let (static_var_compensators, static_var_compensator_rows) =
            filter_rows(self.static_var_compensators(), |v| {
                in_scope.contains(&v.bus)
            });
        let (mut generators, generator_rows) =
            filter_rows(self.generators(), |v| in_scope.contains(&v.bus));
        let (storage, storage_rows) = filter_rows(self.storage(), |v| in_scope.contains(&v.bus));
        let ends_kept = |from: BusId, to: BusId| kept.contains(&from) && kept.contains(&to);
        let (mut branches, branch_rows) = filter_rows(self.branches(), |v| ends_kept(v.from, v.to));
        let (switches, switch_rows) = filter_rows(self.switches(), |v| ends_kept(v.from, v.to));
        let (hvdc, hvdc_rows) = filter_rows(self.hvdc(), |v| ends_kept(v.from, v.to));
        let (mut transformers_3w, transformer_3w_rows) = filter_rows(self.transformers_3w(), |v| {
            v.windings.iter().all(|w| kept.contains(&w.bus))
        });

        // Clear control references that point outside the kept set.
        for br in &mut branches {
            if let Some(c) = &mut br.control
                && c.controlled_bus.is_some_and(|b| !kept.contains(&b))
            {
                c.controlled_bus = None;
            }
        }
        for transformer in &mut transformers_3w {
            for winding in &mut transformer.windings {
                if let Some(control) = &mut winding.control
                    && control
                        .controlled_bus
                        .is_some_and(|bus| !kept.contains(&bus))
                {
                    control.controlled_bus = None;
                }
            }
        }
        for sh in &mut shunts {
            if let Some(c) = &mut sh.control
                && c.control_bus.is_some_and(|b| !kept.contains(&b))
            {
                c.control_bus = None;
            }
        }
        for g in &mut generators {
            if g.regulated_bus.is_some_and(|b| !kept.contains(&b)) {
                g.regulated_bus = None;
            }
        }

        // Keep the area records still referenced by a kept bus (clearing a dangling
        // area-slack), plus the global solver settings. The bus `area` numbers alone
        // can't carry the interchange schedule or the solver tolerances, so dropping
        // them would silently lose data a PSS/E/PSLF write of the subset emits.
        let kept_area_numbers: HashSet<usize> = buses.iter().map(|b| b.area).collect();
        let (mut areas, area_rows) =
            filter_rows(self.areas(), |a| kept_area_numbers.contains(&a.number));
        for area in &mut areas {
            if area.slack_bus.is_some_and(|b| !kept.contains(&b)) {
                area.slack_bus = None;
            }
        }

        let mut net = BalancedNetwork::from_tables(BalancedNetworkTables {
            name: format!("{} (subset)", self.name()),
            base_mva: self.base_mva(),
            base_frequency: self.base_frequency(),
            geo: self.geo().clone(),
            case_metadata: self.case_metadata().clone(),
            detailed_connectivity: self.detailed_connectivity().clone(),
            generated_uids: self.generated_uids().clone(),
            buses: buses.into(),
            loads: loads.into(),
            shunts: shunts.into(),
            static_var_compensators: static_var_compensators.into(),
            branches: branches.into(),
            switches: switches.into(),
            generators: generators.into(),
            storage: storage.into(),
            hvdc: hvdc.into(),
            transformers_3w: transformers_3w.into(),
            areas: areas.into(),
            solver: self.solver().clone(),
            source_format: if self.is_normalized() {
                SourceFormat::Normalized
            } else {
                SourceFormat::InMemory
            },
        });
        subset::filter_connectivity(self, &mut net);
        debug_assert!(
            net.validate().is_ok(),
            "subset produced a dangling reference"
        );
        BusSubset {
            network: net,
            bus_rows,
            load_rows,
            shunt_rows,
            static_var_compensator_rows,
            branch_rows,
            switch_rows,
            generator_rows,
            storage_rows,
            hvdc_rows,
            transformer_3w_rows,
            area_rows,
        }
    }

    /// 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, switches, 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.
    /// [`merge_buses`](BalancedNetwork::merge_buses) is the rule driven merge
    /// that also reports what it removed.
    pub fn merge_bus(&mut self, into: BusId, from: BusId) {
        if into == from {
            return;
        }
        self.remap_buses(|bus| if bus == from { into } else { bus });
        self.branches_mut().retain(|b| b.from != b.to);
        self.switches_mut().retain(|s| s.from != s.to);
        self.hvdc_mut().retain(|d| d.from != d.to);

        // Promote the surviving bus kind, then drop the merged bus.
        let from_kind = self.buses().iter().find(|b| b.id == from).map(|b| b.kind);
        self.buses_mut().retain(|b| b.id != from);
        if let (Some(fk), Some(into_bus)) = (
            from_kind,
            self.buses_mut().iter_mut().find(|b| b.id == into),
        ) && kind_priority(fk) > kind_priority(into_bus.kind)
        {
            into_bus.kind = fk;
        }
        // The topology changed, so the retained source text is stale.
    }

    /// Rewrite every element's bus references through `map`, one pass per
    /// table: load, shunt, static var compensator, generator, storage, branch,
    /// switch, and HVDC buses; generator regulated buses; switched shunt,
    /// transformer, and winding control buses; three winding transformer
    /// windings; and area swing buses. The bus table and the detailed
    /// connectivity are the caller's to keep consistent. A table none of
    /// whose references change is not copied.
    pub(crate) fn remap_buses(&mut self, map: impl Fn(BusId) -> BusId) {
        fn remap_table<T: Clone>(
            table: &mut std::sync::Arc<Vec<T>>,
            touches: impl Fn(&T) -> bool,
            apply: impl FnMut(&mut T),
        ) {
            if table.iter().any(touches) {
                std::sync::Arc::make_mut(table).iter_mut().for_each(apply);
            }
        }
        let moved = |bus: BusId| map(bus) != bus;
        let moved_opt = |bus: Option<BusId>| bus.is_some_and(moved);
        let set = |bus: &mut BusId| *bus = map(*bus);
        let set_opt = |bus: &mut Option<BusId>| {
            if let Some(bus) = bus {
                *bus = map(*bus);
            }
        };
        let tables = self.tables_mut();
        remap_table(&mut tables.loads, |l| moved(l.bus), |l| set(&mut l.bus));
        remap_table(
            &mut tables.shunts,
            |s| moved(s.bus) || moved_opt(s.control.as_ref().and_then(|c| c.control_bus)),
            |s| {
                set(&mut s.bus);
                if let Some(control) = s.control.as_mut() {
                    set_opt(&mut control.control_bus);
                }
            },
        );
        remap_table(
            &mut tables.static_var_compensators,
            |svc| moved(svc.bus),
            |svc| set(&mut svc.bus),
        );
        remap_table(
            &mut tables.generators,
            |g| moved(g.bus) || moved_opt(g.regulated_bus),
            |g| {
                set(&mut g.bus);
                set_opt(&mut g.regulated_bus);
            },
        );
        remap_table(&mut tables.storage, |s| moved(s.bus), |s| set(&mut s.bus));
        remap_table(
            &mut tables.branches,
            |b| {
                moved(b.from)
                    || moved(b.to)
                    || moved_opt(b.control.as_ref().and_then(|c| c.controlled_bus))
            },
            |b| {
                set(&mut b.from);
                set(&mut b.to);
                if let Some(control) = b.control.as_mut() {
                    set_opt(&mut control.controlled_bus);
                }
            },
        );
        remap_table(
            &mut tables.switches,
            |s| moved(s.from) || moved(s.to),
            |s| {
                set(&mut s.from);
                set(&mut s.to);
            },
        );
        remap_table(
            &mut tables.hvdc,
            |d| moved(d.from) || moved(d.to),
            |d| {
                set(&mut d.from);
                set(&mut d.to);
            },
        );
        remap_table(
            &mut tables.transformers_3w,
            |t| {
                t.windings.iter().any(|w| {
                    moved(w.bus) || moved_opt(w.control.as_ref().and_then(|c| c.controlled_bus))
                })
            },
            |t| {
                for w in &mut t.windings {
                    set(&mut w.bus);
                    if let Some(control) = w.control.as_mut() {
                        set_opt(&mut control.controlled_bus);
                    }
                }
            },
        );
        remap_table(
            &mut tables.areas,
            |a| moved_opt(a.slack_bus),
            |a| set_opt(&mut a.slack_bus),
        );
    }

    /// 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.
    ///
    /// This is [`merge_buses`](BalancedNetwork::merge_buses) under
    /// [`ZeroImpedanceRule::ImpedanceMagnitude`] and [`MergeSurvivor::FromBus`]
    /// with closed switches left alone, applied in place; prefer `merge_buses`,
    /// which also returns the bus map, the removed elements, and diagnostics.
    /// A threshold that is negative or not finite merges nothing.
    ///
    /// 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
    /// kept, since merging would collapse that transformer onto one node.
    ///
    /// When the merge fails, for example because a jumper shorts an ideal
    /// transformer with a nonunity tap, nothing is merged and this returns
    /// zero; [`reduce_zero_impedance_with_report`](Self::reduce_zero_impedance_with_report)
    /// reports why.
    pub fn reduce_zero_impedance(&mut self, threshold: f64) -> usize {
        self.reduce_zero_impedance_with_report(threshold).removed
    }

    /// [`reduce_zero_impedance`](Self::reduce_zero_impedance) with the merge's
    /// diagnostics. When the merge fails the network is left unchanged,
    /// `removed` is zero, and the diagnostics hold the error under its own
    /// code, so a failure is no longer indistinguishable from a network with
    /// no jumpers.
    pub fn reduce_zero_impedance_with_report(&mut self, threshold: f64) -> ZeroImpedanceReduction {
        let rule = BusMergeRule::new(
            false,
            Some(ZeroImpedanceRule::ImpedanceMagnitude(threshold)),
        )
        .with_survivor(MergeSurvivor::FromBus);
        match self.merge_buses(&rule) {
            Ok(merge) => {
                let removed = merge.removed_branches.len();
                *self = merge.network;
                ZeroImpedanceReduction {
                    removed,
                    diagnostics: merge.diagnostics,
                }
            }
            Err(error) => ZeroImpedanceReduction {
                removed: 0,
                diagnostics: vec![Diagnostic::of(
                    error.code(),
                    format!("zero impedance reduction merged nothing: {error}"),
                )],
            },
        }
    }

    /// 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 reduce_passthrough_buses(&mut self) -> usize {
        let mut collapsed = 0;
        // Re-scan after each fold: the equivalent branch becomes a section for the
        // next bus in a dummy chain, and the bus list shrinks.
        while let Some(mid) = self
            .buses()
            .iter()
            .map(|b| b.id)
            .find(|&m| self.is_passthrough(m))
        {
            self.collapse_passthrough(mid);
            collapsed += 1;
        }
        collapsed
    }

    /// Whether `m` is a collapsible degree-2 passthrough bus (see
    /// [`reduce_passthrough_buses`](BalancedNetwork::reduce_passthrough_buses)).
    fn is_passthrough(&self, m: BusId) -> bool {
        let Some(bus) = self.buses().iter().find(|b| b.id == m) else {
            return false;
        };
        if bus.kind == BusType::Ref {
            return false;
        }
        if self.loads().iter().any(|l| l.bus == m)
            || self.generators().iter().any(|g| g.bus == m)
            || self.shunts().iter().any(|s| s.bus == m)
            || self
                .static_var_compensators()
                .iter()
                .any(|svc| svc.bus == m)
            || self.storage().iter().any(|s| s.bus == m)
            || self.hvdc().iter().any(|d| d.from == m || d.to == m)
        {
            return false;
        }
        if self
            .transformers_3w()
            .iter()
            .any(|t| t.windings.iter().any(|w| w.bus == m))
        {
            return false;
        }
        if self.areas().iter().any(|a| a.slack_bus == Some(m)) {
            return false;
        }
        let controlled = self
            .branches()
            .iter()
            .any(|b| b.control.as_ref().and_then(|c| c.controlled_bus) == Some(m));
        let winding_controlled = self.transformers_3w().iter().any(|transformer| {
            transformer.windings.iter().any(|winding| {
                winding
                    .control
                    .as_ref()
                    .and_then(|control| control.controlled_bus)
                    == Some(m)
            })
        });
        let regulated = self
            .shunts()
            .iter()
            .any(|s| s.control.as_ref().and_then(|c| c.control_bus) == Some(m));
        let gen_regulated = self.generators().iter().any(|g| g.regulated_bus == Some(m));
        if controlled || winding_controlled || regulated || gen_regulated {
            return false;
        }
        let incident: Vec<&Branch> = self
            .branches()
            .iter()
            .filter(|b| b.from == m || b.to == m)
            .collect();
        if incident.len() != 2 {
            return false;
        }
        let a = other_end(incident[0], m);
        let c = other_end(incident[1], m);
        incident.iter().all(|b| !b.is_transformer() && b.in_service) && a != m && c != m && a != c
    }

    /// Fold the two line sections at passthrough bus `m` into one equivalent branch
    /// and remove `m`. The caller has already checked [`is_passthrough`].
    fn collapse_passthrough(&mut self, m: BusId) {
        let mut sections: Vec<Branch> = Vec::new();
        self.branches_mut().retain(|b| {
            if b.from == m || b.to == m {
                sections.push(b.clone());
                false
            } else {
                true
            }
        });
        debug_assert_eq!(sections.len(), 2, "passthrough bus must have two sections");
        let (s1, s2) = (&sections[0], &sections[1]);
        // Intersect the two sections' angle windows, but never emit an inverted
        // (empty) limit: two disjoint windows give angmin > angmax, which an OPF
        // angle-difference constraint reads as infeasible. Disjoint windows fall
        // back to the union so folding a multi-section line never turns a feasible
        // case infeasible. (Whether series sections should intersect vs sum their
        // windows is a modeling choice; this only fixes the invalid-range case.)
        let mut angmin = s1.angmin.max(s2.angmin);
        let mut angmax = s1.angmax.min(s2.angmax);
        if angmin > angmax {
            angmin = s1.angmin.min(s2.angmin);
            angmax = s1.angmax.max(s2.angmax);
        }
        self.branches_mut().push(Branch {
            name: None,
            from: other_end(s1, m),
            to: other_end(s2, m),
            r: s1.r + s2.r,
            x: s1.x + s2.x,
            b: s1.calc_total_charging_b() + s2.calc_total_charging_b(),
            charging: None,
            rate_a: combine_rate(s1.rate_a, s2.rate_a),
            rate_b: combine_rate(s1.rate_b, s2.rate_b),
            rate_c: combine_rate(s1.rate_c, s2.rate_c),
            rating_sets: Vec::new(),
            current_ratings: None,
            tap: 0.0,
            shift: 0.0,
            in_service: true,
            angmin,
            angmax,
            control: None,
            solution: None,
            uid: None,
            route: None,
            extras: Extras::new(),
        });
        self.buses_mut().retain(|b| b.id != m);
        // The topology changed, so the retained source text is stale.
    }

    /// Scale every transformer's series impedance by its impedance correction
    /// table, at the winding's present turns ratio or phase shift, returning
    /// the number of two winding transformers and three winding correction
    /// targets (windings or pairs, according to ZCOD) scaled.
    ///
    /// A two winding transformer's factor multiplies `r + jx`. A three winding
    /// transformer's factor for a winding multiplies that winding's star
    /// impedance, and the pairwise impedances are restated from the scaled
    /// star. With PSS/E `ZCOD=1`, TAB1/2/3 instead scale nominal Z12/Z23/Z31
    /// at the sole winding with a nonfixed control (even if disabled).
    /// A ZCOD=1 transformer with no unique adjustable winding is skipped;
    /// the RAW reader refuses that ambiguous configuration.
    /// The first call records each scaled transformer's nominal
    /// impedance under `extras["impedance_correction_nominal"]`, and every
    /// call scales that nominal value: a repeated call changes nothing, and a
    /// call after a tap or shift change evaluates the table there. The
    /// corrected impedance is recorded under
    /// `extras["impedance_correction_applied"]`; an impedance edited after
    /// the call no longer matches it and becomes the new nominal value. The
    /// PSS/E writer states the nominal impedance beside the table, as the
    /// format does.
    pub fn apply_impedance_correction(&mut self) -> usize {
        // A normalized network states phase shifts in radians; the tables
        // state degrees.
        let angle_scale = if self.is_normalized() {
            crate::normalize::RAD_TO_DEG
        } else {
            1.0
        };
        let mut scaled = 0;
        for branch in self.branches_mut().iter_mut() {
            let Some(correction) = branch.impedance_correction() else {
                continue;
            };
            let at = match correction.variable {
                ImpedanceCorrectionVariable::Angle => branch.shift * angle_scale,
                _ => branch.calc_effective_tap(),
            };
            let Some(factor) = correction.calc_factor(at) else {
                continue;
            };
            let [r, x] = recorded_nominal(&mut branch.extras, [branch.r, branch.x]);
            (branch.r, branch.x) = complex_product((r, x), factor);
            record_applied(&mut branch.extras, &[branch.r, branch.x]);
            scaled += 1;
        }
        for transformer in self.transformers_3w_mut().iter_mut() {
            let pairwise_mode =
                transformer.extras.get("psse_zcod").and_then(Value::as_i64) == Some(1);
            let controlling = transformer.impedance_correction_control_winding();
            // The RAW reader refuses this ambiguous configuration. If controls
            // were edited afterward, leave this transformer unchanged and
            // contribute zero to the aggregate applied count.
            if pairwise_mode && controlling.is_none() {
                continue;
            }
            let factors: [Option<(f64, f64)>; 3] = std::array::from_fn(|winding| {
                let correction = transformer.winding_impedance_correction(winding)?;
                let setting = if pairwise_mode {
                    controlling.unwrap_or(winding)
                } else {
                    winding
                };
                let w = &transformer.windings[setting];
                let at = match correction.variable {
                    ImpedanceCorrectionVariable::Angle => w.shift * angle_scale,
                    _ => w.tap,
                };
                correction.calc_factor(at)
            });
            if factors.iter().all(Option::is_none) {
                continue;
            }
            let pairwise = transformer.z.map(|z| [z.r, z.x]);
            let nominal = recorded_nominal(&mut transformer.extras, pairwise);
            if pairwise_mode {
                for ((z, [r, x]), factor) in transformer.z.iter_mut().zip(nominal).zip(factors) {
                    (z.r, z.x) = if let Some(factor) = factor {
                        scaled += 1;
                        complex_product((r, x), factor)
                    } else {
                        (r, x)
                    };
                }
                let applied = transformer.z.map(|z| [z.r, z.x]);
                record_applied(&mut transformer.extras, &applied);
                continue;
            }
            let [z12, z23, z31] = nominal;
            let star = |a: [f64; 2], b: [f64; 2], c: [f64; 2]| {
                ((a[0] + b[0] - c[0]) / 2.0, (a[1] + b[1] - c[1]) / 2.0)
            };
            let mut stars = [
                star(z12, z31, z23),
                star(z12, z23, z31),
                star(z23, z31, z12),
            ];
            for (star, factor) in stars.iter_mut().zip(factors) {
                if let Some(factor) = factor {
                    *star = complex_product(*star, factor);
                    scaled += 1;
                }
            }
            for (pair, (a, b)) in [(0, 1), (1, 2), (2, 0)].into_iter().enumerate() {
                transformer.z[pair].r = stars[a].0 + stars[b].0;
                transformer.z[pair].x = stars[a].1 + stars[b].1;
            }
            let applied = transformer.z.map(|z| [z.r, z.x]);
            record_applied(&mut transformer.extras, &applied);
        }
        scaled
    }

    /// Retype to [`BusType::Isolated`] every bus with no in-service electrical
    /// connection — no in-service incident branch, closed switch, 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.
    pub fn retype_isolated_buses(&mut self) -> usize {
        let mut connected: HashSet<BusId> = HashSet::new();
        for br in self.branches().iter().filter(|b| b.in_service) {
            connected.insert(br.from);
            connected.insert(br.to);
        }
        for sw in self.switches().iter().filter(|sw| sw.closed) {
            connected.insert(sw.from);
            connected.insert(sw.to);
        }
        for d in self.hvdc().iter().filter(|d| d.in_service) {
            connected.insert(d.from);
            connected.insert(d.to);
        }
        for t in self.transformers_3w().iter().filter(|t| t.in_service) {
            for (w, in_service) in t.windings.iter().zip(t.winding_in_service()) {
                if in_service {
                    connected.insert(w.bus);
                }
            }
        }
        let mut retyped = 0;
        for b in self.buses_mut() {
            if b.kind != BusType::Isolated && !connected.contains(&b.id) {
                b.kind = BusType::Isolated;
                retyped += 1;
            }
        }
        // Only a real retype invalidates the source; a no-op call stays lossless.

        retyped
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::network::{
        Area, BusType, Extras, Generator, GeneratorEnergySource, Impedance, Load, Transformer3W,
        Winding,
    };

    fn bus(id: usize, area: usize, base_kv: f64) -> Bus {
        Bus {
            id: BusId(id),
            kind: BusType::Pq,
            vm: 1.0,
            va: 0.0,
            base_kv,
            vmax: 1.1,
            vmin: 0.9,
            evhi: None,
            evlo: None,
            area,
            zone: 1,
            name: None,
            uid: None,
            location: None,
            extras: Extras::new(),
        }
    }

    fn line(from: usize, to: usize) -> Branch {
        Branch {
            name: None,
            from: BusId(from),
            to: BusId(to),
            r: 0.0,
            x: 0.1,
            b: 0.0,
            charging: None,
            rate_a: 0.0,
            rate_b: 0.0,
            rate_c: 0.0,
            rating_sets: Vec::new(),
            current_ratings: None,
            tap: 0.0,
            shift: 0.0,
            in_service: true,
            angmin: -360.0,
            angmax: 360.0,
            control: None,
            solution: None,
            uid: None,
            route: None,
            extras: Extras::new(),
        }
    }

    fn load(bus: usize) -> Load {
        Load {
            bus: BusId(bus),
            p: 10.0,
            q: 5.0,
            voltage_model: None,
            in_service: true,
            uid: None,
            extras: Extras::new(),
        }
    }

    /// Two area-1 buses (1, 2) and one area-2 bus (3); a line within area 1 and a
    /// line crossing into area 2.
    fn two_area_net() -> BalancedNetwork {
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 2, 230.0)],
            vec![line(1, 2), line(2, 3)],
        );
        net.loads_mut().push(load(1));
        net.loads_mut().push(load(3));
        net
    }

    fn transformer_3w(a: usize, b: usize, c: usize) -> Transformer3W {
        let winding = |bus| Winding {
            bus: BusId(bus),
            tap: 1.0,
            shift: 0.0,
            nominal_kv: 0.0,
            rate_a: 0.0,
            rate_b: 0.0,
            rate_c: 0.0,
            control: None,
        };
        let imp = Impedance {
            r: 0.0,
            x: 0.1,
            base_mva: 100.0,
        };
        Transformer3W {
            windings: [winding(a), winding(b), winding(c)],
            z: [imp, imp, imp],
            star_vm: 1.0,
            star_va: 0.0,
            mag_g: 0.0,
            mag_b: 0.0,
            in_service: true,
            name: None,
            uid: None,
            extras: Extras::new(),
        }
    }

    fn gen_regulating(bus: usize, regulated: usize) -> Generator {
        Generator {
            bus: BusId(bus),
            energy_source: GeneratorEnergySource::default(),
            pg: 10.0,
            qg: 0.0,
            pmax: 100.0,
            pmin: 0.0,
            qmax: 50.0,
            qmin: -50.0,
            vg: 1.0,
            mbase: 100.0,
            in_service: true,
            cost: None,
            caps: Default::default(),
            voltage_regulation_on: true,
            regulating_terminal: None,
            regulated_bus: Some(BusId(regulated)),
            active_power_control: None,
            uid: None,
        }
    }

    #[test]
    fn subset_clears_a_regulated_bus_outside_the_kept_set() {
        // A generator on in-scope bus 1 regulates bus 3, which the area filter drops.
        let mut net = two_area_net();
        net.generators_mut().push(gen_regulating(1, 3));
        let sel = Selector {
            area: Some((1, 1)),
            ..Selector::default()
        };
        let sub = net.subset(&sel, false);
        assert_eq!(sub.generators().len(), 1);
        assert_eq!(
            sub.generators()[0].regulated_bus,
            None,
            "the dropped remote regulated bus is cleared, not left dangling"
        );
        sub.validate().unwrap();
    }

    #[test]
    fn merge_bus_remaps_regulated_bus_and_area_slack() {
        let mut net = two_area_net();
        net.generators_mut().push(gen_regulating(1, 3)); // gen on bus 1 regulates bus 3
        net.areas_mut().push(Area {
            number: 1,
            slack_bus: Some(BusId(3)),
            net_interchange: 0.0,
            tolerance: 0.0,
            name: None,
            uid: None,
            area_type: None,
        });
        net.merge_bus(BusId(2), BusId(3)); // bus 3 merges into bus 2
        assert_eq!(
            net.generators()[0].regulated_bus,
            Some(BusId(2)),
            "the regulated bus follows the merge"
        );
        assert_eq!(
            net.areas()[0].slack_bus,
            Some(BusId(2)),
            "the area swing follows the merge"
        );
        net.validate().unwrap();
    }

    #[test]
    fn reduce_passthrough_keeps_a_generator_regulated_bus() {
        // Bus 2 is a degree-2 junction with no injection, but a generator on bus 1
        // regulates it, so it is not an inert passthrough.
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), line(2, 3)],
        );
        net.generators_mut().push(gen_regulating(1, 2));
        assert_eq!(net.reduce_passthrough_buses(), 0);
        assert_eq!(net.buses().len(), 3);
        net.validate().unwrap();
    }

    #[test]
    fn subset_by_area_drops_out_of_scope_buses_and_cut_branches() {
        let net = two_area_net();
        let sel = Selector {
            area: Some((1, 1)),
            ..Selector::default()
        };
        let sub = net.subset(&sel, false);

        // Buses 1, 2 kept; bus 3 (area 2) dropped along with the crossing line.
        assert_eq!(sub.buses().len(), 2);
        assert!(sub.buses().iter().all(|b| b.area == 1));
        assert_eq!(sub.branches().len(), 1, "only the intra-area line survives");
        assert_eq!(sub.loads().len(), 1, "the area-2 load is dropped");
        sub.validate().unwrap();
    }

    #[test]
    fn subset_keep_boundary_pulls_in_the_tie_bus() {
        let net = two_area_net();
        let sel = Selector {
            area: Some((1, 1)),
            ..Selector::default()
        };
        let sub = net.subset(&sel, true);

        // Bus 3 is pulled in as a tie bus so the crossing line keeps both ends.
        assert_eq!(sub.buses().len(), 3);
        assert_eq!(sub.branches().len(), 2);
        let tie = sub.buses().iter().find(|b| b.id == BusId(3)).unwrap();
        assert_eq!(tie.extras.get("tie_bus"), Some(&Value::Bool(true)));
        // The tie bus is a stub: its load is not pulled in.
        assert_eq!(sub.loads().len(), 1);
        sub.validate().unwrap();
    }

    #[test]
    fn empty_selector_keeps_everything() {
        let net = two_area_net();
        let sub = net.subset(&Selector::default(), false);
        assert_eq!(sub.buses().len(), net.buses().len());
        assert_eq!(sub.branches().len(), net.branches().len());
    }

    #[test]
    fn base_kv_range_filters_by_voltage() {
        let mut net = two_area_net();
        net.buses_mut()[2].base_kv = 115.0; // bus 3 to a different voltage class
        let sel = Selector {
            base_kv: Some((200.0, 300.0)),
            ..Selector::default()
        };
        let sub = net.subset(&sel, false);
        assert_eq!(sub.buses().len(), 2, "only the 230 kV buses match");
    }

    #[test]
    fn merge_bus_rehomes_elements_and_drops_the_connecting_branch() {
        let mut net = two_area_net(); // buses 1,2,3; lines 1-2, 2-3; loads on 1, 3
        net.merge_bus(BusId(2), BusId(3));

        assert_eq!(net.buses().len(), 2, "bus 3 removed");
        assert!(net.buses().iter().all(|b| b.id != BusId(3)));
        assert_eq!(
            net.branches().len(),
            1,
            "the 2-3 line collapsed to a self-loop"
        );
        assert_eq!(net.branches()[0].from, BusId(1));
        assert_eq!(net.branches()[0].to, BusId(2));
        // Both loads survive; the one on bus 3 moved to bus 2.
        assert_eq!(net.loads().len(), 2);
        assert!(net.loads().iter().any(|l| l.bus == BusId(2)));
        net.validate().unwrap();
    }

    #[test]
    fn merge_bus_keeps_the_stronger_bus_kind() {
        let mut net = two_area_net();
        net.buses_mut()[2].kind = BusType::Ref; // bus 3 is the slack
        net.merge_bus(BusId(2), BusId(3)); // merge the slack into the PQ bus 2
        let two = net.buses().iter().find(|b| b.id == BusId(2)).unwrap();
        assert_eq!(two.kind, BusType::Ref, "the slack designation is not lost");
    }

    #[test]
    fn reduce_passthrough_folds_a_multi_section_line() {
        // A 1-2-3-4 chain where 2 and 3 are dummy junctions; ratings 100 / 80 /
        // unlimited along the sections.
        let mut s1 = line(1, 2);
        s1.rate_a = 100.0;
        let mut s2 = line(2, 3);
        s2.rate_a = 80.0;
        let s3 = line(3, 4); // rate_a 0 == no limit
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![
                bus(1, 1, 230.0),
                bus(2, 1, 230.0),
                bus(3, 1, 230.0),
                bus(4, 1, 230.0),
            ],
            vec![s1, s2, s3],
        );

        let removed = net.reduce_passthrough_buses();
        assert_eq!(removed, 2, "both dummy buses collapse");
        assert_eq!(net.buses().len(), 2);
        assert!(
            net.buses()
                .iter()
                .all(|b| b.id == BusId(1) || b.id == BusId(4))
        );
        assert_eq!(net.branches().len(), 1, "one equivalent branch");
        let eq = &net.branches()[0];
        assert_eq!(
            [eq.from, eq.to].iter().copied().collect::<HashSet<_>>(),
            [BusId(1), BusId(4)].into_iter().collect::<HashSet<_>>(),
        );
        assert!((eq.x - 0.3).abs() < 1e-9, "series reactance sums");
        assert!(
            (eq.rate_a - 80.0).abs() < 1e-9,
            "the more limiting finite rating wins"
        );
        net.validate().unwrap();
    }

    #[test]
    fn reduce_passthrough_keeps_a_bus_with_injection() {
        // Bus 2 is degree 2 but carries a load, so it is not inert.
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), line(2, 3)],
        );
        net.loads_mut().push(load(2));
        assert_eq!(net.reduce_passthrough_buses(), 0);
        assert_eq!(net.buses().len(), 3);
    }

    #[test]
    fn reduce_passthrough_does_not_fold_across_a_transformer() {
        // Section 2-3 is a transformer, so bus 2 is a real terminal, not a junction.
        let mut xfmr = line(2, 3);
        xfmr.tap = 1.0;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), xfmr],
        );
        assert_eq!(net.reduce_passthrough_buses(), 0);
        assert_eq!(net.buses().len(), 3);
    }

    #[test]
    fn retype_isolated_marks_stranded_buses() {
        // Bus 3 has no incident branch.
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2)],
        );
        assert_eq!(net.retype_isolated_buses(), 1);
        let three = net.buses().iter().find(|b| b.id == BusId(3)).unwrap();
        assert_eq!(three.kind, BusType::Isolated);
        // The connected buses keep their kind.
        let one = net.buses().iter().find(|b| b.id == BusId(1)).unwrap();
        assert_eq!(one.kind, BusType::Pq);
        net.validate().unwrap();
    }

    #[test]
    fn retype_isolated_judges_in_service_equipment_only() {
        // The only branch is out of service, so both of its ends are stranded.
        let mut br = line(1, 2);
        br.in_service = false;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0)],
            vec![br],
        );
        assert_eq!(net.retype_isolated_buses(), 2);
        assert!(net.buses().iter().all(|b| b.kind == BusType::Isolated));
    }

    #[test]
    fn retype_isolated_counts_a_closed_switch_as_a_connection() {
        // Bus 3 is reached only through a closed switch; bus 4 only through an
        // open one.
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![
                bus(1, 1, 230.0),
                bus(2, 1, 230.0),
                bus(3, 1, 230.0),
                bus(4, 1, 230.0),
            ],
            vec![line(1, 2)],
        );
        net.switches_mut().extend([
            crate::network::Switch::new(BusId(2), BusId(3), true),
            crate::network::Switch::new(BusId(2), BusId(4), false),
        ]);
        assert_eq!(net.retype_isolated_buses(), 1);
        let kind = |id| net.buses().iter().find(|b| b.id == BusId(id)).unwrap().kind;
        assert_eq!(kind(3), BusType::Pq);
        assert_eq!(kind(4), BusType::Isolated);
    }

    #[test]
    fn retype_isolated_is_idempotent() {
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2)],
        );
        assert_eq!(net.retype_isolated_buses(), 1);
        assert_eq!(net.retype_isolated_buses(), 0, "second pass is a no-op");
    }

    #[test]
    fn reduce_zero_impedance_collapses_jumpers_only() {
        // Buses 1-2 a real line, 2-3 a zero-impedance jumper.
        let mut jumper = line(2, 3);
        jumper.x = 0.0;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), jumper],
        );
        net.loads_mut().push(load(3));

        let removed = net.reduce_zero_impedance(1e-9);
        assert_eq!(removed, 1, "only the jumper is collapsed");
        assert_eq!(net.buses().len(), 2);
        assert_eq!(net.branches().len(), 1, "the real 1-2 line remains");
        assert!(
            net.loads().iter().any(|l| l.bus == BusId(2)),
            "load re-homed"
        );
        net.validate().unwrap();
    }

    #[test]
    fn reduce_zero_impedance_keeps_the_from_bus() {
        // The jumper runs from bus 3 to bus 2, so bus 3 survives although bus
        // 2 has the smaller id.
        let mut jumper = line(3, 2);
        jumper.x = 0.0;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), jumper],
        );
        net.loads_mut().push(load(2));

        assert_eq!(net.reduce_zero_impedance(1e-9), 1);
        let ids: Vec<BusId> = net.buses().iter().map(|b| b.id).collect();
        assert_eq!(ids, [BusId(1), BusId(3)]);
        assert_eq!(net.branches()[0].to, BusId(3));
        assert_eq!(net.loads()[0].bus, BusId(3));
        net.validate().unwrap();
    }

    #[test]
    fn reduce_zero_impedance_keeps_an_open_jumper() {
        // A zero-impedance jumper between 2 and 3 is out of service: it models an
        // open switch, so its endpoints stay separate and must not be merged.
        let mut jumper = line(2, 3);
        jumper.x = 0.0;
        jumper.in_service = false;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), jumper],
        );

        let removed = net.reduce_zero_impedance(1e-9);
        assert_eq!(removed, 0, "an open jumper is left in place");
        assert_eq!(net.buses().len(), 3);
        assert_eq!(net.branches().len(), 2);
        net.validate().unwrap();
    }

    #[test]
    fn a_failed_zero_impedance_reduction_is_reported() {
        // The jumper 1-2 would short an ideal off-nominal transformer between
        // the same buses, which has no finite shunt equivalent, so the merge
        // fails and nothing is merged.
        let mut jumper = line(1, 2);
        jumper.x = 0.0;
        let mut ideal = line(1, 2);
        ideal.x = 0.0;
        ideal.tap = 1.05;
        let mut second = line(2, 3);
        second.x = 0.0;
        let network = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![jumper, ideal, second],
        );

        let mut old = network.clone();
        assert_eq!(old.reduce_zero_impedance(1e-9), 0);
        assert_eq!(old.buses().len(), 3);
        assert_eq!(old.branches().len(), 3);

        let mut reported = network.clone();
        let report = reported.reduce_zero_impedance_with_report(1e-9);
        assert_eq!(report.removed, 0);
        assert_eq!(reported.buses().len(), 3, "nothing is merged");
        assert_eq!(reported.branches().len(), 3);
        let codes: Vec<&str> = report.diagnostics.iter().map(Diagnostic::code).collect();
        assert_eq!(codes, ["BUILD.BRANCH.ZERO_IMPEDANCE"]);
        assert!(
            report.diagnostics[0]
                .message()
                .contains("zero impedance reduction merged nothing"),
            "{}",
            report.diagnostics[0].message()
        );
    }

    #[test]
    fn a_zero_impedance_reduction_reports_the_merge() {
        let mut jumper = line(2, 3);
        jumper.x = 0.0;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 230.0), bus(3, 1, 230.0)],
            vec![line(1, 2), jumper],
        );
        let report = net.reduce_zero_impedance_with_report(1e-9);
        assert_eq!(report.removed, 1);
        let codes: Vec<&str> = report.diagnostics.iter().map(Diagnostic::code).collect();
        assert_eq!(codes, ["CANONICALIZE.MERGE.ZERO_IMPEDANCE"]);
    }

    #[test]
    fn reduce_zero_impedance_keeps_a_3w_winding_pair() {
        // A zero-impedance jumper between buses 2 and 3, which are two windings of
        // the same 3-winding transformer. Merging them would short two windings
        // onto one node, so the jumper is left in place.
        let mut jumper = line(2, 3);
        jumper.x = 0.0;
        let mut net = BalancedNetwork::in_memory(
            "net",
            100.0,
            vec![bus(1, 1, 230.0), bus(2, 1, 138.0), bus(3, 1, 13.8)],
            vec![line(1, 2), jumper],
        );
        net.transformers_3w_mut().push(transformer_3w(1, 2, 3));

        let removed = net.reduce_zero_impedance(1e-9);
        assert_eq!(
            removed, 0,
            "a jumper across two windings of one 3W transformer is kept"
        );
        assert_eq!(net.buses().len(), 3);
        net.validate().unwrap();
    }
}