powerio/

network.rs

//! Format neutral balanced network model.
//!
//! Readers map source formats into a [`BalancedNetwork`], and writers map a network to
//! target formats. Loads and shunts have separate tables, so formats can retain
//! several elements at one bus. MATPOWER demand and shunt fields become those
//! records during parsing. [`IndexedNetwork`](crate::IndexedNetwork) provides
//! the dense analysis view used by matrix builders.
//!
//! A network can retain its source bytes and [`SourceFormat`] for same format
//! writing. Each element also has an [`Extras`] map for source fields not named
//! by the typed model.
//!
//! Formats represent different data. Cross format writers report unsupported
//! fields rather than claiming an exact conversion.

use std::collections::BTreeMap;
use std::sync::Arc;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::geo::{GeoMeta, Location};
use crate::{Error, Result};

/// Source format fields the neutral model does not name, kept for round trips
/// and cross format conversion. Keys are field names; values are JSON scalars.
pub type Extras = BTreeMap<String, Value>;

/// System base frequency in hertz when a format records none. Power networks run
/// at 50 or 60 Hz; 60 is the default for the formats (MATPOWER, PowerModels,
/// egret) that carry no frequency field.
pub const DEFAULT_BASE_FREQUENCY: f64 = 60.0;

/// serde default for [`BalancedNetwork::base_frequency`], so JSON written before the
/// field existed still deserializes (the C ABI and Julia bridge ride on the JSON
/// transport).
fn default_base_frequency() -> f64 {
    DEFAULT_BASE_FREQUENCY
}

/// A source bus ID, preserved from the input format.
///
/// MATPOWER IDs are 1-based and can contain gaps. They are distinct from the
/// zero based dense indices produced by
/// [`IndexedNetwork::bus_index`](crate::IndexedNetwork::bus_index). JSON stores
/// this type as an integer.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(transparent)]
pub struct BusId(pub usize);

impl BusId {
    #[must_use]
    pub const fn new(id: usize) -> Self {
        Self(id)
    }
}

impl std::fmt::Display for BusId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(f)
    }
}

/// Bus type per MATPOWER convention: 1=PQ, 2=PV, 3=ref/slack, 4=isolated.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "UPPERCASE")]
#[repr(u8)]
#[non_exhaustive]
pub enum BusType {
    Pq = 1,
    Pv = 2,
    Ref = 3,
    Isolated = 4,
}

impl BusType {
    /// Map a MATPOWER bus-type code to the enum; unknown codes fall back to PQ.
    pub(crate) fn from_f64(v: f64) -> Self {
        match v as i32 {
            2 => Self::Pv,
            3 => Self::Ref,
            4 => Self::Isolated,
            _ => Self::Pq,
        }
    }

    /// The canonical short name (`"PQ"`, `"PV"`, `"REF"`, `"ISOLATED"`), shared
    /// by the bindings so their bus-type strings can't drift.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Pq => "PQ",
            Self::Pv => "PV",
            Self::Ref => "REF",
            Self::Isolated => "ISOLATED",
        }
    }
}

/// A generator cost curve (`mpc.gencost` row).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct GenCost {
    /// 1 = piecewise linear, 2 = polynomial.
    pub model: u8,
    pub startup: f64,
    pub shutdown: f64,
    /// Number of cost coefficients (polynomial) or breakpoints (piecewise).
    pub ncost: usize,
    /// Raw coefficients, highest order first for the polynomial model:
    /// `[c_{k-1}, …, c1, c0]`.
    pub coeffs: Vec<f64>,
}

impl GenCost {
    /// Build a cost row from the values carried after `ncost`.
    ///
    /// Polynomial rows (`model == 2`) store `ncost` coefficients. Piecewise
    /// linear rows (`model == 1`) store flattened `(x, y)` breakpoint pairs, so
    /// `ncost` is half the coefficient count. Use [`GenCost::with_ncost`] for
    /// malformed source rows or callers that need to preserve an explicit
    /// `ncost`.
    #[must_use]
    pub fn new(model: u8, startup: f64, shutdown: f64, coeffs: Vec<f64>) -> Self {
        let ncost = if model == 1 {
            coeffs.len() / 2
        } else {
            coeffs.len()
        };
        Self {
            model,
            startup,
            shutdown,
            ncost,
            coeffs,
        }
    }

    #[must_use]
    pub fn with_ncost(
        model: u8,
        startup: f64,
        shutdown: f64,
        ncost: usize,
        coeffs: Vec<f64>,
    ) -> Self {
        Self {
            model,
            startup,
            shutdown,
            ncost,
            coeffs,
        }
    }

    /// `(q, c)` for the quadratic cost `½ q p² + c p` from a polynomial
    /// (model 2) row. MATPOWER stores `c2 p² + c1 p + c0`, so `q = 2·c2` and
    /// `c = c1`. Linear rows (`ncost == 2`) give `q = 0`. Piecewise (model 1)
    /// or cubic and higher return `None`.
    pub fn quadratic(&self) -> Option<(f64, f64)> {
        self.quadratic_with_constant().map(|(q, c, _)| (q, c))
    }

    /// `(q, c, c0)` for the quadratic cost `½ q p² + c p + c0` from a
    /// polynomial (model 2) row, keeping the constant term that
    /// [`quadratic`](Self::quadratic) drops. Linear rows (`ncost == 2`) give
    /// `q = 0`; constant rows (`ncost == 1`) give `q = c = 0`. Piecewise
    /// (model 1) or cubic and higher return `None`.
    pub fn quadratic_with_constant(&self) -> Option<(f64, f64, f64)> {
        if self.model != 2 {
            return None;
        }
        // Reject a row whose coefficient slice is shorter than `ncost` claims,
        // rather than reading the wrong powers by position.
        if self.coeffs.len() < self.ncost {
            return None;
        }
        // Matches on the stated arity, so a cubic row is refused even when its
        // leading coefficient is zero. `quadratic_with_constant_tol` is the
        // reader that lowers the order first.
        match self.ncost {
            3 => Some((2.0 * self.coeffs[0], self.coeffs[1], self.coeffs[2])),
            2 => Some((0.0, self.coeffs[0], self.coeffs[1])),
            1 => Some((0.0, 0.0, self.coeffs[0])),
            _ => None,
        }
    }

    /// Largest leading polynomial coefficient that
    /// [`quadratic_with_constant_tol`](Self::quadratic_with_constant_tol)
    /// reads as a rounding artifact of the source, not as a term of the curve.
    pub const LEADING_COEFF_TOL: f64 = 1e-12;

    /// `(q, c, c0)` as [`quadratic_with_constant`](Self::quadratic_with_constant)
    /// gives it, after the leading coefficients at or below `tol` come off the
    /// row.
    ///
    /// A model 2 row often carries a leading coefficient near `1e-17`, which
    /// the source produced by rounding. Such a row states a linear curve and
    /// reads as a quadratic one. Pass
    /// [`LEADING_COEFF_TOL`](Self::LEADING_COEFF_TOL) to strip the artifact,
    /// or `0.0` to strip an exact zero alone.
    pub fn quadratic_with_constant_tol(&self, tol: f64) -> Option<(f64, f64, f64)> {
        if self.model != 2 {
            return None;
        }
        if self.coeffs.len() < self.ncost {
            return None;
        }
        let row = &self.coeffs[..self.ncost];
        let mut first = 0;
        while first + 1 < row.len() && row[first].abs() <= tol {
            first += 1;
        }
        match row.len() - first {
            3 => Some((2.0 * row[first], row[first + 1], row[first + 2])),
            2 => Some((0.0, row[first], row[first + 1])),
            1 => Some((0.0, 0.0, row[first])),
            _ => None,
        }
    }
}

/// Which format a [`BalancedNetwork`] was read from. Drives the same format byte exact
/// echo on write.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub enum SourceFormat {
    Matpower,
    PowerModelsJson,
    EgretJson,
    Psse,
    PowerWorld,
    PandapowerJson,
    /// Read from a GE PSLF `.epc` case. Same source text is retained, so a
    /// same-format write echoes it byte-for-byte; a cross-format or
    /// source-dropped write goes through the `.epc` serializer
    /// ([`write_pslf`](crate::write_pslf)).
    Pslf,
    /// Read from a PowerWorld `.pwb` binary case. Read only: there is no
    /// `.pwb` writer and no retained source text, so writing goes through
    /// another format's writer.
    PowerWorldBinary,
    /// Built in memory, for example from synth or an edited case; no source text.
    InMemory,
    /// A normalized derived form ([`BalancedNetwork::to_normalized`]): per unit, radians,
    /// filtered, source bus ids preserved. Distinct from
    /// [`InMemory`](SourceFormat::InMemory) so consumers can tell a per unit
    /// product from a raw in memory network; it has no source text and a different
    /// unit basis than a parsed network.
    Normalized,
    /// Read back from a gridfm-datakit Parquet dataset (the ML→classical bridge,
    /// `powerio-matrix`'s `read_gridfm_dataset`). A lossy, power flow complete
    /// reconstruction with no retained source text: original bus ids are
    /// synthesized `1..n`, per element load/shunt granularity is folded to one
    /// synthetic element per bus, and HVDC/storage/piecewise costs are absent.
    Gridfm,
    /// Read from a PyPSA CSV folder. This is a folder format rather than a
    /// single retained text document, so same-format writes are canonicalized.
    PypsaCsv,
    /// Read from an ARPA-E GO Challenge 3 JSON input document. The source is a
    /// unit commitment data set; the neutral transmission model keeps a static
    /// first interval network and retains the source text for the full data.
    Goc3Json,
    /// Read from a Surge native JSON document.
    SurgeJson,
    /// Read from one raw JSON document in a DeepMind OPFData release. The
    /// source carries both solver initial values and a solution. The balanced
    /// model represents the solved snapshot and retains the source for an
    /// exact write back to the same format.
    DeepMindOpfDataJson,
}

impl SourceFormat {
    /// Stable lowercase token for provenance and reporting (package origin,
    /// CLI summaries, Python bindings). The match is exhaustive here so a new
    /// variant fails compilation at the one mapping instead of silently
    /// reporting "unknown" from a downstream wildcard copy.
    #[must_use]
    pub fn name(self) -> &'static str {
        match self {
            SourceFormat::Matpower => "matpower",
            SourceFormat::PowerModelsJson => "powermodels-json",
            SourceFormat::EgretJson => "egret-json",
            SourceFormat::Psse => "psse",
            SourceFormat::PowerWorld => "powerworld",
            SourceFormat::PandapowerJson => "pandapower-json",
            SourceFormat::Pslf => "pslf",
            SourceFormat::PowerWorldBinary => "powerworld-pwb",
            SourceFormat::InMemory => "in-memory",
            SourceFormat::Normalized => "normalized",
            SourceFormat::Gridfm => "gridfm",
            SourceFormat::PypsaCsv => "pypsa-csv",
            SourceFormat::Goc3Json => "goc3-json",
            SourceFormat::SurgeJson => "surge-json",
            SourceFormat::DeepMindOpfDataJson => "opfdata-json",
        }
    }
}

