powerio_dist/bmopf/

write.rs

//! [`MulticonductorNetwork`] into strict BMOPF JSON.
//!
//! Output is schema valid wherever the schema permits the data.
//!
//! Numbers serialize through serde_json (shortest round trip form).
//! Nonfinite values cannot appear in JSON; they emit as 0 with a warning
//! naming the element and field.

use std::collections::{BTreeMap, BTreeSet};
use std::f64::consts::{FRAC_PI_2, PI, TAU};

use serde_json::{Map, Value, json};

use super::BmopfSchemaVersion;
use crate::convert::TextEmission;
use crate::diagnostics::codes as C;
use crate::diagnostics::{Diagnostic, DiagnosticInfo};
use crate::model::{
    ActivePowerReference, ActivePowerUnit, ConductorMatrix, Configuration, ControlVoltageReference,
    DistControlProfile, DistGenerator, DistIbr, DistLoadVoltageModel, DistTransformer, DistWinding,
    DistWindingConn, Extras, MulticonductorNetwork, ReactivePowerReference, ReactivePowerUnit,
    VoltVarControl, VoltWattControl, VoltageSource, n_winding_impedance_base,
    open_delta_connection, open_delta_pairable, pair_keys, winding_phase_pair,
};

/// Canonical identity of the default schema. Fresh proposal output uses
/// [`BmopfSchemaVersion::retrieval_url`] in `meta.$schema`.
pub const BMOPF_SCHEMA_ID: &str = BmopfSchemaVersion::Bmopf020.schema_id();

/// The version of the schema the writer targets by default, and the value it
/// stamps into `meta.schema_version`. It is
/// [`BmopfSchemaVersion::default`]`().version()`.
pub const BMOPF_SCHEMA_VERSION: &str = BmopfSchemaVersion::Bmopf020.version();

/// Untyped classes that belong to the BMOPF ecosystem. Schema 0.1.0 has no
/// top-level table for them (`additionalProperties: false` plus the free form
/// `extras` object), so under that version they re-emit under `extras`;
/// schema 0.2.0 declares all but `capacitor` at the top level, and
/// [`Writer::raw_table_at_top_level`] answers which.
const RAW_BMOPF_EXTRAS_TABLES: &[&str] = &[
    "ibr",
    "control_profile",
    "dc_bus",
    "dc_branch",
    "dc_grounding",
    "dc_load",
    "dc_source",
    "time_series",
    // An OpenDSS capacitor the dss reader could not type (a nonpositive
    // phase count) stays an untyped object. The typed `capacitor` table of
    // schema 0.1.0 is strict, so the raw properties cannot go there; they
    // re-emit under `extras`, which the schema leaves free-form.
    "capacitor",
];

/// The reader's verbatim stash of a source document's own `extras` object.
const BMOPF_EXTRAS_STASH: &str = "bmopf_extras";

/// The reader's verbatim stash of a source document's `meta` object.
const BMOPF_META_STASH: &str = "bmopf_meta";

/// The reader's verbatim stash of a source document's `terminal_conventions`.
const BMOPF_TERMINAL_CONVENTIONS_STASH: &str = "bmopf_terminal_conventions";

const IBR_EXTRA_FIELDS: &[&str] = &[
    "dc_link_coupled",
    "p_dc_min",
    "p_dc_max",
    "dc_bus",
    "dc_terminal_map",
    "dc_control",
    "dc_v_set",
    "dc_p_ref",
    "dc_droop",
    "dc_deadband",
    "r_filter",
    "x_filter",
    "b_filter_shunt",
    "grid_forming",
    "v_ref_internal",
    "cost",
    "energy_cost_rate",
    "time_series",
];

const BMOPF_DELTA_ROLLS_EXTRA: &str = "bmopf_delta_rolls";

/// Upper bound on the model-driven dimensions this writer expands
/// quadratically: the winding count feeding the `x_sc` pair table and the
/// conductor count an absent matrix is materialized at as zeros. The BMOPF
/// and DSS readers cap the same quantities at 64 on their way in, but callers
/// can construct a `MulticonductorNetwork` without those caps, and a
/// linear-size model could otherwise demand O(n²) memory here. No physical
/// element comes near this bound.
const MAX_DIM: usize = 64;

const TRANSFORMER_NO_LOAD_ALLOWED_EXTRAS: [&str; 8] = [
    "bmopf_power_base",
    "bmopf_winding_metadata",
    "g_no_load",
    "b_no_load",
    "no_load_shunt",
    "%noloadloss",
    "%imag",
    BMOPF_DELTA_ROLLS_EXTRA,
];
/// The BMOPFTools schema extension fields the regulator subtypes carry
/// beyond the shared transformer shape; read into extras verbatim and
/// re-emitted verbatim.
const REGULATOR_EXTENSION_EXTRAS: [&str; 5] = [
    "tap_ratio_min",
    "tap_ratio_max",
    "regulator_type",
    "i_max_from",
    "i_max_to",
];

/// The stated regulator ohm fields a BMOPF read stashes verbatim so a round
/// trip reproduces exactly the fields the source stated.
const REGULATOR_STATED_OHMS: [&str; 4] = [
    "r_series_from",
    "r_series_to",
    "x_series_from",
    "x_series_to",
];

const TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS: [&str; 19] = [
    "tap_min",
    "tap_max",
    "mintap",
    "maxtap",
    "numtaps",
    "pmd_tm_set",
    "pmd_tm_lb",
    "pmd_tm_ub",
    "pmd_tm_fix",
    "pmd_tm_step",
    "g_no_load",
    "b_no_load",
    "no_load_shunt",
    "r_neutral_from",
    "x_neutral_from",
    "r_neutral_to",
    "x_neutral_to",
    "%noloadloss",
    "%imag",
];

/// The regulator subtypes keep both the shared allowed extras and the
/// extension fields.
fn regulator_allowed_extras() -> Vec<&'static str> {
    TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS
        .iter()
        .chain(REGULATOR_EXTENSION_EXTRAS.iter())
        .chain(REGULATOR_STATED_OHMS.iter())
        .copied()
        .collect()
}

/// Options for BMOPF JSON output.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct BmopfEmitOptions {
    /// The schema version to write against.
    ///
    /// The default is [`BmopfSchemaVersion::Bmopf020`], the version that states
    /// every class the model carries, so output relocates nothing. Set
    /// [`BmopfSchemaVersion::Bmopf010`] to write the version the task force
    /// accepts, which moves the classes it has no table for under `extras`
    /// and reports each move.
    pub schema_version: BmopfSchemaVersion,
    /// Compatibility setting; coordinates always use schema-valid `extras.geojson`.
    /// Both values retain supported bus locations and line paths.
    pub sideload_coordinates: bool,
}

impl BmopfEmitOptions {
    /// The options with the schema version replaced.
    #[must_use]
    pub const fn with_schema_version(mut self, schema_version: BmopfSchemaVersion) -> Self {
        self.schema_version = schema_version;
        self
    }
}

/// Emits the strict BMOPF document. Every field the schema cannot carry
/// is reported in the warnings.
///
/// Transformer taps, neutral impedance, no load admittance, and the tables
/// schema 0.1.0 dropped from the top level move under `extras` instead of
/// being dropped; [the module docs](crate::bmopf) enumerate them, and state
/// when the emitted `terminal_conventions` block stops being valid.
///
/// # Panics
///
/// Never in practice: the document is maps, strings, and finite numbers,
/// which always serialize.
#[cfg(test)]
pub(crate) fn emit_bmopf_json_text(net: &MulticonductorNetwork) -> TextEmission {
    emit_bmopf_json_text_with_options(net, BmopfEmitOptions::default())
}

/// Emits BMOPF JSON with explicit options. Parks the same fields under
/// `extras` as [`emit_bmopf_json_text`].
///
/// # Panics
///
/// Never in practice: the document is maps, strings, and finite numbers,
/// which always serialize.
pub(crate) fn emit_bmopf_json_text_with_options(
    net: &MulticonductorNetwork,
    options: BmopfEmitOptions,
) -> TextEmission {
    let mut w = Writer {
        options,
        warnings: crate::diagnostics::Diagnostics::new(),
        transformer_overflow: Map::new(),
        dropped_extras: BTreeMap::new(),
    };
    let doc = w.document(net);
    w.flush_dropped_extras();
    TextEmission::new(
        serde_json::to_string_pretty(&doc).expect("maps and finite numbers") + "\n",
        Vec::new(),
        w.warnings,
    )
}

struct Writer {
    options: BmopfEmitOptions,
    warnings: crate::diagnostics::Diagnostics,
    /// Transformer fields with no slot in the schema 0.1.0 subtype defs
    /// (taps, neutral impedance, no load admittance), relocated to
    /// `extras.transformer.<subtype>.<name>` instead of dropped.
    transformer_overflow: Map<String, Value>,
    /// Passthrough extras with no schema slot, keyed by field name with the
    /// elements that carried them, flushed as one aggregated finding per
    /// field: on a real feeder one warning per field per element buried
    /// every finding a consumer would act on (#377).
    dropped_extras: BTreeMap<String, Vec<String>>,
}

impl Writer {
    fn warn(&mut self, info: &'static DiagnosticInfo, msg: impl Into<String>) {
        self.warnings.push(info, msg);
    }

    fn diagnostic(
        &mut self,
        code: &'static DiagnosticInfo,
        element_path: impl Into<String>,
        message: impl Into<String>,
        details: Map<String, Value>,
    ) {
        let mut diagnostic = Diagnostic::of(code, message)
            .with_details(details)
            .expect("writer-built details stay within the record bounds");
        crate::diagnostics::attach_target(&mut diagnostic, element_path.into());
        self.warnings.record(diagnostic);
    }

    fn transformer_diagnostic(
        &mut self,
        t: &DistTransformer,
        code: &'static DiagnosticInfo,
        message: impl Into<String>,
        mut details: Map<String, Value>,
    ) {
        details.insert("transformer".into(), json!(&t.name));
        self.diagnostic(code, format!("transformer {}", t.name), message, details);
    }

    /// Finite number guard (the jnum pattern): JSON has no Inf/NaN.
    fn num(&mut self, v: f64, what: &str) -> Value {
        if v.is_finite() {
            json!(v)
        } else {
            self.warn(
                &C::EMIT_BMOPF_VALUE_DEFAULTED,
                format!("{what}: nonfinite value emitted as 0"),
            );
            json!(0.0)
        }
    }

    fn nums(&mut self, vs: &[f64], what: &str) -> Value {
        Value::Array(vs.iter().map(|&v| self.num(v, what)).collect())
    }

    /// A rating/bound array. PMD spells an unbounded phase as JSON null,
    /// which restores as ±Inf; BMOPF has no unbounded spelling, and the
    /// `num` zero fallback would turn "no limit" into a zero limit. Drop
    /// the whole field with a warning instead.
    fn bounds(&mut self, vs: &[f64], what: &str) -> Option<Value> {
        if vs.iter().all(|v| v.is_finite()) {
            Some(json!(vs))
        } else {
            self.warn(
                &C::EMIT_BMOPF_FIELD_DROPPED,
                format!(
                    "{what}: nonfinite entries (an unbounded phase) have no BMOPF spelling; \
                 field dropped"
                ),
            );
            None
        }
    }

    fn extras_dropped(&mut self, extras: &crate::model::Extras, what: &str) {
        for key in extras.keys() {
            // `bmopf_subtype` is reader bookkeeping; `conn` marks a delta shunt
            // whose geometry already lives in the off diagonal B matrix, so it
            // is preserved, not dropped.
            if key == "bmopf_subtype" || key == "conn" {
                continue;
            }
            self.dropped_extras
                .entry(key.clone())
                .or_default()
                .push(what.to_owned());
        }
    }

    /// The elements a details list names before it collapses to a count: the
    /// record stays attributable without one details value growing with the
    /// case.
    const DROPPED_ELEMENT_LIST_CAP: usize = 100;

    /// One aggregated finding per dropped field name, carrying the count and
    /// the element list in details and, for a single element, the target.
    fn flush_dropped_extras(&mut self) {
        for (key, elements) in std::mem::take(&mut self.dropped_extras) {
            let count = elements.len();
            let mut details = Map::new();
            details.insert("field".into(), json!(key));
            details.insert("count".into(), json!(count));
            details.insert(
                "elements".into(),
                json!(elements[..count.min(Self::DROPPED_ELEMENT_LIST_CAP)]),
            );
            if count > Self::DROPPED_ELEMENT_LIST_CAP {
                details.insert("elements_truncated".into(), json!(true));
            }
            let message = if count == 1 {
                format!(
                    "{}: `{key}` has no place in the BMOPF schema; dropped from the output",
                    elements[0]
                )
            } else {
                format!("`{key}` has no place in the BMOPF schema; dropped from {count} elements")
            };
            let mut diagnostic = Diagnostic::of(&C::EMIT_BMOPF_FIELD_DROPPED, message)
                .with_details(details)
                .expect("writer-built details stay within the record bounds");
            if count == 1 {
                crate::diagnostics::attach_target(&mut diagnostic, elements[0].clone());
            }
            self.warnings.record(diagnostic);
        }
    }

    /// Provenance + schema-vintage self-identification (the BMOPF `meta` object):
    /// "generated by powerio vX, targeting BMOPF schema vintage Y." The writer
    /// owns `$schema`, `frequency`, and `case_study_generator`; every other
    /// schema `meta` field of a BMOPF source (title, authors, license, ...)
    /// folds back from the reader's stash, so a round trip keeps the case
    /// provenance. Deterministic and round-trip stable — no generated
    /// timestamp, and nothing that depends on the immediate source format
    /// (which a round trip would change) — so canonical output is idempotent.
    /// The selected schema is identified by its retrieval URI and provenance.
    fn meta(&mut self, net: &MulticonductorNetwork) -> Value {
        let mut m = Map::new();
        m.insert(
            "$schema".into(),
            json!(self.options.schema_version.retrieval_url()),
        );
        // Schema 0.1.0 has no `schema_version` field, and its `meta` rejects
        // what it does not declare, so only 0.2.0 states the version twice.
        if self.options.schema_version == BmopfSchemaVersion::Bmopf020 {
            m.insert(
                "schema_version".into(),
                json!(self.options.schema_version.version()),
            );
        }
        m.insert(
            "frequency".into(),
            self.num(net.base_frequency(), "meta frequency"),
        );
        m.insert(
            "case_study_generator".into(),
            json!({"tool": "powerio", "version": env!("CARGO_PKG_VERSION")}),
        );
        if let Some(Value::Object(stash)) = net.extras().get(BMOPF_META_STASH) {
            for (key, value) in stash {
                match key.as_str() {
                    // Writer-owned: this document is powerio's emission, at
                    // the model's frequency, against the version above. A
                    // source `schema_version` names the version that document
                    // was written against, not this one.
                    "$schema" | "schema_version" | "frequency" | "case_study_generator" => {}
                    "title" | "description" | "license" | "authors" | "data_sources"
                    | "created" | "modified" | "provenance" | "version" => {
                        m.insert(key.clone(), value.clone());
                    }
                    other => self.warn(
                        &C::EMIT_BMOPF_FIELD_DROPPED,
                        format!("meta `{other}` has no slot in the BMOPF schema; dropped"),
                    ),
                }
            }
        }
        if self.options.schema_version == BmopfSchemaVersion::Bmopf020 {
            proposal_provenance(&mut m);
        }
        Value::Object(m)
    }

