powerio/format/

powermodels.rs

//! Write a [`BalancedNetwork`] as PowerModels.jl network data JSON.
//!
//! Output is idiomatic PowerModels data with `per_unit = true`, the same form
//! PowerModels itself exports: powers are divided by `baseMVA`, angles are in
//! radians, and gen cost coefficients are rescaled to the per-unit basis (a
//! polynomial term `p^j` by `baseMVA^j`, a piecewise curve's MW breakpoints by
//! `1/baseMVA`). Because the data already declares per unit, `parse_file(out.json)`
//! reads it with PowerModels' default `validate = true` without rerunning
//! `make_per_unit!`, so it lands on the same network as `parse_file(case.m)`.
//! Loads and shunts are first-class on the `BalancedNetwork`; branch terminal admittance
//! writes as PowerModels' `g_fr`/`b_fr`/`g_to`/`b_to` fields, with MATPOWER
//! `BR_B` expanded only when no richer terminal model is present. `transformer`
//! follows PowerModels' rule (raw tap `≠ 0`). `hvdc`/`storage` are mapped to the
//! closest PowerModels blocks and emit a warning when present.

use std::sync::Arc;

use serde_json::{Map, Value};

use super::{Conversion, finish, jnum, warn_extra_branch_rating_sets};
use crate::network::{
    BalancedNetwork, Branch, BranchCharging, BranchCurrentRatings, BranchSolution, Bus, BusId,
    BusType, GEN_EXTRA_KEYS, GenCost, Generator, Hvdc, Load, LoadVoltageModel, Shunt, SourceFormat,
    Storage, Switch,
};
use crate::normalize::{self, GEN_PU_KEYS};
use crate::{Error, Result};

#[must_use]
#[expect(clippy::too_many_lines)]
pub fn write_powermodels_json(net: &BalancedNetwork) -> Conversion {
    let mut warnings = Vec::new();

    // Per-unit write factors, the exact inverse of the reader's pscale/ascale:
    // powers ÷ baseMVA, angles degrees → radians. Cost rescale needs the base.
    let base = net.base_mva;
    let p = 1.0 / base;
    let a = normalize::DEG_TO_RAD;

    let mut bus = Map::new();
    for b in &net.buses {
        bus.insert(b.id.to_string(), bus_obj(b, a));
    }

    let mut branch = Map::new();
    for (i, br) in net.branches.iter().enumerate() {
        let idx = i + 1;
        branch.insert(idx.to_string(), branch_obj(br, idx, p, a));
    }

    let mut gen_map = Map::new();
    for (i, g) in net.generators.iter().enumerate() {
        let idx = i + 1;
        gen_map.insert(idx.to_string(), gen_obj(g, idx, p, base));
    }

    let mut load = Map::new();
    for (i, l) in net.loads.iter().enumerate() {
        let idx = i + 1;
        load.insert(idx.to_string(), load_obj(l, idx, p));
    }
    let mut shunt = Map::new();
    for (i, s) in net.shunts.iter().enumerate() {
        let idx = i + 1;
        shunt.insert(idx.to_string(), shunt_obj(s, idx, p));
    }

    let mut dcline = Map::new();
    for (i, dc) in net.hvdc.iter().enumerate() {
        let idx = i + 1;
        dcline.insert(idx.to_string(), dcline_obj(dc, idx, p));
    }
    let mut storage = Map::new();
    for (i, st) in net.storage.iter().enumerate() {
        let idx = i + 1;
        storage.insert(idx.to_string(), storage_obj(st, idx, p));
    }
    let mut switch = Map::new();
    for (i, sw) in net.switches.iter().enumerate() {
        let idx = i + 1;
        switch.insert(idx.to_string(), switch_obj(sw, idx, p));
    }
    if !dcline.is_empty() {
        warnings.push(format!(
            "{} dcline(s) mapped with warnings to the PowerModels dcline schema",
            dcline.len()
        ));
    }
    if !storage.is_empty() {
        warnings.push(format!(
            "{} storage unit(s) mapped with warnings to the PowerModels storage schema",
            storage.len()
        ));
    }
    if !net.transformers_3w.is_empty() {
        warnings.push(format!(
            "{} 3-winding transformer(s) dropped: the PowerModels JSON writer emits no 3-winding record",
            net.transformers_3w.len()
        ));
    }
    let voltage_loads = net
        .loads
        .iter()
        .filter(|l| {
            l.voltage_model
                .as_ref()
                .is_some_and(LoadVoltageModel::has_non_matpower_fields)
        })
        .count();
    if voltage_loads > 0 {
        warnings.push(format!(
            "{voltage_loads} voltage dependent load model(s) dropped: PowerModels load records carry static pd/qd only"
        ));
    }
    warn_extra_branch_rating_sets("PowerModels JSON", net, &mut warnings);
    if net
        .buses
        .iter()
        .any(|b| b.evhi.is_some() || b.evlo.is_some())
    {
        warnings.push(
            "emergency voltage band(s) (EVHI/EVLO) dropped: this writer carries one voltage band"
                .into(),
        );
    }

    let mut root = Map::new();
    root.insert("name".into(), Value::String(net.name.clone()));
    root.insert("baseMVA".into(), jnum(net.base_mva));
    root.insert("per_unit".into(), Value::Bool(true));
    root.insert("source_type".into(), Value::String("matpower".into()));
    root.insert("source_version".into(), Value::String("2".into()));
    root.insert("bus".into(), Value::Object(bus));
    root.insert("branch".into(), Value::Object(branch));
    root.insert("gen".into(), Value::Object(gen_map));
    root.insert("load".into(), Value::Object(load));
    root.insert("shunt".into(), Value::Object(shunt));
    root.insert("dcline".into(), Value::Object(dcline));
    root.insert("storage".into(), Value::Object(storage));
    root.insert("switch".into(), Value::Object(switch));

    finish(root, warnings)
}

/// PowerModels back-reference `["bus"|"branch"|…, index]`.
fn source_id(kind: &str, idx: usize) -> Value {
    Value::Array(vec![Value::String(kind.into()), Value::from(idx as u64)])
}