/// A balanced network with stable source bus IDs and separate element tables.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct BalancedNetwork {
    pub name: String,
    pub base_mva: f64,
    /// System base frequency in hertz (50 or 60). Threaded through the formats
    /// that record it (PSS/E `BASFRQ`, pandapower `f_hz`) and defaulted to
    /// [`DEFAULT_BASE_FREQUENCY`] for the rest. Load-bearing for any
    /// reactance↔henry conversion (pandapower line charging) and reported as a
    /// fidelity loss when a non-default value writes to a format with no
    /// frequency field.
    #[serde(default = "default_base_frequency")]
    pub base_frequency: f64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub geo: Option<GeoMeta>,
    pub buses: Vec<Bus>,
    pub loads: Vec<Load>,
    pub shunts: Vec<Shunt>,
    pub branches: Vec<Branch>,
    #[serde(default)]
    pub switches: Vec<Switch>,
    pub generators: Vec<Generator>,
    pub storage: Vec<Storage>,
    pub hvdc: Vec<Hvdc>,
    /// Three-winding transformers, kept as typed records rather than folded into
    /// `branches`, so a star point and the per-winding data survive a round trip.
    /// `#[serde(default)]` so JSON written before the field existed still
    /// deserializes. [`IndexedNetwork`](crate::IndexedNetwork) lowers each
    /// in-service record into a star bus plus three branches (via
    /// [`Transformer3W::star_expansion`]) before building any matrix, so a
    /// 3-winding transformer does appear in `Y_bus`/connectivity; the canonical
    /// model keeps the typed record for round-trip fidelity.
    #[serde(default)]
    pub transformers_3w: Vec<Transformer3W>,
    /// Area records: scheduled interchange and per-area swing bus. Distinct from
    /// the bare `area` number on each [`Bus`]; this is the area's metadata, which
    /// every conversion dropped before. `#[serde(default)]` so older JSON still
    /// deserializes.
    #[serde(default)]
    pub areas: Vec<Area>,
    /// Solver / solution-control metadata when the source carries it, else `None`.
    /// `#[serde(default)]` so older JSON still deserializes.
    #[serde(default)]
    pub solver: Option<SolverParams>,
    pub source_format: SourceFormat,
    /// Raw source text, when read from a textual format; enables a byte-exact
    /// same-format round-trip. `Arc<String>` (not `Arc<str>`) is deliberate: a
    /// reader that already owns the buffer (the MATPOWER file path) moves it in
    /// with no second copy of the whole file. The trade is one extra indirection
    /// per access; don't "simplify" it back to `Arc<str>`, which would reintroduce
    /// the copy this avoids.
    ///
    /// Skipped in JSON: the structured tables are the transport, not the raw
    /// echo, and skipping also keeps serde's `rc` feature out of the build. A
    /// `from_json` round-trip returns this as `None`.
    #[serde(skip)]
    pub source: Option<Arc<String>>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Bus {
    /// Stable bus id (1-based in MATPOWER; preserved verbatim).
    pub id: BusId,
    pub kind: BusType,
    /// Voltage magnitude (p.u.).
    pub vm: f64,
    /// Voltage angle (degrees).
    pub va: f64,
    pub base_kv: f64,
    pub vmax: f64,
    pub vmin: f64,
    /// Emergency (short-term) voltage band, set only when the source states one
    /// distinct from the normal [`vmax`](Bus::vmax)/[`vmin`](Bus::vmin) band (PSS/E
    /// `EVHI`/`EVLO`). `None` means the emergency band equals the normal band, so
    /// read `evhi.unwrap_or(vmax)` / `evlo.unwrap_or(vmin)`. `#[serde(default)]` so
    /// JSON written before the fields existed still deserializes.
    #[serde(default)]
    pub evhi: Option<f64>,
    #[serde(default)]
    pub evlo: Option<f64>,
    pub area: usize,
    pub zone: usize,
    pub name: Option<String>,
    /// Stable row identity for `.pio.json` payloads and operating point updates:
    /// the source record uid where the format defines one (GOC3), synthesized at
    /// package build otherwise. `#[serde(default)]` so JSON written before the
    /// field existed still deserializes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    /// Optional bus coordinates in the network coordinate space.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub location: Option<Location>,
    pub extras: Extras,
}