    fn document(&mut self, net: &MulticonductorNetwork) -> Value {
        let mut doc = Map::new();
        if let Some(name) = &net.name() {
            doc.insert("name".into(), json!(name));
        }
        let meta = self.meta(net);
        doc.insert("meta".into(), meta);
        if let Some(Value::Object(tc)) = net.extras().get(BMOPF_TERMINAL_CONVENTIONS_STASH) {
            doc.insert("terminal_conventions".into(), Value::Object(tc.clone()));
        } else if let Some(tc) = authored_terminal_conventions(net) {
            doc.insert("terminal_conventions".into(), tc);
        }
        self.buses(net, &mut doc);
        self.line_codes(net, &mut doc);

        self.branches(net, &mut doc);
        self.injections(net, &mut doc);
        self.capacitors(net, &mut doc);

        let transformers = self.transformers(net);
        if !transformers.is_empty() {
            doc.insert("transformer".into(), Value::Object(transformers));
        }

        // Schema 0.1.0 has no top-level table for the IBR, control profile,
        // DC, and time series classes, so under that version they emit under
        // `extras`; schema 0.2.0 declares them, so they emit in place.
        let mut extras = Map::new();
        if let Some(Value::Object(stash)) = net.extras().get(BMOPF_EXTRAS_STASH) {
            extras.extend(stash.clone());
        }
        match self.options.schema_version {
            BmopfSchemaVersion::Bmopf010 => {
                self.control_profiles(net, &mut extras);
                self.ibrs(net, &mut extras);
            }
            BmopfSchemaVersion::Bmopf020 => {
                self.control_profiles(net, &mut doc);
                self.ibrs(net, &mut doc);
            }
        }
        self.untyped_bmopf_tables(net, &mut doc, &mut extras);
        if !self.transformer_overflow.is_empty() {
            let overflow = std::mem::take(&mut self.transformer_overflow);
            extras.insert("transformer".into(), Value::Object(overflow));
        }
        self.cost_version(&mut doc, &mut extras);
        if let Some(geometry) = super::geo::collection(net) {
            extras.insert("geojson".into(), geometry);
        }
        if !extras.is_empty() {
            doc.insert("extras".into(), Value::Object(extras));
        }
        self.warn_unemitted_untyped(net);
        Value::Object(doc)
    }

    fn cost_version(&mut self, doc: &mut Map<String, Value>, extras: &mut Map<String, Value>) {
        for class in ["generator", "ibr", "voltage_source"] {
            let Some(table) = doc.get_mut(class).and_then(Value::as_object_mut) else {
                continue;
            };
            for (name, value) in table {
                let Some(record) = value.as_object_mut() else {
                    continue;
                };
                if self.options.schema_version == BmopfSchemaVersion::Bmopf020 {
                    if let Some(cost) = record.remove("cost") {
                        record.entry("energy_cost_rate").or_insert(cost);
                    }
                } else if class == "voltage_source" {
                    for field in ["cost", "energy_cost_rate"] {
                        if let Some(cost) = record.remove(field) {
                            let table = extras.entry(class).or_insert_with(|| json!({}));
                            if !table.is_object() {
                                self.warn(
                                    &C::EMIT_BMOPF_FIELD_DROPPED,
                                    "voltage-source extension is not an object",
                                );
                                continue;
                            }
                            let source = table
                                .as_object_mut()
                                .unwrap()
                                .entry(name)
                                .or_insert_with(|| json!({}));
                            if !source.is_object() {
                                self.warn(
                                    &C::EMIT_BMOPF_FIELD_DROPPED,
                                    "voltage-source extension record is not an object",
                                );
                                continue;
                            }
                            source.as_object_mut().unwrap().insert(field.into(), cost);
                            self.warn(&C::EMIT_BMOPF_RETAINED_SOURCE_ONLY, format!("voltage source {name}: {field} retained in extras.voltage_source for BMOPF 0.1.0"));
                        }
                    }
                }
            }
        }
    }

    fn buses(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        let mut buses = Map::new();
        for b in net.buses() {
            let mut o = Map::new();
            o.insert("terminal_names".into(), json!(b.terminals));
            if !b.grounded.is_empty() {
                o.insert("perfectly_grounded_terminals".into(), json!(b.grounded));
            }
            for (key, scalar, phases) in [
                ("v_min", b.v_min, &b.v_min_phase),
                ("v_max", b.v_max, &b.v_max_phase),
            ] {
                if let Some(v) = scalar {
                    o.insert(
                        key.into(),
                        Value::Array(vec![
                            self.num(v, key);
                            b.phase_indices(doc.get("terminal_conventions")).len()
                        ]),
                    );
                } else if let Some(values) = phases {
                    o.insert(key.into(), self.nums(values, key));
                }
            }
            for (key, bound) in [
                ("vpn_min", &b.vpn_min),
                ("vpn_max", &b.vpn_max),
                ("vpp_min", &b.vpp_min),
                ("vpp_max", &b.vpp_max),
            ] {
                if let Some(v) = bound {
                    o.insert(key.into(), self.nums(v, &format!("bus {key}")));
                }
            }
            for (key, bound) in [
                ("vpos_min", b.vpos_min),
                ("vpos_max", b.vpos_max),
                ("vneg_max", b.vneg_max),
                ("vzero_max", b.vzero_max),
                ("vn_max", b.vn_max),
            ] {
                if let Some(v) = bound {
                    o.insert(key.into(), self.num(v, &format!("bus {key}")));
                }
            }
            self.bus_location(b);
            // Other extras have no bus fields in the schema.
            self.extras_dropped(&b.extras, &format!("bus {}", b.id));
            buses.insert(b.id.clone(), Value::Object(o));
        }
        doc.insert("bus".into(), Value::Object(buses));
    }

    fn line_codes(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        if !net.line_codes().is_empty() {
            let mut codes = Map::new();
            for c in net.line_codes() {
                let mut o = Map::new();
                // The schema requires R_series_1_1 and X_series_1_1; an
                // empty matrix would drop them and invalidate the output.
                let dim = c.r_series.len().max(c.x_series.len()).max(1);
                if c.r_series.is_empty() && c.x_series.is_empty() {
                    self.warn(
                        &C::EMIT_BMOPF_VALUE_DEFAULTED,
                        format!(
                            "linecode {}: no series matrix; emitted as 1 conductor \
                         zero impedance",
                            c.name
                        ),
                    );
                } else if c.r_series.is_empty() || c.x_series.is_empty() {
                    self.warn(
                        &C::EMIT_BMOPF_VALUE_DEFAULTED,
                        format!(
                            "linecode {}: R_series and X_series sizes disagree; the \
                         empty one emitted as zeros",
                            c.name
                        ),
                    );
                }
                self.required_matrix(&mut o, "R_series", &c.r_series, dim, &c.name);
                self.required_matrix(&mut o, "X_series", &c.x_series, dim, &c.name);
                self.flat_matrix(&mut o, "G_from", &c.g_from, &c.name);
                self.flat_matrix(&mut o, "G_to", &c.g_to, &c.name);
                self.flat_matrix(&mut o, "B_from", &c.b_from, &c.name);
                self.flat_matrix(&mut o, "B_to", &c.b_to, &c.name);
                if let Some(i_max) = &c.i_max
                    && let Some(v) = self.bounds(i_max, &format!("linecode {} i_max", c.name))
                {
                    o.insert("i_max".into(), v);
                }
                if let Some(s_max) = &c.s_max
                    && let Some(v) = self.bounds(s_max, &format!("linecode {} s_max", c.name))
                {
                    o.insert("s_max".into(), v);
                }
                if let Some(source) = &c.source {
                    o.insert("source".into(), json!(source));
                }
                self.extras_dropped(&c.extras, &format!("linecode {}", c.name));
                codes.insert(c.name.clone(), Value::Object(o));
            }
            doc.insert("linecode".into(), Value::Object(codes));
        }
    }

    fn bus_location(&mut self, b: &crate::model::DistBus) {
        if let Some(location) = b.location
            && (!location.x.is_finite() || !location.y.is_finite())
        {
            self.diagnostic(
                &C::EMIT_BMOPF_BUS_LOCATION_DROPPED,
                format!("bus {}", b.id),
                format!(
                    "bus {}: nonfinite location cannot be written to GeoJSON",
                    b.id
                ),
                json!({ "bus": b.id, "x": location.x, "y": location.y })
                    .as_object()
                    .expect("object literal")
                    .clone(),
            );
        }
    }

    fn warn_unemitted_untyped(&mut self, net: &MulticonductorNetwork) {
        for u in net.untyped_objects() {
            if Self::is_emitted_untyped(u) {
                continue;
            }
            let message = format!(
                "{} {}: class is not represented in BMOPF; dropped from the output",
                u.class, u.name
            );
            if u.class == "regcontrol" || u.class == "autotrans" {
                let mut details = Map::new();
                details.insert("class".into(), json!(&u.class));
                details.insert("name".into(), json!(&u.name));
                let code = if u.class == "regcontrol" {
                    &C::EMIT_BMOPF_REGCONTROL_DROPPED
                } else {
                    &C::EMIT_BMOPF_AUTOTRANSFORMER_DROPPED
                };
                self.diagnostic(code, format!("{} {}", u.class, u.name), message, details);
            } else {
                self.warn(&C::EMIT_BMOPF_RECORD_DROPPED, message);
            }
        }
    }

    fn is_emitted_untyped(u: &crate::model::UntypedObject) -> bool {
        RAW_BMOPF_EXTRAS_TABLES.contains(&u.class.as_str()) || u.class.starts_with("transformer.")
    }

    /// Untyped BMOPF ecosystem objects, one pass: the tables that lost
    /// their top-level slots in schema 0.1.0 re-emit under `extras`, while
    /// untyped transformer subtypes keep their place under `transformer`.
    fn untyped_bmopf_tables(
        &mut self,
        net: &MulticonductorNetwork,
        doc: &mut Map<String, Value>,
        extras: &mut Map<String, Value>,
    ) {
        self.clear_non_table_extras_slots(net, extras);
        for u in net.untyped_objects() {
            let subtype = u.class.strip_prefix("transformer.");
            if subtype.is_none() && !RAW_BMOPF_EXTRAS_TABLES.contains(&u.class.as_str()) {
                continue;
            }
            let mut unplaced = Vec::new();
            let Some(value) = raw_bmopf_value(u, &mut unplaced) else {
                self.warn(
                    &C::EMIT_BMOPF_RECORD_DROPPED,
                    format!(
                        "{} {}: the untyped BMOPF object carries no field this writer can \
                     place; dropped from the output",
                        u.class, u.name
                    ),
                );
                continue;
            };
            for text in unplaced {
                self.diagnostic(
                    &C::EMIT_BMOPF_FIELD_DROPPED,
                    format!("{} {}", u.class, u.name),
                    format!(
                        "{} {}: the value `{text}` has no field name; dropped from the \
                     output, the named fields beside it are kept",
                        u.class, u.name
                    ),
                    Map::new(),
                );
            }
            // An untyped transformer subtype lands in the top-level
            // `transformer` table, not under `extras`. Name the slot the
            // object really went to, so a warning points at the part of the
            // document a reader must look at.
            let top_level = subtype.is_none() && self.raw_table_at_top_level(&u.class);
            let slot_path = match subtype {
                Some(sub) => format!("transformer.{sub}"),
                None if top_level => u.class.clone(),
                None => format!("extras.{}", u.class),
            };
            let slot = match subtype {
                Some(sub) => doc
                    .entry("transformer")
                    .or_insert_with(|| Value::Object(Map::new()))
                    .as_object_mut()
                    .expect("the writer builds the transformer table as an object")
                    .entry(sub.to_string())
                    .or_insert_with(|| Value::Object(Map::new())),
                None if top_level => doc
                    .entry(u.class.clone())
                    .or_insert_with(|| Value::Object(Map::new())),
                None => extras
                    .entry(u.class.clone())
                    .or_insert_with(|| Value::Object(Map::new())),
            };
            // `clear_non_table_extras_slots` makes this hold, and every slot
            // the writer creates is a table. The path still runs on untrusted
            // input, so a surprise drops the object instead of the process.
            let Some(table) = slot.as_object_mut() else {
                self.warn(
                    &C::EMIT_BMOPF_RECORD_DROPPED,
                    format!(
                        "{} {}: the `{slot_path}` slot is not a table; dropped from the output",
                        u.class, u.name
                    ),
                );
                continue;
            };
            if table.insert(u.name.clone(), value).is_some() {
                self.warn(
                    &C::EMIT_BMOPF_VALUE_SUBSTITUTED,
                    format!(
                        "{} {}: the source `{slot_path}` carried an entry of the same name; \
                     the top-level object replaced it",
                        u.class, u.name
                    ),
                );
            }
        }
    }

    /// Whether this untyped BMOPF class has a top-level table in the version
    /// being written.
    ///
    /// Schema 0.2.0 declares every class in [`RAW_BMOPF_EXTRAS_TABLES`] except
    /// `capacitor`, whose top-level table stays strict there, so a capacitor
    /// too malformed to type still has no slot in it and keeps its raw
    /// properties under `extras`.
    fn raw_table_at_top_level(&self, class: &str) -> bool {
        self.options.schema_version == BmopfSchemaVersion::Bmopf020 && class != "capacitor"
    }

    /// `extras` is seeded from the source document's own `extras` object, so
    /// a value under one of the relocated table names is input, not something
    /// this writer built. A value that is not a table has no slot for a named
    /// entry; warn once per name and replace it with an empty table, which
    /// the untyped objects of that class then fill.
    fn clear_non_table_extras_slots(
        &mut self,
        net: &MulticonductorNetwork,
        extras: &mut Map<String, Value>,
    ) {
        let classes: BTreeSet<&str> = net
            .untyped_objects()
            .iter()
            .map(|u| u.class.as_str())
            .filter(|class| RAW_BMOPF_EXTRAS_TABLES.contains(class))
            .filter(|class| !self.raw_table_at_top_level(class))
            .collect();
        for class in classes {
            if extras.get(class).is_some_and(|v| !v.is_object()) {
                self.warn(
                    &C::EMIT_BMOPF_VALUE_SUBSTITUTED,
                    format!(
                        "extras `{class}`: the source value is not a table; replaced by the \
                     top-level `{class}` objects"
                    ),
                );
                extras.insert(class.to_string(), Value::Object(Map::new()));
            }
        }
    }