fn status_int(in_service: bool) -> Value {
    Value::from(u64::from(in_service))
}

fn bus_obj(b: &Bus, a: f64) -> Value {
    let mut m = Map::new();
    m.insert("bus_i".into(), Value::from(b.id.0 as u64));
    m.insert("index".into(), Value::from(b.id.0 as u64));
    m.insert("bus_type".into(), Value::from(u64::from(b.kind as u8)));
    m.insert("vm".into(), jnum(b.vm));
    m.insert("va".into(), jnum(b.va * a));
    m.insert("vmax".into(), jnum(b.vmax));
    m.insert("vmin".into(), jnum(b.vmin));
    m.insert("base_kv".into(), jnum(b.base_kv));
    m.insert("area".into(), Value::from(b.area as u64));
    m.insert("zone".into(), Value::from(b.zone as u64));
    if let Some(name) = &b.name {
        m.insert("name".into(), Value::String(name.clone()));
    }
    m.insert("source_id".into(), source_id("bus", b.id.0));
    Value::Object(m)
}

fn branch_obj(br: &Branch, idx: usize, p: f64, a: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("f_bus".into(), Value::from(br.from.0 as u64));
    m.insert("t_bus".into(), Value::from(br.to.0 as u64));
    m.insert("br_r".into(), jnum(br.r));
    m.insert("br_x".into(), jnum(br.x));
    let charging = br.terminal_charging();
    m.insert("b_fr".into(), jnum(charging.b_fr));
    m.insert("b_to".into(), jnum(charging.b_to));
    m.insert("g_fr".into(), jnum(charging.g_fr));
    m.insert("g_to".into(), jnum(charging.g_to));
    m.insert("tap".into(), jnum(br.effective_tap()));
    m.insert("shift".into(), jnum(br.shift * a));
    m.insert("br_status".into(), status_int(br.in_service));
    m.insert("angmin".into(), jnum(br.angmin * a));
    m.insert("angmax".into(), jnum(br.angmax * a));
    // PowerModels' rule: a transformer is a branch with an off-nominal raw tap.
    // A pure phase shifter (tap 0, shift ≠ 0) is not flagged, matching matpower.jl.
    m.insert("transformer".into(), Value::Bool(br.tap != 0.0));
    // PowerModels omits a rate when it is 0 (unlimited).
    if br.rate_a != 0.0 {
        m.insert("rate_a".into(), jnum(br.rate_a * p));
    }
    if br.rate_b != 0.0 {
        m.insert("rate_b".into(), jnum(br.rate_b * p));
    }
    if br.rate_c != 0.0 {
        m.insert("rate_c".into(), jnum(br.rate_c * p));
    }
    if let Some(current) = br.current_ratings {
        if current.c_rating_a != 0.0 {
            m.insert("c_rating_a".into(), jnum(current.c_rating_a));
        }
        if current.c_rating_b != 0.0 {
            m.insert("c_rating_b".into(), jnum(current.c_rating_b));
        }
        if current.c_rating_c != 0.0 {
            m.insert("c_rating_c".into(), jnum(current.c_rating_c));
        }
    }
    if let Some(solution) = br.solution {
        m.insert("pf".into(), jnum(solution.pf * p));
        m.insert("qf".into(), jnum(solution.qf * p));
        m.insert("pt".into(), jnum(solution.pt * p));
        m.insert("qt".into(), jnum(solution.qt * p));
    }
    m.insert("source_id".into(), source_id("branch", idx));
    Value::Object(m)
}

fn gen_obj(g: &Generator, idx: usize, p: f64, base: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("gen_bus".into(), Value::from(g.bus.0 as u64));
    m.insert("pg".into(), jnum(g.pg * p));
    m.insert("qg".into(), jnum(g.qg * p));
    m.insert("qmax".into(), jnum(g.qmax * p));
    m.insert("qmin".into(), jnum(g.qmin * p));
    m.insert("vg".into(), jnum(g.vg));
    m.insert("mbase".into(), jnum(g.mbase));
    m.insert("gen_status".into(), status_int(g.in_service));
    m.insert("pmax".into(), jnum(g.pmax * p));
    m.insert("pmin".into(), jnum(g.pmin * p));
    // Gen capability columns, in PowerModels' field order, for those present. Only
    // the ramp rates are per-unitized; the PQ curve points and apf stay raw.
    for (i, key) in GEN_EXTRA_KEYS.iter().enumerate() {
        if let Some(v) = g.caps[i] {
            let scaled = if GEN_PU_KEYS.contains(key) {
                jnum(v * p)
            } else {
                jnum(v)
            };
            m.insert((*key).into(), scaled);
        }
    }
    if let Some(cost) = &g.cost {
        let coeffs: Vec<Value> = normalize::cost_to_pu(cost, base)
            .into_iter()
            .map(jnum)
            .collect();
        // Emit `ncost` consistent with the coefficients actually written. The reader
        // un-scales by the array length, so a mismatched `ncost` (from a malformed
        // row that claimed more coefficients than it carried) would reconstruct the
        // wrong polynomial degree.
        let ncost = if cost.model == 1 {
            coeffs.len() / 2
        } else {
            coeffs.len()
        };
        m.insert("model".into(), Value::from(u64::from(cost.model)));
        m.insert("ncost".into(), Value::from(ncost as u64));
        m.insert("startup".into(), jnum(cost.startup));
        m.insert("shutdown".into(), jnum(cost.shutdown));
        m.insert("cost".into(), Value::Array(coeffs));
    }
    m.insert("source_id".into(), source_id("gen", idx));
    Value::Object(m)
}

fn load_obj(l: &Load, idx: usize, p: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("load_bus".into(), Value::from(l.bus.0 as u64));
    m.insert("pd".into(), jnum(l.p * p));
    m.insert("qd".into(), jnum(l.q * p));
    m.insert("status".into(), status_int(l.in_service));
    m.insert("source_id".into(), source_id("bus", l.bus.0));
    Value::Object(m)
}