impl Bus {
    #[must_use]
    pub fn new(id: BusId, kind: BusType, base_kv: f64) -> Self {
        Self {
            id,
            kind,
            vm: 1.0,
            va: 0.0,
            base_kv,
            vmax: 1.1,
            vmin: 0.9,
            evhi: None,
            evlo: None,
            area: 1,
            zone: 1,
            name: None,
            uid: None,
            location: None,
            extras: Extras::new(),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Load {
    pub bus: BusId,
    /// Active demand (MW).
    pub p: f64,
    /// Reactive demand (MVAr).
    pub q: f64,
    /// Voltage dependence, when the source states one. `None` is constant power.
    #[serde(default)]
    pub voltage_model: Option<LoadVoltageModel>,
    pub in_service: bool,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Load {
    #[must_use]
    pub fn new(bus: BusId, p: f64, q: f64) -> Self {
        Self {
            bus,
            p,
            q,
            voltage_model: None,
            in_service: true,
            uid: None,
            extras: Extras::new(),
        }
    }
}

/// Voltage dependence for a transmission load.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "kind", rename_all = "snake_case")]
#[non_exhaustive]
pub enum LoadVoltageModel {
    /// Explicit constant power marker.
    ConstantPower,
    /// ZIP load split in source units. The three active parts sum to
    /// [`Load::p`], and the three reactive parts sum to [`Load::q`].
    Zip {
        p_constant_power: f64,
        q_constant_power: f64,
        p_constant_current: f64,
        q_constant_current: f64,
        p_constant_impedance: f64,
        q_constant_impedance: f64,
        #[serde(default)]
        v_nom: Option<f64>,
        /// Source load type code, when a format has one (PSS/E `ID`/`LOADTYPE`
        /// style metadata).
        #[serde(default)]
        load_type: Option<i32>,
        /// Source scaling factor, when a format has one.
        #[serde(default)]
        scaling: Option<f64>,
    },
    /// Exponential voltage model: `P = p * (V / v_nom)^gamma_p`,
    /// `Q = q * (V / v_nom)^gamma_q`.
    Exponential {
        p: f64,
        q: f64,
        #[serde(default)]
        v_nom: Option<f64>,
        gamma_p: f64,
        gamma_q: f64,
    },
}

impl LoadVoltageModel {
    #[must_use]
    pub fn has_non_matpower_fields(&self) -> bool {
        match self {
            Self::ConstantPower => false,
            Self::Zip {
                p_constant_current,
                q_constant_current,
                p_constant_impedance,
                q_constant_impedance,
                v_nom,
                load_type,
                scaling,
                ..
            } => {
                *p_constant_current != 0.0
                    || *q_constant_current != 0.0
                    || *p_constant_impedance != 0.0
                    || *q_constant_impedance != 0.0
                    || v_nom.is_some()
                    || load_type.is_some()
                    || scaling.is_some()
            }
            Self::Exponential { .. } => true,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Shunt {
    pub bus: BusId,
    /// Shunt conductance (MW at V = 1 p.u.).
    pub g: f64,
    /// Shunt susceptance (MVAr at V = 1 p.u.). For a switched shunt this is the
    /// initial (steady-state) value within the [`control`](Shunt::control) blocks.
    pub b: f64,
    pub in_service: bool,
    /// Switching-control data when this is a switched (adjustable) shunt; `None`
    /// for a fixed shunt. `#[serde(default)]` so JSON written before the field
    /// existed still deserializes.
    #[serde(default)]
    pub control: Option<SwitchedShuntControl>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Shunt {
    #[must_use]
    pub fn new(bus: BusId, g: f64, b: f64) -> Self {
        Self {
            bus,
            g,
            b,
            in_service: true,
            control: None,
            uid: None,
            extras: Extras::new(),
        }
    }
}

/// How a switched shunt adjusts its susceptance. Maps to the PSS/E `MODSW` code.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum SwitchedShuntMode {
    /// Fixed at its initial susceptance, no automatic switching (`MODSW` 0).
    Locked,
    /// Continuous adjustment within the block range (`MODSW` 1).
    Continuous,
    /// Discrete adjustment in fixed steps (`MODSW` 2 and up).
    Discrete,
}

/// One block of a switched shunt: `steps` equal increments of susceptance `b`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct ShuntBlock {
    pub steps: u32,
    /// Susceptance increment per step (MVAr at V = 1 p.u.).
    pub b: f64,
}

impl ShuntBlock {
    #[must_use]
    pub const fn new(steps: u32, b: f64) -> Self {
        Self { steps, b }
    }
}

/// Switching-control data for a switched shunt ([`Shunt::control`]): the mode,
/// the regulated voltage band and bus, the reactive-range percentage, and the
/// adjustable susceptance blocks. The shunt's [`b`](Shunt::b) is the initial
/// value within the blocks' total range.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct SwitchedShuntControl {
    pub mode: SwitchedShuntMode,
    /// Regulated voltage band (per unit).
    pub vhigh: f64,
    pub vlow: f64,
    /// The regulated bus; `None` means the shunt regulates its own bus.
    pub control_bus: Option<BusId>,
    /// Percent of the controlled device's reactive range to apply (PSS/E `RMPCT`).
    pub rmpct: f64,
    pub blocks: Vec<ShuntBlock>,
}

impl SwitchedShuntControl {
    #[must_use]
    pub fn new(mode: SwitchedShuntMode, vhigh: f64, vlow: f64, blocks: Vec<ShuntBlock>) -> Self {
        Self {
            mode,
            vhigh,
            vlow,
            control_bus: None,
            rmpct: 100.0,
            blocks,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Branch {
    pub from: BusId,
    pub to: BusId,
    /// Series resistance (p.u.).
    pub r: f64,
    /// Series reactance (p.u.).
    pub x: f64,
    /// MATPOWER compatible total line charging susceptance (p.u.). This is the
    /// legacy total projection; when [`charging`](Branch::charging) is present,
    /// per terminal admittance is canonical and this field is compatibility data.
    pub b: f64,
    /// Per terminal shunt admittance (p.u.). If absent, derive symmetric
    /// susceptance from [`b`](Branch::b).
    #[serde(default)]
    pub charging: Option<BranchCharging>,
    pub rate_a: f64,
    pub rate_b: f64,
    pub rate_c: f64,
    /// Additional MVA rating sets beyond A/B/C. Matrix builders continue to use
    /// `rate_a` unless they opt into one of these named sets.
    #[serde(default)]
    pub rating_sets: Vec<BranchRatingSet>,
    /// Current ratings, when the source distinguishes them from MVA ratings.
    #[serde(default)]
    pub current_ratings: Option<BranchCurrentRatings>,
    /// Tap ratio, MATPOWER convention: 0 means "no tap" (a line), treated as 1.
    pub tap: f64,
    /// Phase shift (degrees).
    pub shift: f64,
    pub in_service: bool,
    pub angmin: f64,
    pub angmax: f64,
    /// Regulating-transformer control data, when this branch is a transformer
    /// under automatic tap or phase control. `None` for lines and for fixed-ratio
    /// transformers. `#[serde(default)]` so JSON written before the field existed
    /// still deserializes.
    #[serde(default)]
    pub control: Option<TransformerControl>,
    /// Solved branch flow values, when present in a case snapshot.
    #[serde(default)]
    pub solution: Option<BranchSolution>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    /// Polyline route in the network's coordinate space (`BalancedNetwork.geo`),
    /// present only when a source provides intermediate geometry; endpoint
    /// only rendering derives from the bus locations. `#[serde(default)]` so
    /// JSON written before the field existed still deserializes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub route: Option<Vec<Location>>,
    pub extras: Extras,
}

/// Extra branch MVA rating set beyond the canonical A/B/C columns.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct BranchRatingSet {
    pub name: String,
    pub rate_mva: f64,
}

impl BranchRatingSet {
    #[must_use]
    pub fn new(name: impl Into<String>, rate_mva: f64) -> Self {
        Self {
            name: name.into(),
            rate_mva,
        }
    }
}

/// Per terminal branch shunt admittance in p.u. This is the canonical
/// physical branch shunt model when present.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct BranchCharging {
    pub g_fr: f64,
    pub b_fr: f64,
    pub g_to: f64,
    pub b_to: f64,
}

impl BranchCharging {
    #[must_use]
    pub const fn new(g_fr: f64, b_fr: f64, g_to: f64, b_to: f64) -> Self {
        Self {
            g_fr,
            b_fr,
            g_to,
            b_to,
        }
    }

    #[must_use]
    pub fn from_total_b(b: f64) -> Self {
        Self {
            g_fr: 0.0,
            b_fr: b / 2.0,
            g_to: 0.0,
            b_to: b / 2.0,
        }
    }

    #[must_use]
    pub fn total_b(self) -> f64 {
        self.b_fr + self.b_to
    }

    #[must_use]
    pub fn total_g(self) -> f64 {
        self.g_fr + self.g_to
    }

    #[must_use]
    pub fn is_matpower_symmetric(self) -> bool {
        self.g_fr.abs() <= f64::EPSILON
            && self.g_to.abs() <= f64::EPSILON
            && (self.b_fr - self.b_to).abs() <= f64::EPSILON
    }
}

/// Current limits for a branch, in source units.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct BranchCurrentRatings {
    pub c_rating_a: f64,
    pub c_rating_b: f64,
    pub c_rating_c: f64,
}

impl BranchCurrentRatings {
    #[must_use]
    pub const fn new(c_rating_a: f64, c_rating_b: f64, c_rating_c: f64) -> Self {
        Self {
            c_rating_a,
            c_rating_b,
            c_rating_c,
        }
    }
}

/// Solved branch terminal flows in MW/MVAr.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct BranchSolution {
    pub pf: f64,
    pub qf: f64,
    pub pt: f64,
    pub qt: f64,
}

impl BranchSolution {
    #[must_use]
    pub const fn new(pf: f64, qf: f64, pt: f64, qt: f64) -> Self {
        Self { pf, qf, pt, qt }
    }
}

impl Branch {
    #[must_use]
    pub fn new(from: BusId, to: BusId, r: f64, x: f64) -> Self {
        Self {
            from,
            to,
            r,
            x,
            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(),
        }
    }

    /// Effective tap ratio (0 ⇒ 1).
    #[must_use]
    pub fn effective_tap(&self) -> f64 {
        if self.tap == 0.0 { 1.0 } else { self.tap }
    }

    /// [`effective_tap`](Self::effective_tap) for a builder that divides by it,
    /// which the remap of an exact 0.0 does not make safe on its own.
    ///
    /// # Errors
    /// [`Error::DegenerateTap`] under
    /// [`MIN_DIVISIBLE_MAGNITUDE`](crate::dc::MIN_DIVISIBLE_MAGNITUDE), where a
    /// tap scales an admittance past anything a matrix can carry. `row` only
    /// labels the error.
    pub fn divisible_tap(&self, row: usize) -> Result<f64> {
        let tap = self.effective_tap();
        if !tap.is_finite() || tap.abs() < crate::dc::MIN_DIVISIBLE_MAGNITUDE {
            return Err(Error::DegenerateTap { row, tap });
        }
        Ok(tap)
    }

    /// Per terminal shunt admittance, deriving the legacy symmetric MATPOWER
    /// charging model when the richer field is absent.
    #[must_use]
    pub fn terminal_charging(&self) -> BranchCharging {
        self.charging
            .unwrap_or_else(|| BranchCharging::from_total_b(self.b))
    }

    /// Series admittance `(g, b) = (r, −x) / (r² + x²)` of the branch pi
    /// model, the primitive beside [`effective_tap`](Self::effective_tap) and
    /// [`terminal_charging`](Self::terminal_charging). `Ok(None)` for a zero
    /// impedance branch — one whose impedance magnitude is under
    /// [`MIN_DIVISIBLE_MAGNITUDE`](crate::dc::MIN_DIVISIBLE_MAGNITUDE); the
    /// caller decides whether that is a skip or an error.
    ///
    /// # Errors
    /// [`Error::NonFiniteSusceptance`] when `r`/`x` are NaN/Inf, so a bad
    /// value cannot write NaN or a silent zero downstream. `row` only labels
    /// the error.
    pub fn series_admittance(&self, row: usize) -> Result<Option<(f64, f64)>> {
        series_admittance_of(self.r, self.x, row)
    }

    /// Apparent power bound, per unit, for a branch the source left unrated
    /// (`rate_a == 0`, which reads as unlimited). `angle_window_rad` is the
    /// widest angle difference the branch may hold, in radians. That window
    /// and the two terminal voltage ceilings give the widest voltage phasor
    /// difference the branch can hold. The difference over `|Z|` bounds the
    /// current, and the larger ceiling turns the current into power. Returns
    /// `0.0` for a zero impedance branch — one under
    /// [`MIN_DIVISIBLE_MAGNITUDE`](crate::dc::MIN_DIVISIBLE_MAGNITUDE), the
    /// bound the rest of the builders divide by — which stays unlimited.
    ///
    /// The caller supplies the window in radians, because
    /// [`angmin`](Self::angmin) and [`angmax`](Self::angmax) are degrees in
    /// the neutral model and radians in a normalized network, and a branch
    /// cannot tell which it holds. Convert them with
    /// [`IndexedNetwork::angle_radians`](crate::IndexedNetwork::angle_radians),
    /// which reads the convention of the network. The method takes the
    /// magnitude of the window and holds it at `π`, the widest phasor
    /// separation two terminals can have.
    #[must_use]
    pub fn synthesize_rate_a(&self, angle_window_rad: f64, fr_vmax: f64, to_vmax: f64) -> f64 {
        // The same bound `series_admittance_of` divides by, so the two agree on
        // which branch has no impedance to bound a current with.
        let zmag = self.r.hypot(self.x);
        if zmag < crate::dc::MIN_DIVISIBLE_MAGNITUDE {
            return 0.0;
        }
        let window = angle_window_rad.abs().min(std::f64::consts::PI);
        let separation =
            (fr_vmax * fr_vmax + to_vmax * to_vmax - 2.0 * fr_vmax * to_vmax * window.cos()).sqrt();
        fr_vmax.max(to_vmax) * separation / zmag
    }

    /// Total susceptance projection for MATPOWER shaped formats that only carry
    /// one line charging value.
    #[must_use]
    pub fn total_charging_b(&self) -> f64 {
        self.terminal_charging().total_b()
    }

    /// Whether this branch has charging that a MATPOWER branch row cannot carry.
    #[must_use]
    pub fn has_non_matpower_charging(&self) -> bool {
        self.charging
            .is_some_and(|charging| !charging.is_matpower_symmetric())
    }

    /// A transformer iff the raw tap field is nonzero (an explicit `1` counts) or
    /// there is a phase shift.
    #[must_use]
    pub fn is_transformer(&self) -> bool {
        self.tap != 0.0 || self.shift != 0.0
    }

    /// True when the branch constrains its angle difference, i.e. the limits
    /// deviate from the ±360° "unconstrained" default. Formats without angle
    /// limit fields (PSS/E, PowerWorld) use this to warn on what they drop.
    #[must_use]
    pub fn has_angle_limits(&self) -> bool {
        self.angmin > -360.0 || self.angmax < 360.0
    }
}

/// The series admittance `(g, b)` of an impedance, guarded.
///
/// `None` is an impedance too small to divide by, under
/// [`MIN_DIVISIBLE_MAGNITUDE`](crate::dc::MIN_DIVISIBLE_MAGNITUDE); the caller
/// decides whether that is a skip or an error. The bound is on the impedance
/// magnitude, not on `r² + x²`, which is its square: bounding the square would
/// refuse impedances the DC builders divide by.
///
/// Y_bus takes `r` already zeroed under the XB scheme, so it passes its own
/// pair rather than a branch's.
///
/// # Errors
/// [`Error::NonFiniteSusceptance`] when `r`/`x` are NaN/Inf, so a bad value
/// cannot write NaN or a silent zero downstream. NaN leaves `hypot` NaN, which
/// is not below the bound, so it arrives at that check rather than reading as
/// zero impedance. `row` only labels the error.
pub fn series_admittance_of(r: f64, x: f64, row: usize) -> Result<Option<(f64, f64)>> {
    if r.hypot(x) < crate::dc::MIN_DIVISIBLE_MAGNITUDE {
        return Ok(None);
    }
    let denom = r * r + x * x;
    if !denom.is_finite() {
        return Err(Error::NonFiniteSusceptance { row });
    }
    Ok(Some((r / denom, -x / denom)))
}

/// A transmission switch. Closed switches are preserved as data; matrix builders
/// do not lower them into zero impedance branches.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Switch {
    pub from: BusId,
    pub to: BusId,
    pub closed: bool,
    #[serde(default)]
    pub thermal_rating: Option<f64>,
    #[serde(default)]
    pub current_rating: Option<f64>,
    #[serde(default)]
    pub pf: Option<f64>,
    #[serde(default)]
    pub qf: Option<f64>,
    #[serde(default)]
    pub pt: Option<f64>,
    #[serde(default)]
    pub qt: Option<f64>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Switch {
    #[must_use]
    pub fn new(from: BusId, to: BusId, closed: bool) -> Self {
        Self {
            from,
            to,
            closed,
            thermal_rating: None,
            current_rating: None,
            pf: None,
            qf: None,
            pt: None,
            qt: None,
            uid: None,
            extras: Extras::new(),
        }
    }
}

/// What a regulating transformer's tap (or phase shift) automatically controls.
/// Maps to the PSS/E control code `COD` and the PSLF transformer `type`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum TransformerControlMode {
    /// Fixed ratio, no automatic adjustment (PSS/E `COD` 0/±4, PSLF type 1).
    Fixed,
    /// Bus voltage control via tap (LTC; PSS/E `COD` ±1, PSLF type 2).
    Voltage,
    /// Reactive power flow control via tap (PSS/E `COD` ±2).
    ReactiveFlow,
    /// Active power flow control via phase shift (PSS/E `COD` ±3, PSLF type 4).
    ActiveFlow,
}

/// Automatic-control data for a regulating transformer ([`Branch::control`]).
///
/// The limits carry whatever the [`mode`](TransformerControl::mode) regulates:
/// `tap_min`/`tap_max` bound the tap ratio (or the phase angle, for
/// [`ActiveFlow`](TransformerControlMode::ActiveFlow)), and `band_min`/`band_max`
/// bound the controlled quantity (the regulated voltage band, or the
/// scheduled MW/MVAr). `ntp` is the number of discrete tap positions and
/// `controlled_bus` is the regulated bus (`None` = the transformer's own
/// terminal). `mva_base` is the winding MVA base the impedance is referred to.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct TransformerControl {
    pub mode: TransformerControlMode,
    pub controlled_bus: Option<BusId>,
    pub tap_min: f64,
    pub tap_max: f64,
    pub band_min: f64,
    pub band_max: f64,
    pub ntp: u32,
    pub mva_base: f64,
}

impl Default for TransformerControl {
    fn default() -> Self {
        // PSS/E's documented defaults for an unset winding-control block.
        TransformerControl {
            mode: TransformerControlMode::Fixed,
            controlled_bus: None,
            tap_min: 0.9,
            tap_max: 1.1,
            band_min: 0.9,
            band_max: 1.1,
            ntp: 33,
            mva_base: 0.0,
        }
    }
}

impl TransformerControl {
    #[must_use]
    pub fn new(mode: TransformerControlMode) -> Self {
        Self {
            mode,
            ..Self::default()
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Generator {
    pub bus: BusId,
    /// Real power set point (MW).
    pub pg: f64,
    /// Reactive power set point (MVAr).
    pub qg: f64,
    pub pmax: f64,
    pub pmin: f64,
    pub qmax: f64,
    pub qmin: f64,
    /// Voltage set point (p.u.).
    pub vg: f64,
    pub mbase: f64,
    pub in_service: bool,
    pub cost: Option<GenCost>,
    /// The MATPOWER gen capability / ramp columns past `PMIN`, aligned to
    /// `GEN_EXTRA_KEYS` by index (`None` for a column the source omitted).
    /// A fixed array, not an [`Extras`] map: a string-keyed map per generator
    /// costs 11 heap allocations each, which dominates the parse of a large
    /// generator-heavy case. Surfaced into formats that name them (PowerModels).
    /// On the JSON snapshot it is a name-keyed object (see `caps_serde`) so the
    /// schema stays additive when `GEN_EXTRA_KEYS` grows; `#[serde(default)]` so a
    /// snapshot that omits it deserializes to the empty set.
    #[serde(default = "default_caps", with = "caps_serde")]
    #[cfg_attr(feature = "schema", schemars(with = "BTreeMap<String, f64>"))]
    pub caps: GenCaps,
    /// The remote bus whose voltage this generator regulates, when that is not its
    /// own terminal bus (PSS/E `IREG`). `None` means it regulates its own bus.
    /// Part of the cross-element voltage-control graph: a format that names a
    /// remote regulated bus (PSS/E) keeps it across a round trip instead of
    /// collapsing every generator onto its own terminal. `#[serde(default)]` so
    /// JSON written before the field existed still deserializes.
    #[serde(default)]
    pub regulated_bus: Option<BusId>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
}

impl Generator {
    #[must_use]
    pub fn new(bus: BusId) -> Self {
        Self {
            bus,
            pg: 0.0,
            qg: 0.0,
            pmax: 0.0,
            pmin: 0.0,
            qmax: 0.0,
            qmin: 0.0,
            vg: 1.0,
            mbase: 0.0,
            in_service: true,
            cost: None,
            caps: default_caps(),
            regulated_bus: None,
            uid: None,
        }
    }

    /// True when any capability / ramp column is present. Formats without those
    /// fields (PSS/E, PowerWorld) use this to warn on what they drop.
    #[must_use]
    pub fn has_caps(&self) -> bool {
        self.caps.iter().any(Option::is_some)
    }
}

/// A generator's capability / ramp columns, one slot per `GEN_EXTRA_KEYS` name.
pub type GenCaps = [Option<f64>; GEN_EXTRA_KEYS.len()];

/// The empty capability set, for a JSON snapshot that omits the field entirely.
fn default_caps() -> GenCaps {
    [None; GEN_EXTRA_KEYS.len()]
}

/// Serialize [`GenCaps`] as a name-keyed object (`{"ramp_30": 1.2, ...}`) keyed by
/// [`GEN_EXTRA_KEYS`], emitting only the present slots, instead of a length-exact
/// array. A fixed-length array round-trips through serde only at exactly its
/// current length: the day `GEN_EXTRA_KEYS` grows a column, every old snapshot
/// fails to deserialize and every new one fails on an old build, and the C ABI
/// ties the JSON snapshot schema to its version, so that is a forced ABI break.
/// The named map makes a new key purely additive: an old document simply lacks it
/// (deserializes to `None`), and an unknown key from a newer document is ignored.
/// In memory `caps` stays a fixed array, so the per-generator allocation cost the
/// array avoids is unchanged; only the serialized form is named.
mod caps_serde {
    use super::{GEN_EXTRA_KEYS, GenCaps};
    use serde::de::{Deserialize, Deserializer};
    use serde::ser::{SerializeMap, Serializer};
    use std::collections::BTreeMap;

    pub(super) fn serialize<S: Serializer>(caps: &GenCaps, s: S) -> Result<S::Ok, S::Error> {
        let present = caps.iter().filter(|v| v.is_some()).count();
        let mut map = s.serialize_map(Some(present))?;
        for (key, slot) in GEN_EXTRA_KEYS.iter().zip(caps.iter()) {
            if let Some(value) = slot {
                map.serialize_entry(key, value)?;
            }
        }
        map.end()
    }

    pub(super) fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<GenCaps, D::Error> {
        // Accept an explicit `null` as the empty set (treated like an omitted
        // field), so a producer that encodes "no caps" as `null` round-trips the
        // same way `cost: Option<_>` does. `#[serde(default)]` only covers an
        // absent key, not a present `null`.
        let named = Option::<BTreeMap<String, f64>>::deserialize(d)?.unwrap_or_default();
        let mut caps: GenCaps = [None; GEN_EXTRA_KEYS.len()];
        for (slot, key) in caps.iter_mut().zip(GEN_EXTRA_KEYS.iter()) {
            *slot = named.get(*key).copied();
        }
        Ok(caps)
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Storage {
    pub bus: BusId,
    pub ps: f64,
    pub qs: f64,
    pub energy: f64,
    pub energy_rating: f64,
    pub charge_rating: f64,
    pub discharge_rating: f64,
    pub charge_efficiency: f64,
    pub discharge_efficiency: f64,
    pub thermal_rating: f64,
    #[serde(default)]
    pub current_rating: Option<f64>,
    pub qmin: f64,
    pub qmax: f64,
    pub r: f64,
    pub x: f64,
    pub p_loss: f64,
    pub q_loss: f64,
    pub in_service: bool,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Storage {
    #[must_use]
    pub fn new(bus: BusId) -> Self {
        Self {
            bus,
            ps: 0.0,
            qs: 0.0,
            energy: 0.0,
            energy_rating: 0.0,
            charge_rating: 0.0,
            discharge_rating: 0.0,
            charge_efficiency: 1.0,
            discharge_efficiency: 1.0,
            thermal_rating: 0.0,
            current_rating: None,
            qmin: 0.0,
            qmax: 0.0,
            r: 0.0,
            x: 0.0,
            p_loss: 0.0,
            q_loss: 0.0,
            in_service: true,
            uid: None,
            extras: Extras::new(),
        }
    }
}

/// A two-terminal HVDC line (MATPOWER `dcline`).
///
/// `pf`/`pt`/`qf`/`qt` are stored in MATPOWER's sign convention regardless of
/// source: the PowerModels reader un-flips `pt`/`qf`/`qt` on the way in, and the
/// PowerModels writer re-flips them on the way out (PowerModels.jl uses the
/// opposite sign). The flip is a format-boundary translation, so a derived view
/// like `to_normalized` keeps the MATPOWER convention and only scales to per unit.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Hvdc {
    pub from: BusId,
    pub to: BusId,
    pub in_service: bool,
    pub pf: f64,
    pub pt: f64,
    pub qf: f64,
    pub qt: f64,
    pub vf: f64,
    pub vt: f64,
    pub pmin: f64,
    pub pmax: f64,
    pub qminf: f64,
    pub qmaxf: f64,
    pub qmint: f64,
    pub qmaxt: f64,
    pub loss0: f64,
    pub loss1: f64,
    #[serde(default)]
    pub cost: Option<GenCost>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Hvdc {
    #[must_use]
    pub fn new(from: BusId, to: BusId) -> Self {
        Self {
            from,
            to,
            in_service: true,
            pf: 0.0,
            pt: 0.0,
            qf: 0.0,
            qt: 0.0,
            vf: 1.0,
            vt: 1.0,
            pmin: 0.0,
            pmax: 0.0,
            qminf: 0.0,
            qmaxf: 0.0,
            qmint: 0.0,
            qmaxt: 0.0,
            loss0: 0.0,
            loss1: 0.0,
            cost: None,
            uid: None,
            extras: Extras::new(),
        }
    }
}

/// An area record: the area's scheduled net interchange and its swing bus.
///
/// The [`number`](Area::number) matches the `area` field carried on each
/// [`Bus`]; this table holds the per-area metadata (the interchange target and
/// the area slack) that the bus number alone can't. Maps to the PSS/E area record
/// (`I, ISW, PDES, PTOL, ARNAME`).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Area {
    pub number: usize,
    /// The area swing (slack) bus, or `None` when unset.
    pub slack_bus: Option<BusId>,
    /// Scheduled net interchange (MW); positive is export out of the area.
    pub net_interchange: f64,
    /// Interchange tolerance bandwidth (MW).
    pub tolerance: f64,
    pub name: Option<String>,
}

impl Area {
    #[must_use]
    pub fn new(number: usize) -> Self {
        Self {
            number,
            slack_bus: None,
            net_interchange: 0.0,
            tolerance: 0.0,
            name: None,
        }
    }
}

/// Solver / solution-control metadata: the Newton tolerance and iteration cap,
/// the zero-impedance threshold, and the per-quantity adjustment-enable flags.
///
/// Each field is optional because a source states only the ones it carries. No
/// power flow physics, but it determines whether a downstream solver reproduces
/// the source tool's converged answer. Maps to the PSS/E v34+ system-wide block
/// (`GENERAL THRSHZ`, `NEWTON TOLN`/`ITMXN`, `SOLVER ACTAPS`/`AREAIN`/`PHSHFT`/
/// `DCTAPS`/`SWSHNT`).
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct SolverParams {
    /// Newton power flow mismatch tolerance (`NEWTON TOLN`).
    pub newton_tolerance: Option<f64>,
    /// Newton iteration cap (`NEWTON ITMXN`).
    pub max_iterations: Option<u32>,
    /// Branches with `|x|` below this are treated as zero impedance (`GENERAL THRSHZ`).
    pub zero_impedance_threshold: Option<f64>,
    /// Whether the solver adjusts transformer taps (`SOLVER ACTAPS`).
    pub adjust_taps: Option<bool>,
    /// Whether the solver adjusts area interchange (`SOLVER AREAIN`).
    pub adjust_area_interchange: Option<bool>,
    /// Whether the solver adjusts phase-shift angles (`SOLVER PHSHFT`).
    pub adjust_phase_shift: Option<bool>,
    /// Whether the solver adjusts DC line taps (`SOLVER DCTAPS`).
    pub adjust_dc_taps: Option<bool>,
    /// Whether the solver adjusts switched shunts (`SOLVER SWSHNT`).
    pub adjust_switched_shunt: Option<bool>,
}

impl SolverParams {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// True when no field is set (so readers can avoid attaching an empty record).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        *self == SolverParams::default()
    }
}

/// A series impedance with the MVA base it is expressed on. Used pairwise by
/// [`Transformer3W`]; a self-contained unit so the base travels with the value
/// instead of being implied by position.
///
/// `r`/`x` are per unit on the *system* base (the same `CZ = 1` convention as
/// [`Branch::r`]/[`Branch::x`], so the matrix math needs no rebasing); `base_mva`
/// records the winding-pair MVA base the source file declared (PSS/E `SBASE1-2`
/// and friends), kept so a write-back reproduces it and so a future `CZ = 2`
/// reader has somewhere to put the winding base it must rebase from. Room to grow
/// (winding voltage base, turns-ratio units) as the transformer control work
/// lands without reshaping the [`Transformer3W::z`] array.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Impedance {
    pub r: f64,
    pub x: f64,
    pub base_mva: f64,
}

impl Impedance {
    #[must_use]
    pub const fn new(r: f64, x: f64, base_mva: f64) -> Self {
        Self { r, x, base_mva }
    }
}

/// One winding of a [`Transformer3W`]: its terminal bus, off-nominal ratio, phase
/// shift, nominal voltage, and thermal ratings.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Winding {
    pub bus: BusId,
    /// Off-nominal turns ratio (1.0 = nominal); the PSS/E `WINDV`, `CW = 1`.
    pub tap: f64,
    /// Phase shift (degrees).
    pub shift: f64,
    /// Winding nominal voltage (kV); 0 defers to the terminal bus base kV.
    pub nominal_kv: f64,
    pub rate_a: f64,
    pub rate_b: f64,
    pub rate_c: f64,
}

impl Winding {
    #[must_use]
    pub fn new(bus: BusId) -> Self {
        Self {
            bus,
            tap: 1.0,
            shift: 0.0,
            nominal_kv: 0.0,
            rate_a: 0.0,
            rate_b: 0.0,
            rate_c: 0.0,
        }
    }
}

/// A three winding transformer with three terminal buses joined at a star point.
///
/// Series impedance is stored for winding pairs 1-2, 2-3, and 3-1. The record
/// also retains star point voltage and per winding control data. PSS/E three
/// winding records and PSLF tertiary winding records map to this type.
/// [`star_expansion`](Transformer3W::star_expansion) turns it into the synthetic
/// star bus plus three branches for a consumer that works in the bus-branch model;
/// [`IndexedNetwork`](crate::IndexedNetwork) applies it before building any matrix,
/// so a 3-winding transformer contributes to `Y_bus` and connectivity.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[non_exhaustive]
pub struct Transformer3W {
    /// The three windings, in order (primary, secondary, tertiary).
    pub windings: [Winding; 3],
    /// Pairwise series impedance `[z12, z23, z31]` (primary-secondary,
    /// secondary-tertiary, tertiary-primary), each per unit on the system base
    /// with its declared MVA base.
    pub z: [Impedance; 3],
    /// Star-point voltage magnitude (p.u.) and angle (degrees), as solved.
    pub star_vm: f64,
    pub star_va: f64,
    /// Magnetizing shunt referred to the star point (p.u. on the system base).
    pub mag_g: f64,
    pub mag_b: f64,
    pub in_service: bool,
    pub name: Option<String>,
    /// Stable row identity; see [`Bus::uid`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uid: Option<String>,
    pub extras: Extras,
}

impl Transformer3W {
    #[must_use]
    pub fn new(windings: [Winding; 3], z: [Impedance; 3]) -> Self {
        Self {
            windings,
            z,
            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(),
        }
    }

    /// The per-winding star impedances `(r, x)` — winding *k* to the star point —
    /// from the pairwise values, per unit on the system base.
    ///
    /// Standard pairwise→star conversion: `z1 = (z12 + z31 - z23) / 2`, and so on.
    /// Because the impedances are already on a common base, the split is linear in
    /// `r` and `x` separately.
    #[must_use]
    pub fn star_impedances(&self) -> [(f64, f64); 3] {
        let [z12, z23, z31] = self.z;
        let half = |a: f64, b: f64, c: f64| (a + b - c) / 2.0;
        [
            (half(z12.r, z31.r, z23.r), half(z12.x, z31.x, z23.x)),
            (half(z12.r, z23.r, z31.r), half(z12.x, z23.x, z31.x)),
            (half(z23.r, z31.r, z12.r), half(z23.x, z31.x, z12.x)),
        ]
    }

    /// Expand into a synthetic star [`Bus`] (id `star_id`) plus three [`Branch`]es,
    /// one per winding, for a consumer that works in the bus-branch model.
    /// [`IndexedNetwork`](crate::IndexedNetwork) calls this via
    /// `BalancedNetwork::expand_transformers_3w` when assembling matrix inputs. The star
    /// bus carries the stored star voltage and the magnetizing shunt is left to the
    /// caller; each branch takes its winding's tap, phase shift, and ratings.
    #[must_use]
    pub fn star_expansion(&self, star_id: BusId) -> (Bus, [Branch; 3]) {
        let star = Bus {
            id: star_id,
            kind: BusType::Pq,
            vm: self.star_vm,
            va: self.star_va,
            base_kv: self.windings[0].nominal_kv,
            vmax: 1.1,
            vmin: 0.9,
            evhi: None,
            evlo: None,
            area: 0,
            zone: 0,
            name: self.name.clone(),
            uid: self.uid.clone(),
            location: None,
            extras: Extras::new(),
        };
        let zs = self.star_impedances();
        let branch = |w: &Winding, (r, x): (f64, f64)| Branch {
            from: w.bus,
            to: star_id,
            r,
            x,
            b: 0.0,
            charging: None,
            rate_a: w.rate_a,
            rate_b: w.rate_b,
            rate_c: w.rate_c,
            rating_sets: Vec::new(),
            current_ratings: None,
            tap: w.tap,
            shift: w.shift,
            in_service: self.in_service,
            angmin: -360.0,
            angmax: 360.0,
            control: None,
            solution: None,
            uid: None,
            route: None,
            extras: Extras::new(),
        };
        let branches = [
            branch(&self.windings[0], zs[0]),
            branch(&self.windings[1], zs[1]),
            branch(&self.windings[2], zs[2]),
        ];
        (star, branches)
    }
}

/// The MATPOWER gen capability / ramp columns past `PMIN`, in order. The index
/// into this array is the slot index into a [`GenCaps`].
pub(crate) const GEN_EXTRA_KEYS: [&str; 11] = [
    "pc1", "pc2", "qc1min", "qc1max", "qc2min", "qc2max", "ramp_agc", "ramp_10", "ramp_30",
    "ramp_q", "apf",
];

/// A value-domain finding from [`BalancedNetwork::validate_values`]: an element field
/// whose value falls outside its physical range, paired with the value
/// [`repair`](BalancedNetwork::repair) would set in its place.
///
/// `#[non_exhaustive]`: a returns-only record, so downstream code reads it but
/// never constructs it, leaving room to add locator fields without a break.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct Diagnostic {
    /// Human-readable element locator, e.g. `"bus 3"` or `"generator at bus 5"`.
    pub element: String,
    pub field: &'static str,
    pub old: f64,
    pub new: f64,
    pub reason: &'static str,
}

/// Voltage magnitude (p.u.) repair: non-positive or above 2 (or non-finite) → 1.0.
/// A zero magnitude is treated as out of domain (a de-energized placeholder), not
/// a valid 0 p.u.
fn repair_vm(vm: f64) -> Option<f64> {
    (!vm.is_finite() || vm <= 0.0 || vm > 2.0).then_some(1.0)
}

/// Voltage angle (degrees) repair: `|va| > 2000` (or non-finite) → 0.0.
fn repair_va(va: f64) -> Option<f64> {
    (!va.is_finite() || va.abs() > 2000.0).then_some(0.0)
}

/// Generator MVA base repair: non-positive (or non-finite) → the system base.
fn repair_mbase(mbase: f64, sbase: f64) -> Option<f64> {
    (!mbase.is_finite() || mbase <= 0.0).then_some(sbase)
}

/// Generator voltage setpoint (p.u.) repair: non-positive (or non-finite) → 1.0.
fn repair_vg(vg: f64) -> Option<f64> {
    (!vg.is_finite() || vg <= 0.0).then_some(1.0)
}

/// The three element counts the star lowering changes, from
/// [`BalancedNetwork::lowered_lengths`]. Every other family keeps its length, since the
/// lowering only appends a star bus, its winding branches, and a magnetizing
/// shunt.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct LoweredLengths {
    pub(crate) buses: usize,
    pub(crate) branches: usize,
    pub(crate) shunts: usize,
}

impl BalancedNetwork {
    #[must_use]
    pub fn new(name: impl Into<String>, base_mva: f64) -> BalancedNetwork {
        BalancedNetwork {
            name: name.into(),
            base_mva,
            base_frequency: DEFAULT_BASE_FREQUENCY,
            geo: None,
            buses: Vec::new(),
            loads: Vec::new(),
            shunts: Vec::new(),
            branches: Vec::new(),
            switches: Vec::new(),
            generators: Vec::new(),
            storage: Vec::new(),
            hvdc: Vec::new(),
            transformers_3w: Vec::new(),
            areas: Vec::new(),
            solver: None,
            source_format: SourceFormat::InMemory,
            source: None,
        }
    }

    /// 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).
    #[must_use]
    pub fn in_memory(
        name: impl Into<String>,
        base_mva: f64,
        buses: Vec<Bus>,
        branches: Vec<Branch>,
    ) -> BalancedNetwork {
        let mut net = Self::new(name, base_mva);
        net.buses = buses;
        net.branches = branches;
        net
    }

    /// Serialize the structured tables to model JSON. The C ABI and language
    /// bindings use this representation. The retained `source` text is
    /// excluded (see the field's `#[serde(skip)]`), so the byte-exact echo
    /// stays on the same-format write path; a [`from_json`](BalancedNetwork::from_json)
    /// round-trip reproduces every field except `source`, which returns `None`.
    ///
    /// JSON has no `Inf`/`NaN`: `serde_json` writes a non-finite field as
    /// `null`, which [`from_json`](BalancedNetwork::from_json) rejects on the way back
    /// (`null` is not an `f64`). The write stays total, the bindings
    /// materialize every parsed network through this transport, and readers
    /// legitimately produce `Inf` limits, but such a snapshot does not round
    /// trip; [`write_as`](crate::write_as) reports the degradation as a
    /// fidelity warning naming the field.
    ///
    /// # Errors
    /// A `serde_json` serialization failure (none arise from this model today).
    pub fn to_json(&self) -> crate::Result<String> {
        serde_json::to_string(self).map_err(|e| Error::FormatRead {
            format: "JSON",
            message: e.to_string(),
        })
    }

    /// The paths of every non-finite numeric field, empty when all values are
    /// finite. Drives the snapshot writer's degradation warning (see
    /// [`to_json`](BalancedNetwork::to_json)): serde writes EVERY non-finite `f64` as
    /// `null`, so the warning must name them all, not just the first, or the
    /// caller fixes one field and the snapshot still fails to read back.
    /// `extras` maps hold `serde_json::Value`, which cannot carry a non-finite
    /// number, so only the typed `f64` fields need scanning. Every struct is
    /// destructured exhaustively: adding an `f64` field without classifying it
    /// here is a compile error, not a silently unguarded value.
    // The length IS the exhaustive field walk; splitting it would only scatter
    // the per-struct lists the compile-time check exists to keep in one place.
    #[allow(clippy::too_many_lines)]
    pub(crate) fn non_finite_fields(&self) -> Vec<String> {
        fn bad<'a>(
            fields: impl IntoIterator<Item = (&'a str, f64)>,
        ) -> impl Iterator<Item = &'a str> {
            fields
                .into_iter()
                .filter_map(|(name, v)| (!v.is_finite()).then_some(name))
        }
        let mut out = Vec::new();
        if !self.base_mva.is_finite() {
            out.push("base_mva".into());
        }
        if !self.base_frequency.is_finite() {
            out.push("base_frequency".into());
        }
        for (i, b) in self.buses.iter().enumerate() {
            #[rustfmt::skip]
            let Bus { id: _, kind: _, vm, va, base_kv, vmax, vmin, evhi: _, evlo: _, area: _, zone: _, name: _, uid: _, location, extras: _ } = b;
            let fields = [
                ("vm", *vm),
                ("va", *va),
                ("base_kv", *base_kv),
                ("vmax", *vmax),
                ("vmin", *vmin),
            ];
            out.extend(bad(fields).map(|f| format!("buses[{i}].{f}")));
            if let Some(location) = location {
                let fields = [("location.x", location.x), ("location.y", location.y)];
                out.extend(bad(fields).map(|f| format!("buses[{i}].{f}")));
            }
        }
        for (i, l) in self.loads.iter().enumerate() {
            let Load {
                bus: _,
                p,
                q,
                voltage_model,
                in_service: _,
                uid: _,
                extras: _,
            } = l;
            out.extend(bad([("p", *p), ("q", *q)]).map(|f| format!("loads[{i}].{f}")));
            if let Some(model) = voltage_model {
                match model {
                    LoadVoltageModel::ConstantPower => {}
                    LoadVoltageModel::Zip {
                        p_constant_power,
                        q_constant_power,
                        p_constant_current,
                        q_constant_current,
                        p_constant_impedance,
                        q_constant_impedance,
                        v_nom,
                        load_type: _,
                        scaling,
                    } => {
                        let fields = [
                            ("p_constant_power", *p_constant_power),
                            ("q_constant_power", *q_constant_power),
                            ("p_constant_current", *p_constant_current),
                            ("q_constant_current", *q_constant_current),
                            ("p_constant_impedance", *p_constant_impedance),
                            ("q_constant_impedance", *q_constant_impedance),
                        ];
                        out.extend(bad(fields).map(|f| format!("loads[{i}].voltage_model.{f}")));
                        if matches!(v_nom, Some(v) if !v.is_finite()) {
                            out.push(format!("loads[{i}].voltage_model.v_nom"));
                        }
                        if matches!(scaling, Some(v) if !v.is_finite()) {
                            out.push(format!("loads[{i}].voltage_model.scaling"));
                        }
                    }
                    LoadVoltageModel::Exponential {
                        p,
                        q,
                        v_nom,
                        gamma_p,
                        gamma_q,
                    } => {
                        out.extend(
                            bad([
                                ("p", *p),
                                ("q", *q),
                                ("gamma_p", *gamma_p),
                                ("gamma_q", *gamma_q),
                            ])
                            .map(|f| format!("loads[{i}].voltage_model.{f}")),
                        );
                        if matches!(v_nom, Some(v) if !v.is_finite()) {
                            out.push(format!("loads[{i}].voltage_model.v_nom"));
                        }
                    }
                }
            }
        }
        for (i, s) in self.shunts.iter().enumerate() {
            let Shunt {
                bus: _,
                g,
                b,
                in_service: _,
                control: _,
                uid: _,
                extras: _,
            } = s;
            out.extend(bad([("g", *g), ("b", *b)]).map(|f| format!("shunts[{i}].{f}")));
        }
        for (i, br) in self.branches.iter().enumerate() {
            #[rustfmt::skip]
            let Branch { from: _, to: _, r, x, b, charging, rate_a, rate_b, rate_c, rating_sets, current_ratings, tap, shift, in_service: _, angmin, angmax, control: _, solution, uid: _, route: _, extras: _ } = br;
            let fields = [
                ("r", *r),
                ("x", *x),
                ("b", *b),
                ("rate_a", *rate_a),
                ("rate_b", *rate_b),
                ("rate_c", *rate_c),
                ("tap", *tap),
                ("shift", *shift),
                ("angmin", *angmin),
                ("angmax", *angmax),
            ];
            out.extend(bad(fields).map(|f| format!("branches[{i}].{f}")));
            out.extend(
                rating_sets
                    .iter()
                    .enumerate()
                    .filter(|(_, r)| !r.rate_mva.is_finite())
                    .map(|(j, _)| format!("branches[{i}].rating_sets[{j}].rate_mva")),
            );
            if let Some(charging) = charging {
                let BranchCharging {
                    g_fr,
                    b_fr,
                    g_to,
                    b_to,
                } = charging;
                let fields = [
                    ("g_fr", *g_fr),
                    ("b_fr", *b_fr),
                    ("g_to", *g_to),
                    ("b_to", *b_to),
                ];
                out.extend(bad(fields).map(|f| format!("branches[{i}].charging.{f}")));
            }
            if let Some(current) = current_ratings {
                let BranchCurrentRatings {
                    c_rating_a,
                    c_rating_b,
                    c_rating_c,
                } = current;
                let fields = [
                    ("c_rating_a", *c_rating_a),
                    ("c_rating_b", *c_rating_b),
                    ("c_rating_c", *c_rating_c),
                ];
                out.extend(bad(fields).map(|f| format!("branches[{i}].current_ratings.{f}")));
            }
            if let Some(solution) = solution {
                let BranchSolution { pf, qf, pt, qt } = solution;
                out.extend(
                    bad([("pf", *pf), ("qf", *qf), ("pt", *pt), ("qt", *qt)])
                        .map(|f| format!("branches[{i}].solution.{f}")),
                );
            }
        }
        for (i, sw) in self.switches.iter().enumerate() {
            let Switch {
                from: _,
                to: _,
                closed: _,
                thermal_rating,
                current_rating,
                pf,
                qf,
                pt,
                qt,
                uid: _,
                extras: _,
            } = sw;
            for (field, value) in [
                ("thermal_rating", *thermal_rating),
                ("current_rating", *current_rating),
                ("pf", *pf),
                ("qf", *qf),
                ("pt", *pt),
                ("qt", *qt),
            ] {
                if matches!(value, Some(v) if !v.is_finite()) {
                    out.push(format!("switches[{i}].{field}"));
                }
            }
        }
        for (i, g) in self.generators.iter().enumerate() {
            #[rustfmt::skip]
            let Generator { bus: _, pg, qg, pmax, pmin, qmax, qmin, vg, mbase, in_service: _, cost, caps, regulated_bus: _, uid: _ } = g;
            let fields = [
                ("pg", *pg),
                ("qg", *qg),
                ("pmax", *pmax),
                ("pmin", *pmin),
                ("qmax", *qmax),
                ("qmin", *qmin),
                ("vg", *vg),
                ("mbase", *mbase),
            ];
            out.extend(bad(fields).map(|f| format!("generators[{i}].{f}")));
            if let Some(GenCost {
                model: _,
                startup,
                shutdown,
                ncost: _,
                coeffs,
            }) = cost
            {
                out.extend(
                    bad([("startup", *startup), ("shutdown", *shutdown)])
                        .map(|f| format!("generators[{i}].cost.{f}")),
                );
                if coeffs.iter().any(|c| !c.is_finite()) {
                    out.push(format!("generators[{i}].cost.coeffs"));
                }
            }
            // Name the exact cap key (caps serializes as a name-keyed object, so
            // the null lands at generators[i].caps.<key>, e.g. ramp_30), matching
            // the key-level precision of every other field.
            for (key, slot) in GEN_EXTRA_KEYS.iter().zip(caps.iter()) {
                if matches!(slot, Some(v) if !v.is_finite()) {
                    out.push(format!("generators[{i}].caps.{key}"));
                }
            }
        }
        for (i, s) in self.storage.iter().enumerate() {
            #[rustfmt::skip]
            let Storage { bus: _, ps, qs, energy, energy_rating, charge_rating, discharge_rating, charge_efficiency, discharge_efficiency, thermal_rating, current_rating, qmin, qmax, r, x, p_loss, q_loss, in_service: _, uid: _, extras: _ } = s;
            let fields = [
                ("ps", *ps),
                ("qs", *qs),
                ("energy", *energy),
                ("energy_rating", *energy_rating),
                ("charge_rating", *charge_rating),
                ("discharge_rating", *discharge_rating),
                ("charge_efficiency", *charge_efficiency),
                ("discharge_efficiency", *discharge_efficiency),
                ("thermal_rating", *thermal_rating),
                ("qmin", *qmin),
                ("qmax", *qmax),
                ("r", *r),
                ("x", *x),
                ("p_loss", *p_loss),
                ("q_loss", *q_loss),
            ];
            out.extend(bad(fields).map(|f| format!("storage[{i}].{f}")));
            if matches!(current_rating, Some(v) if !v.is_finite()) {
                out.push(format!("storage[{i}].current_rating"));
            }
        }
        for (i, h) in self.hvdc.iter().enumerate() {
            #[rustfmt::skip]
            let Hvdc { from: _, to: _, in_service: _, pf, pt, qf, qt, vf, vt, pmin, pmax, qminf, qmaxf, qmint, qmaxt, loss0, loss1, cost, uid: _, extras: _ } = h;
            let fields = [
                ("pf", *pf),
                ("pt", *pt),
                ("qf", *qf),
                ("qt", *qt),
                ("vf", *vf),
                ("vt", *vt),
                ("pmin", *pmin),
                ("pmax", *pmax),
                ("qminf", *qminf),
                ("qmaxf", *qmaxf),
                ("qmint", *qmint),
                ("qmaxt", *qmaxt),
                ("loss0", *loss0),
                ("loss1", *loss1),
            ];
            out.extend(bad(fields).map(|f| format!("hvdc[{i}].{f}")));
            if let Some(GenCost {
                model: _,
                startup,
                shutdown,
                ncost: _,
                coeffs,
            }) = cost
            {
                out.extend(
                    bad([("startup", *startup), ("shutdown", *shutdown)])
                        .map(|f| format!("hvdc[{i}].cost.{f}")),
                );
                if coeffs.iter().any(|c| !c.is_finite()) {
                    out.push(format!("hvdc[{i}].cost.coeffs"));
                }
            }
        }
        out
    }

    /// Serialize this network to `format`, preserving the retained source text
    /// on same-format writes and reporting any target-format fidelity warnings.
    ///
    /// # Errors
    /// As [`write_as`](crate::write_as): only a model JSON serialization failure.
    pub fn to_format(&self, format: crate::TargetFormat) -> crate::Result<crate::Conversion> {
        crate::write_as(self, format)
    }

    /// Serialize this network with write-time cost policies.
    ///
    /// The network itself is not mutated. Default options preserve
    /// [`to_format`](Self::to_format) behavior.
    pub fn to_format_with_options(
        &self,
        format: crate::TargetFormat,
        options: &crate::WriteOptions,
    ) -> crate::Result<crate::Conversion> {
        crate::write_as_with_options(self, format, options)
    }

    /// Serialize this network to MATPOWER `.m` text.
    ///
    /// This is byte-exact when the network was parsed from MATPOWER and still
    /// carries its retained source text.
    #[must_use]
    pub fn to_matpower(&self) -> String {
        crate::write_matpower(self)
    }

    /// Rebuild a `BalancedNetwork` from JSON produced by [`to_json`](BalancedNetwork::to_json).
    ///
    /// Validates the result (no buses, unique bus ids, no dangling references)
    /// before returning, so the JSON transport (the C ABI and Julia bridge ride
    /// on it) can't hand back a network the file readers would have rejected
    /// (the same no-buses guard `read_source` applies to every parse path).
    pub fn from_json(text: &str) -> crate::Result<BalancedNetwork> {
        // Tolerate a leading UTF-8 byte order mark, as the format readers do.
        let text = text.trim_start_matches('\u{feff}');
        let net: BalancedNetwork = serde_json::from_str(text).map_err(|e| Error::FormatRead {
            format: "JSON",
            message: e.to_string(),
        })?;
        net.check_references("JSON")?;
        if net.buses.is_empty() {
            return Err(Error::FormatRead {
                format: "JSON",
                message: "case has no buses".into(),
            });
        }
        Ok(net)
    }

    /// Whether this is a normalized (per-unit, radian, filtered)
    /// derived product from [`to_normalized`](BalancedNetwork::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.
    #[must_use]
    pub fn is_normalized(&self) -> bool {
        self.source_format == SourceFormat::Normalized
    }

    /// 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`](BalancedNetwork::to_normalized), the gridfm
    /// export) call this; any other unit-sensitive consumer should too.
    pub fn check_base_mva(&self) -> crate::Result<()> {
        if self.base_mva.is_finite() && self.base_mva > 0.0 {
            Ok(())
        } else {
            Err(crate::Error::InvalidBaseMva {
                base: self.base_mva,
            })
        }
    }

    /// Report element fields whose values fall outside their physical domain,
    /// without changing anything. Each [`Diagnostic`] names the element, the
    /// field, the current value, the value [`repair`](BalancedNetwork::repair) would set,
    /// and why.
    ///
    /// This generalizes the per-reader value clamps (a bus voltage magnitude
    /// outside `[0, 2]`, an angle past `±2000°`, a zero generator MVA base or
    /// voltage setpoint) into one pass any consumer can run, separate from the
    /// structural [`validate`](BalancedNetwork::validate) (which only checks ids and
    /// references). It is non-mutating; call [`repair`](BalancedNetwork::repair) to apply
    /// the fixes.
    #[must_use]
    pub fn validate_values(&self) -> Vec<Diagnostic> {
        let mut out = Vec::new();
        for b in &self.buses {
            if let Some(new) = repair_vm(b.vm) {
                out.push(Diagnostic {
                    element: format!("bus {}", b.id),
                    field: "vm",
                    old: b.vm,
                    new,
                    reason: "voltage magnitude outside [0, 2] p.u.",
                });
            }
            if let Some(new) = repair_va(b.va) {
                out.push(Diagnostic {
                    element: format!("bus {}", b.id),
                    field: "va",
                    old: b.va,
                    new,
                    reason: "voltage angle outside ±2000°",
                });
            }
        }
        for g in &self.generators {
            if let Some(new) = repair_mbase(g.mbase, self.base_mva) {
                out.push(Diagnostic {
                    element: format!("generator at bus {}", g.bus),
                    field: "mbase",
                    old: g.mbase,
                    new,
                    reason: "non-positive generator MVA base",
                });
            }
            if let Some(new) = repair_vg(g.vg) {
                out.push(Diagnostic {
                    element: format!("generator at bus {}", g.bus),
                    field: "vg",
                    old: g.vg,
                    new,
                    reason: "non-positive voltage setpoint",
                });
            }
        }
        out
    }

    /// Drop the retained source text after an in-place mutation, so a later
    /// [`write_as`](crate::write_as) to the source format re-serializes the
    /// modified model instead of echoing the now-stale original bytes. A no-op
    /// operation leaves the source intact, keeping the byte-exact echo for an
    /// unmodified round trip.
    pub(crate) fn invalidate_source(&mut self) {
        self.source = None;
    }

    /// Clamp every out-of-domain value to its repaired value (the same rules
    /// [`validate_values`](BalancedNetwork::validate_values) reports), returning the list
    /// of changes made. A second call returns an empty list (the values are now
    /// in domain).
    pub fn repair(&mut self) -> Vec<Diagnostic> {
        let findings = self.validate_values();
        let sbase = self.base_mva;
        for b in &mut self.buses {
            if let Some(new) = repair_vm(b.vm) {
                b.vm = new;
            }
            if let Some(new) = repair_va(b.va) {
                b.va = new;
            }
        }
        for g in &mut self.generators {
            if let Some(new) = repair_mbase(g.mbase, sbase) {
                g.mbase = new;
            }
            if let Some(new) = repair_vg(g.vg) {
                g.vg = new;
            }
        }
        // The repairs changed the model, so the retained source no longer matches.
        if !findings.is_empty() {
            self.invalidate_source();
        }
        findings
    }

    /// The element counts [`Self::expand_transformers_3w`] would produce, read off
    /// the transformer records instead of building the lowering. A caller that
    /// only needs the lowered lengths — sizing a per-row map, say — would
    /// otherwise pay a whole `BalancedNetwork` clone for three `len()` calls.
    /// `lowered_lengths_match_the_expansion` pins the two against each other.
    pub(crate) fn lowered_lengths(&self) -> LoweredLengths {
        let mut lengths = LoweredLengths {
            buses: self.buses.len(),
            branches: self.branches.len(),
            shunts: self.shunts.len(),
        };
        for t in self.transformers_3w.iter().filter(|t| t.in_service) {
            lengths.buses += 1;
            lengths.branches += 3;
            if t.mag_g != 0.0 || t.mag_b != 0.0 {
                lengths.shunts += 1;
            }
        }
        lengths
    }

    /// A bus-branch lowering of the network for analysis: each in-service
    /// 3-winding transformer becomes a synthetic star bus, its three winding
    /// branches, and (when present) its magnetizing shunt, so the matrix builders
    /// and connectivity see it. Returns the network unchanged (borrowed) when
    /// there are no 3-winding transformers, so the common case allocates nothing.
    ///
    /// The canonical `BalancedNetwork` keeps the typed [`Transformer3W`] records; this is
    /// the derived analysis form that [`IndexedNetwork`](crate::IndexedNetwork)
    /// builds behind the scenes, so callers never see the synthetic buses in the
    /// model they read or write.
    pub(crate) fn expand_transformers_3w(&self) -> std::borrow::Cow<'_, BalancedNetwork> {
        if self.transformers_3w.is_empty() {
            return std::borrow::Cow::Borrowed(self);
        }
        let mut net = self.clone();
        // The star branches carry per-unit impedance (CZ = 1), the same convention
        // the matrix builders read straight off a branch, so no rebasing. The
        // magnetizing shunt is an admittance, so it scales like every other shunt:
        // by the per-unit base for a raw network, by 1 for a normalized one.
        let scale = if net.is_normalized() {
            1.0
        } else {
            net.base_mva
        };
        // check_references refuses bus ids without headroom for these
        // synthetic ids on every parse path; the checked arithmetic turns a
        // programmatic caller's overflow into a loud panic instead of a
        // wrapped id aliasing an existing bus.
        let base_id = net
            .buses
            .iter()
            .map(|b| b.id.0)
            .max()
            .unwrap_or(0)
            .checked_add(1)
            .expect("bus id space exhausted for star expansion");
        for (k, t) in self
            .transformers_3w
            .iter()
            .filter(|t| t.in_service)
            .enumerate()
        {
            let star_id = BusId(
                base_id
                    .checked_add(k)
                    .expect("bus id space exhausted for star expansion"),
            );
            let (star, branches) = t.star_expansion(star_id);
            net.buses.push(star);
            net.branches.extend(branches);
            if t.mag_g != 0.0 || t.mag_b != 0.0 {
                net.shunts.push(Shunt {
                    bus: star_id,
                    g: t.mag_g * scale,
                    b: t.mag_b * scale,
                    in_service: true,
                    control: None,
                    uid: None,
                    extras: Extras::new(),
                });
            }
        }
        net.transformers_3w.clear();
        std::borrow::Cow::Owned(net)
    }