    /// Lines and switches.
    fn branches(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        if !net.lines().is_empty() {
            let mut lines = Map::new();
            for l in net.lines() {
                let mut o = Map::new();
                o.insert("length".into(), self.num(l.length, "line length"));
                o.insert("linecode".into(), json!(l.linecode));
                o.insert("bus_from".into(), json!(l.bus_from));
                o.insert("bus_to".into(), json!(l.bus_to));
                o.insert("terminal_map_from".into(), json!(l.terminal_map_from));
                o.insert("terminal_map_to".into(), json!(l.terminal_map_to));
                let what = format!("line {}", l.name);
                if let Some(i_max) = &l.i_max
                    && let Some(v) = self.bounds(i_max, &format!("{what} i_max"))
                {
                    o.insert("i_max".into(), v);
                }
                if let Some(s_max) = &l.s_max
                    && let Some(v) = self.bounds(s_max, &format!("{what} s_max"))
                {
                    o.insert("s_max".into(), v);
                }
                self.extras_dropped(&l.extras, &what);
                lines.insert(l.name.clone(), Value::Object(o));
            }
            doc.insert("line".into(), Value::Object(lines));
        }
        if !net.switches().is_empty() {
            let mut switches = Map::new();
            for s in net.switches() {
                let mut o = Map::new();
                o.insert("bus_from".into(), json!(s.bus_from));
                o.insert("bus_to".into(), json!(s.bus_to));
                o.insert("terminal_map_from".into(), json!(s.terminal_map_from));
                o.insert("terminal_map_to".into(), json!(s.terminal_map_to));
                o.insert("open_switch".into(), json!(s.open));
                if let Some(i_max) = &s.i_max
                    && let Some(v) = self.bounds(i_max, &format!("switch {} i_max", s.name))
                {
                    o.insert("i_max".into(), v);
                }
                self.extras_dropped(&s.extras, &format!("switch {}", s.name));
                switches.insert(s.name.clone(), Value::Object(o));
            }
            doc.insert("switch".into(), Value::Object(switches));
        }
    }

    /// Rated capacitor banks (schema 0.1.0 `capacitor`), distinct from the
    /// raw admittance `shunt` table.
    fn capacitors(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        if net.capacitors().is_empty() {
            return;
        }
        let mut caps = Map::new();
        for c in net.capacitors() {
            let mut o = Map::new();
            o.insert("bus".into(), json!(c.bus));
            o.insert("terminal_map".into(), json!(c.terminal_map));
            o.insert("configuration".into(), json!(config_str(c.configuration)));
            o.insert("q_rated".into(), self.num(c.q_rated, "capacitor q_rated"));
            o.insert("v_nom".into(), self.num(c.v_nom, "capacitor v_nom"));
            self.extras_dropped(&c.extras, &format!("capacitor {}", c.name));
            caps.insert(c.name.clone(), Value::Object(o));
        }
        doc.insert("capacitor".into(), Value::Object(caps));
    }

    /// Loads, generators, shunts, and the voltage sources.
    fn injections(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        let mut loads = Map::new();
        for l in net.loads() {
            let mut o = Map::new();
            o.insert("configuration".into(), json!(config_str(l.configuration)));
            o.insert("p_nom".into(), self.nums(&l.p_nom, "load p_nom"));
            o.insert("q_nom".into(), self.nums(&l.q_nom, "load q_nom"));
            o.insert("bus".into(), json!(l.bus));
            o.insert("terminal_map".into(), json!(l.terminal_map));
            self.load_voltage_model(&mut o, &l.voltage_model, &format!("load {}", l.name));
            self.extras_dropped(&l.extras, &format!("load {}", l.name));
            loads.insert(l.name.clone(), Value::Object(o));
        }
        let mut gens = Map::new();
        for g in net.generators() {
            gens.insert(g.name.clone(), self.generator(g));
        }
        if !loads.is_empty() {
            doc.insert("load".into(), Value::Object(loads));
        }
        if !gens.is_empty() {
            doc.insert("generator".into(), Value::Object(gens));
        }
        if !net.shunts().is_empty() {
            let mut shunts = Map::new();
            for s in net.shunts() {
                let mut o = Map::new();
                o.insert("bus".into(), json!(s.bus));
                o.insert("terminal_map".into(), json!(s.terminal_map));
                // The schema requires G_1_1 and B_1_1.
                let dim = s.g.len().max(s.b.len()).max(1);
                if s.g.is_empty() && s.b.is_empty() {
                    self.warn(
                        &C::EMIT_BMOPF_VALUE_DEFAULTED,
                        format!(
                            "shunt {}: no admittance matrix; emitted as 1 conductor \
                         zero admittance",
                            s.name
                        ),
                    );
                } else if s.g.is_empty() || s.b.is_empty() {
                    self.warn(
                        &C::EMIT_BMOPF_VALUE_DEFAULTED,
                        format!(
                            "shunt {}: G and B sizes disagree; the empty one emitted \
                         as zeros",
                            s.name
                        ),
                    );
                }
                self.required_matrix(&mut o, "G", &s.g, dim, &s.name);
                self.required_matrix(&mut o, "B", &s.b, dim, &s.name);
                self.extras_dropped(&s.extras, &format!("shunt {}", s.name));
                shunts.insert(s.name.clone(), Value::Object(o));
            }
            doc.insert("shunt".into(), Value::Object(shunts));
        }
        self.voltage_sources(net, doc);
    }

    fn voltage_sources(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        let emitted_sources = bmopf_voltage_sources(net);
        let mut sources = Map::new();
        if emitted_sources.is_empty() {
            self.warn(
                &C::EMIT_BMOPF_SOURCE_COUNT,
                "network has no voltage source; BMOPF requires exactly one",
            );
        }
        for (i, vs) in emitted_sources.iter().enumerate() {
            if i > 0 {
                self.warn(
                    &C::EMIT_BMOPF_SOURCE_COUNT,
                    format!(
                        "voltage source {}: the BMOPF formulation expects exactly one source; \
                     this network has {}",
                        vs.name,
                        emitted_sources.len()
                    ),
                );
            }
            let mut o = Map::new();
            o.insert(
                "v_magnitude".into(),
                self.nums(&vs.v_magnitude, "voltage_source v_magnitude"),
            );
            o.insert(
                "v_angle".into(),
                self.nums(&vs.v_angle, "voltage_source v_angle"),
            );
            o.insert("bus".into(), json!(&vs.bus));
            o.insert("terminal_map".into(), json!(&vs.terminal_map));
            let mut extras = vs.extras.clone();
            if let Some(rates) = &vs.energy_cost_rate {
                o.insert(
                    "energy_cost_rate".into(),
                    self.nums(rates, "voltage source energy cost rate"),
                );
                extras.remove("energy_cost_rate");
                extras.remove("cost");
            }
            if let Some(cost) = extras.remove("cost") {
                o.insert("cost".into(), cost);
            }
            self.extras_dropped(&extras, &format!("voltage source {}", vs.name));
            for (name, extras) in &vs.dropped_extras {
                self.extras_dropped(extras, &format!("voltage source {name}"));
            }
            sources.insert(vs.name.clone(), Value::Object(o));
        }
        doc.insert("voltage_source".into(), Value::Object(sources));
    }

    fn control_profiles(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        if net.control_profiles().is_empty() {
            return;
        }
        let mut profiles = Map::new();
        for profile in net.control_profiles() {
            profiles.insert(profile.name.clone(), self.control_profile(profile));
        }
        doc.insert("control_profile".into(), Value::Object(profiles));
    }

    fn control_profile(&mut self, profile: &DistControlProfile) -> Value {
        let mut o = Map::new();
        if let Some(pf) = &profile.power_factor {
            o.insert(
                "power_factor".into(),
                json!({ "pf": self.num(pf.pf, "power factor") }),
            );
        }
        if let Some(vv) = &profile.volt_var {
            o.insert("volt_var".into(), self.volt_var(vv));
        }
        if let Some(vw) = &profile.volt_watt {
            o.insert("volt_watt".into(), self.volt_watt(vw));
        }
        for (key, value) in &profile.extras {
            if value.is_object() {
                o.insert(key.clone(), value.clone());
            } else {
                self.warn(&C::EMIT_BMOPF_FIELD_DROPPED, format!(
                    "control_profile {}: extra `{key}` is not an object; dropped from the output",
                    profile.name
                ));
            }
        }
        Value::Object(o)
    }

    fn volt_var(&mut self, vv: &VoltVarControl) -> Value {
        let mut o = Map::new();
        if let Some(v) = vv.voltage_reference {
            o.insert("voltage_reference".into(), json_enum(v));
        }
        o.insert(
            "breakpoints".into(),
            self.nums(&vv.breakpoints, "volt_var breakpoints"),
        );
        o.insert(
            "q_limits".into(),
            self.nums(&vv.q_limits, "volt_var q_limits"),
        );
        if let Some(v) = vv.q_unit {
            o.insert("q_unit".into(), json_enum::<ReactivePowerUnit>(v));
        }
        if let Some(v) = vv.q_ref {
            o.insert("q_ref".into(), json_enum::<ReactivePowerReference>(v));
        }
        if let Some(v) = vv.p_min_for_q {
            o.insert("p_min_for_q".into(), self.num(v, "volt_var p_min_for_q"));
        }
        if let Some(v) = vv.p_min_for_q_max {
            o.insert(
                "p_min_for_q_max".into(),
                self.num(v, "volt_var p_min_for_q_max"),
            );
        }
        Value::Object(o)
    }

    fn volt_watt(&mut self, vw: &VoltWattControl) -> Value {
        let mut o = Map::new();
        if let Some(v) = vw.voltage_reference {
            o.insert(
                "voltage_reference".into(),
                json_enum::<ControlVoltageReference>(v),
            );
        }
        o.insert(
            "breakpoints".into(),
            self.nums(&vw.breakpoints, "volt_watt breakpoints"),
        );
        o.insert(
            "p_limits".into(),
            self.nums(&vw.p_limits, "volt_watt p_limits"),
        );
        if let Some(v) = vw.p_unit {
            o.insert("p_unit".into(), json_enum::<ActivePowerUnit>(v));
        }
        if let Some(v) = vw.p_ref {
            o.insert("p_ref".into(), json_enum::<ActivePowerReference>(v));
        }
        Value::Object(o)
    }

    fn ibrs(&mut self, net: &MulticonductorNetwork, doc: &mut Map<String, Value>) {
        if net.ibrs().is_empty() {
            return;
        }
        let mut ibrs = Map::new();
        for ibr in net.ibrs() {
            ibrs.insert(ibr.name.clone(), self.ibr(ibr));
        }
        doc.insert("ibr".into(), Value::Object(ibrs));
    }

    fn ibr(&mut self, ibr: &DistIbr) -> Value {
        let mut o = Map::new();
        o.insert("bus".into(), json!(ibr.bus));
        o.insert("terminal_map".into(), json!(ibr.terminal_map));
        o.insert("topology".into(), json_enum(ibr.topology));
        o.insert("prime_mover".into(), json_enum(ibr.prime_mover));
        o.insert("s_max".into(), self.nums(&ibr.s_max, "ibr s_max"));
        if let Some(v) = &ibr.i_max {
            o.insert("i_max".into(), self.nums(v, "ibr i_max"));
        }
        if let Some(v) = ibr.p_avail {
            o.insert("p_avail".into(), self.num(v, "ibr p_avail"));
        }
        if let Some(v) = &ibr.p_min {
            o.insert("p_min".into(), self.nums(v, "ibr p_min"));
        }
        if let Some(v) = &ibr.p_max {
            o.insert("p_max".into(), self.nums(v, "ibr p_max"));
        }
        if let Some(v) = &ibr.q_min {
            o.insert("q_min".into(), self.nums(v, "ibr q_min"));
        }
        if let Some(v) = &ibr.q_max {
            o.insert("q_max".into(), self.nums(v, "ibr q_max"));
        }
        if let Some(v) = &ibr.control_profile {
            o.insert("control_profile".into(), json!(v));
        }
        if let Some(v) = ibr.voltage_aggregation {
            o.insert("voltage_aggregation".into(), json_enum(v));
        }
        for (key, value) in &ibr.extras {
            if IBR_EXTRA_FIELDS.contains(&key.as_str()) {
                o.insert(key.clone(), value.clone());
            } else {
                self.warn(&C::EMIT_BMOPF_FIELD_DROPPED, format!(
                    "ibr {}: extra `{key}` has no place in the BMOPF schema; dropped from the output",
                    ibr.name
                ));
            }
        }
        Value::Object(o)
    }

    fn load_voltage_model(
        &mut self,
        o: &mut Map<String, Value>,
        model: &DistLoadVoltageModel,
        what: &str,
    ) {
        match model {
            DistLoadVoltageModel::ConstantPower { v_nom } => {
                o.insert("model".into(), json!("CONSTANT_POWER"));
                if !v_nom.is_empty() {
                    o.insert("v_nom".into(), self.nums(v_nom, &format!("{what} v_nom")));
                }
            }
            DistLoadVoltageModel::ConstantCurrent { v_nom } => {
                o.insert("model".into(), json!("CONSTANT_CURRENT"));
                o.insert("v_nom".into(), self.nums(v_nom, &format!("{what} v_nom")));
            }
            DistLoadVoltageModel::ConstantImpedance { v_nom } => {
                o.insert("model".into(), json!("CONSTANT_IMPEDANCE"));
                o.insert("v_nom".into(), self.nums(v_nom, &format!("{what} v_nom")));
            }
            DistLoadVoltageModel::Zip {
                v_nom,
                alpha_z,
                alpha_i,
                alpha_p,
                beta_z,
                beta_i,
                beta_p,
            } => {
                o.insert("model".into(), json!("ZIP"));
                o.insert("v_nom".into(), self.nums(v_nom, &format!("{what} v_nom")));
                o.insert(
                    "alpha_z".into(),
                    self.nums(alpha_z, &format!("{what} alpha_z")),
                );
                o.insert(
                    "alpha_i".into(),
                    self.nums(alpha_i, &format!("{what} alpha_i")),
                );
                o.insert(
                    "alpha_p".into(),
                    self.nums(alpha_p, &format!("{what} alpha_p")),
                );
                o.insert(
                    "beta_z".into(),
                    self.nums(beta_z, &format!("{what} beta_z")),
                );
                o.insert(
                    "beta_i".into(),
                    self.nums(beta_i, &format!("{what} beta_i")),
                );
                o.insert(
                    "beta_p".into(),
                    self.nums(beta_p, &format!("{what} beta_p")),
                );
            }
            DistLoadVoltageModel::Exponential {
                v_nom,
                gamma_p,
                gamma_q,
            } => {
                o.insert("model".into(), json!("EXPONENTIAL"));
                o.insert("v_nom".into(), self.nums(v_nom, &format!("{what} v_nom")));
                o.insert(
                    "gamma_p".into(),
                    self.nums(gamma_p, &format!("{what} gamma_p")),
                );
                o.insert(
                    "gamma_q".into(),
                    self.nums(gamma_q, &format!("{what} gamma_q")),
                );
            }
        }
    }