fn shunt_obj(s: &Shunt, idx: usize, p: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("shunt_bus".into(), Value::from(s.bus.0 as u64));
    m.insert("gs".into(), jnum(s.g * p));
    m.insert("bs".into(), jnum(s.b * p));
    m.insert("status".into(), status_int(s.in_service));
    m.insert("source_id".into(), source_id("bus", s.bus.0));
    Value::Object(m)
}

fn dcline_obj(dc: &Hvdc, idx: usize, p: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("f_bus".into(), Value::from(dc.from.0 as u64));
    m.insert("t_bus".into(), Value::from(dc.to.0 as u64));
    m.insert("br_status".into(), status_int(dc.in_service));
    m.insert("pf".into(), jnum(dc.pf * p));
    // MATPOWER uses the opposite sign for Pt/Qf/Qt; PowerModels flips them.
    m.insert("pt".into(), jnum(-dc.pt * p));
    m.insert("qf".into(), jnum(-dc.qf * p));
    m.insert("qt".into(), jnum(-dc.qt * p));
    m.insert("vf".into(), jnum(dc.vf));
    m.insert("vt".into(), jnum(dc.vt));
    // Per-end active-power bounds, derived from the aggregate Pmin/Pmax and the
    // loss model exactly as PowerModels' matpower loader does (_mp2pm_dcline!), so
    // the line reads back through PowerModels' own correct_dclines! pass. Derived
    // in raw MW, then per-unitized like everything else.
    let (pminf, pmaxf, pmint, pmaxt) = dcline_p_bounds(dc.pmin, dc.pmax, dc.loss0, dc.loss1);
    m.insert("pminf".into(), jnum(pminf * p));
    m.insert("pmaxf".into(), jnum(pmaxf * p));
    m.insert("pmint".into(), jnum(pmint * p));
    m.insert("pmaxt".into(), jnum(pmaxt * p));
    // The original aggregate bounds, kept raw, as PowerModels does.
    m.insert("mp_pmin".into(), jnum(dc.pmin));
    m.insert("mp_pmax".into(), jnum(dc.pmax));
    m.insert("qminf".into(), jnum(dc.qminf * p));
    m.insert("qmaxf".into(), jnum(dc.qmaxf * p));
    m.insert("qmint".into(), jnum(dc.qmint * p));
    m.insert("qmaxt".into(), jnum(dc.qmaxt * p));
    m.insert("loss0".into(), jnum(dc.loss0 * p));
    m.insert("loss1".into(), jnum(dc.loss1));
    if let Some(cost) = &dc.cost {
        let coeffs: Vec<Value> = normalize::cost_to_pu(cost, 1.0 / p)
            .into_iter()
            .map(jnum)
            .collect();
        let ncost = if cost.model == 1 {
            coeffs.len() / 2
        } else {
            coeffs.len()
        };
        m.insert("model".into(), Value::from(u64::from(cost.model)));
        m.insert("ncost".into(), Value::from(ncost as u64));
        m.insert("startup".into(), jnum(cost.startup));
        m.insert("shutdown".into(), jnum(cost.shutdown));
        m.insert("cost".into(), Value::Array(coeffs));
    }
    m.insert("source_id".into(), source_id("dcline", idx));
    Value::Object(m)
}

/// Per-end active-power bounds `(pminf, pmaxf, pmint, pmaxt)` for an HVDC line,
/// from the aggregate Pmin/Pmax and the loss model, branching on the bound signs
/// exactly as PowerModels' `_mp2pm_dcline!` does. Inputs and outputs are raw MW.
fn dcline_p_bounds(pmin: f64, pmax: f64, loss0: f64, loss1: f64) -> (f64, f64, f64, f64) {
    let l = 1.0 - loss1;
    if pmin >= 0.0 && pmax >= 0.0 {
        (pmin, pmax, loss0 - pmax * l, loss0 - pmin * l)
    } else if pmin >= 0.0 {
        (pmin, (-pmax + loss0) / l, pmax, loss0 - pmin * l)
    } else if pmax >= 0.0 {
        ((pmin + loss0) / l, pmax, loss0 - pmax * l, -pmin)
    } else {
        ((pmin + loss0) / l, (-pmax + loss0) / l, pmax, -pmin)
    }
}

fn storage_obj(st: &Storage, idx: usize, p: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("storage_bus".into(), Value::from(st.bus.0 as u64));
    // ps/qs are the dispatch setpoint; PowerModels' make_per_unit! leaves them raw
    // (it rescales the energy/ratings/limits below), so we do too.
    m.insert("ps".into(), jnum(st.ps));
    m.insert("qs".into(), jnum(st.qs));
    m.insert("energy".into(), jnum(st.energy * p));
    m.insert("energy_rating".into(), jnum(st.energy_rating * p));
    m.insert("charge_rating".into(), jnum(st.charge_rating * p));
    m.insert("discharge_rating".into(), jnum(st.discharge_rating * p));
    m.insert("charge_efficiency".into(), jnum(st.charge_efficiency));
    m.insert("discharge_efficiency".into(), jnum(st.discharge_efficiency));
    m.insert("thermal_rating".into(), jnum(st.thermal_rating * p));
    if let Some(current_rating) = st.current_rating {
        m.insert("current_rating".into(), jnum(current_rating));
    }
    m.insert("qmin".into(), jnum(st.qmin * p));
    m.insert("qmax".into(), jnum(st.qmax * p));
    m.insert("r".into(), jnum(st.r));
    m.insert("x".into(), jnum(st.x));
    m.insert("p_loss".into(), jnum(st.p_loss * p));
    m.insert("q_loss".into(), jnum(st.q_loss * p));
    m.insert("status".into(), status_int(st.in_service));
    m.insert("source_id".into(), source_id("storage", idx));
    Value::Object(m)
}