    /// Check structural integrity: bus ids are unique and every element
    /// references an existing bus. The file readers and [`from_json`](BalancedNetwork::from_json)
    /// run this; a `BalancedNetwork` built by hand (or mutated, e.g. by a scenario
    /// generator) should call it before handing the network to
    /// [`IndexedNetwork`](crate::IndexedNetwork), whose dense indexing assumes it.
    pub fn validate(&self) -> crate::Result<()> {
        self.check_references("network")
    }

    /// Error if two buses share an id, or if any element references a bus that
    /// doesn't exist. Readers call this after parsing so a missing/garbled id
    /// (which would otherwise default to a placeholder and silently re-wire the
    /// network) fails loudly instead.
    pub(crate) fn check_references(&self, format: &'static str) -> crate::Result<()> {
        // HashSet, not BTreeSet: building the id set and probing it once per branch
        // endpoint / load / shunt / gen is the dominant cost of a large parse, and
        // a BTreeSet pays a log-n pointer-chasing probe each time. Pre-size to skip
        // rehashing.
        let mut ids = std::collections::HashSet::with_capacity(self.buses.len());
        for b in &self.buses {
            if !ids.insert(b.id) {
                return Err(Error::FormatRead {
                    format,
                    message: format!("duplicate bus id {}", b.id),
                });
            }
        }
        let check = |bus: BusId, what: &str| -> crate::Result<()> {
            if ids.contains(&bus) {
                Ok(())
            } else {
                Err(Error::FormatRead {
                    format,
                    message: format!("{what} references unknown bus {bus}"),
                })
            }
        };
        // Format the context only on the error path, not once per branch.
        for (i, br) in self.branches.iter().enumerate() {
            for bus in [br.from, br.to] {
                if !ids.contains(&bus) {
                    return Err(Error::FormatRead {
                        format,
                        message: format!("branch {i} references unknown bus {bus}"),
                    });
                }
            }
            if let Some(bus) = br.control.as_ref().and_then(|c| c.controlled_bus) {
                check(bus, "transformer control")?;
            }
        }
        for (i, sw) in self.switches.iter().enumerate() {
            for bus in [sw.from, sw.to] {
                if !ids.contains(&bus) {
                    return Err(Error::FormatRead {
                        format,
                        message: format!("switch {i} references unknown bus {bus}"),
                    });
                }
            }
        }
        for l in &self.loads {
            check(l.bus, "load")?;
        }
        for s in &self.shunts {
            check(s.bus, "shunt")?;
            if let Some(bus) = s.control.as_ref().and_then(|c| c.control_bus) {
                check(bus, "switched-shunt control")?;
            }
        }
        for g in &self.generators {
            check(g.bus, "generator")?;
            if let Some(bus) = g.regulated_bus {
                check(bus, "generator voltage control")?;
            }
        }
        for d in &self.hvdc {
            check(d.from, "dcline")?;
            check(d.to, "dcline")?;
        }
        for s in &self.storage {
            check(s.bus, "storage")?;
        }
        for a in &self.areas {
            if let Some(slack) = a.slack_bus {
                check(slack, "area swing")?;
            }
        }
        for t in &self.transformers_3w {
            for w in &t.windings {
                check(w.bus, "3-winding transformer")?;
            }
        }
        // Star expansion allocates synthetic bus ids `max_bus_id + 1 + k`, one
        // per in-service 3-winding transformer; a bus id near usize::MAX would
        // overflow that allocation (and in release wrap onto an existing bus).
        // The base id `max + 1` is computed whenever any 3-winding transformer
        // is present, even if none is in service, so the headroom is
        // `max(1, in-service count)`. No real case sits there, so refuse it at
        // the boundary like any other malformed reference.
        if !self.transformers_3w.is_empty()
            && let Some(max_id) = self.buses.iter().map(|b| b.id.0).max()
        {
            let needed = self
                .transformers_3w
                .iter()
                .filter(|t| t.in_service)
                .count()
                .max(1);
            if max_id.checked_add(needed).is_none() {
                return Err(Error::FormatRead {
                    format,
                    message: format!(
                        "bus id {max_id} leaves no room to allocate synthetic star bus ids \
                         for 3-winding transformers"
                    ),
                });
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn close(actual: f64, expected: f64) {
        assert!((actual - expected).abs() < 1e-12, "{actual} != {expected}");
    }

    #[test]
    fn quadratic_with_constant_keeps_c0_across_ncost() {
        let full = GenCost::new(2, 0.0, 0.0, vec![1.5, 2.0, 5.0]);
        assert_eq!(full.quadratic_with_constant(), Some((3.0, 2.0, 5.0)));
        assert_eq!(full.quadratic(), Some((3.0, 2.0)));

        let linear = GenCost::new(2, 0.0, 0.0, vec![2.0, 5.0]);
        assert_eq!(linear.quadratic_with_constant(), Some((0.0, 2.0, 5.0)));

        let constant = GenCost::new(2, 0.0, 0.0, vec![5.0]);
        assert_eq!(constant.quadratic_with_constant(), Some((0.0, 0.0, 5.0)));

        let piecewise = GenCost::new(1, 0.0, 0.0, vec![0.0, 0.0, 1.0, 1.0]);
        assert_eq!(piecewise.quadratic_with_constant(), None);

        let cubic = GenCost::new(2, 0.0, 0.0, vec![1.0, 1.0, 1.0, 1.0]);
        assert_eq!(cubic.quadratic_with_constant(), None);

        let truncated = GenCost::with_ncost(2, 0.0, 0.0, 3, vec![1.0]);
        assert_eq!(truncated.quadratic_with_constant(), None);
    }

    #[test]
    fn a_leading_coefficient_below_the_tolerance_comes_off_the_row() {
        let artifact = GenCost::new(2, 0.0, 0.0, vec![1e-17, 2.0, 5.0]);
        assert_eq!(
            artifact.quadratic_with_constant(),
            Some((2e-17, 2.0, 5.0)),
            "the untouched reader keeps the artifact"
        );
        assert_eq!(
            artifact.quadratic_with_constant_tol(GenCost::LEADING_COEFF_TOL),
            Some((0.0, 2.0, 5.0))
        );
        assert_eq!(
            artifact.quadratic_with_constant_tol(0.0),
            Some((2e-17, 2.0, 5.0)),
            "a zero tolerance strips an exact zero alone"
        );

        // A row states a curve of a lower order once the leading zeros are off,
        // so a cubic row the untouched reader refuses reads as a quadratic one.
        let padded = GenCost::new(2, 0.0, 0.0, vec![0.0, 1.5, 2.0, 5.0]);
        assert_eq!(padded.quadratic_with_constant(), None);
        assert_eq!(
            padded.quadratic_with_constant_tol(0.0),
            Some((3.0, 2.0, 5.0))
        );

        let flat = GenCost::new(2, 0.0, 0.0, vec![1e-17, 1e-17, 1e-17]);
        assert_eq!(
            flat.quadratic_with_constant_tol(GenCost::LEADING_COEFF_TOL),
            Some((0.0, 0.0, 1e-17)),
            "the last coefficient stays, whatever its magnitude"
        );

        let piecewise = GenCost::new(1, 0.0, 0.0, vec![0.0, 0.0, 1.0, 1.0]);
        assert_eq!(
            piecewise.quadratic_with_constant_tol(GenCost::LEADING_COEFF_TOL),
            None
        );

        let truncated = GenCost::with_ncost(2, 0.0, 0.0, 3, vec![1.0]);
        assert_eq!(
            truncated.quadratic_with_constant_tol(GenCost::LEADING_COEFF_TOL),
            None
        );

        let quartic = GenCost::new(2, 0.0, 0.0, vec![1.0, 1.0, 1.0, 1.0, 1.0]);
        assert_eq!(
            quartic.quadratic_with_constant_tol(GenCost::LEADING_COEFF_TOL),
            None
        );
    }

    #[test]
    fn synthesized_rate_follows_the_angle_window_and_the_voltage_ceilings() {
        let br = Branch::new(BusId(1), BusId(2), 0.03, 0.04);
        let expected = |window: f64, fr: f64, to: f64| {
            let separation = (fr * fr + to * to - 2.0 * fr * to * window.cos()).sqrt();
            fr.max(to) * separation / 0.05
        };
        close(
            br.synthesize_rate_a(0.5, 1.1, 1.06),
            expected(0.5, 1.1, 1.06),
        );

        // A wider window gives a looser bound.
        assert!(br.synthesize_rate_a(0.8, 1.1, 1.06) > br.synthesize_rate_a(0.5, 1.1, 1.06));

        // The magnitude of the window is what counts, and it holds at π.
        close(
            br.synthesize_rate_a(-0.5, 1.1, 1.06),
            expected(0.5, 1.1, 1.06),
        );
        for window in [6.0, 2.0 * std::f64::consts::PI, -360.0] {
            close(
                br.synthesize_rate_a(window, 1.1, 1.06),
                expected(std::f64::consts::PI, 1.1, 1.06),
            );
        }

        let ideal = Branch::new(BusId(1), BusId(2), 0.0, 0.0);
        close(ideal.synthesize_rate_a(0.5, 1.1, 1.1), 0.0);
    }

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

    fn winding(b: usize) -> Winding {
        Winding {
            bus: BusId(b),
            tap: 1.0,
            shift: 0.0,
            nominal_kv: 230.0,
            rate_a: 100.0,
            rate_b: 0.0,
            rate_c: 0.0,
        }
    }

    fn transformer_3w() -> Transformer3W {
        let z = |r, x| Impedance {
            r,
            x,
            base_mva: 100.0,
        };
        Transformer3W {
            windings: [winding(1), winding(2), winding(3)],
            z: [z(0.01, 0.10), z(0.02, 0.20), z(0.03, 0.30)],
            star_vm: 0.98,
            star_va: -1.5,
            mag_g: 0.0,
            mag_b: 0.0,
            in_service: true,
            name: Some("T1".into()),
            uid: None,
            extras: Extras::new(),
        }
    }

    #[test]
    fn star_impedances_split_the_pairwise_values() {
        // z1 = (z12 + z31 - z23)/2, z2 = (z12 + z23 - z31)/2, z3 = (z23 + z31 - z12)/2.
        let [(r1, x1), (r2, x2), (r3, x3)] = transformer_3w().star_impedances();
        close(r1, 0.01);
        close(x1, 0.10);
        close(r2, 0.0);
        close(x2, 0.0);
        close(r3, 0.02);
        close(x3, 0.20);
    }

    #[test]
    fn star_expansion_builds_a_star_bus_and_three_branches() {
        let t = transformer_3w();
        let (star, branches) = t.star_expansion(BusId(99));

        assert_eq!(star.id, BusId(99));
        close(star.vm, 0.98);
        close(star.va, -1.5);
        // Each branch runs from its winding bus to the star, carrying the
        // winding tap and ratings and the split impedance.
        for (i, br) in branches.iter().enumerate() {
            assert_eq!(br.from, t.windings[i].bus);
            assert_eq!(br.to, BusId(99));
            close(br.tap, 1.0);
            close(br.rate_a, 100.0);
        }
        close(branches[2].r, 0.02);
        close(branches[2].x, 0.20);
    }

    #[test]
    fn three_winding_transformer_survives_json_transport() {
        let mut net =
            BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2), bus(3)], Vec::new());
        net.transformers_3w.push(transformer_3w());
        net.validate().unwrap();

        let back = BalancedNetwork::from_json(&net.to_json().unwrap()).unwrap();
        assert_eq!(back.transformers_3w.len(), 1);
        close(back.transformers_3w[0].z[1].x, 0.20);
        assert_eq!(back.transformers_3w[0].windings[2].bus, BusId(3));
    }