    fn generator(&mut self, g: &DistGenerator) -> Value {
        let mut o = Map::new();
        // BMOPF generators carry bounds and cost, no dispatch setpoint: a
        // fixed injection becomes pinned bounds. Explicit source bounds win
        // over the setpoint, which then has nowhere to go.
        let what = format!("generator {}", g.name);
        for (key_lo, key_hi, lo, hi, nom) in [
            ("p_min", "p_max", &g.p_min, &g.p_max, &g.p_nom),
            ("q_min", "q_max", &g.q_min, &g.q_max, &g.q_nom),
        ] {
            if lo.is_some() || hi.is_some() {
                // Pinned bounds ARE the setpoint; only a setpoint that
                // differs from the bounds has nowhere to go.
                let pinned = lo.as_deref() == Some(nom) && hi.as_deref() == Some(nom);
                if !nom.is_empty() && !nom.iter().all(|&v| v == 0.0) && !pinned {
                    self.diagnostic(
                        &C::EMIT_BMOPF_FIELD_DROPPED,
                        what.clone(),
                        format!(
                            "{what}: explicit {key_lo}/{key_hi} bounds win over the setpoint, \
                         which has no BMOPF field"
                        ),
                        Map::new(),
                    );
                }
                if let Some(v) = lo
                    && let Some(v) = self.bounds(v, &format!("{what} {key_lo}"))
                {
                    o.insert(key_lo.into(), v);
                }
                if let Some(v) = hi
                    && let Some(v) = self.bounds(v, &format!("{what} {key_hi}"))
                {
                    o.insert(key_hi.into(), v);
                }
            } else if !nom.is_empty() {
                // A fixed injection becomes pinned bounds.
                o.insert(key_lo.into(), self.nums(nom, key_lo));
                o.insert(key_hi.into(), self.nums(nom, key_hi));
            }
        }
        // BMOPF generation cost is per phase conductor. The model stores the
        // stated array exactly; a one-entry statement broadcasts to the
        // phase count, and an absent cost defaults to zero with a warning.
        let n_phase = if g.p_nom.is_empty() {
            g.terminal_map.len().max(1)
        } else {
            g.p_nom.len()
        };
        let cost = match &g.cost {
            Some(stated) if stated.len() == 1 => vec![stated[0]; n_phase],
            Some(stated) => {
                if stated.len() != n_phase {
                    self.warnings.push(
                        &C::EMIT_BMOPF_VALUE_SUBSTITUTED,
                        format!(
                            "{what}: cost states {} entries for {n_phase} phases; \
                             emitted as stated",
                            stated.len()
                        ),
                    );
                }
                stated.clone()
            }
            None => {
                self.warnings.push(
                    &C::EMIT_BMOPF_VALUE_DEFAULTED,
                    format!("{what}: no generation cost in the source; emitted cost 0"),
                );
                vec![0.0; n_phase]
            }
        };
        o.insert("cost".into(), self.nums(&cost, "generator cost"));
        if let Some(s_max) = &g.s_max
            && let Some(v) = self.bounds(s_max, &format!("{what} s_max"))
        {
            o.insert("s_max".into(), v);
        }
        if let Some(i_max) = &g.i_max
            && let Some(v) = self.bounds(i_max, &format!("{what} i_max"))
        {
            o.insert("i_max".into(), v);
        }
        o.insert("bus".into(), json!(g.bus));
        o.insert("configuration".into(), json!(config_str(g.configuration)));
        o.insert("terminal_map".into(), json!(g.terminal_map));
        if g.configuration == Configuration::Delta {
            self.warn(
                &C::EMIT_BMOPF_VALUE_SUBSTITUTED,
                format!(
                    "{what}: the BMOPF formulation covers WYE generators; DELTA emitted as written"
                ),
            );
        }
        self.extras_dropped(&g.extras, &what);
        Value::Object(o)
    }

    /// Transformers keyed by subtype; wye-wye three phase units decompose
    /// into one single_phase entry per phase, the convention the public
    /// example networks use.
    fn transformers(&mut self, net: &MulticonductorNetwork) -> Map<String, Value> {
        let mut by_subtype: Map<String, Value> = Map::new();
        let insert = |sub: &str, name: String, v: Value, map: &mut Map<String, Value>| {
            map.entry(sub.to_string())
                .or_insert_with(|| Value::Object(Map::new()))
                .as_object_mut()
                .expect("subtype maps are objects")
                .insert(name, v);
        };
        let merged = self.open_delta_pairs(net, &mut by_subtype);
        for t in net.transformers() {
            if merged.contains(&t.name) {
                continue;
            }
            self.warn_nonuniform_per_phase_taps(t);
            match classify(t) {
                Kind::SinglePhase => {
                    if t.windings.iter().any(|w| w.conn == DistWindingConn::Delta) {
                        // An open wye / open delta leg. The single_phase shape
                        // carries the terminals and impedance faithfully, but
                        // has no field for the wye/delta connection, so a
                        // consumer that models the subtype literally reads it
                        // as a wye-wye unit. Flag it; the line to line topology
                        // survives in the terminal map.
                        let connection = match (t.windings[0].conn, t.windings[1].conn) {
                            (DistWindingConn::Wye, DistWindingConn::Delta) => "wye/delta",
                            (DistWindingConn::Delta, DistWindingConn::Wye) => "delta/wye",
                            _ => "delta",
                        };
                        let mut details = Map::new();
                        details.insert("connection".into(), json!(connection));
                        details.insert("emitted_subtype".into(), json!("single_phase"));
                        self.transformer_diagnostic(
                            t,
                            &C::EMIT_BMOPF_TRANSFORMER_CONNECTION_LOSSY,
                            format!(
                                "transformer {}: single phase wye/delta emitted as single_phase; \
                                 the wye/delta connection is not encoded in the subtype, only the \
                                 line to line terminal map",
                                t.name
                            ),
                            details,
                        );
                    }
                    let v = self.two_winding(t, &t.windings[0], &t.windings[1], 1.0, true, true);
                    insert("single_phase", t.name.clone(), v, &mut by_subtype);
                }
                Kind::SinglePhaseShape(sub) => {
                    let v = self.two_winding(t, &t.windings[0], &t.windings[1], 1.0, true, true);
                    insert(sub, t.name.clone(), v, &mut by_subtype);
                }
                kind @ (Kind::Autotransformer | Kind::OpenDeltaLeg) => {
                    // A lone Kind::OpenDeltaLeg is a leg whose partner is
                    // missing or no longer identical: still a single phase
                    // autotransformer on its own.
                    if matches!(kind, Kind::OpenDeltaLeg) {
                        self.warn_unpaired_open_delta_leg(t);
                    }
                    let v = self.autotransformer(t);
                    insert(
                        "single_phase_autotransformer",
                        t.name.clone(),
                        v,
                        &mut by_subtype,
                    );
                }
                Kind::CenterTap => {
                    let v = self.center_tap(t);
                    insert("center_tap", t.name.clone(), v, &mut by_subtype);
                }
                Kind::WyeDelta => {
                    let v = self.three_phase(t, 0);
                    insert("wye_delta", t.name.clone(), v, &mut by_subtype);
                }
                Kind::DeltaWye => {
                    let v = self.three_phase(t, 1);
                    insert("delta_wye", t.name.clone(), v, &mut by_subtype);
                }
                Kind::WyeWye3 => {
                    for (k, v) in self.decompose_wye_wye(t) {
                        insert("single_phase", k, v, &mut by_subtype);
                    }
                }
                Kind::NWinding => {
                    let v = self.n_winding(t);
                    insert("n_winding", t.name.clone(), v, &mut by_subtype);
                }
                Kind::Unsupported(why) => {
                    let mut details = Map::new();
                    details.insert("reason".into(), json!(&why));
                    details.insert("phases".into(), json!(t.phases));
                    details.insert("windings".into(), json!(t.windings.len()));
                    self.transformer_diagnostic(
                        t,
                        &C::EMIT_BMOPF_TRANSFORMER_UNSUPPORTED,
                        format!(
                            "transformer {}: {why}; not representable in the BMOPF transformer \
                             subtypes, dropped from the output",
                            t.name
                        ),
                        details,
                    );
                }
            }
        }
        self.split_transformer_overflow(&mut by_subtype);
        by_subtype
    }

    /// Places the nine transformer fields schema 0.1.0 has no subtype slot
    /// for (taps, neutral impedance, no load admittance).
    ///
    /// Under schema 0.2.0 the two-winding subtypes declare all nine, so the
    /// fields stay in the subtype object and only the three tap names change:
    /// 0.2.0 spells the ratio `tap_ratio`, `tap_ratio_min`, `tap_ratio_max`,
    /// matching its regulator subtypes.
    ///
    /// Under schema 0.1.0 the subtype objects are
    /// `additionalProperties: false`, so the nine move to
    /// `extras.transformer.<subtype>.<name>` with one warning per
    /// transformer. Subtypes 0.1.0 leaves undefined (`n_winding`, untyped
    /// passthrough) are untouched under either version. The module docs
    /// enumerate the moved set for consumers; extend both together.
    fn split_transformer_overflow(&mut self, by_subtype: &mut Map<String, Value>) {
        // The transformer fields the emitters still produce that have no
        // subtype slot in schema 0.1.0. Listing the moved set (rather than
        // an allow-list of the schema shape) keeps the failure mode loud: a
        // future emitted field lands in the subtype object, where the schema
        // validation tests reject it if it has no slot.
        const MOVED_FIELDS: &[&str] = &[
            "tap",
            "tap_min",
            "tap_max",
            "r_neutral_from",
            "x_neutral_from",
            "r_neutral_to",
            "x_neutral_to",
            "g_no_load",
            "b_no_load",
            "no_load_shunt",
        ];
        if self.options.schema_version == BmopfSchemaVersion::Bmopf020 {
            rename_tap_fields(by_subtype);
            return;
        }
        for subtype in [
            "n_winding",
            "single_phase_autotransformer",
            "open_delta_regulator",
        ] {
            if let Some(table) = by_subtype.remove(subtype) {
                self.transformer_overflow.insert(subtype.into(), table);
                self.warnings.push(&C::EMIT_BMOPF_RETAINED_SOURCE_ONLY,
                    format!("transformer.{subtype} is represented under extras.transformer in schema 0.1.0"));
            }
        }
        for subtype in ["single_phase", "center_tap", "wye_delta", "delta_wye"] {
            let Some(Value::Object(table)) = by_subtype.get_mut(subtype) else {
                continue;
            };
            for (name, entry) in table.iter_mut() {
                let Value::Object(o) = entry else { continue };
                let moved: Vec<String> = MOVED_FIELDS
                    .iter()
                    .filter(|k| o.contains_key(**k))
                    .map(|k| (*k).to_string())
                    .collect();
                if moved.is_empty() {
                    continue;
                }
                let mut overflow = Map::new();
                for key in &moved {
                    if let Some(v) = o.remove(key) {
                        overflow.insert(key.clone(), v);
                    }
                }
                self.warnings.push(
                    &C::EMIT_BMOPF_RETAINED_SOURCE_ONLY,
                    format!(
                        "transformer {name}: {} have no {subtype} slot in BMOPF schema 0.1.0; \
                     kept under extras.transformer",
                        moved.join(", ")
                    ),
                );
                self.transformer_overflow
                    .entry(subtype.to_string())
                    .or_insert_with(|| Value::Object(Map::new()))
                    .as_object_mut()
                    .expect("overflow subtype tables are objects")
                    .insert(name.clone(), Value::Object(overflow));
            }
        }
    }

    fn warn_unpaired_open_delta_leg(&mut self, t: &DistTransformer) {
        self.transformer_diagnostic(
            t,
            &C::EMIT_BMOPF_VALUE_SUBSTITUTED,
            format!(
                "transformer {}: open delta leg has no matching partner leg; \
                 emitted as single_phase_autotransformer",
                t.name
            ),
            Map::new(),
        );
    }

    /// Merges classified open delta leg pairs into single
    /// `open_delta_regulator` objects and returns the merged transformer
    /// names. Legs are paired by shared bus pair; the pair must spell one of
    /// the three connections and stay electrically identical, else each leg
    /// falls back to `single_phase_autotransformer` in the main loop.
    fn open_delta_pairs(
        &mut self,
        net: &MulticonductorNetwork,
        by_subtype: &mut Map<String, Value>,
    ) -> BTreeSet<String> {
        let mut merged = BTreeSet::new();
        let mut groups: BTreeMap<(String, String), Vec<&DistTransformer>> = BTreeMap::new();
        for t in net.transformers() {
            if !matches!(classify(t), Kind::OpenDeltaLeg) {
                continue;
            }
            let key = (
                t.windings[0].bus.to_ascii_lowercase(),
                t.windings[1].bus.to_ascii_lowercase(),
            );
            groups.entry(key).or_default().push(t);
        }
        for legs in groups.into_values() {
            let [a, b] = legs[..] else { continue };
            let pair = |t: &DistTransformer| winding_phase_pair(&t.windings[0]);
            let (Some(pa), Some(pb)) = (pair(a), pair(b)) else {
                continue;
            };
            let Some((connection, swapped)) = open_delta_connection(pa, pb) else {
                continue;
            };
            if !open_delta_pairable(a, b) {
                continue;
            }
            let (first, second) = if swapped { (b, a) } else { (a, b) };
            self.warn_nonuniform_per_phase_taps(first);
            self.warn_nonuniform_per_phase_taps(second);
            let mut details = Map::new();
            details.insert("merged_leg".into(), json!(&second.name));
            details.insert("connection".into(), json!(connection));
            self.transformer_diagnostic(
                first,
                &C::EMIT_BMOPF_TRANSFORMER_OPEN_DELTA_MERGED,
                format!(
                    "transformer {}: legs {} and {} emitted as one open_delta_regulator \
                     `{}` (connection {connection})",
                    first.name, first.name, second.name, first.name
                ),
                details,
            );
            let v = self.open_delta_regulator(first, second, connection);
            by_subtype
                .entry("open_delta_regulator".to_string())
                .or_insert_with(|| Value::Object(Map::new()))
                .as_object_mut()
                .expect("subtype maps are objects")
                .insert(first.name.clone(), v);
            merged.insert(first.name.clone());
            merged.insert(second.name.clone());
        }
        merged
    }

    /// The `single_phase_autotransformer` shape of the BMOPFTools schema
    /// extension: a step voltage regulator as series plus common winding.
    /// No `v_nom` fields; the ratio is `tap_ratio` (regulated over source).
    fn autotransformer(&mut self, t: &DistTransformer) -> Value {
        let from = &t.windings[0];
        let to = &t.windings[1];
        let mut o = self.regulator_fields(t, from, to);
        o.insert("terminal_map_from".into(), json!(from.terminal_map));
        o.insert("terminal_map_to".into(), json!(to.terminal_map));
        if let Some(ratio) = self.regulator_tap_ratio(t, from, to)
            && (ratio - 1.0).abs() > 1e-12
        {
            o.insert("tap_ratio".into(), self.num(ratio, "transformer tap_ratio"));
        }
        for key in REGULATOR_EXTENSION_EXTRAS {
            if let Some(v) = t.extras.get(key) {
                o.insert(key.into(), v.clone());
            }
        }
        self.warn_unrepresented_neutral_fields(t, "single_phase_autotransformer");
        self.transformer_extras_dropped(t, &regulator_allowed_extras());
        o.into()
    }