fn switch_obj(sw: &Switch, idx: usize, p: f64) -> Value {
    let mut m = Map::new();
    m.insert("index".into(), Value::from(idx as u64));
    m.insert("f_bus".into(), Value::from(sw.from.0 as u64));
    m.insert("t_bus".into(), Value::from(sw.to.0 as u64));
    m.insert("state".into(), status_int(sw.closed));
    if let Some(rating) = sw.thermal_rating {
        m.insert("thermal_rating".into(), jnum(rating * p));
    }
    if let Some(rating) = sw.current_rating {
        m.insert("current_rating".into(), jnum(rating));
    }
    if let Some(pf) = sw.pf {
        m.insert("pf".into(), jnum(pf * p));
    }
    if let Some(qf) = sw.qf {
        m.insert("qf".into(), jnum(qf * p));
    }
    if let Some(pt) = sw.pt {
        m.insert("pt".into(), jnum(pt * p));
    }
    if let Some(qt) = sw.qt {
        m.insert("qt".into(), jnum(qt * p));
    }
    m.insert("source_id".into(), source_id("switch", idx));
    Value::Object(m)
}

// ---- Reader: PowerModels JSON → BalancedNetwork -------------------------------------

const FMT: &str = "PowerModels JSON";

/// Parse PowerModels.jl network data JSON into a [`BalancedNetwork`]. Loads and shunts
/// are read as separate elements and the raw text is retained, so writing back
/// to PowerModels JSON is a byte-exact echo. `per_unit = true` input (powerio's own
/// output, and PowerModels' own export) is converted to the neutral MW/degree
/// convention (powers ×baseMVA, angles to degrees, cost coefficients un-scaled),
/// following PowerModels' own exceptions (storage `ps`/`qs` stay raw, dcline
/// `pt`/`qf`/`qt` flip sign); `per_unit = false` is read as-is.
pub fn parse_powermodels_json(content: &str) -> Result<BalancedNetwork> {
    let mut warnings = Vec::new();
    parse_powermodels_json_source(Arc::new(content.to_owned()), None, &mut warnings)
}

/// Owned-source entry used by the format hub: parse by borrowing `source`, then
/// move the buffer into the retained source (no copy). `name_hint` (e.g. a file
/// stem) names the network when the JSON carries no `name`.
pub(crate) fn parse_powermodels_json_source(
    source: Arc<String>,
    name_hint: Option<&str>,
    warnings: &mut Vec<String>,
) -> Result<BalancedNetwork> {
    let content: &str = &source;
    let root: Value = serde_json::from_str(content).map_err(|e| Error::FormatRead {
        format: FMT,
        message: e.to_string(),
    })?;
    let root = root.as_object().ok_or_else(|| Error::FormatRead {
        format: FMT,
        message: "top level is not a JSON object".into(),
    })?;

    // `baseMVA` is every per-unit divisor here; zero, negative, or non-finite
    // would silently poison the scaled quantities with NaN/Inf or flipped
    // signs, so reject it at the door.
    let base_mva = root
        .get("baseMVA")
        .and_then(Value::as_f64)
        .filter(|b| b.is_finite() && *b > 0.0)
        .ok_or_else(|| Error::FormatRead {
            format: FMT,
            message: "missing, nonpositive, or non-finite numeric `baseMVA`".into(),
        })?;
    let per_unit = root
        .get("per_unit")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    if root
        .get("multinetwork")
        .and_then(Value::as_bool)
        .unwrap_or(false)
    {
        warnings.push("multinetwork=true: only the top-level single snapshot was read".into());
    }
    let pscale = if per_unit { base_mva } else { 1.0 };
    let ascale = if per_unit { normalize::RAD_TO_DEG } else { 1.0 };
    let name = root
        .get("name")
        .and_then(Value::as_str)
        .or(name_hint)
        .unwrap_or("case")
        .to_string();

    let net = BalancedNetwork {
        name,
        base_mva,
        base_frequency: crate::network::DEFAULT_BASE_FREQUENCY,
        geo: None,
        buses: sorted(root, "bus", "index")
            .iter()
            .map(|v| read_bus(v, ascale))
            .collect::<Result<Vec<_>>>()?,
        loads: sorted(root, "load", "index")
            .iter()
            .map(|v| read_load(v, pscale))
            .collect(),
        shunts: sorted(root, "shunt", "index")
            .iter()
            .map(|v| read_shunt(v, pscale))
            .collect(),
        branches: read_branches(root, pscale, ascale, warnings),
        switches: sorted(root, "switch", "index")
            .iter()
            .map(|v| read_switch(v, pscale))
            .collect(),
        generators: sorted(root, "gen", "index")
            .iter()
            .map(|v| read_gen(v, pscale, base_mva, per_unit))
            .collect(),
        storage: sorted(root, "storage", "index")
            .iter()
            .map(|v| read_storage(v, pscale))
            .collect(),
        hvdc: sorted(root, "dcline", "index")
            .iter()
            .map(|v| read_hvdc(v, pscale, base_mva, per_unit))
            .collect(),
        transformers_3w: Vec::new(),
        areas: Vec::new(),
        solver: None,
        source_format: SourceFormat::PowerModelsJson,
        source: Some(source),
    };
    net.check_references(FMT)?;
    Ok(net)
}

/// Elements of a top-level section, ordered by their integer `idx_key` so a
/// re-emitted file assigns the same running keys.
fn sorted<'a>(root: &'a Map<String, Value>, section: &str, idx_key: &str) -> Vec<&'a Value> {
    sorted_keyed(root, section, idx_key)
        .into_iter()
        .map(|(_, v)| v)
        .collect()
}

/// [`sorted`] keeping each entry's map key. Only PowerModels.jl written files
/// repeat the key in an inner `index`, so the key is the identity a
/// diagnostic can always name.
fn sorted_keyed<'a>(
    root: &'a Map<String, Value>,
    section: &str,
    idx_key: &str,
) -> Vec<(&'a str, &'a Value)> {
    let Some(obj) = root.get(section).and_then(Value::as_object) else {
        return Vec::new();
    };
    let mut items: Vec<(&str, &Value)> = obj.iter().map(|(k, v)| (k.as_str(), v)).collect();
    items.sort_by_key(|(_, v)| v.get(idx_key).and_then(Value::as_i64).unwrap_or(0));
    items
}