    #[test]
    fn lowered_lengths_match_the_expansion() {
        // `lowered_lengths` counts what `expand_transformers_3w` would append
        // instead of building it. The two must agree on every mix: an
        // out-of-service unit appends nothing, and only a unit with magnetizing
        // admittance appends a shunt.
        let mut magnetizing = transformer_3w();
        magnetizing.mag_b = 0.02;
        let mut out_of_service = transformer_3w();
        out_of_service.in_service = false;
        out_of_service.mag_g = 0.01;

        for units in [
            vec![],
            vec![transformer_3w()],
            vec![magnetizing.clone()],
            vec![out_of_service.clone()],
            vec![transformer_3w(), magnetizing, out_of_service],
        ] {
            let mut net =
                BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2), bus(3)], Vec::new());
            net.shunts.push(Shunt::new(BusId(1), 0.0, 0.5));
            net.transformers_3w = units;

            let counted = net.lowered_lengths();
            let built = net.expand_transformers_3w();
            assert_eq!(counted.buses, built.buses.len());
            assert_eq!(counted.branches, built.branches.len());
            assert_eq!(counted.shunts, built.shunts.len());
        }
    }

    #[test]
    fn check_references_rejects_bus_ids_without_star_expansion_headroom() {
        // A bus id at usize::MAX would make the synthetic star id
        // `max_bus_id + 1 + k` overflow during indexed analysis; the parse
        // boundary refuses it like any other malformed reference.
        let mut net = BalancedNetwork::in_memory(
            "t",
            100.0,
            vec![bus(1), bus(2), bus(3), bus(usize::MAX)],
            Vec::new(),
        );
        net.transformers_3w.push(transformer_3w());
        let err = net.validate().unwrap_err().to_string();
        assert!(
            err.contains("no room to allocate synthetic star bus ids"),
            "got {err}"
        );
    }

    #[test]
    fn star_expansion_headroom_counts_only_in_service_transformers() {
        // The headroom needed is the in-service transformer count (plus the
        // base id), not the total: an out-of-service unit allocates no star
        // bus, so a network that only fits the in-service count must not be
        // rejected. max bus id usize::MAX - 1 fits one in-service star id
        // (max + 1) but not two.
        let mut net = BalancedNetwork::in_memory(
            "t",
            100.0,
            vec![bus(1), bus(2), bus(3), bus(usize::MAX - 1)],
            Vec::new(),
        );
        net.transformers_3w.push(transformer_3w());
        let mut out_of_service = transformer_3w();
        out_of_service.in_service = false;
        net.transformers_3w.push(out_of_service);
        net.validate()
            .expect("in-service count fits; must not be rejected");
    }

    #[test]
    fn check_references_rejects_a_dangling_winding_bus() {
        let mut net = BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2)], Vec::new());
        net.transformers_3w.push(transformer_3w()); // winding 3 references bus 3
        let err = net.validate().unwrap_err().to_string();
        assert!(
            err.contains("3-winding transformer references unknown bus 3"),
            "got {err}"
        );
    }

    /// A regulating transformer (bus 1→2) controlling the voltage at bus `reg`.
    fn regulating_branch(reg: usize) -> Branch {
        Branch {
            from: BusId(1),
            to: BusId(2),
            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: 1.0,
            shift: 0.0,
            in_service: true,
            angmin: -360.0,
            angmax: 360.0,
            control: Some(TransformerControl {
                mode: TransformerControlMode::Voltage,
                controlled_bus: Some(BusId(reg)),
                tap_min: 0.95,
                tap_max: 1.05,
                band_min: 1.0,
                band_max: 1.02,
                ntp: 17,
                mva_base: 100.0,
            }),
            solution: None,
            uid: None,
            route: None,
            extras: Extras::new(),
        }
    }

    #[test]
    fn transformer_control_survives_json_transport() {
        let mut net =
            BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2), bus(3)], Vec::new());
        net.branches.push(regulating_branch(3));
        net.validate().unwrap();

        let back = BalancedNetwork::from_json(&net.to_json().unwrap()).unwrap();
        let c = back.branches[0].control.as_ref().unwrap();
        assert_eq!(c.mode, TransformerControlMode::Voltage);
        assert_eq!(c.controlled_bus, Some(BusId(3)));
        close(c.tap_max, 1.05);
        assert_eq!(c.ntp, 17);
    }

    #[test]
    fn gen_caps_serialize_as_a_named_map_that_grows_additively() {
        let mut caps: GenCaps = [None; GEN_EXTRA_KEYS.len()];
        caps[8] = Some(1.5); // ramp_30
        caps[10] = Some(0.5); // apf
        let g = Generator {
            bus: BusId(1),
            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,
            regulated_bus: None,
            uid: None,
        };

        // caps is a name-keyed object emitting only the present slots, not a
        // length-exact array.
        let json = serde_json::to_string(&g).unwrap();
        assert!(json.contains(r#""caps":{"#), "caps is an object: {json}");
        assert!(json.contains(r#""ramp_30":1.5"#) && json.contains(r#""apf":0.5"#));
        let back: Generator = serde_json::from_str(&json).unwrap();
        assert_eq!(back.caps, g.caps);

        // Growing GEN_EXTRA_KEYS stays additive: an unknown future key is ignored,
        // a missing key reads as None, and an omitted field is the empty set.
        let with_future = r#"{"bus":1,"pg":10,"qg":0,"pmax":100,"pmin":0,"qmax":50,"qmin":-50,
            "vg":1,"mbase":100,"in_service":true,"cost":null,
            "caps":{"ramp_30":1.5,"future_ramp":9.9}}"#;
        let g2: Generator = serde_json::from_str(with_future).unwrap();
        assert_eq!(g2.caps[8], Some(1.5));
        assert_eq!(g2.caps.iter().filter(|v| v.is_some()).count(), 1);
        let no_caps = r#"{"bus":1,"pg":10,"qg":0,"pmax":100,"pmin":0,"qmax":50,"qmin":-50,
            "vg":1,"mbase":100,"in_service":true,"cost":null}"#;
        let g3: Generator = serde_json::from_str(no_caps).unwrap();
        assert!(!g3.has_caps());

        // An explicit `"caps":null` is the empty set too, the same as omitting it.
        let null_caps = r#"{"bus":1,"pg":10,"qg":0,"pmax":100,"pmin":0,"qmax":50,"qmin":-50,
            "vg":1,"mbase":100,"in_service":true,"cost":null,"caps":null}"#;
        let g4: Generator = serde_json::from_str(null_caps).unwrap();
        assert!(!g4.has_caps());
    }

    #[test]
    fn non_finite_fields_lists_every_offender_not_just_the_first() {
        let bus = |id, vm| Bus {
            id: BusId(id),
            kind: BusType::Pq,
            vm,
            va: 0.0,
            base_kv: 230.0,
            vmax: 1.1,
            vmin: 0.9,
            evhi: None,
            evlo: None,
            area: 1,
            zone: 1,
            name: None,
            uid: None,
            location: None,
            extras: Extras::new(),
        };
        let branch = Branch {
            from: BusId(1),
            to: BusId(2),
            r: 0.0,
            x: f64::INFINITY,
            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(),
        };
        // A non-finite generator capability reports at its exact key path
        // (caps serializes as a name-keyed object), not the parent `caps`.
        let mut g = Generator {
            bus: BusId(1),
            pg: 0.0,
            qg: 0.0,
            pmax: 0.0,
            pmin: 0.0,
            qmax: 0.0,
            qmin: 0.0,
            vg: 1.0,
            mbase: 100.0,
            in_service: true,
            cost: None,
            caps: GenCaps::default(),
            regulated_bus: None,
            uid: None,
        };
        g.caps[8] = Some(f64::INFINITY); // ramp_30
        // Three distinct non-finite fields: a bus vm (NaN), a branch x (Inf), and
        // a generator ramp_30 cap (Inf).
        let mut net = BalancedNetwork::in_memory(
            "nf",
            100.0,
            vec![bus(1, f64::NAN), bus(2, 1.0)],
            vec![branch],
        );
        net.generators.push(g);
        let fields = net.non_finite_fields();
        assert!(fields.contains(&"buses[0].vm".to_string()), "{fields:?}");
        assert!(fields.contains(&"branches[0].x".to_string()), "{fields:?}");
        assert!(
            fields.contains(&"generators[0].caps.ramp_30".to_string()),
            "caps reported at key precision: {fields:?}"
        );
        assert_eq!(
            fields.len(),
            3,
            "exactly the three offenders, no more: {fields:?}"
        );
    }

    #[test]
    fn check_references_rejects_a_dangling_controlled_bus() {
        let mut net = BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2)], Vec::new());
        net.branches.push(regulating_branch(9)); // controls a bus that doesn't exist
        let err = net.validate().unwrap_err().to_string();
        assert!(
            err.contains("transformer control references unknown bus 9"),
            "got {err}"
        );
    }

    /// A discrete switched shunt on bus 1 regulating the voltage at bus `reg`.
    fn switched_shunt(reg: usize) -> Shunt {
        Shunt {
            bus: BusId(1),
            g: 0.0,
            b: 19.0,
            in_service: true,
            control: Some(SwitchedShuntControl {
                mode: SwitchedShuntMode::Discrete,
                vhigh: 1.05,
                vlow: 0.95,
                control_bus: Some(BusId(reg)),
                rmpct: 100.0,
                blocks: vec![
                    ShuntBlock { steps: 2, b: 25.0 },
                    ShuntBlock { steps: 1, b: 50.0 },
                ],
            }),
            uid: None,
            extras: Extras::new(),
        }
    }

    #[test]
    fn switched_shunt_control_survives_json_transport() {
        let mut net =
            BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2), bus(3)], Vec::new());
        net.shunts.push(switched_shunt(3));
        net.validate().unwrap();

        let back = BalancedNetwork::from_json(&net.to_json().unwrap()).unwrap();
        let c = back.shunts[0].control.as_ref().unwrap();
        assert_eq!(c.mode, SwitchedShuntMode::Discrete);
        assert_eq!(c.control_bus, Some(BusId(3)));
        assert_eq!(c.blocks.len(), 2);
        close(c.blocks[1].b, 50.0);
    }

    #[test]
    fn check_references_rejects_a_dangling_switched_shunt_control_bus() {
        let mut net = BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2)], Vec::new());
        net.shunts.push(switched_shunt(9)); // controls a bus that doesn't exist
        let err = net.validate().unwrap_err().to_string();
        assert!(
            err.contains("switched-shunt control references unknown bus 9"),
            "got {err}"
        );
    }

    #[test]
    fn validate_values_flags_and_repair_clamps_out_of_domain_values() {
        let mut net = BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2)], Vec::new());
        net.buses[0].vm = 0.0; // outside [0, 2]
        net.buses[1].va = 9000.0; // past ±2000°
        net.generators.push(Generator {
            bus: BusId(1),
            pg: 10.0,
            qg: 0.0,
            pmax: 100.0,
            pmin: 0.0,
            qmax: 50.0,
            qmin: -50.0,
            vg: 0.0,    // non-positive setpoint
            mbase: 0.0, // non-positive base
            in_service: true,
            cost: None,
            caps: Default::default(),
            regulated_bus: None,
            uid: None,
        });

        let diags = net.validate_values();
        let fields: std::collections::BTreeSet<_> = diags.iter().map(|d| d.field).collect();
        assert_eq!(
            fields,
            ["mbase", "va", "vg", "vm"].into_iter().collect(),
            "all four out-of-domain fields reported"
        );
        // Non-mutating: the network still holds the bad values.
        close(net.buses[0].vm, 0.0);

        let applied = net.repair();
        assert_eq!(applied.len(), diags.len());
        close(net.buses[0].vm, 1.0);
        close(net.buses[1].va, 0.0);
        close(net.generators[0].mbase, 100.0); // → base_mva
        close(net.generators[0].vg, 1.0);
        // Idempotent: nothing left to repair.
        assert!(net.validate_values().is_empty());
    }

    #[test]
    fn validate_values_is_empty_for_a_clean_network() {
        let net = BalancedNetwork::in_memory("t", 100.0, vec![bus(1), bus(2)], Vec::new());
        assert!(net.validate_values().is_empty());
    }
}