    /// The `open_delta_regulator` shape of the BMOPFTools schema extension:
    /// two identical line to line regulating legs stated once, with the
    /// phase pairing carried by `connection` and per leg `tap_ratio` entries.
    fn open_delta_regulator(
        &mut self,
        first: &DistTransformer,
        second: &DistTransformer,
        connection: &'static str,
    ) -> Value {
        let from = &first.windings[0];
        let to = &first.windings[1];
        let mut o = self.regulator_fields(first, from, to);
        // The pairing check pins the legs to phases {1, 2, 3}; the object
        // spans the whole phase set on both sides.
        o.insert("terminal_map_from".into(), json!(["1", "2", "3"]));
        o.insert("terminal_map_to".into(), json!(["1", "2", "3"]));
        o.insert("connection".into(), json!(connection));
        let a1 = self.regulator_tap_ratio(first, from, to);
        let a2 = self.regulator_tap_ratio(second, &second.windings[0], &second.windings[1]);
        if let (Some(a1), Some(a2)) = (a1, a2)
            && ((a1 - 1.0).abs() > 1e-12 || (a2 - 1.0).abs() > 1e-12)
        {
            o.insert(
                "tap_ratio".into(),
                self.nums(&[a1, a2], "transformer tap_ratio"),
            );
        }
        for key in REGULATOR_EXTENSION_EXTRAS {
            if let Some(v) = first.extras.get(key) {
                o.insert(key.into(), v.clone());
            }
        }
        for t in [first, second] {
            self.warn_unrepresented_neutral_fields(t, "open_delta_regulator");
            self.transformer_extras_dropped(t, &regulator_allowed_extras());
        }
        o.into()
    }

    /// The fields the two regulator subtypes share: buses, rating, and the
    /// series impedance in referred ohms, leakage on the from side.
    fn regulator_fields(
        &mut self,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
    ) -> Map<String, Value> {
        let s = from.s_rating;
        let zb_from = base_impedance(from.v_ref, s);
        let zb_to = base_impedance(to.v_ref, s);
        let mut o = Map::new();
        o.insert("bus_from".into(), json!(from.bus));
        o.insert("bus_to".into(), json!(to.bus));
        o.insert("s_rating".into(), self.num(s, "transformer s_rating"));
        // A network read from BMOPF stashed the stated ohm fields verbatim
        // (the g_no_load pattern), including which of them the source stated
        // at all; prefer those so a round trip reproduces the object exactly.
        let stated = [
            "r_series_from",
            "r_series_to",
            "x_series_from",
            "x_series_to",
        ]
        .iter()
        .any(|key| t.extras.contains_key(*key));
        if stated {
            for key in [
                "r_series_from",
                "r_series_to",
                "x_series_from",
                "x_series_to",
            ] {
                if let Some(v) = t.extras.get(key) {
                    o.insert(key.into(), v.clone());
                }
            }
        } else {
            self.referred_ohms(&mut o, "r_series_from", from.r_pct, zb_from, t, "from");
            self.referred_ohms(&mut o, "r_series_to", to.r_pct, zb_to, t, "to");
            if t.xsc_pct.is_empty() {
                self.transformer_diagnostic(
                    t,
                    &C::EMIT_BMOPF_TRANSFORMER_MISSING_XSC,
                    format!(
                        "transformer {}: xsc_pct is empty; emitted x_series_from=0",
                        t.name
                    ),
                    Map::new(),
                );
            }
            let xhl = t.xsc_pct.first().copied().unwrap_or(0.0);
            self.referred_ohms(&mut o, "x_series_from", xhl, zb_from, t, "from");
            o.insert("x_series_to".into(), json!(0.0));
        }
        self.transformer_no_load_fields(&mut o, t, from, s);
        o
    }

    /// The regulation ratio (regulated over source): the to side tap over
    /// the from side tap. `None` (with a warning) when the taps cannot form
    /// a nonnegative finite ratio.
    fn regulator_tap_ratio(
        &mut self,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
    ) -> Option<f64> {
        let ratio = to.tap / from.tap;
        if ratio.is_finite() && ratio >= 0.0 {
            return Some(ratio);
        }
        let mut details = Map::new();
        details.insert("from_tap".into(), json!(from.tap));
        details.insert("to_tap".into(), json!(to.tap));
        self.transformer_diagnostic(
            t,
            &C::EMIT_BMOPF_TRANSFORMER_TAP_DROPPED,
            format!(
                "transformer {}: taps ({}, {}) cannot form a nonnegative finite \
                 BMOPF tap_ratio; dropped",
                t.name, from.tap, to.tap
            ),
            details,
        );
        None
    }