fn f(v: &Value, key: &str) -> f64 {
    v.get(key).and_then(Value::as_f64).unwrap_or(0.0)
}
fn f_or(v: &Value, key: &str, default: f64) -> f64 {
    v.get(key).and_then(Value::as_f64).unwrap_or(default)
}
fn uid(v: &Value, key: &str) -> usize {
    v.get(key).and_then(Value::as_u64).unwrap_or(0) as usize
}
/// A 0/1 status field; absent ⇒ in service. Some producers write a JSON
/// boolean instead of the MATPOWER 0/1 number; `as_f64` returns `None` for a
/// bool, so without the explicit arm a `false` here would read back as in
/// service.
fn flag(v: &Value, key: &str) -> bool {
    match v.get(key) {
        Some(Value::Bool(b)) => *b,
        Some(value) => value.as_f64() != Some(0.0),
        None => true,
    }
}

fn bustype(code: i64) -> BusType {
    match code {
        2 => BusType::Pv,
        3 => BusType::Ref,
        4 => BusType::Isolated,
        _ => BusType::Pq,
    }
}

/// Element keys the neutral model names directly are dropped here; whatever's left
/// is preserved as extras for round trips and cross format conversion.
fn extras_excluding(v: &Value, known: &[&str]) -> crate::network::Extras {
    v.as_object().map_or_else(Default::default, |obj| {
        obj.iter()
            .filter(|(k, _)| !known.contains(&k.as_str()))
            .map(|(k, val)| (k.clone(), val.clone()))
            .collect()
    })
}

fn read_bus(v: &Value, ascale: f64) -> Result<Bus> {
    let id = v
        .get("bus_i")
        .or_else(|| v.get("index"))
        .and_then(Value::as_u64)
        .ok_or_else(|| Error::FormatRead {
            format: FMT,
            message: "bus record missing integer `bus_i`".into(),
        })? as usize;
    Ok(Bus {
        id: BusId(id),
        kind: bustype(v.get("bus_type").and_then(Value::as_i64).unwrap_or(1)),
        vm: f_or(v, "vm", 1.0),
        va: f(v, "va") * ascale,
        base_kv: f(v, "base_kv"),
        vmax: f(v, "vmax"),
        vmin: f(v, "vmin"),
        evhi: None,
        evlo: None,
        area: uid(v, "area"),
        zone: uid(v, "zone"),
        name: v.get("name").and_then(Value::as_str).map(str::to_string),
        uid: None,
        location: None,
        extras: extras_excluding(
            v,
            &[
                "bus_i",
                "index",
                "bus_type",
                "vm",
                "va",
                "vmax",
                "vmin",
                "base_kv",
                "area",
                "zone",
                "name",
                "source_id",
            ],
        ),
    })
}

fn read_load(v: &Value, pscale: f64) -> Load {
    Load {
        bus: BusId(uid(v, "load_bus")),
        p: f(v, "pd") * pscale,
        q: f(v, "qd") * pscale,
        voltage_model: None,
        in_service: flag(v, "status"),
        uid: None,
        extras: extras_excluding(v, &["load_bus", "pd", "qd", "status", "index", "source_id"]),
    }
}

fn read_shunt(v: &Value, pscale: f64) -> Shunt {
    Shunt {
        bus: BusId(uid(v, "shunt_bus")),
        g: f(v, "gs") * pscale,
        b: f(v, "bs") * pscale,
        in_service: flag(v, "status"),
        control: None,
        uid: None,
        extras: extras_excluding(
            v,
            &["shunt_bus", "gs", "bs", "status", "index", "source_id"],
        ),
    }
}

/// Read the branch table, reporting the taps the `transformer` flag makes
/// this reader discard. One aggregated warning names the first few branches
/// and the total: a producer that never sets the flag would otherwise emit
/// one line per transformer.
fn read_branches(
    root: &Map<String, Value>,
    pscale: f64,
    ascale: f64,
    warnings: &mut Vec<String>,
) -> Vec<Branch> {
    const NAMED: usize = 3;
    let mut discarded: Vec<String> = Vec::new();
    let branches = sorted_keyed(root, "branch", "index")
        .iter()
        .map(|(key, v)| read_branch(v, pscale, ascale, key, &mut discarded))
        .collect();
    if !discarded.is_empty() {
        let head = discarded
            .iter()
            .take(NAMED)
            .cloned()
            .collect::<Vec<_>>()
            .join(", ");
        let rest = discarded.len().saturating_sub(NAMED);
        let tail = if rest > 0 {
            format!(" and {rest} more")
        } else {
            String::new()
        };
        warnings.push(format!(
            "{} branch(es) carry an off-nominal `tap` without `transformer: true`, \
             so the tap is discarded and the branch reads as a line: {head}{tail}",
            discarded.len()
        ));
    }
    branches
}

// Exact compare on purpose: only the literal 1.0 carries no information.
// An epsilon compare would silence the warning for real near-unit taps.
#[allow(clippy::float_cmp)]
fn read_branch(
    v: &Value,
    pscale: f64,
    ascale: f64,
    key: &str,
    discarded: &mut Vec<String>,
) -> Branch {
    // PowerModels stores the effective tap (1.0 for a line); the `transformer`
    // flag disambiguates an explicit-tap transformer from a line, which is what
    // the neutral raw-tap convention (0 = line) needs.
    let transformer = v
        .get("transformer")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let tap = if transformer {
        f_or(v, "tap", 1.0)
    } else {
        // The `transformer` flag decides the type, so this rule drops a
        // non-unit tap on an untagged branch. Warn about the drop. Taps of
        // 1 and 0 both mean no off-nominal ratio and stay quiet.
        if let Some(raw) = v.get("tap").and_then(Value::as_f64) {
            if raw != 0.0 && raw != 1.0 {
                discarded.push(format!(
                    "`{key}` ({} -> {}) tap {raw}",
                    uid(v, "f_bus"),
                    uid(v, "t_bus"),
                ));
            }
        }
        0.0
    };
    Branch {
        from: BusId(uid(v, "f_bus")),
        to: BusId(uid(v, "t_bus")),
        r: f(v, "br_r"),
        x: f(v, "br_x"),
        b: f(v, "b_fr") + f(v, "b_to"),
        charging: Some(BranchCharging {
            g_fr: f(v, "g_fr"),
            b_fr: f(v, "b_fr"),
            g_to: f(v, "g_to"),
            b_to: f(v, "b_to"),
        }),
        rate_a: f(v, "rate_a") * pscale,
        rate_b: f(v, "rate_b") * pscale,
        rate_c: f(v, "rate_c") * pscale,
        rating_sets: Vec::new(),
        current_ratings: has_any(v, &["c_rating_a", "c_rating_b", "c_rating_c"]).then_some(
            BranchCurrentRatings {
                c_rating_a: f(v, "c_rating_a"),
                c_rating_b: f(v, "c_rating_b"),
                c_rating_c: f(v, "c_rating_c"),
            },
        ),
        tap,
        shift: f(v, "shift") * ascale,
        in_service: flag(v, "br_status"),
        angmin: f(v, "angmin") * ascale,
        angmax: f(v, "angmax") * ascale,
        control: None,
        solution: has_any(v, &["pf", "qf", "pt", "qt"]).then_some(BranchSolution {
            pf: f(v, "pf") * pscale,
            qf: f(v, "qf") * pscale,
            pt: f(v, "pt") * pscale,
            qt: f(v, "qt") * pscale,
        }),
        uid: None,
        route: None,
        extras: extras_excluding(
            v,
            &[
                "f_bus",
                "t_bus",
                "br_r",
                "br_x",
                "b_fr",
                "b_to",
                "g_fr",
                "g_to",
                "tap",
                "shift",
                "br_status",
                "angmin",
                "angmax",
                "transformer",
                "rate_a",
                "rate_b",
                "rate_c",
                "c_rating_a",
                "c_rating_b",
                "c_rating_c",
                "pf",
                "qf",
                "pt",
                "qt",
                "index",
                "source_id",
            ],
        ),
    }
}

fn has_any(v: &Value, keys: &[&str]) -> bool {
    keys.iter().any(|key| v.get(*key).is_some())
}

fn read_switch(v: &Value, pscale: f64) -> Switch {
    let closed = if v.get("state").is_some() {
        flag(v, "state")
    } else {
        flag(v, "status")
    };
    Switch {
        from: BusId(uid(v, "f_bus")),
        to: BusId(uid(v, "t_bus")),
        closed,
        thermal_rating: v
            .get("thermal_rating")
            .and_then(Value::as_f64)
            .map(|x| x * pscale),
        current_rating: v.get("current_rating").and_then(Value::as_f64),
        pf: v.get("pf").and_then(Value::as_f64).map(|x| x * pscale),
        qf: v.get("qf").and_then(Value::as_f64).map(|x| x * pscale),
        pt: v.get("pt").and_then(Value::as_f64).map(|x| x * pscale),
        qt: v.get("qt").and_then(Value::as_f64).map(|x| x * pscale),
        uid: None,
        extras: extras_excluding(
            v,
            &[
                "f_bus",
                "t_bus",
                "state",
                "status",
                "thermal_rating",
                "current_rating",
                "pf",
                "qf",
                "pt",
                "qt",
                "index",
                "source_id",
            ],
        ),
    }
}

fn read_gen(v: &Value, pscale: f64, base_mva: f64, per_unit: bool) -> Generator {
    let mut caps: crate::network::GenCaps = [None; GEN_EXTRA_KEYS.len()];
    for (i, key) in GEN_EXTRA_KEYS.iter().enumerate() {
        if let Some(val) = v.get(*key).and_then(Value::as_f64) {
            // Only the ramp rates are per-unit; the PQ curve points and apf are raw.
            caps[i] = Some(if GEN_PU_KEYS.contains(key) {
                val * pscale
            } else {
                val
            });
        }
    }
    let cost = v.get("model").map(|_| read_cost(v, base_mva, per_unit));
    Generator {
        bus: BusId(uid(v, "gen_bus")),
        pg: f(v, "pg") * pscale,
        qg: f(v, "qg") * pscale,
        // The writer emits an unbounded limit (±Inf) as JSON null; read a missing
        // limit back as unbounded, not as a binding 0.0. (±Inf · pscale stays ±Inf.)
        pmax: f_or(v, "pmax", f64::INFINITY) * pscale,
        pmin: f_or(v, "pmin", f64::NEG_INFINITY) * pscale,
        qmax: f_or(v, "qmax", f64::INFINITY) * pscale,
        qmin: f_or(v, "qmin", f64::NEG_INFINITY) * pscale,
        vg: f_or(v, "vg", 1.0),
        mbase: f_or(v, "mbase", base_mva),
        in_service: flag(v, "gen_status"),
        cost,
        caps,
        regulated_bus: None,
        uid: None,
    }
}