    /// Shared single_phase / center_tap shape. `to_scale` rescales the to
    /// side ratings (used by the wye-wye decomposition).
    fn two_winding(
        &mut self,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
        s_scale: f64,
        emit_no_load: bool,
        warn_extras: bool,
    ) -> Value {
        let s = from.s_rating * s_scale;
        let zb_from = base_impedance(from.v_ref, s);
        let zb_to = base_impedance(to.v_ref, s);
        let mut o = Map::new();
        o.insert("bus_from".into(), json!(from.bus));
        o.insert("bus_to".into(), json!(to.bus));
        o.insert("s_rating".into(), self.num(s, "transformer s_rating"));
        o.insert(
            "v_nom_from".into(),
            self.num(from.v_ref, "transformer v_nom_from"),
        );
        o.insert(
            "v_nom_to".into(),
            self.num(to.v_ref, "transformer v_nom_to"),
        );
        self.referred_ohms(&mut o, "r_series_from", from.r_pct, zb_from, t, "from");
        self.referred_ohms(&mut o, "r_series_to", to.r_pct, zb_to, t, "to");
        // The whole leakage reactance rides on the from side, the
        // convention the public example uses.
        if t.xsc_pct.is_empty() {
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_MISSING_XSC,
                format!(
                    "transformer {}: xsc_pct is empty; emitted x_series_from=0",
                    t.name
                ),
                Map::new(),
            );
        }
        let xhl = t.xsc_pct.first().copied().unwrap_or(0.0);
        self.referred_ohms(&mut o, "x_series_from", xhl, zb_from, t, "from");
        o.insert("x_series_to".into(), json!(0.0));
        o.insert("terminal_map_from".into(), json!(from.terminal_map));
        o.insert("terminal_map_to".into(), json!(to.terminal_map));
        self.transformer_neutral_fields(&mut o, t, from, to);
        self.transformer_tap_fields(&mut o, t, from, to);
        if emit_no_load {
            self.transformer_no_load_fields(&mut o, t, from, s);
        }
        if warn_extras {
            self.transformer_extras_dropped(t, &TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS);
        }
        o.into()
    }

    fn center_tap(&mut self, t: &DistTransformer) -> Value {
        let from = &t.windings[0];
        let (w2, w3) = (&t.windings[1], &t.windings[2]);
        let common = center_tap_common_terminal(w2, w3);
        let r_neutral = self.center_tap_neutral(t, "r_neutral", w2.r_neutral, w3.r_neutral);
        let x_neutral = self.center_tap_neutral(t, "x_neutral", w2.x_neutral, w3.x_neutral);
        if (w2.tap - w3.tap).abs() > 1e-9 {
            let mut details = Map::new();
            details.insert("from_tap".into(), json!(from.tap));
            details.insert("secondary_taps".into(), json!([w2.tap, w3.tap]));
            details.insert("emitted_secondary_tap".into(), json!(w2.tap));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_CENTER_TAP_TAP_COLLAPSED,
                format!(
                    "transformer {}: center tap secondary half winding taps ({}, {}) differ; emitted the first half tap",
                    t.name, w2.tap, w3.tap
                ),
                details,
            );
        }
        let to = center_tap_to_winding(w2, w3, &common, from.s_rating, r_neutral, x_neutral);
        if w2.s_rating.to_bits() != from.s_rating.to_bits()
            || w3.s_rating.to_bits() != from.s_rating.to_bits()
        {
            let mut details = Map::new();
            details.insert("from_s_rating".into(), json!(from.s_rating));
            details.insert("half_s_ratings".into(), json!([w2.s_rating, w3.s_rating]));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_CENTER_TAP_RATING_COLLAPSED,
                format!(
                    "transformer {}: center tap half winding s_ratings ({}, {}) differ \
                     from the primary's {}; BMOPF carries one transformer rating, and \
                     the first secondary half rating is used for the to-side impedance base",
                    t.name, w2.s_rating, w3.s_rating, from.s_rating
                ),
                details,
            );
        }
        let s = from.s_rating;
        let zb_from = winding_base(from);
        let zb_to = winding_base(w2);
        if t.xsc_pct.is_empty() {
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_MISSING_XSC,
                format!(
                    "transformer {}: xsc_pct is empty; emitted x_series_from=0",
                    t.name
                ),
                Map::new(),
            );
        }
        let (x_from_pct, x_to_pct) = self.center_tap_leakage_percentages(t);

        let mut o = Map::new();
        o.insert("bus_from".into(), json!(from.bus));
        o.insert("bus_to".into(), json!(to.bus));
        o.insert("s_rating".into(), self.num(s, "transformer s_rating"));
        o.insert(
            "v_nom_from".into(),
            self.num(from.v_ref, "transformer v_nom_from"),
        );
        o.insert(
            "v_nom_to".into(),
            self.num(to.v_ref, "transformer v_nom_to"),
        );
        self.referred_ohms(&mut o, "r_series_from", from.r_pct, zb_from, t, "from");
        self.referred_ohms(&mut o, "r_series_to", w2.r_pct, zb_to, t, "to");
        self.referred_ohms(&mut o, "x_series_from", x_from_pct, zb_from, t, "from");
        self.referred_ohms(&mut o, "x_series_to", x_to_pct, zb_to, t, "to");
        o.insert("terminal_map_from".into(), json!(from.terminal_map));
        o.insert("terminal_map_to".into(), json!(to.terminal_map));
        self.transformer_neutral_fields(&mut o, t, from, &to);
        self.transformer_tap_fields(&mut o, t, from, &to);
        self.transformer_no_load_fields(&mut o, t, from, s);
        self.transformer_extras_dropped(t, &TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS);
        o.into()
    }

    /// The lumped series resistance on the wye base, in ohms. Each winding
    /// holds its percent resistance on its own rating base, so each term is
    /// `r_pct / 100 * v_wye^2 / s_rating`. A rating that is not positive
    /// makes its term undefined; that term drops with a warning, so the
    /// output keeps the resistance of the other winding instead of an
    /// infinity that `num` would then emit as a lossless zero.
    fn referred_resistance(
        &mut self,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
        v_wye2: f64,
    ) -> f64 {
        let mut total = 0.0;
        for (side, w) in [("from", from), ("to", to)] {
            if w.s_rating > 0.0 && w.s_rating.is_finite() {
                total += w.r_pct / w.s_rating;
            } else if w.r_pct != 0.0 {
                self.diagnostic(
                    &C::EMIT_BMOPF_FIELD_DROPPED,
                    format!("transformer {}", t.name),
                    format!(
                        "transformer {}: the `{side}` winding rating is not positive, so its \
                     resistance has no base to refer to; the term is dropped from r_series",
                        t.name
                    ),
                    Map::new(),
                );
            }
        }
        total / 100.0 * v_wye2
    }

    /// Emit one series impedance field from a percent on `base`, or drop the
    /// field with a warning when the rating leaves that base undefined.
    fn referred_ohms(
        &mut self,
        o: &mut Map<String, Value>,
        key: &str,
        pct: f64,
        base: Option<f64>,
        t: &DistTransformer,
        side: &str,
    ) {
        match base {
            Some(zb) => {
                let value = self.num(pct / 100.0 * zb, key);
                o.insert(key.into(), value);
            }
            None => self.diagnostic(
                &C::EMIT_BMOPF_FIELD_DROPPED,
                format!("transformer {}", t.name),
                format!(
                    "transformer {}: the `{side}` winding rating is not positive, so its \
                 percent impedance has no base to refer to; `{key}` is dropped from \
                 the output",
                    t.name
                ),
                Map::new(),
            ),
        }
    }

    fn center_tap_leakage_percentages(&mut self, t: &DistTransformer) -> (f64, f64) {
        let (x_from_pct, x_to_pct) = center_tap_star_percentages(&t.xsc_pct);
        if x_from_pct.is_finite()
            && x_to_pct.is_finite()
            && x_from_pct >= -1e-12
            && x_to_pct >= -1e-12
        {
            return (x_from_pct.max(0.0), x_to_pct.max(0.0));
        }
        let xhl = t.xsc_pct.first().copied().unwrap_or(0.0);
        let emitted_from = if xhl.is_finite() { xhl.max(0.0) } else { 0.0 };
        let mut details = Map::new();
        details.insert("xsc_pct".into(), json!(&t.xsc_pct));
        details.insert("star_percentages".into(), json!([x_from_pct, x_to_pct]));
        details.insert("emitted_percentages".into(), json!([emitted_from, 0.0]));
        self.transformer_diagnostic(
            t,
            &C::EMIT_BMOPF_TRANSFORMER_CENTER_TAP_LEAKAGE_UNREPRESENTABLE,
            format!(
                "transformer {}: center tap leakage star arms ({x_from_pct}, {x_to_pct}) \
                 are not representable as nonnegative BMOPF fields; emitted xhl on the \
                 from side and zero on the to side",
                t.name
            ),
            details,
        );
        (emitted_from, 0.0)
    }

    /// Both three phase subtypes use the schema 0.1.0 lumped form: one
    /// `r_series`/`x_series` pair referred to the wye winding's base (the
    /// split `_from`/`_to` fields lost their slots in 0.1.0).
    fn three_phase(&mut self, t: &DistTransformer, wye_idx: usize) -> Value {
        let from = &t.windings[0];
        let to = &t.windings[1];
        let s = from.s_rating;
        let mut o = Map::new();
        o.insert("bus_from".into(), json!(from.bus));
        o.insert("bus_to".into(), json!(to.bus));
        o.insert("s_rating".into(), self.num(s, "transformer s_rating"));
        o.insert(
            "v_nom_from".into(),
            self.num(from.v_ref, "transformer v_nom_from"),
        );
        o.insert(
            "v_nom_to".into(),
            self.num(to.v_ref, "transformer v_nom_to"),
        );
        if t.xsc_pct.is_empty() {
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_MISSING_XSC,
                format!(
                    "transformer {}: xsc_pct is empty; emitted x_series=0",
                    t.name,
                ),
                Map::new(),
            );
        }
        let xhl = t.xsc_pct.first().copied().unwrap_or(0.0);
        let wye = &t.windings[wye_idx];
        let v_wye2 = wye.v_ref * wye.v_ref;
        // Each winding's percent resistance is on its own rating base; refer
        // both to the wye side before lumping (identical to the plain sum
        // when the ratings match). XHL is on the first winding's base.
        let r_series = self.referred_resistance(t, from, to, v_wye2);
        o.insert(
            "r_series".into(),
            self.num(r_series, "transformer r_series"),
        );
        // XHL is a percent on the first winding's rating base. That base is
        // the same one `referred_resistance` guards, so guard it here too: an
        // unusable rating must not reach the output as a zero reactance.
        let x_base = base_impedance(wye.v_ref, s);
        self.referred_ohms(&mut o, "x_series", xhl, x_base, t, "from");
        o.insert("terminal_map_from".into(), json!(from.terminal_map));
        o.insert("terminal_map_to".into(), json!(to.terminal_map));
        self.transformer_neutral_fields(&mut o, t, from, to);
        self.transformer_tap_fields(&mut o, t, from, to);
        self.transformer_no_load_fields(&mut o, t, from, s);
        self.transformer_extras_dropped(t, &TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS);
        o.into()
    }

    fn n_winding(&mut self, t: &DistTransformer) -> Value {
        let s = t
            .extras
            .get("bmopf_power_base")
            .and_then(Value::as_f64)
            .unwrap_or_else(|| t.windings.first().map_or(f64::NAN, |w| w.s_rating));
        let mut o = Map::new();
        o.insert("s_rating".into(), self.num(s, "transformer s_rating"));
        let windings: Vec<Value> = t
            .windings
            .iter()
            .enumerate()
            .map(|(idx, w)| {
                let mut wj = Map::new();
                wj.insert("bus".into(), json!(w.bus));
                wj.insert("terminal_map".into(), json!(w.terminal_map));
                wj.insert(
                    "v_nom".into(),
                    self.num(n_winding_bmopf_v_nom(w), "transformer winding v_nom"),
                );
                wj.insert(
                    "configuration".into(),
                    json!(match w.conn {
                        DistWindingConn::Wye => "WYE",
                        DistWindingConn::Delta => "DELTA",
                    }),
                );
                let zbase = n_winding_base(w, w.s_rating).unwrap_or(f64::NAN);
                wj.insert(
                    "r_winding".into(),
                    self.num(w.r_pct / 100.0 * zbase, "transformer winding r_winding"),
                );
                wj.insert("s_rating".into(), self.num(w.s_rating, "winding s_rating"));
                wj.insert("tap_ratio".into(), self.num(w.tap, "winding tap_ratio"));
                if w.r_neutral.is_some_and(|r| r < 0.0) {
                    self.warn(&C::EMIT_BMOPF_FIELD_DROPPED, format!("transformer {} winding {idx}: open OpenDSS neutral has no internal impedance branch; neutral impedance fields omitted", t.name));
                } else {
                    for (key, value) in [("r_neutral", w.r_neutral), ("x_neutral", w.x_neutral)] {
                        if let Some(value) = value { wj.insert(key.into(), self.num(value, key)); }
                    }
                }
                if let Some(metadata) = t.extras.get("bmopf_winding_metadata").and_then(|v| v.get(idx.to_string())).and_then(Value::as_object) {
                    for (key, value) in metadata { wj.insert(key.clone(), value.clone()); }
                }
                if let Some(delta_roll) = bmopf_delta_roll(t, idx, w) {
                    wj.insert("delta_roll".into(), json!(delta_roll));
                }
                Value::Object(wj)
            })
            .collect();
        o.insert("windings".into(), Value::Array(windings));
        let base_z = t
            .windings
            .first()
            .and_then(|w| n_winding_base(w, s))
            .unwrap_or(f64::NAN);
        let x_sc = self.n_winding_x_sc(t, base_z);
        o.insert("x_sc".into(), Value::Object(x_sc));
        if let Some(first) = t.windings.first() {
            self.transformer_no_load_fields(&mut o, t, first, s);
        }
        self.transformer_extras_dropped(t, &TRANSFORMER_NO_LOAD_ALLOWED_EXTRAS);
        o.into()
    }

    /// The `x_sc` pair table for an n_winding transformer. The winding count
    /// is model input, so the quadratic pair expansion is capped at
    /// [`MAX_DIM`] with a diagnostic.
    fn n_winding_x_sc(&mut self, t: &DistTransformer, base_z: f64) -> Map<String, Value> {
        let mut x_sc = Map::new();
        let n_windings = t.windings.len();
        if n_windings > MAX_DIM {
            let mut details = Map::new();
            details.insert("windings".into(), json!(n_windings));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_WINDINGS_CLAMPED,
                format!(
                    "transformer {}: {n_windings} windings exceed the supported \
                     maximum of {MAX_DIM}; x_sc pairs beyond it are dropped",
                    t.name
                ),
                details,
            );
        }
        for (idx, (i, j)) in pair_keys(n_windings.min(MAX_DIM)).into_iter().enumerate() {
            let x_pct = t.xsc_pct.get(idx).copied().unwrap_or_else(|| {
                let mut details = Map::new();
                details.insert("winding_pair".into(), json!(format!("{}_{}", i + 1, j + 1)));
                self.transformer_diagnostic(
                    t,
                    &C::EMIT_BMOPF_TRANSFORMER_MISSING_XSC,
                    format!(
                        "transformer {}: missing x_sc for winding pair {}_{}; emitted 0",
                        t.name,
                        i + 1,
                        j + 1
                    ),
                    details,
                );
                0.0
            });
            x_sc.insert(
                format!("{}_{}", i + 1, j + 1),
                self.num(x_pct / 100.0 * base_z, "transformer x_sc"),
            );
        }
        x_sc
    }

    /// A three phase wye-wye unit becomes one single_phase entry per phase
    /// (`name_1`..), each at line to neutral voltage and a third of the
    /// rating. That keeps the impedance base v^2/s, so the percent values
    /// carry over unchanged. The public IEEE13 example records the line to
    /// line voltage on its decomposed units instead; both are self
    /// consistent, they differ in the v_ref convention.
    fn decompose_wye_wye(&mut self, t: &DistTransformer) -> Vec<(String, Value)> {
        let mut out = Vec::new();
        let (from, to) = (&t.windings[0], &t.windings[1]);
        let sqrt3 = 3f64.sqrt();
        for k in 0..t.phases {
            let per = |w: &DistWinding| {
                let neutral = w.terminal_map.last().cloned().unwrap_or_default();
                DistWinding {
                    bus: w.bus.clone(),
                    terminal_map: vec![w.terminal_map[k].clone(), neutral],
                    conn: DistWindingConn::Wye,
                    v_ref: w.v_ref / sqrt3,
                    s_rating: w.s_rating / 3.0,
                    r_pct: w.r_pct,
                    tap: w.tap,
                    r_neutral: if k == 0 { w.r_neutral } else { None },
                    x_neutral: if k == 0 { w.x_neutral } else { None },
                }
            };
            let f = per(from);
            let to_1 = per(to);
            let mut t1 = t.clone();
            t1.windings = vec![f.clone(), to_1.clone()];
            t1.phases = 1;
            split_no_load_extras(&mut t1, t.phases);
            let v = self.two_winding(&t1, &f, &to_1, 1.0, true, false);
            out.push((format!("{}_{}", t.name, k + 1), v));
        }
        let mut details = Map::new();
        details.insert("emitted_subtype".into(), json!("single_phase"));
        details.insert("units".into(), json!(t.phases));
        self.transformer_diagnostic(
            t,
            &C::EMIT_BMOPF_TRANSFORMER_WYE_WYE_DECOMPOSED,
            format!(
                "transformer {}: three phase wye-wye decomposed into {} single_phase units",
                t.name, t.phases
            ),
            details,
        );
        self.transformer_extras_dropped(t, &TRANSFORMER_TWO_WINDING_ALLOWED_EXTRAS);
        out
    }

    fn transformer_tap_fields(
        &mut self,
        o: &mut Map<String, Value>,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
    ) {
        if to.tap.abs() <= 1e-12 {
            if (from.tap - 1.0).abs() > 1e-12 || (to.tap - 1.0).abs() > 1e-12 {
                let mut details = Map::new();
                details.insert("from_tap".into(), json!(from.tap));
                details.insert("to_tap".into(), json!(to.tap));
                self.transformer_diagnostic(
                    t,
                    &C::EMIT_BMOPF_TRANSFORMER_TAP_DROPPED,
                    format!(
                        "transformer {}: to-side tap {} cannot form a finite BMOPF ratio; dropped",
                        t.name, to.tap
                    ),
                    details,
                );
            }
        } else {
            let tap = from.tap / to.tap;
            if (tap - 1.0).abs() > 1e-12 || t.extras.contains_key("tap") {
                o.insert("tap".into(), self.num(tap, "transformer tap"));
            }
        }
        for key in ["tap_min", "tap_max"] {
            if let Some(v) = extras_number(&t.extras, key) {
                o.insert(key.into(), self.num(v, &format!("transformer {key}")));
            }
        }
    }

    fn warn_nonuniform_per_phase_taps(&mut self, t: &DistTransformer) {
        let Some(tm_set) = t.extras.get("pmd_tm_set").and_then(Value::as_array) else {
            return;
        };
        for (idx, raw) in tm_set.iter().enumerate() {
            let Some(taps) = tap_values(raw) else {
                continue;
            };
            let Some(first) = taps.first().copied() else {
                continue;
            };
            if taps.iter().any(|tap| (tap - first).abs() > 1e-9) {
                let mut details = Map::new();
                details.insert("winding".into(), json!(idx + 1));
                details.insert("source_taps".into(), json!(taps));
                details.insert("emitted_winding_tap".into(), json!(first));
                self.transformer_diagnostic(
                    t,
                    &C::EMIT_BMOPF_TRANSFORMER_PER_PHASE_TAP_COLLAPSED,
                    format!(
                        "transformer {}: winding {} has non-uniform per phase taps; emitted the first phase tap",
                        t.name,
                        idx + 1
                    ),
                    details,
                );
            }
        }
    }

    fn transformer_neutral_fields(
        &mut self,
        o: &mut Map<String, Value>,
        t: &DistTransformer,
        from: &DistWinding,
        to: &DistWinding,
    ) {
        for (side, winding) in [("from", from), ("to", to)] {
            let resistance = format!("r_neutral_{side}");
            let reactance = format!("x_neutral_{side}");
            self.transformer_neutral_field(o, t, &resistance, winding.r_neutral);
            if winding.r_neutral.is_some_and(|r| r < 0.0) {
                if let Some(x) = winding.x_neutral {
                    self.warn(&C::EMIT_BMOPF_TRANSFORMER_NEUTRAL_DROPPED,
                        format!("transformer {}: {reactance}={x} omitted with the open neutral encoded by negative {resistance}", t.name));
                }
            } else {
                self.transformer_neutral_field(o, t, &reactance, winding.x_neutral);
            }
        }
    }

    fn transformer_neutral_field(
        &mut self,
        o: &mut Map<String, Value>,
        t: &DistTransformer,
        key: &str,
        value: Option<f64>,
    ) {
        let Some(v) = value else {
            return;
        };
        if v.is_finite() && v >= 0.0 {
            o.insert(key.into(), json!(v));
        } else {
            let mut details = Map::new();
            details.insert("field".into(), json!(key));
            details.insert("value".into(), json!(v));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_NEUTRAL_DROPPED,
                format!(
                    "transformer {}: {key}={v} is not a nonnegative finite BMOPF neutral impedance; dropped",
                    t.name
                ),
                details,
            );
        }
    }

    fn center_tap_neutral(
        &mut self,
        t: &DistTransformer,
        field: &str,
        a: Option<f64>,
        b: Option<f64>,
    ) -> Option<f64> {
        if let (Some(a), Some(b)) = (a, b) {
            let mut details = Map::new();
            details.insert("field".into(), json!(field));
            details.insert("values".into(), json!([a, b]));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_CENTER_TAP_NEUTRAL_COLLAPSED,
                format!(
                    "transformer {}: center tap secondary has two {field} values ({a}, {b}); emitted the first",
                    t.name
                ),
                details,
            );
        }
        a.or(b)
    }

    fn warn_unrepresented_neutral_fields(&mut self, t: &DistTransformer, target: &str) {
        for (idx, w) in t.windings.iter().enumerate() {
            if w.r_neutral.is_some() || w.x_neutral.is_some() {
                let mut details = Map::new();
                details.insert("target".into(), json!(target));
                details.insert("winding".into(), json!(idx + 1));
                self.transformer_diagnostic(
                    t,
                    &C::EMIT_BMOPF_TRANSFORMER_NEUTRAL_DROPPED,
                    format!(
                        "transformer {} winding {}: neutral impedance has no {target} field; dropped",
                        t.name,
                        idx + 1
                    ),
                    details,
                );
            }
        }
    }

    fn transformer_no_load_fields(
        &mut self,
        o: &mut Map<String, Value>,
        t: &DistTransformer,
        _from: &DistWinding,
        s: f64,
    ) {
        if let Some(shunt) = t.extras.get("no_load_shunt") {
            o.insert("no_load_shunt".into(), shunt.clone());
            return;
        }
        if t.extras.contains_key("g_no_load") || t.extras.contains_key("b_no_load") {
            for key in ["g_no_load", "b_no_load"] {
                if let Some(value) = t.extras.get(key) {
                    o.insert(key.into(), value.clone());
                }
            }
            return;
        }
        let loss = extras_number(&t.extras, "%noloadloss");
        let imag = extras_number(&t.extras, "%imag");
        if loss.is_none() && imag.is_none() {
            return;
        }
        // OpenDSS places the exciting branch on physical winding 2. Its
        // terminal admittance includes the winding tap and the per-coil base.
        let voltage = t
            .windings
            .get(1)
            .map(|w| crate::model::winding_coil_voltage(w, t.phases));
        if let Some(voltage) = voltage
            && voltage.is_finite()
            && voltage > 0.0
            && s.is_finite()
            && s > 0.0
            && loss.is_none_or(|v| v >= 0.0)
            && imag.is_none_or(|v| v >= 0.0)
        {
            let y_base = s / t.phases.max(1) as f64 / voltage.powi(2);
            o.insert(
                "no_load_shunt".into(),
                json!({
                    "winding": 2,
                    "g": loss.unwrap_or(0.0) / 100.0 * y_base,
                    "b": -imag.unwrap_or(0.0) / 100.0 * y_base,
                }),
            );
        } else {
            let details = Map::from_iter([("field".into(), json!("no_load_shunt"))]);
            self.transformer_diagnostic(t, &C::EMIT_BMOPF_TRANSFORMER_NO_LOAD_SHUNT_UNCONVERTIBLE,
                format!("transformer {}: no-load percentages require nonnegative values, a positive power base and a positive winding-2 coil voltage", t.name), details);
        }
    }

    fn transformer_extras_dropped(&mut self, t: &DistTransformer, allowed: &[&str]) {
        for key in t.extras.keys() {
            if key == "bmopf_subtype" || key == "tap" || allowed.contains(&key.as_str()) {
                continue;
            }
            let mut details = Map::new();
            details.insert("field".into(), json!(key));
            self.transformer_diagnostic(
                t,
                &C::EMIT_BMOPF_TRANSFORMER_EXTRA_DROPPED,
                format!(
                    "transformer {}: `{key}` has no place in the BMOPF schema; dropped from the output",
                    t.name
                ),
                details,
            );
        }
    }

    /// Emits a matrix whose `_1_1` entry the schema requires; an empty one
    /// becomes `dim` by `dim` zeros so the required key exists. `dim` derives
    /// from a sibling matrix's row count, which model input controls, so the
    /// dense zero fill is capped at [`MAX_DIM`].
    fn required_matrix(
        &mut self,
        o: &mut Map<String, Value>,
        prefix: &str,
        m: &ConductorMatrix,
        dim: usize,
        name: &str,
    ) {
        if m.is_empty() {
            let dim = if dim > MAX_DIM {
                self.warn(
                    &C::EMIT_BMOPF_VALUE_CLAMPED,
                    format!(
                        "{name}: {prefix} dimension {dim} exceeds the supported \
                     maximum of {MAX_DIM}; zero matrix clamped"
                    ),
                );
                MAX_DIM
            } else {
                dim
            };
            self.flat_matrix(o, prefix, &vec![vec![0.0; dim]; dim], name);
        } else {
            self.flat_matrix(o, prefix, m, name);
        }
    }

    fn flat_matrix(
        &mut self,
        o: &mut Map<String, Value>,
        prefix: &str,
        m: &ConductorMatrix,
        name: &str,
    ) {
        for (i, row) in m.iter().enumerate() {
            for (j, &v) in row.iter().enumerate() {
                o.insert(
                    format!("{prefix}_{}_{}", i + 1, j + 1),
                    self.num(v, &format!("{name} {prefix}")),
                );
            }
        }
    }
}