fn read_cost(v: &Value, base_mva: f64, per_unit: bool) -> GenCost {
    // Keep non-numeric entries as NaN rather than dropping them: silently filtering
    // would shift every later coefficient's polynomial degree.
    let mut coeffs_raw: Vec<f64> = v
        .get("cost")
        .and_then(Value::as_array)
        .map(|a| a.iter().map(|c| c.as_f64().unwrap_or(f64::NAN)).collect())
        .unwrap_or_default();
    // An out-of-range model number must not wrap into 1/2 (`as u8` turns 257
    // into Piecewise and rescales coefficients that were never per-unit);
    // saturate into the unknown-model passthrough instead.
    let model = v
        .get("model")
        .and_then(Value::as_u64)
        .map_or(2, |m| u8::try_from(m).unwrap_or(u8::MAX));
    // MATPOWER pads gencost rows to the matrix width with trailing zeros, and
    // third-party JSON can retain that padding. Trim to the declared ncost
    // before the per-unit unscale, as `cost_to_pu` does on the way out, so
    // padding can't read as a higher-degree polynomial and mis-scale every
    // coefficient.
    // Fallible conversion: an ncost beyond usize (32-bit targets) reads as
    // undeclared instead of truncating into a small in-range value.
    let declared_ncost = v
        .get("ncost")
        .and_then(Value::as_u64)
        .and_then(|n| usize::try_from(n).ok());
    if let Some(n) = declared_ncost {
        let keep = if model == 1 { n.saturating_mul(2) } else { n };
        if keep < coeffs_raw.len() {
            coeffs_raw.truncate(keep);
        }
    }
    let k = coeffs_raw.len();
    // Undo PowerModels' per-unit cost scaling for the neutral MW basis (the
    // inverse of the writer's per-unit rescale); a non-per-unit source is read
    // as-is.
    let coeffs = if per_unit {
        normalize::cost_from_pu(&coeffs_raw, model, base_mva)
    } else {
        coeffs_raw
    };
    // A polynomial's ncost is its coefficient count; a piecewise curve stores
    // 2·ncost values ((mw, cost) pairs).
    let default_ncost = if model == 1 { k / 2 } else { k };
    GenCost {
        model,
        startup: f(v, "startup"),
        shutdown: f(v, "shutdown"),
        // Clamp to what the coefficients can back: an ncost declared beyond
        // the vector length would make the GenCost internally inconsistent.
        ncost: declared_ncost.map_or(default_ncost, |n| n.min(default_ncost)),
        coeffs,
    }
}

fn read_hvdc(v: &Value, pscale: f64, base_mva: f64, per_unit: bool) -> Hvdc {
    // Aggregate bounds come from PowerModels' raw originals (mp_pmin/mp_pmax); fall
    // back to the from-end per-unit bounds for input that lacks them.
    let pmin = v
        .get("mp_pmin")
        .and_then(Value::as_f64)
        .unwrap_or_else(|| f(v, "pminf") * pscale);
    let pmax = v
        .get("mp_pmax")
        .and_then(Value::as_f64)
        .unwrap_or_else(|| f(v, "pmaxf") * pscale);
    Hvdc {
        from: BusId(uid(v, "f_bus")),
        to: BusId(uid(v, "t_bus")),
        in_service: flag(v, "br_status"),
        pf: f(v, "pf") * pscale,
        // PowerModels flips Pt/Qf/Qt vs MATPOWER; undo it for the neutral model.
        pt: -f(v, "pt") * pscale,
        qf: -f(v, "qf") * pscale,
        qt: -f(v, "qt") * pscale,
        vf: f_or(v, "vf", 1.0),
        vt: f_or(v, "vt", 1.0),
        pmin,
        pmax,
        // Unbounded reactive limits (±Inf) write as null; read them back unbounded.
        qminf: f_or(v, "qminf", f64::NEG_INFINITY) * pscale,
        qmaxf: f_or(v, "qmaxf", f64::INFINITY) * pscale,
        qmint: f_or(v, "qmint", f64::NEG_INFINITY) * pscale,
        qmaxt: f_or(v, "qmaxt", f64::INFINITY) * pscale,
        loss0: f(v, "loss0") * pscale,
        loss1: f(v, "loss1"),
        cost: v.get("model").map(|_| read_cost(v, base_mva, per_unit)),
        uid: None,
        extras: extras_excluding(
            v,
            &[
                "f_bus",
                "t_bus",
                "br_status",
                "pf",
                "pt",
                "qf",
                "qt",
                "vf",
                "vt",
                "pmin",
                "pmax",
                "mp_pmin",
                "mp_pmax",
                "pminf",
                "pmaxf",
                "pmint",
                "pmaxt",
                "qminf",
                "qmaxf",
                "qmint",
                "qmaxt",
                "loss0",
                "loss1",
                "model",
                "ncost",
                "startup",
                "shutdown",
                "cost",
                "index",
                "source_id",
            ],
        ),
    }
}

fn read_storage(v: &Value, pscale: f64) -> Storage {
    Storage {
        bus: BusId(uid(v, "storage_bus")),
        ps: f(v, "ps"),
        qs: f(v, "qs"),
        energy: f(v, "energy") * pscale,
        energy_rating: f(v, "energy_rating") * pscale,
        charge_rating: f(v, "charge_rating") * pscale,
        discharge_rating: f(v, "discharge_rating") * pscale,
        charge_efficiency: f_or(v, "charge_efficiency", 1.0),
        discharge_efficiency: f_or(v, "discharge_efficiency", 1.0),
        thermal_rating: f(v, "thermal_rating") * pscale,
        current_rating: v.get("current_rating").and_then(Value::as_f64),
        // Unbounded reactive limits (±Inf) write as null; read them back unbounded.
        qmin: f_or(v, "qmin", f64::NEG_INFINITY) * pscale,
        qmax: f_or(v, "qmax", f64::INFINITY) * pscale,
        r: f(v, "r"),
        x: f(v, "x"),
        p_loss: f(v, "p_loss") * pscale,
        q_loss: f(v, "q_loss") * pscale,
        in_service: flag(v, "status"),
        uid: None,
        extras: extras_excluding(
            v,
            &[
                "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",
                "status",
                "index",
                "source_id",
            ],
        ),
    }
}

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

    fn approx(a: f64, b: f64) -> bool {
        (a - b).abs() <= 1e-9 * a.abs().max(b.abs()).max(1.0)
    }

    #[test]
    fn boolean_status_fields_read_out_of_service() {
        let doc = r#"{"baseMVA":100.0,"per_unit":true,
            "bus":{"1":{"bus_i":1,"bus_type":3,"vm":1.0,"va":0.0,"base_kv":345.0},
                   "2":{"bus_i":2,"bus_type":1,"vm":1.0,"va":0.0,"base_kv":345.0}},
            "branch":{"1":{"f_bus":1,"t_bus":2,"br_r":0.01,"br_x":0.1,"br_status":false}},
            "gen":{"1":{"gen_bus":1,"pg":0.5,"gen_status":false}}}"#;
        let net = parse_powermodels_json(doc).unwrap();
        assert!(
            !net.branches[0].in_service,
            "br_status: false must read out of service"
        );
        assert!(
            !net.generators[0].in_service,
            "gen_status: false must read out of service"
        );
    }

    #[test]
    #[allow(clippy::float_cmp)] // exact values pass straight through the reader
    fn nonunit_tap_without_transformer_flag_warns_and_stays_a_line() {
        let doc = r#"{"baseMVA":100.0,"per_unit":true,
            "bus":{"1":{"bus_i":1,"bus_type":3,"vm":1.0,"va":0.0,"base_kv":345.0},
                   "2":{"bus_i":2,"bus_type":1,"vm":1.0,"va":0.0,"base_kv":345.0}},
            "branch":{"1":{"index":1,"f_bus":1,"t_bus":2,"br_r":0.01,"br_x":0.1,"tap":1.05},
                      "2":{"index":2,"f_bus":1,"t_bus":2,"br_r":0.01,"br_x":0.1,"tap":1.0},
                      "3":{"index":3,"f_bus":1,"t_bus":2,"br_r":0.01,"br_x":0.1,
                           "tap":1.05,"transformer":true}}}"#;
        let mut warnings = Vec::new();
        let net =
            parse_powermodels_json_source(Arc::new(doc.to_owned()), None, &mut warnings).unwrap();
        // The inference rule is unchanged: without the flag the tap is dropped
        // (raw 0 = line); only the drop of a non-unit value is reported.
        assert_eq!(net.branches[0].tap, 0.0);
        assert_eq!(net.branches[1].tap, 0.0);
        assert_eq!(net.branches[2].tap, 1.05);
        // One aggregated warning naming the offending branch by its map key,
        // which is the identity a file without an inner `index` still has.
        assert_eq!(warnings.len(), 1, "{warnings:?}");
        assert!(
            warnings[0].contains("1 branch(es)") && warnings[0].contains("`1` (1 -> 2) tap 1.05"),
            "{warnings:?}"
        );
    }

    #[test]
    fn nonpositive_base_mva_is_rejected() {
        for base in ["0.0", "-100.0", "1e999"] {
            let doc = format!(
                r#"{{"baseMVA":{base},"bus":{{"1":{{"bus_i":1,"bus_type":3,"vm":1.0,"va":0.0,"base_kv":345.0}}}}}}"#
            );
            assert!(
                parse_powermodels_json(&doc).is_err(),
                "baseMVA {base} must be rejected"
            );
        }
    }

    #[test]
    fn padded_cost_rows_trim_to_ncost_before_unscaling() {
        // MATPOWER pads gencost rows to the matrix width; the trailing zero
        // here is padding, and ncost declares the real quadratic. Untrimmed,
        // the per-unit unscale would treat the row as cubic and divide every
        // coefficient by an extra factor of base.
        let v: Value = serde_json::json!({
            "gen_bus": 1, "model": 2, "ncost": 3,
            "cost": [1.0, 1.0, 1.0, 0.0]
        });
        let cost = read_cost(&v, 100.0, true);
        assert_eq!(cost.ncost, 3);
        assert_eq!(cost.coeffs.len(), 3);
        assert!(approx(cost.coeffs[0], 1e-4));
        assert!(approx(cost.coeffs[1], 1e-2));
        assert!(approx(cost.coeffs[2], 1.0));
    }

    #[test]
    fn out_of_range_cost_model_does_not_wrap_into_rescaling() {
        // 257 as u8 would wrap to 1 (piecewise) and rescale coefficients that
        // were never per-unit; it must saturate into the unknown-model
        // passthrough instead.
        let v: Value = serde_json::json!({
            "gen_bus": 1, "model": 257,
            "cost": [10.0, 5.0]
        });
        let cost = read_cost(&v, 100.0, true);
        assert_eq!(cost.coeffs, vec![10.0, 5.0]);
    }

    #[test]
    fn gen_pu_keys_subset_of_extra_keys() {
        // The per-unitized columns must be a subset of the emitted capability
        // columns; a key not in GEN_EXTRA_KEYS would never be written or scaled,
        // and a typo here silently mis-scales a ramp rate.
        for k in GEN_PU_KEYS {
            assert!(
                GEN_EXTRA_KEYS.contains(&k),
                "{k} is not a GEN_EXTRA_KEYS column"
            );
        }
    }

    #[test]
    fn dcline_p_bounds_four_quadrants() {
        // loss0 = 1, loss1 = 0.1 ⇒ l = 0.9. Each sign quadrant of (pmin, pmax)
        // hand-computed against PowerModels' _mp2pm_dcline!.
        let q1 = dcline_p_bounds(2.0, 10.0, 1.0, 0.1);
        assert!(
            approx(q1.0, 2.0) && approx(q1.1, 10.0) && approx(q1.2, -8.0) && approx(q1.3, -0.8)
        );

        let q2 = dcline_p_bounds(2.0, -5.0, 1.0, 0.1);
        assert!(
            approx(q2.0, 2.0)
                && approx(q2.1, 6.0 / 0.9)
                && approx(q2.2, -5.0)
                && approx(q2.3, -0.8)
        );

        let q3 = dcline_p_bounds(-3.0, 10.0, 1.0, 0.1);
        assert!(
            approx(q3.0, -2.0 / 0.9)
                && approx(q3.1, 10.0)
                && approx(q3.2, -8.0)
                && approx(q3.3, 3.0)
        );

        let q4 = dcline_p_bounds(-3.0, -5.0, 1.0, 0.1);
        assert!(
            approx(q4.0, -2.0 / 0.9)
                && approx(q4.1, 6.0 / 0.9)
                && approx(q4.2, -5.0)
                && approx(q4.3, 3.0)
        );
    }
}