/// Spells the two-winding tap ratio the way schema 0.2.0 names it.
///
/// 0.1.0 has no slot for the ratio at all, so the emitters spell it `tap`;
/// 0.2.0 declares `tap_ratio` on the two-winding subtypes and on both
/// regulator subtypes, so one name covers every transformer that has a ratio.
/// The value is unchanged: it is the multiplier on the nameplate turns ratio
/// in both spellings.
fn rename_tap_fields(by_subtype: &mut Map<String, Value>) {
    const RENAMED: [(&str, &str); 3] = [
        ("tap", "tap_ratio"),
        ("tap_min", "tap_ratio_min"),
        ("tap_max", "tap_ratio_max"),
    ];
    for subtype in ["single_phase", "center_tap", "wye_delta", "delta_wye"] {
        let Some(Value::Object(table)) = by_subtype.get_mut(subtype) else {
            continue;
        };
        for entry in table.values_mut() {
            let Value::Object(o) = entry else { continue };
            for (from, to) in RENAMED {
                if let Some(value) = o.remove(from) {
                    o.insert(to.to_string(), value);
                }
            }
        }
    }
}

#[derive(Clone)]
struct SourceEmit {
    name: String,
    bus: String,
    terminal_map: Vec<String>,
    v_magnitude: Vec<f64>,
    v_angle: Vec<f64>,
    energy_cost_rate: Option<Vec<f64>>,
    extras: Extras,
    dropped_extras: Vec<(String, Extras)>,
}

impl From<&VoltageSource> for SourceEmit {
    fn from(source: &VoltageSource) -> Self {
        Self {
            name: source.name.clone(),
            bus: source.bus.clone(),
            terminal_map: source.terminal_map.clone(),
            v_magnitude: source.v_magnitude.clone(),
            v_angle: source.v_angle.clone(),
            energy_cost_rate: source.energy_cost_rate.clone(),
            extras: source.extras.clone(),
            dropped_extras: Vec::new(),
        }
    }
}

#[derive(Clone)]
struct PhaseSource {
    label: String,
    magnitude: f64,
    angle: f64,
    neutral: Option<String>,
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum PhaseArrangement {
    Zero,
    Quadrature,
    Positive,
    Negative,
    AntiPhase,
    Incoherent,
}

fn bmopf_voltage_sources(net: &MulticonductorNetwork) -> Vec<SourceEmit> {
    let emitted: Vec<SourceEmit> = net.sources().iter().map(SourceEmit::from).collect();
    let bus_ids: BTreeMap<String, String> = net
        .buses()
        .iter()
        .map(|bus| (bus.id.to_ascii_lowercase(), bus.id.clone()))
        .collect();
    let mut by_bus: BTreeMap<String, Vec<usize>> = BTreeMap::new();
    for (i, source) in emitted.iter().enumerate() {
        by_bus
            .entry(source.bus.to_ascii_lowercase())
            .or_default()
            .push(i);
    }

    let mut replacements = BTreeMap::new();
    let mut removed = BTreeSet::new();
    for (bus_key, indices) in by_bus.iter().filter(|(_, indices)| indices.len() > 1) {
        if let Some((keep, merged)) =
            merge_voltage_source_group(&emitted, indices, bus_ids.get(bus_key))
        {
            replacements.insert(keep, merged);
            removed.extend(indices.iter().copied().filter(|i| *i != keep));
        }
    }

    emitted
        .into_iter()
        .enumerate()
        .filter_map(|(i, source)| {
            if removed.contains(&i) {
                None
            } else {
                Some(replacements.remove(&i).unwrap_or(source))
            }
        })
        .collect()
}

fn merge_voltage_source_group(
    sources: &[SourceEmit],
    indices: &[usize],
    bus_id: Option<&String>,
) -> Option<(usize, SourceEmit)> {
    let mut sorted = indices.to_vec();
    sorted.sort_by(|a, b| sources[*a].name.cmp(&sources[*b].name));

    let mut phases = Vec::new();
    let mut seen = BTreeSet::new();
    for index in &sorted {
        let source = &sources[*index];
        if source.energy_cost_rate.is_some() || source_has_bounds_or_cost(&source.extras) {
            return None;
        }
        let (rank, phase) = single_phase_source(source)?;
        if !seen.insert(rank) {
            return None;
        }
        phases.push((rank, phase));
    }

    if phases.len() < 2 {
        return None;
    }
    phases.sort_by_key(|(rank, _)| *rank);

    let neutral = phases.first()?.1.neutral.clone();
    if phases.iter().any(|(_, phase)| phase.neutral != neutral) {
        return None;
    }

    match phase_arrangement(phases.iter().map(|(_, phase)| phase.angle)) {
        PhaseArrangement::Zero | PhaseArrangement::Positive | PhaseArrangement::Negative => {}
        PhaseArrangement::Quadrature
        | PhaseArrangement::AntiPhase
        | PhaseArrangement::Incoherent => {
            return None;
        }
    }

    let keep = sorted
        .iter()
        .copied()
        .find(|i| sources[*i].name == "source")
        .unwrap_or(sorted[0]);
    let mut merged = sources[keep].clone();
    if let Some(bus_id) = bus_id {
        merged.bus.clone_from(bus_id);
    }
    merged.terminal_map = phases
        .iter()
        .map(|(_, phase)| phase.label.clone())
        .collect();
    merged.v_magnitude = phases.iter().map(|(_, phase)| phase.magnitude).collect();
    merged.v_angle = phases.iter().map(|(_, phase)| phase.angle).collect();
    if let Some(neutral) = neutral {
        merged.terminal_map.push(neutral);
        merged.v_magnitude.push(0.0);
        merged.v_angle.push(0.0);
    }
    merged.dropped_extras = sorted
        .iter()
        .copied()
        .filter(|i| *i != keep)
        .map(|i| (sources[i].name.clone(), sources[i].extras.clone()))
        .collect();
    Some((keep, merged))
}

fn source_has_bounds_or_cost(extras: &Extras) -> bool {
    [
        "p_min",
        "p_max",
        "q_min",
        "q_max",
        "cost",
        "energy_cost_rate",
    ]
    .iter()
    .any(|key| extras.contains_key(*key))
}

fn single_phase_source(source: &SourceEmit) -> Option<(usize, PhaseSource)> {
    let mut phase = None;
    let mut neutral = None;
    for (i, label) in source.terminal_map.iter().enumerate() {
        if let Some(rank) = phase_rank(label) {
            if phase.replace((rank, label.clone(), i)).is_some() {
                return None;
            }
        } else if neutral.replace(label.clone()).is_some() {
            return None;
        }
    }
    let (rank, label, index) = phase?;
    Some((
        rank,
        PhaseSource {
            label,
            magnitude: *source.v_magnitude.get(index)?,
            angle: *source.v_angle.get(index)?,
            neutral,
        },
    ))
}

fn phase_rank(label: &str) -> Option<usize> {
    match label {
        "1" | "a" | "A" => Some(0),
        "2" | "b" | "B" => Some(1),
        "3" | "c" | "C" => Some(2),
        _ => None,
    }
}

fn phase_arrangement(angles: impl IntoIterator<Item = f64>) -> PhaseArrangement {
    let angles: Vec<f64> = angles.into_iter().collect();
    if angles.len() < 2 {
        return PhaseArrangement::Incoherent;
    }
    if angles.len() == 2 {
        return separation_of_diff(angles[0] - angles[1]);
    }
    let mut arrangement = None;
    for i in 0..angles.len() {
        let next = (i + 1) % angles.len();
        let current = separation_of_diff(angles[i] - angles[next]);
        if current == PhaseArrangement::Incoherent {
            return PhaseArrangement::Incoherent;
        }
        if let Some(previous) = arrangement {
            if previous != current {
                return PhaseArrangement::Incoherent;
            }
        } else {
            arrangement = Some(current);
        }
    }
    arrangement.unwrap_or(PhaseArrangement::Incoherent)
}

fn separation_of_diff(diff: f64) -> PhaseArrangement {
    let diff = wrap_pi(diff);
    let adiff = diff.abs();
    if adiff <= PI / 6.0 {
        PhaseArrangement::Zero
    } else if (adiff - FRAC_PI_2).abs() <= PI / 12.0 {
        PhaseArrangement::Quadrature
    } else if (adiff - TAU / 3.0).abs() <= PI / 6.0 {
        if diff > 0.0 {
            PhaseArrangement::Positive
        } else {
            PhaseArrangement::Negative
        }
    } else if (adiff - PI).abs() <= PI / 12.0 {
        PhaseArrangement::AntiPhase
    } else {
        PhaseArrangement::Incoherent
    }
}

fn wrap_pi(angle: f64) -> f64 {
    let wrapped = (angle + PI).rem_euclid(TAU) - PI;
    if (wrapped + PI).abs() < f64::EPSILON {
        PI
    } else {
        wrapped
    }
}

enum Kind {
    SinglePhase,
    /// Two windings already in the shared single_phase/center_tap shape,
    /// emitted under the named subtype.
    SinglePhaseShape(&'static str),
    /// A dss classified step voltage regulator, emitted under the
    /// `single_phase_autotransformer` subtype of the BMOPFTools schema
    /// extension.
    Autotransformer,
    /// One line to line leg of a dss classified open delta regulator bank;
    /// two legs merge into one `open_delta_regulator` object.
    OpenDeltaLeg,
    CenterTap,
    WyeDelta,
    DeltaWye,
    WyeWye3,
    NWinding,
    Unsupported(String),
}

fn classify(t: &DistTransformer) -> Kind {
    // A network read from BMOPF records its subtype; trust it so writing
    // back reproduces the grouping (center tap reads as two windings).
    // An unknown or shape mismatched subtype falls through to the shape
    // based classification below.
    if let Some(sub) = t.extras.get("bmopf_subtype").and_then(|v| v.as_str()) {
        if t.windings.len() == 2 {
            match sub {
                "single_phase" => return Kind::SinglePhase,
                "center_tap" => return Kind::SinglePhaseShape("center_tap"),
                "wye_delta" => return Kind::WyeDelta,
                "delta_wye" => return Kind::DeltaWye,
                "single_phase_autotransformer" => return Kind::Autotransformer,
                "open_delta_regulator" => return Kind::OpenDeltaLeg,
                _ => {}
            }
        }
        if sub == "n_winding" && t.windings.len() >= 2 {
            return Kind::NWinding;
        }
    }
    let conns: Vec<DistWindingConn> = t.windings.iter().map(|w| w.conn).collect();
    match (t.phases, conns.as_slice()) {
        // single_phase covers the plain 1-phase unit in every conn pairing:
        // a delta winding here is one wired line to line (an open wye or
        // open delta leg, or both legs of a fixed tap open delta bank). The
        // single_phase shape holds it: two phase terminals, no conn
        // discriminator, and the line to line v_ref makes the per winding
        // impedance base v^2/s already right — which reads the same for one
        // delta winding or two.
        (
            1,
            [
                DistWindingConn::Wye | DistWindingConn::Delta,
                DistWindingConn::Wye | DistWindingConn::Delta,
            ],
        ) => Kind::SinglePhase,
        (
            1,
            [
                DistWindingConn::Wye,
                DistWindingConn::Wye,
                DistWindingConn::Wye,
            ],
        ) => Kind::CenterTap,
        (3, [DistWindingConn::Wye, DistWindingConn::Delta]) => Kind::WyeDelta,
        (3, [DistWindingConn::Delta, DistWindingConn::Wye]) => Kind::DeltaWye,
        // The decomposition indexes terminal_map[phase] and takes the last
        // entry as the neutral; anything else is not safely decomposable.
        (3, [DistWindingConn::Wye, DistWindingConn::Wye])
            if t.windings
                .iter()
                .all(|w| w.terminal_map.len() == t.phases + 1) =>
        {
            Kind::WyeWye3
        }
        (3, [DistWindingConn::Wye, DistWindingConn::Wye]) => Kind::Unsupported(
            "three phase wye-wye whose terminal maps do not list each phase plus a neutral".into(),
        ),
        (_, _) if t.windings.len() >= 3 => Kind::NWinding,
        _ => Kind::Unsupported(format!(
            "{} phase with {} windings ({:?})",
            t.phases,
            t.windings.len(),
            conns
        )),
    }
}

/// The re-emitted form of an untyped object.
///
/// A BMOPF sourced object rides as one unkeyed blob, which is the JSON the
/// document declared. A dss sourced object rides as key/value property
/// pairs, which rebuild into an object; without that arm every dss sourced
/// untyped object failed the JSON parse and dropped.
/// Rebuild the value of an untyped object. One unnamed property alone is the
/// whole object as JSON text. Otherwise each named property is one field.
///
/// An unnamed property beside named ones has no field name, so this writer
/// cannot place it. It goes to `unplaced` for the caller to report, and the
/// named fields still reach the output; dropping the whole object over one
/// positional token would lose every field beside it.
fn raw_bmopf_value(u: &crate::model::UntypedObject, unplaced: &mut Vec<String>) -> Option<Value> {
    if let [(None, text)] = u.props.as_slice() {
        return serde_json::from_str(text).ok();
    }
    let mut o = Map::new();
    for (key, text) in &u.props {
        let Some(key) = key.as_ref() else {
            unplaced.push(text.clone());
            continue;
        };
        let value = serde_json::from_str(text).unwrap_or_else(|_| Value::String(text.clone()));
        o.insert(key.clone(), value);
    }
    (!o.is_empty()).then_some(Value::Object(o))
}

fn extras_number(extras: &crate::model::Extras, key: &str) -> Option<f64> {
    let v = extras.get(key)?;
    v.as_f64()
        .or_else(|| v.as_i64().map(|v| v as f64))
        .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
        .filter(|v| v.is_finite())
}

fn tap_values(v: &Value) -> Option<Vec<f64>> {
    if let Some(items) = v.as_array() {
        let out: Vec<f64> = items.iter().filter_map(value_number).collect();
        Some(out)
    } else {
        value_number(v).map(|tap| vec![tap])
    }
}

fn value_number(v: &Value) -> Option<f64> {
    v.as_f64()
        .or_else(|| v.as_i64().map(|v| v as f64))
        .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
        .filter(|v| v.is_finite())
}

fn split_no_load_extras(t: &mut DistTransformer, phases: usize) {
    let phases = phases.max(1) as f64;
    for key in ["g_no_load", "b_no_load"] {
        if let Some(v) = extras_number(&t.extras, key) {
            t.extras.insert(key.into(), json!(v / phases));
        }
    }
}

fn center_tap_common_terminal(w2: &DistWinding, w3: &DistWinding) -> String {
    w2.terminal_map
        .iter()
        .find(|term| w3.terminal_map.contains(term))
        .cloned()
        .unwrap_or_default()
}

fn center_tap_to_winding(
    w2: &DistWinding,
    w3: &DistWinding,
    common: &str,
    s_rating: f64,
    r_neutral: Option<f64>,
    x_neutral: Option<f64>,
) -> DistWinding {
    let terminal_map = center_tap_terminal_map(w2, w3, common);
    DistWinding {
        bus: w2.bus.clone(),
        terminal_map,
        conn: DistWindingConn::Wye,
        v_ref: w2.v_ref,
        s_rating,
        r_pct: w2.r_pct,
        tap: w2.tap,
        r_neutral,
        x_neutral,
    }
}

fn center_tap_terminal_map(w2: &DistWinding, w3: &DistWinding, common: &str) -> Vec<String> {
    let mut hots: Vec<String> = Vec::new();
    for term in w2.terminal_map.iter().chain(&w3.terminal_map) {
        if term != common && !hots.contains(term) {
            hots.push(term.clone());
        }
    }
    let first = hots.first().cloned().unwrap_or_default();
    let second = hots.get(1).cloned().unwrap_or_default();
    vec![first, common.to_string(), second]
}

fn center_tap_star_percentages(xsc_pct: &[f64]) -> (f64, f64) {
    let xhl = xsc_pct.first().copied().unwrap_or(0.0);
    let xht = xsc_pct.get(1).copied().unwrap_or(xhl);
    let xlt = xsc_pct.get(2).copied().unwrap_or(0.0);
    ((xhl + xht - xlt) / 2.0, (xhl + xlt - xht) / 2.0)
}

fn winding_base(w: &DistWinding) -> Option<f64> {
    base_impedance(w.v_ref, w.s_rating)
}

/// Base impedance `v^2 / s` in ohms, or None when the rating gives the
/// percent quantities no base. Dividing by a rating that is not positive
/// yields an infinity, and `num` then emits that infinity as a zero: a
/// zero-resistance and, worse, a zero-reactance transformer reads as a short
/// circuit. The schema leaves every series impedance field optional, so the
/// caller drops the field instead, and an absent field reads as unknown.
fn base_impedance(v_ref: f64, s: f64) -> Option<f64> {
    (s > 0.0 && s.is_finite()).then(|| v_ref * v_ref / s)
}

fn n_winding_phase_count(w: &DistWinding) -> usize {
    crate::model::n_winding_phase_count(w.conn, &w.terminal_map)
}

fn n_winding_bmopf_v_nom(w: &DistWinding) -> f64 {
    if w.conn == DistWindingConn::Wye && n_winding_phase_count(w) >= 2 {
        w.v_ref / 3f64.sqrt()
    } else {
        w.v_ref
    }
}

fn n_winding_base(w: &DistWinding, s: f64) -> Option<f64> {
    n_winding_impedance_base(n_winding_phase_count(w), n_winding_bmopf_v_nom(w), s)
}

fn bmopf_delta_roll(t: &DistTransformer, idx: usize, w: &DistWinding) -> Option<i64> {
    if w.conn != DistWindingConn::Delta {
        return None;
    }
    t.extras
        .get(BMOPF_DELTA_ROLLS_EXTRA)
        .and_then(Value::as_object)
        .and_then(|rolls| rolls.get(&(idx + 1).to_string()))
        .and_then(Value::as_i64)
        .filter(|roll| *roll == 1 || *roll == -1)
        .or(Some(-1))
}

/// The phase and neutral label lists, from the bus terminal names. The rule
/// is the one the schema prescribes for an absent `terminal_conventions`
/// block: an `n` or `N` label is neutral, every other label is a phase.
/// Add deterministic producer provenance without replacing source metadata.
fn proposal_provenance(meta: &mut Map<String, Value>) {
    let record = json!({
        "producer": "powerio", "producer_version": env!("CARGO_PKG_VERSION"),
        "schema_status": "proposal", "schema_version": "0.2.0",
        "schema_commit": super::BMOPF_PROPOSAL_COMMIT,
        "schema_sha256": super::BMOPF_PROPOSAL_SHA256,
        "schema_id": BmopfSchemaVersion::Bmopf020.schema_id(),
        "schema_retrieval_url": BmopfSchemaVersion::Bmopf020.retrieval_url(),
        "schema_upstream_url": super::BMOPF_PROPOSAL_URL
    });
    let provenance = meta.entry("provenance").or_insert_with(|| json!({}));
    let Some(provenance) = provenance.as_object_mut() else {
        return;
    };
    let mut index = 0;
    loop {
        let key = if index == 0 {
            "powerio_bmopf".to_owned()
        } else {
            format!("powerio_bmopf_{index}")
        };
        match provenance.get(&key) {
            Some(existing) if existing == &record => break,
            Some(_) => index += 1,
            None => {
                provenance.insert(key, record);
                break;
            }
        }
    }
}

/// Labels keep first-seen order and case-sensitive identity.
fn authored_terminal_conventions(net: &MulticonductorNetwork) -> Option<Value> {
    let neutral_names: BTreeSet<&String> = net
        .buses()
        .iter()
        .flat_map(|bus| {
            let phases = bus.phase_indices(None);
            bus.terminals
                .iter()
                .enumerate()
                .filter_map(move |(index, name)| (!phases.contains(&index)).then_some(name))
        })
        .collect();
    let mut phase = Vec::new();
    let mut neutral = Vec::new();
    for bus in net.buses() {
        for term in &bus.terminals {
            let labels = if neutral_names.contains(term) {
                &mut neutral
            } else {
                &mut phase
            };
            if !labels.contains(&term) {
                labels.push(term);
            }
        }
    }
    (!phase.is_empty() || !neutral.is_empty()).then(|| json!({"phase": phase, "neutral": neutral}))
}

fn config_str(c: Configuration) -> &'static str {
    match c {
        Configuration::Wye => "WYE",
        Configuration::Delta => "DELTA",
        Configuration::SinglePhase => "SINGLE_PHASE",
    }
}

fn json_enum<T: serde::Serialize>(value: T) -> Value {
    serde_json::to_value(value).expect("enum serializes to a string")
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::{DistLoadVoltageModel, IbrPrimeMover, IbrTopology};
    use crate::testkit::parse_bmopf_str;

    /// A dropped field's diagnostic code must never claim the field was
    /// kept, and a kept-under-extras diagnostic must never claim the field
    /// was dropped. Exercises the writer's own field-dropped and
    /// retained-source-only call sites directly, since the two only differ
    /// by which paths trigger each one.
    #[test]
    fn dropped_and_retained_bmopf_diagnostics_do_not_contradict_their_own_message() {
        // Schema 0.1.0: the retained-under-extras path is the one that
        // relocates a transformer field, and only that version relocates.
        let mut w = Writer {
            options: BmopfEmitOptions {
                schema_version: BmopfSchemaVersion::Bmopf010,
                ..BmopfEmitOptions::default()
            },
            warnings: crate::diagnostics::Diagnostics::new(),
            transformer_overflow: Map::new(),
            dropped_extras: BTreeMap::new(),
        };

        // A non-object control_profile extra and an ibr extra outside the
        // allowed set both take the field-dropped path.
        let mut profile = DistControlProfile::new("cp1");
        profile.extras.insert("weird".into(), json!(42));
        w.control_profile(&profile);

        let mut ibr = DistIbr::new(
            "pv1",
            "b1",
            vec!["1".into(), "2".into(), "3".into()],
            IbrTopology::ThreeLeg,
            IbrPrimeMover::Pv,
            vec![1.0, 1.0, 1.0],
        );
        ibr.extras.insert("not_a_schema_field".into(), json!(1));
        w.ibr(&ibr);

        // A moved transformer field takes the retained-under-extras path.
        let mut by_subtype = Map::new();
        by_subtype.insert("single_phase".into(), json!({ "t1": { "tap": 1.05 } }));
        w.split_transformer_overflow(&mut by_subtype);

        let records = w.warnings.records();
        let dropped: Vec<_> = records
            .iter()
            .filter(|d| d.code() == "EMIT.BMOPF.FIELD_DROPPED")
            .collect();
        let retained: Vec<_> = records
            .iter()
            .filter(|d| d.code() == "EMIT.BMOPF.RETAINED_SOURCE_ONLY")
            .collect();
        assert!(!dropped.is_empty(), "{records:?}");
        assert!(!retained.is_empty(), "{records:?}");
        for d in dropped {
            assert!(
                !d.message().contains("kept under extras"),
                "FIELD_DROPPED message claims the field was kept: {}",
                d.message()
            );
        }
        for d in retained {
            assert!(
                !d.message().contains("dropped"),
                "RETAINED_SOURCE_ONLY message claims the field was dropped: {}",
                d.message()
            );
        }
    }

    #[test]
    fn load_voltage_models_round_trip_through_bmopf() {
        let text = r#"{
            "bus": {
                "b1": {"terminal_names": ["1", "2", "3", "4"], "perfectly_grounded_terminals": ["4"]}
            },
            "voltage_source": {
                "source": {
                    "bus": "b1", "terminal_map": ["1", "2", "3", "4"],
                    "v_magnitude": [7200.0, 7200.0, 7200.0, 0.0],
                    "v_angle": [0.0, -120.0, 120.0, 0.0]
                }
            },
            "load": {
                "zip": {
                    "bus": "b1", "terminal_map": ["1", "2", "3", "4"],
                    "configuration": "WYE", "p_nom": [1.0, 2.0, 3.0], "q_nom": [0.1, 0.2, 0.3],
                    "model": "zip", "v_nom": [7200.0, 7200.0, 7200.0],
                    "alpha_z": [0.2, 0.2, 0.2], "alpha_i": [0.3, 0.3, 0.3], "alpha_p": [0.5, 0.5, 0.5],
                    "beta_z": [0.1, 0.1, 0.1], "beta_i": [0.4, 0.4, 0.4], "beta_p": [0.5, 0.5, 0.5]
                },
                "exp": {
                    "bus": "b1", "terminal_map": ["1", "2", "3", "4"],
                    "configuration": "WYE", "p_nom": [1.0, 1.0, 1.0], "q_nom": [0.0, 0.0, 0.0],
                    "model": "exponential", "v_nom": [7200.0, 7200.0, 7200.0],
                    "gamma_p": [1.2, 1.2, 1.2], "gamma_q": [2.1, 2.1, 2.1]
                }
            }
        }"#;
        let net = parse_bmopf_str(text).unwrap();
        let zip = net.loads().iter().find(|l| l.name == "zip").unwrap();
        let exp = net.loads().iter().find(|l| l.name == "exp").unwrap();
        assert!(matches!(
            &zip.voltage_model,
            DistLoadVoltageModel::Zip { alpha_z, .. } if alpha_z == &vec![0.2, 0.2, 0.2]
        ));
        assert!(matches!(
            &exp.voltage_model,
            DistLoadVoltageModel::Exponential { gamma_q, .. } if gamma_q == &vec![2.1, 2.1, 2.1]
        ));

        let out = emit_bmopf_json_text(&net);
        assert!(
            out.render_diagnostics().is_empty(),
            "{:?}",
            out.render_diagnostics()
        );
        let v: Value = serde_json::from_str(&out.text).unwrap();
        assert_eq!(
            v["load"]["zip"]["alpha_i"],
            serde_json::json!([0.3, 0.3, 0.3])
        );
        assert_eq!(
            v["load"]["exp"]["gamma_p"],
            serde_json::json!([1.2, 1.2, 1.2])
        );
    }

    /// A model built without the reader caps must not force quadratic
    /// allocation out of linear-size input.
    #[test]
    fn oversized_model_dimensions_are_clamped_not_expanded() {
        use crate::model::{
            DistLineCode, DistShunt, DistTransformer, DistWinding, DistWindingConn,
        };

        let mut net = crate::model::MulticonductorNetwork::default();
        // A linecode whose R rows imply a huge dimension while X is empty
        // would materialize dim x dim zeros for X.
        let mut lc = DistLineCode::new("big", Vec::new(), Vec::new());
        lc.r_series = vec![Vec::new(); 100_000];
        net.line_codes_mut().push(lc);
        // Same shape for a shunt's G/B pair.
        net.shunts_mut().push(DistShunt::new(
            "big",
            "b",
            Vec::new(),
            vec![Vec::new(); 100_000],
            Vec::new(),
        ));
        // A winding count beyond the cap would expand to ~n²/2 x_sc pairs.
        let winding = DistWinding::new("b", Vec::new(), DistWindingConn::Wye, 1.0, 1.0);
        net.transformers_mut().push(DistTransformer::new(
            "many",
            vec![winding; MAX_DIM + 6],
            Vec::new(),
            3,
        ));

        let out = emit_bmopf_json_text(&net);
        let v: Value = serde_json::from_str(&out.text).unwrap();
        let count_keys = |m: &Value, prefix: &str| {
            m.as_object()
                .unwrap()
                .keys()
                .filter(|k| k.starts_with(prefix))
                .count()
        };
        assert_eq!(
            count_keys(&v["linecode"]["big"], "X_series_"),
            MAX_DIM * MAX_DIM
        );
        assert_eq!(count_keys(&v["shunt"]["big"], "B_"), MAX_DIM * MAX_DIM);
        assert_eq!(
            v["transformer"]["n_winding"]["many"]["x_sc"]
                .as_object()
                .unwrap()
                .len(),
            MAX_DIM * (MAX_DIM - 1) / 2
        );
        assert!(
            out.render_diagnostics()
                .iter()
                .any(|w| w.contains("exceeds the supported maximum")),
            "{:?}",
            out.render_diagnostics()
        );
    }
}