powerio/format/

mod.rs

//! Readers and writers for supported case formats, all meeting at [`BalancedNetwork`].
//!
//! Each format module owns its reader and/or writer: MATPOWER `.m`,
//! PowerModels JSON, PSS/E `.raw`, PowerWorld `.aux`, egret `ModelData` JSON,
//! pandapower JSON, PyPSA CSV folders, PSLF `.epc`, GO Challenge 3 JSON, and
//! Surge JSON, and DeepMind OPFData JSON. PowerWorld `.pwb` cases, GO Challenge
//! 3 and OPFData JSON canonical output, and PowerWorld `.pwd` displays are read
//! only. Case input and
//! output formats meet here, so adding a writable format is one module plus
//! one hub registration.
//! [`parse_file`] reads BalancedNetwork cases, detecting the format from its extension;
//! [`parse_display_file`] reads display artifacts such as PowerWorld `.pwd`.
//! [`write_as`] serializes a `BalancedNetwork` to text targets. Directory formats,
//! such as PyPSA CSV folders, use explicit filesystem helpers. Non-finite
//! numeric values, such as MATPOWER `Inf`/`NaN` angle limits, are written as
//! JSON `null`.
//!
//! # Fidelity behavior
//!
//! Conversion is two-tier:
//!
//! - **Same format writes return the original text.** A reader keeps its source
//!   text (see [`BalancedNetwork`]), so writing back to the same format returns every
//!   field, comment, and numeric token.
//! - **Cross-format keeps maximal fidelity with itemized loss.** Whatever the
//!   target format cannot represent is reported in the [`Conversion`] `warnings`,
//!   never dropped silently. On the read side, readers itemize what they ignore
//!   in [`Parsed`] `warnings`.

use std::collections::{BTreeSet, HashMap};
use std::fmt;
use std::str::FromStr;
use std::sync::Arc;

use serde_json::{Map, Value};

use crate::gen_cost::{GenCostPatch, MissingGenCostPolicy};
use crate::network::{BalancedNetwork, Branch, BranchRatingSet, Bus, BusId, BusType, SourceFormat};
use crate::{Error, Result};
use routing::{Detection, JsonClass, SourceFormat as DetectedFormat, TransmissionFormat};

mod egret;
#[doc(hidden)]
pub mod goc3;
mod matpower;
mod opfdata;
mod pandapower;
mod powermodels;
pub mod powerworld;
mod pslf;
mod psse;
mod pypsa;
pub mod routing;
mod surge;

pub use egret::{parse_egret_json, write_egret_json};
pub use goc3::parse_goc3_json;
pub use matpower::{parse_matpower, parse_matpower_file, write_matpower};
pub use opfdata::parse_deepmind_opfdata_json;
pub use pandapower::{parse_pandapower_json, write_pandapower_json};
pub use powermodels::{parse_powermodels_json, write_powermodels_json};
pub use powerworld::{PwdDisplay, PwdSubstation, parse_powerworld, write_powerworld};
pub use pslf::{parse_pslf, write_pslf};
pub use psse::{parse_psse, write_psse, write_psse_rev};
pub use pypsa::{PypsaCsvOutputs, read_pypsa_csv_folder, write_pypsa_csv_folder};
pub use surge::{parse_surge_json, write_surge_json};

/// A target interchange format. See [`write_as`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum TargetFormat {
    /// PowerModels.jl network data JSON.
    PowerModelsJson,
    /// egret `ModelData` JSON.
    EgretJson,
    /// PSS/E `.raw` at the given revision. `rev` selects the record layout the
    /// writer emits (33, 34, or 35); 33 is the historical default. The reader
    /// takes the revision from the file header, so this only affects writes.
    Psse { rev: u32 },
    /// PowerWorld auxiliary `.aux`.
    PowerWorld,
    /// pandapower `pandapowerNet` JSON.
    PandapowerJson,
    /// MATPOWER `.m` (round-trip; byte-exact when the case kept its source).
    Matpower,
    /// Compatibility alias for [`BalancedNetwork::to_json`] and [`BalancedNetwork::from_json`].
    /// New code should call those methods directly.
    #[doc(hidden)]
    PowerioJson,
    /// GE PSLF `.epc` (round-trip; byte-exact when the case kept its source).
    Pslf,
    /// ARPA-E GO Challenge 3 JSON input data. This is read only except for
    /// same format source echo when the parsed network still carries its source.
    Goc3Json,
    /// Surge native JSON network document.
    SurgeJson,
    /// One JSON document from a DeepMind OPFData release. Read only except for
    /// an exact write back to the retained source format.
    DeepMindOpfDataJson,
}

impl TargetFormat {
    /// Conventional file extension for this format (no leading dot).
    #[must_use]
    pub fn extension(self) -> &'static str {
        match self {
            TargetFormat::PowerModelsJson
            | TargetFormat::EgretJson
            | TargetFormat::PandapowerJson
            | TargetFormat::PowerioJson
            | TargetFormat::Goc3Json
            | TargetFormat::SurgeJson
            | TargetFormat::DeepMindOpfDataJson => "json",
            TargetFormat::Psse { .. } => "raw",
            TargetFormat::PowerWorld => "aux",
            TargetFormat::Matpower => "m",
            TargetFormat::Pslf => "epc",
        }
    }

    /// Human-readable format name for diagnostics.
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            TargetFormat::PowerModelsJson => "PowerModels JSON",
            TargetFormat::EgretJson => "egret JSON",
            TargetFormat::Psse { .. } => "PSS/E .raw",
            TargetFormat::PowerWorld => "PowerWorld .aux",
            TargetFormat::PandapowerJson => "pandapower JSON",
            TargetFormat::Matpower => "MATPOWER .m",
            TargetFormat::PowerioJson => "PowerIO JSON",
            TargetFormat::Pslf => "PSLF .epc",
            TargetFormat::Goc3Json => "GO Challenge 3 JSON",
            TargetFormat::SurgeJson => "Surge JSON",
            TargetFormat::DeepMindOpfDataJson => "DeepMind OPFData JSON",
        }
    }

    /// Canonical API token for this format.
    #[must_use]
    pub fn token(self) -> &'static str {
        match self {
            TargetFormat::PowerModelsJson => "powermodels-json",
            TargetFormat::EgretJson => "egret-json",
            TargetFormat::Psse { rev: 34 } => "psse34",
            TargetFormat::Psse { rev: 35 } => "psse35",
            TargetFormat::Psse { .. } => "psse",
            TargetFormat::PowerWorld => "powerworld",
            TargetFormat::PandapowerJson => "pandapower-json",
            TargetFormat::Matpower => "matpower",
            TargetFormat::PowerioJson => "powerio-json",
            TargetFormat::Pslf => "pslf",
            TargetFormat::Goc3Json => "goc3-json",
            TargetFormat::SurgeJson => "surge-json",
            TargetFormat::DeepMindOpfDataJson => "opfdata-json",
        }
    }
}

impl fmt::Display for TargetFormat {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.token())
    }
}

impl FromStr for TargetFormat {
    type Err = Error;

    fn from_str(name: &str) -> Result<Self> {
        target_format_from_name(name).ok_or_else(|| Error::UnknownFormat(name.to_string()))
    }
}

/// A display artifact format. These files are not power network cases and do
/// not parse to [`BalancedNetwork`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum DisplayFormat {
    /// PowerWorld oneline display `.pwd`.
    PowerWorld,
    /// The standalone geographic document ([`crate::geo::GeoLayer`]):
    /// canonical `.geo.json`, read tolerantly from GeoJSON, aliased CSV/JSON
    /// records, and headerless buscoords CSV.
    GeoJson,
}

impl DisplayFormat {
    /// Conventional file extension for this display format (no leading dot).
    #[must_use]
    pub fn extension(self) -> &'static str {
        match self {
            DisplayFormat::PowerWorld => "pwd",
            DisplayFormat::GeoJson => crate::geo::GEO_LAYER_EXTENSION,
        }
    }

    /// Human-readable format name for diagnostics.
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            DisplayFormat::PowerWorld => "PowerWorld .pwd",
            DisplayFormat::GeoJson => "geo layer",
        }
    }

    /// Canonical API token for this format.
    #[must_use]
    pub fn token(self) -> &'static str {
        match self {
            DisplayFormat::PowerWorld => "powerworld-display",
            DisplayFormat::GeoJson => "geojson",
        }
    }
}

impl fmt::Display for DisplayFormat {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.token())
    }
}

impl FromStr for DisplayFormat {
    type Err = Error;

    fn from_str(name: &str) -> Result<Self> {
        display_format_from_name(name).ok_or_else(|| Error::UnknownFormat(name.to_string()))
    }
}

/// Map a display format name to a [`DisplayFormat`], or `None` if unrecognized.
/// Accepts `pwd`, `powerworld-pwd`, and `powerworld-display`; `geojson`,
/// `geo-json`, and `geo` name the geographic layer.
#[must_use]
pub fn display_format_from_name(name: &str) -> Option<DisplayFormat> {
    Some(match name.to_ascii_lowercase().as_str() {
        "pwd" | "powerworld-pwd" | "powerworld-display" => DisplayFormat::PowerWorld,
        "geojson" | "geo-json" | "geo" => DisplayFormat::GeoJson,
        _ => return None,
    })
}

/// Map a format name (with the common aliases) to a [`TargetFormat`], or `None`
/// if unrecognized. Accepts `matpower`/`m`, `powermodels-json`/`powermodels`/`pm`,
/// `egret-json`/`egret`, `pandapower-json`/`pandapower`/`pp`, `psse`/`raw`,
/// `powerworld`/`aux`, `pslf`/`epc`, `goc3-json`/`goc3`, and
/// `surge-json`/`surge`, and `opfdata-json`/`opfdata`/`gridopt`. The
/// `powerio-json`/`powerio`/`json` names remain
/// compatibility aliases for the model JSON methods.
/// Case-insensitive. The one place the bindings (Python, C ABI) share, so a new
/// text format means one new arm here, not three. PyPSA CSV folders, GridFM
/// datasets, and PowerWorld `.pwb` are directory or read only inputs with no
/// text target; they are routed by [`crate::format::routing`].
///
/// The `powermodelsjson`/`egretjson`/`pandapowerjson` aliases let a
/// [`SourceFormat`]'s string form (`{:?}` lowercased, e.g. `"PowerModelsJson"`)
/// round-trip back to a target, so `net.to_format(other.source_format)` works
/// for every format.
#[must_use]
pub fn target_format_from_name(name: &str) -> Option<TargetFormat> {
    Some(match routing::transmission_format_from_name(name)? {
        TransmissionFormat::Matpower => TargetFormat::Matpower,
        TransmissionFormat::PowerModelsJson => TargetFormat::PowerModelsJson,
        TransmissionFormat::EgretJson => TargetFormat::EgretJson,
        TransmissionFormat::Psse => TargetFormat::Psse { rev: 33 },
        TransmissionFormat::Psse34 => TargetFormat::Psse { rev: 34 },
        TransmissionFormat::Psse35 => TargetFormat::Psse { rev: 35 },
        TransmissionFormat::PowerWorld => TargetFormat::PowerWorld,
        TransmissionFormat::PandapowerJson => TargetFormat::PandapowerJson,
        TransmissionFormat::PowerioJson => TargetFormat::PowerioJson,
        TransmissionFormat::Pslf => TargetFormat::Pslf,
        TransmissionFormat::Goc3Json => TargetFormat::Goc3Json,
        TransmissionFormat::SurgeJson => TargetFormat::SurgeJson,
        TransmissionFormat::DeepMindOpfDataJson => TargetFormat::DeepMindOpfDataJson,
        TransmissionFormat::PypsaCsv | TransmissionFormat::Pwb | TransmissionFormat::Gridfm => {
            return None;
        }
    })
}

/// Output of a display parse. PowerWorld `.pwd` produces
/// [`DisplayData::PowerWorld`]; a geographic sidecar produces
/// [`DisplayData::Geo`].
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum DisplayData {
    /// PowerWorld oneline display data.
    PowerWorld(PwdDisplay),
    /// A standalone geographic layer.
    Geo(crate::geo::GeoLayer),
}

impl DisplayData {
    /// The display format represented by this value.
    #[must_use]
    pub fn format(&self) -> DisplayFormat {
        match self {
            DisplayData::PowerWorld(_) => DisplayFormat::PowerWorld,
            DisplayData::Geo(_) => DisplayFormat::GeoJson,
        }
    }
}

fn display_file_guidance() -> Error {
    Error::UnknownFormat(
        "a PowerWorld .pwd is display data, not a BalancedNetwork case; \
         use parse_display_file(path, None)"
            .into(),
    )
}

/// Parse display bytes in the named display `format`.
///
/// # Errors
/// [`Error::UnknownFormat`] if `format` is not a display format; otherwise the
/// reader's own [`Error`] on malformed input.
pub fn parse_display_bytes(bytes: &[u8], format: &str) -> Result<DisplayData> {
    let fmt =
        display_format_from_name(format).ok_or_else(|| Error::UnknownFormat(format.to_string()))?;
    match fmt {
        DisplayFormat::PowerWorld => Ok(DisplayData::PowerWorld(powerworld::parse_pwd_display(
            bytes,
        )?)),
        // The tolerant reader's own notes are available through
        // `GeoLayer::parse_bytes` for callers that want them.
        DisplayFormat::GeoJson => Ok(DisplayData::Geo(
            crate::geo::GeoLayer::parse_bytes(bytes, None)?.layer,
        )),
    }
}

/// Parse the display file at `path`, choosing the reader from `from` or, when
/// `None`, from the extension. A `.pwd` extension selects PowerWorld display
/// data.
///
/// # Errors
/// [`Error::UnknownFormat`] if `from` is unrecognized or the extension cannot
/// be mapped; [`Error::Io`] if the file cannot be read; the reader's own
/// [`Error`] on malformed input.
pub fn parse_display_file(
    path: impl AsRef<std::path::Path>,
    from: Option<&str>,
) -> Result<DisplayData> {
    let path = path.as_ref();
    let fmt = match from {
        Some(f) => {
            display_format_from_name(f).ok_or_else(|| Error::UnknownFormat(f.to_string()))?
        }
        None => match path
            .extension()
            .and_then(|e| e.to_str())
            .map(str::to_ascii_lowercase)
            .as_deref()
        {
            Some("pwd") => DisplayFormat::PowerWorld,
            Some("geojson") => DisplayFormat::GeoJson,
            // `.geo.json` is the canonical layer name; a bare `.json` stays
            // ambiguous (it is usually a case file).
            Some("json")
                if path
                    .file_name()
                    .and_then(|name| name.to_str())
                    .is_some_and(|name| {
                        name.to_ascii_lowercase()
                            .ends_with(crate::geo::GEO_LAYER_EXTENSION)
                    }) =>
            {
                DisplayFormat::GeoJson
            }
            other => {
                return Err(Error::UnknownFormat(format!(
                    "cannot infer display format from file extension {other:?}; \
                     pass an explicit display format"
                )));
            }
        },
    };
    let bytes = std::fs::read(path)?;
    match fmt {
        DisplayFormat::PowerWorld => Ok(DisplayData::PowerWorld(powerworld::parse_pwd_display(
            &bytes,
        )?)),
        DisplayFormat::GeoJson => Ok(DisplayData::Geo(
            crate::geo::GeoLayer::parse_bytes(&bytes, path.file_name().and_then(|n| n.to_str()))?
                .layer,
        )),
    }
}

/// Whether a format name means a PyPSA CSV folder. PyPSA folders are directory
/// inputs, not text targets, so they have no [`TargetFormat`] arm; this is the
/// companion alias matcher to [`target_format_from_name`] and the one place the
/// PyPSA aliases live.
fn is_pypsa_csv_name(name: &str) -> bool {
    matches!(
        name.to_ascii_lowercase().replace(['-', '_'], "").as_str(),
        "pypsacsv" | "pypsa"
    )
}

/// Whether a source format name means PSLF EPC.
fn is_pslf_name(name: &str) -> bool {
    matches!(
        name.to_ascii_lowercase().replace(['-', '_'], "").as_str(),
        "pslf" | "epc" | "pslfepc"
    )
}

/// Parse the case file at `path`, choosing the reader from `from` (the
/// [`target_format_from_name`] names plus `pypsa-csv`/`pypsa`, `pwb`, `pslf`,
/// and `epc`) or, when `None`, from the path: a directory containing
/// `network.csv` parses as a PyPSA CSV folder (any other directory fails:
/// [`Error::UnknownFormat`] when its name maps to no extension, the I/O error
/// otherwise), and a file maps by extension (`m`/`json`/`raw`/`aux`/`pwb`/`epc`),
/// case insensitively (issue #97: `.RAW` is as common as `.raw` in the wild). A
/// `.json` file is classified by top level shape markers: pandapower
/// (`"_class": "pandapowerNet"`), egret (`elements` and `system`), GO Challenge
/// 3 (`network` plus `time_series_input`/`reliability`), Surge JSON
/// (`format: "surge-json"`), OPFData (`grid`, `solution`, and `metadata`),
/// powerio-json (`buses` plus network keys), and PowerModels JSON (`baseMVA`,
/// `branch`, `gen`, or `gencost`). JSON matching
/// distribution markers, ambiguous markers, or no known markers returns
/// [`Error::UnknownFormat`]. Pass `from` to force a
/// transmission format. PowerWorld `.pwb` is a binary read only format with no
/// retained source; PSLF `.epc` is text and has a writer. Returns [`Parsed`]:
/// the network plus the reader's fidelity warnings.
///
/// The one path-based parser the CLI and the Python/C/Julia bindings share (each
/// exposes the same `parse_file(path, from)` shape), so adding a source format is
/// one edit here, not one per binding. For in-memory text use [`parse_str`].
///
/// # Errors
/// [`Error::UnknownFormat`] if `from` is unrecognized or the extension can't be
/// mapped; [`Error::Io`] if the file can't be read; the reader's own [`Error`]
/// on malformed input.
pub fn parse_file(path: impl AsRef<std::path::Path>, from: Option<&str>) -> Result<Parsed> {
    let path = path.as_ref();
    // PyPSA CSV folders are directories, not files; dispatch them before any
    // extension logic. `from` accepts the pypsa aliases, and a bare directory
    // with a `network.csv` auto-detects.
    if from.is_some_and(is_pypsa_csv_name)
        || (from.is_none() && path.is_dir() && path.join("network.csv").is_file())
    {
        return pypsa::read_pypsa_csv_folder(path);
    }
    // PowerWorld `.pwb` is binary and read only; dispatch it before the text
    // read. `from` accepts "pwb" for files with a different extension.
    let ext = path
        .extension()
        .and_then(|e| e.to_str())
        .map(str::to_ascii_lowercase);
    if from.is_some_and(|f| f.eq_ignore_ascii_case("pwb"))
        || (from.is_none() && ext.as_deref() == Some("pwb"))
    {
        let bytes = std::fs::read(path)?;
        let stem = path.file_stem().and_then(|s| s.to_str());
        // The binary reader is total (no fidelity warnings); wrap its network
        // in the shared [`Parsed`] shape.
        let network = powerworld::parse_pwb(&bytes, stem)?;
        return Ok(Parsed::without_document(network, Vec::new()));
    }
    if from.is_some_and(is_pslf_name) || (from.is_none() && ext.as_deref() == Some("epc")) {
        let text = std::fs::read_to_string(path)?;
        let stem = path.file_stem().and_then(|s| s.to_str());
        let mut warnings = Vec::new();
        let source = strip_bom(Arc::new(text), &mut warnings);
        let network = pslf::parse_pslf_source(source, stem, &mut warnings)?;
        reject_empty_case(&network, "PSLF .epc")?;
        return Ok(Parsed::without_document(network, warnings));
    }
    if from
        .and_then(target_format_from_name)
        .is_some_and(|format| format == TargetFormat::DeepMindOpfDataJson)
        && matches!(ext.as_deref(), Some("pt" | "gz"))
    {
        return Err(Error::UnknownFormat(
            "OPFData .pt tensor caches and .tar.gz archives are not case files; extract and parse an example_N.json source file"
                .into(),
        ));
    }
    // Settle the format before touching the file: an unmapped or binary
    // extension must surface as UnknownFormat, not as the UTF-8 read error
    // the text formats' loader would hit first. `.pwd` gets its own arm
    // because the display sibling ships next to every case file in the wild
    // and carries no case data.
    if from.is_none() && ext.as_deref() == Some("pwd") {
        return Err(display_file_guidance());
    }
    let fmt_hint = match from {
        Some(f) => {
            if display_format_from_name(f).is_some() {
                return Err(display_file_guidance());
            }
            Some(target_format_from_name(f).ok_or_else(|| unknown_source_format(f))?)
        }
        None => {
            // Everything but `.json` (sniffed below) resolves without the text.
            match ext.as_deref() {
                Some("m") => Some(TargetFormat::Matpower),
                Some("raw") => Some(TargetFormat::Psse { rev: 33 }),
                Some("aux") => Some(TargetFormat::PowerWorld),
                Some("json") => None,
                Some("dss") => return Err(unknown_source_format("dss")),
                other => {
                    return Err(Error::UnknownFormat(format!(
                        "cannot infer from file extension {other:?}; \
                         pass an explicit source format"
                    )));
                }
            }
        }
    };
    // Read the file once into an owned buffer; the reader moves it straight into
    // the retained source (byte-exact round-trip) with no copy. Sniffing a
    // `.json` borrows the text before the move.
    let text = std::fs::read_to_string(path)?;
    let fmt = match fmt_hint {
        Some(fmt) => fmt,
        None => sniff_json(&text)?,
    };
    // The file stem is the name hint for formats that don't carry their own name.
    let stem = path.file_stem().and_then(|s| s.to_str());
    read_source(Arc::new(text), fmt, stem)
}

/// Strip a leading UTF-8 byte order mark before the reader sees the text.
/// Windows tooling saves case files with one, and every text reader here
/// (serde_json first among them) treats it as garbage in the first token. The
/// retained source loses the mark, so a same-format echo differs by exactly
/// those three bytes; the warning itemizes that per the fidelity policy.
fn strip_bom(source: Arc<String>, warnings: &mut Vec<String>) -> Arc<String> {
    let Some(stripped) = source.strip_prefix('\u{feff}') else {
        return source;
    };
    warnings.push(
        "leading UTF-8 byte order mark removed; a same-format write returns the text without it"
            .to_owned(),
    );
    Arc::new(stripped.to_owned())
}

/// Read an owned `source` buffer as `fmt`, using `name_hint` (e.g. the file
/// stem) when the format carries no name of its own. The single format→reader
/// map: [`parse_file`] and [`parse_str`] both funnel through it, so every format
/// is dispatched the same way. Each reader takes the owned `Arc` so
/// it moves the buffer straight into the retained source (no copy) and is free
/// to specialize its parse internally. Owns the [`Parsed`] warnings vector;
/// readers that report fidelity loss append to it.
fn read_source(source: Arc<String>, fmt: TargetFormat, name_hint: Option<&str>) -> Result<Parsed> {
    let mut warnings = Vec::new();
    let source = strip_bom(source, &mut warnings);
    let mut document = None;
    let net = match fmt {
        TargetFormat::Matpower => matpower::parse_matpower_source(source, name_hint),
        TargetFormat::PowerModelsJson => {
            powermodels::parse_powermodels_json_source(source, name_hint, &mut warnings)
        }
        TargetFormat::Psse { .. } => psse::parse_psse_source(source, name_hint, &mut warnings),
        TargetFormat::PowerWorld => {
            powerworld::parse_powerworld_source(source, name_hint, &mut warnings)
        }
        TargetFormat::EgretJson => egret::parse_egret_source(source, name_hint),
        TargetFormat::PandapowerJson => {
            pandapower::parse_pandapower_source(source, name_hint, &mut warnings)
        }
        // The canonical snapshot: validated deserialization of the model itself.
        // It carries its own name and source_format, so the hint doesn't apply.
        TargetFormat::PowerioJson => BalancedNetwork::from_json(&source),
        // PSLF read normally enters through the `is_pslf_name`/`.epc` fast path in
        // parse_file / parse_str; this arm keeps the funnel total.
        TargetFormat::Pslf => pslf::parse_pslf_source(source, name_hint, &mut warnings),
        TargetFormat::Goc3Json => {
            goc3::parse_goc3_source(source, name_hint, &mut warnings).map(|(net, goc3)| {
                document = Some(SourceDocument::Goc3(goc3));
                net
            })
        }
        TargetFormat::SurgeJson => surge::parse_surge_source(source, name_hint, &mut warnings),
        TargetFormat::DeepMindOpfDataJson => {
            opfdata::parse_opfdata_source(source, name_hint, &mut warnings)
        }
    }?;
    reject_empty_case(&net, fmt.label())?;
    Ok(Parsed {
        network: net,
        warnings,
        document,
    })
}

/// Geographic metadata for a reader that harvested longitude/latitude
/// coordinates: `Some` once any bus carries a location, so a case without
/// coordinates serializes exactly as before. The space is stamped geographic
/// only when every point fits longitude/latitude bounds; a source that
/// violates its format's own convention (projected meters in a pandapower
/// `geo` column) reads as unknown instead of claiming WGS84.
pub(crate) fn geographic_meta(buses: &[Bus]) -> Option<crate::geo::GeoMeta> {
    let mut located = buses.iter().filter_map(|bus| bus.location).peekable();
    located.peek()?;
    let in_bounds = located.all(|location| location.x.abs() <= 180.0 && location.y.abs() <= 90.0);
    Some(crate::geo::GeoMeta {
        space: if in_bounds {
            crate::geo::CoordinateSpace::Geographic { crs: None }
        } else {
            crate::geo::CoordinateSpace::Unknown
        },
        kind: None,
    })
}

/// A case with no buses is content-free for every consumer. Most readers
/// already reject it on a missing required table, but a JSON carrying only
/// `baseMVA` would otherwise parse to a hollow network; reject it in the
/// [`read_source`] funnel so every parse path (file and in-memory) is guarded,
/// and in the PyPSA folder reader, which bypasses the funnel.
pub(crate) fn reject_empty_case(net: &BalancedNetwork, format: &'static str) -> Result<()> {
    if net.buses.is_empty() {
        return Err(Error::FormatRead {
            format,
            message: "case has no buses".into(),
        });
    }
    Ok(())
}

/// An unrecognized source format token. When the token names a distribution
/// format (`dss`, `pmd`, `bmopf`), the error points at the distribution
/// surface instead of echoing the token: this parser reads only balanced
/// transmission formats.
fn unknown_source_format(name: &str) -> Error {
    if let Some(dist) = routing::distribution_format_from_name(name) {
        return Error::UnknownFormat(format!(
            "`{}` is a distribution format, and this parser reads only balanced \
             transmission formats; use the distribution surface (powerio_dist::parse_file, \
             pio_dist_parse_file in C, or the format-routed parse_file in the bindings)",
            dist.name()
        ));
    }
    Error::UnknownFormat(name.to_string())
}

/// The JSON formats share the `.json` extension, so an explicit source format
/// isn't always given. Classification lives here so the CLI and bindings use
/// the same top level markers as the Rust parsers.
fn sniff_json(text: &str) -> Result<TargetFormat> {
    match routing::classify_json_text(text) {
        JsonClass::Package => Err(Error::UnknownFormat(
            "JSON is a .pio.json package; read it with the package entry points \
             (pio_package_parse_str in C, powerio.Package.from_json in Python, \
             read_package in Julia)"
                .into(),
        )),
        JsonClass::Case(Detection::Known(DetectedFormat::Transmission(format))) => {
            transmission_json_target(format)
        }
        JsonClass::Case(Detection::Known(DetectedFormat::Distribution(format))) => {
            Err(Error::UnknownFormat(format!(
                "JSON looks like distribution `{}`; use the distribution parser or pass an explicit transmission format",
                format.name()
            )))
        }
        JsonClass::Case(Detection::Ambiguous) => Err(Error::UnknownFormat(
            "ambiguous JSON markers; pass an explicit source format".into(),
        )),
        JsonClass::Case(Detection::Unknown) => Err(Error::UnknownFormat(
            "cannot infer JSON format; pass an explicit source format".into(),
        )),
    }
}

fn transmission_json_target(format: TransmissionFormat) -> Result<TargetFormat> {
    match format {
        TransmissionFormat::PowerModelsJson => Ok(TargetFormat::PowerModelsJson),
        TransmissionFormat::EgretJson => Ok(TargetFormat::EgretJson),
        TransmissionFormat::PandapowerJson => Ok(TargetFormat::PandapowerJson),
        TransmissionFormat::PowerioJson => Ok(TargetFormat::PowerioJson),
        TransmissionFormat::Goc3Json => Ok(TargetFormat::Goc3Json),
        TransmissionFormat::SurgeJson => Ok(TargetFormat::SurgeJson),
        TransmissionFormat::DeepMindOpfDataJson => Ok(TargetFormat::DeepMindOpfDataJson),
        other => Err(Error::UnknownFormat(format!(
            "JSON classifier returned non-JSON transmission format `{}`",
            other.name()
        ))),
    }
}

/// Parse in-memory case `text` of the named `format` (see
/// [`target_format_from_name`]). Returns [`Parsed`]: the network plus the
/// reader's fidelity warnings.
///
/// # Errors
/// [`Error::UnknownFormat`] if `format` is unrecognized; the reader's own
/// [`Error`] on malformed input.
pub fn parse_str(text: &str, format: &str) -> Result<Parsed> {
    parse_str_with_name(text, format, None)
}

/// [`parse_str`] with a name hint for formats that carry no name of their own
/// (the role the file stem plays in [`parse_file`]). Lets a caller that already
/// read a file's text keep the stem-derived case name without going back
/// through the filesystem.
///
/// # Errors
/// As [`parse_str`].
pub fn parse_str_with_name(text: &str, format: &str, name_hint: Option<&str>) -> Result<Parsed> {
    if is_pslf_name(format) {
        let mut warnings = Vec::new();
        let source = strip_bom(Arc::new(text.to_owned()), &mut warnings);
        let network = pslf::parse_pslf_source(source, name_hint, &mut warnings)?;
        reject_empty_case(&network, "PSLF .epc")?;
        return Ok(Parsed::without_document(network, warnings));
    }
    let fmt = target_format_from_name(format).ok_or_else(|| unknown_source_format(format))?;
    read_source(Arc::new(text.to_owned()), fmt, name_hint)
}

/// Parse in-memory case `bytes` of the named `format`. Accepts every name
/// [`parse_str`] does, plus `pwb`: PowerWorld binary has no text form, so this
/// is the only in-memory entry point that reaches it. Text formats decode as
/// UTF-8 and take the [`parse_str`] path from there.
///
/// A caller that already holds the file's bytes — an upload, an archive
/// member, a database blob — parses them here rather than staging a temporary
/// file for [`parse_file`].
///
/// # Errors
/// [`Error::UnknownFormat`] if `format` is unrecognized; [`Error::FormatRead`]
/// if a text format's bytes are not UTF-8; the reader's own [`Error`] on
/// malformed input.
pub fn parse_bytes(bytes: &[u8], format: &str) -> Result<Parsed> {
    parse_bytes_with_name(bytes, format, None)
}

/// [`parse_bytes`] with a name hint, as [`parse_str_with_name`] is to
/// [`parse_str`].
///
/// # Errors
/// As [`parse_bytes`].
pub fn parse_bytes_with_name(
    bytes: &[u8],
    format: &str,
    name_hint: Option<&str>,
) -> Result<Parsed> {
    if format.eq_ignore_ascii_case("pwb") {
        // Total reader, no fidelity warnings; same call parse_file makes.
        let network = powerworld::parse_pwb(bytes, name_hint)?;
        return Ok(Parsed::without_document(network, Vec::new()));
    }
    // A display format reaches a different return type, so name the entry
    // point that returns it instead of failing as an unknown case format.
    if display_format_from_name(format).is_some() {
        return Err(Error::UnknownFormat(format!(
            "{format} is display data, not a BalancedNetwork case; \
             use parse_display_bytes(bytes, \"{format}\")"
        )));
    }
    let text = std::str::from_utf8(bytes).map_err(|e| Error::FormatRead {
        format: "case text",
        message: format!("not valid UTF-8: {e}"),
    })?;
    parse_str_with_name(text, format, name_hint)
}

/// Output of a parse: the network plus the reader's fidelity warnings,
/// tables and columns the model cannot carry, reported instead of dropped
/// silently. Empty for readers that don't report read warnings (currently
/// readers that do not need to reduce any source fields).
///
/// `#[non_exhaustive]`: a returns-only type, so downstream code reads it but
/// never constructs it, leaving room to add parse metadata without a breaking
/// change.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct Parsed {
    pub network: BalancedNetwork,
    pub warnings: Vec<String>,
    /// The source document for formats whose downstream adapters reuse the
    /// reader's parse (see [`SourceDocument`]); `None` for every other format.
    pub document: Option<SourceDocument>,
}

impl Parsed {
    /// Wrap a reader result for a format without a shared source document.
    pub(crate) fn without_document(network: BalancedNetwork, warnings: Vec<String>) -> Self {
        Self {
            network,
            warnings,
            document: None,
        }
    }
}

/// A format's source document, parsed once by the reader and handed forward so
/// downstream adapters derive their data from the same parse instead of
/// reparsing the retained source text. Today that is the GOC3 document, which
/// the operating point extractor in `powerio-pkg` consumes.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum SourceDocument {
    Goc3(Arc<goc3::Goc3Document>),
}

/// Output of a conversion: the serialized text plus any fidelity warnings:
/// data the target can't represent, defaults synthesized, or blocks mapped best
/// effort. An empty `warnings` means a faithful conversion. For [`convert_file`]
/// and [`convert_str`], `warnings` carries the read side ([`Parsed`] warnings)
/// too, ahead of the write side.
///
/// `#[non_exhaustive]`: a returns-only type, so downstream code reads it but
/// never constructs it, leaving room to add fidelity metadata without a breaking
/// change.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct Conversion {
    pub text: String,
    pub warnings: Vec<String>,
}

/// Optional write-time policies layered on top of the neutral [`BalancedNetwork`].
///
/// The default is a no-op and preserves the old `write_as` / `convert_*`
/// behavior. Non-default options work on a cloned network and never mutate the
/// caller's case.
#[derive(Debug, Clone, Default)]
pub struct WriteOptions {
    pub missing_gen_cost: MissingGenCostPolicy,
    pub gen_cost_patches: Vec<GenCostPatch>,
}

impl WriteOptions {
    #[must_use]
    pub fn is_default(&self) -> bool {
        self.missing_gen_cost.is_preserve() && self.gen_cost_patches.is_empty()
    }
}

/// Convert a [`BalancedNetwork`] to `format`. Writing back to the source format returns
/// the retained source text; otherwise the network is serialized into the target.
///
/// # Errors
/// Only a `PowerioJson` serialization failure. A non-finite value is not an
/// error: readers can produce
/// `Inf` limits and the bindings materialize every network through the
/// snapshot, so it is written as `null` with a fidelity warning naming the
/// field: that output serves the one-way transports but does not read back
/// (the validating reader rejects the `null`).
pub fn write_as(net: &BalancedNetwork, format: TargetFormat) -> Result<Conversion> {
    if is_echo(net, format) {
        if let Some(src) = &net.source {
            return Ok(Conversion {
                text: src.to_string(),
                warnings: Vec::new(),
            });
        }
    }
    let mut conv = match format {
        TargetFormat::PowerModelsJson => write_powermodels_json(net),
        TargetFormat::EgretJson => write_egret_json(net),
        TargetFormat::Psse { rev } => write_psse_rev(net, rev),
        TargetFormat::PowerWorld => write_powerworld(net),
        TargetFormat::PandapowerJson => write_pandapower_json(net),
        // From another source (or no retained source): canonical MATPOWER from
        // the folded model, which itemizes what it can't carry (HVDC, gen caps,
        // extras, a partial-cost case).
        TargetFormat::Matpower => matpower::write_matpower_conversion(net),
        // The snapshot serializes the model itself, so the usual target
        // passes don't apply (warn_normalized_tap would even be FALSE here:
        // the snapshot preserves the line/transformer labels it warns about);
        // return before them. The one fidelity loss the snapshot can suffer
        // is JSON's missing Inf/NaN: serde writes them as `null`, which
        // `from_json` rejects on the way back, so warn, naming every field.
        TargetFormat::PowerioJson => {
            return net.to_json().map(|text| Conversion {
                text,
                warnings: net
                    .non_finite_fields()
                    .into_iter()
                    .map(|path| {
                        format!(
                            "{path} is not finite; JSON has no Inf/NaN, so it is written as \
                             null and this snapshot will not read back as powerio-json"
                        )
                    })
                    .collect(),
            });
        }
        TargetFormat::Pslf => write_pslf(net),
        TargetFormat::SurgeJson => write_surge_json(net),
        TargetFormat::Goc3Json => {
            return Err(Error::WriteUnsupported {
                format: "goc3-json",
            });
        }
        TargetFormat::DeepMindOpfDataJson => {
            return Err(Error::WriteUnsupported {
                format: "opfdata-json",
            });
        }
    };
    warn_normalized_tap(net, format, &mut conv);
    warn_missing_reference(net, format, &mut conv);
    warn_dropped_frequency(net, format, &mut conv);
    warn_dropped_locations(net, format, &mut conv);
    warn_psse_downgrade(net, format, &mut conv);
    warn_dropped_transformer_charging(net, format, &mut conv);
    Ok(conv)
}

/// Convert a [`BalancedNetwork`] with write-time cost policies. The old [`write_as`]
/// behavior is preserved when `options` is default.
pub fn write_as_with_options(
    net: &BalancedNetwork,
    format: TargetFormat,
    options: &WriteOptions,
) -> Result<Conversion> {
    if options.is_default() {
        return write_as(net, format);
    }

    let mut working = net.clone();
    let report =
        working.apply_gen_cost_policy(&options.gen_cost_patches, options.missing_gen_cost)?;
    let mut policy_warnings = Vec::new();
    if report.patched > 0 {
        policy_warnings.push(format!(
            "generator cost patch applied to {} generator(s)",
            report.patched
        ));
    }
    if report.synthesized > 0 {
        policy_warnings.push(match options.missing_gen_cost {
            MissingGenCostPolicy::Fill {
                c2,
                c1,
                c0,
                startup,
                shutdown,
            } => format!(
                "generator cost synthesized for {} generator(s): model 2, ncost 3, \
                 coeffs [{c2}, {c1}, {c0}], startup {startup}, shutdown {shutdown}",
                report.synthesized
            ),
            _ => unreachable!("only Fill synthesizes costs"),
        });
    }
    if report.patched > 0 || report.synthesized > 0 {
        working.source = None;
    }

    let mut conv = write_as(&working, format)?;
    policy_warnings.append(&mut conv.warnings);
    conv.warnings = policy_warnings;
    Ok(conv)
}

/// Allocate a circuit id for an element keyed by `key` — a bus for loads/shunts,
/// or a `(from, to)` pair for branches: reuse the source-supplied `preferred` id
/// when it is still free on this key, else the lowest free positional id. Keeps
/// parallel devices distinct so the `(key, id)` uniqueness rule the PSS/E and
/// PSLF records require holds even when the source supplies colliding ids.
pub(super) fn allocate_circuit_id<K: Ord + Clone>(
    preferred: Option<&str>,
    key: K,
    used: &mut std::collections::BTreeMap<K, std::collections::BTreeSet<String>>,
) -> String {
    let taken = used.entry(key).or_default();
    if let Some(id) = preferred {
        if taken.insert(id.to_owned()) {
            return id.to_owned();
        }
    }
    let mut n = 1u32;
    loop {
        let candidate = n.to_string();
        if taken.insert(candidate.clone()) {
            return candidate;
        }
        n += 1;
    }
}

/// Warn when a PSS/E source is re-serialized at an older revision than its own.
/// `parse_file` maps every `.raw` to revision 33 and the `psse`/`raw` aliases
/// resolve to 33, so writing a v34/v35 source through the default target skips
/// the echo path (revisions differ) and re-emits the v33 layout, dropping the
/// modern records (12 named ratings, load DG/LOADTYPE columns, the system-wide
/// block) and any unmodeled section the echo would have preserved. Name the
/// downgrade instead of performing it silently.
fn warn_psse_downgrade(net: &BalancedNetwork, format: TargetFormat, conv: &mut Conversion) {
    if let (TargetFormat::Psse { rev }, SourceFormat::Psse, Some(src)) =
        (format, net.source_format, net.source.as_ref())
    {
        let src_rev = psse::header_rev(src);
        if src_rev > rev {
            conv.warnings.push(format!(
                "PSS/E source is revision {src_rev} but the write target is revision {rev}; \
                 the older layout drops fields the source carried (write to psse{src_rev} to keep them)"
            ));
        }
    }
}

/// Warn when a non-default system frequency writes to a format with no frequency
/// field. PSS/E (`BASFRQ`) and pandapower (`f_hz`) carry it; MATPOWER,
/// PowerModels, egret, and PowerWorld have nowhere to put it, so a 50 Hz case
/// would silently read back as the 60 Hz default. Report the loss instead.
fn warn_dropped_frequency(net: &BalancedNetwork, format: TargetFormat, conv: &mut Conversion) {
    let carries_frequency = matches!(
        format,
        TargetFormat::Psse { .. } | TargetFormat::PandapowerJson
    );
    if carries_frequency {
        return;
    }
    if (net.base_frequency - crate::network::DEFAULT_BASE_FREQUENCY).abs() > 1e-9 {
        conv.warnings.push(format!(
            "system base frequency {} Hz dropped: {} has no frequency field (reads back as {} Hz)",
            net.base_frequency,
            format.label(),
            crate::network::DEFAULT_BASE_FREQUENCY
        ));
    }
}

/// Warn when the case carries bus locations and the target has no geometry
/// concept. PowerWorld aux (`Latitude:1`/`Longitude:1`) and pandapower
/// (`geo`) carry them, and the PyPSA folder writer (`x`/`y`) has its own
/// path; MATPOWER, PSS/E, PowerModels, egret, PSLF, and Surge have nowhere to
/// put them, matching the `base_frequency` behavior. `powerio geo extract`
/// writes the sidecar as the escape hatch.
fn warn_dropped_locations(net: &BalancedNetwork, format: TargetFormat, conv: &mut Conversion) {
    let carries_locations = matches!(
        format,
        TargetFormat::PowerWorld | TargetFormat::PandapowerJson
    );
    if carries_locations {
        return;
    }
    let n = net.buses.iter().filter(|b| b.location.is_some()).count();
    let routed = net.branches.iter().filter(|b| b.route.is_some()).count();
    if n > 0 || routed > 0 {
        conv.warnings.push(format!(
            "{n} bus location(s) and {routed} branch route(s) dropped: {} has no \
             coordinate field (write a .geo.json sidecar to keep them)",
            format.label()
        ));
    }
}

/// Warn when a transformer carries line charging and the target's
/// transformer record has no susceptance column to hold it. The PSLF `.epc`
/// transformer record is the one such target; PSS/E writes representable
/// magnetizing admittance and the MATPOWER shaped writers keep the legacy total
/// projection on the branch row, so neither drops it.
fn warn_dropped_transformer_charging(
    net: &BalancedNetwork,
    format: TargetFormat,
    conv: &mut Conversion,
) {
    if !matches!(format, TargetFormat::Pslf) {
        return;
    }
    let n = net
        .branches
        .iter()
        .filter(|b| b.is_transformer() && b.total_charging_b() != 0.0)
        .count();
    if n > 0 {
        conv.warnings.push(format!(
            "{n} transformer(s) carry line charging that the PSLF .epc transformer \
             record cannot represent; the charging was dropped"
        ));
    }
}

pub(super) fn branch_rating_set_drop_warning(
    target: &str,
    branch_index: usize,
    branch: &Branch,
    rating: &BranchRatingSet,
) -> String {
    format!(
        "branch {} ({} to {}) rating set {}={} MVA dropped: {} has no field for branch rating sets beyond rate_a, rate_b, and rate_c",
        branch_index + 1,
        branch.from,
        branch.to,
        rating.name,
        rating.rate_mva,
        target
    )
}

pub(super) fn warn_extra_branch_rating_sets(
    target: &str,
    net: &BalancedNetwork,
    warnings: &mut Vec<String>,
) {
    for (branch_index, branch) in net.branches.iter().enumerate() {
        for rating in &branch.rating_sets {
            warnings.push(branch_rating_set_drop_warning(
                target,
                branch_index,
                branch,
                rating,
            ));
        }
    }
}

/// Convert a case file to `to`, optionally forcing the source format with
/// `from`.
///
/// This is the canonical file-conversion helper shared by the bindings. It
/// parses `path` once, writes the resulting [`BalancedNetwork`] to `to`, and returns the
/// converted text plus any fidelity warnings, read side first. An echo (writing
/// back to the source format) returns the retained text with no warnings.
///
/// # Errors
/// As [`parse_file`].
pub fn convert_file(
    path: impl AsRef<std::path::Path>,
    to: TargetFormat,
    from: Option<&str>,
) -> Result<Conversion> {
    let parsed = parse_file(path, from)?;
    let mut conv = write_as(&parsed.network, to)?;
    if !is_echo(&parsed.network, to) {
        conv.warnings.splice(0..0, parsed.warnings);
    }
    Ok(conv)
}

/// Convert a case file with write-time cost policies.
pub fn convert_file_with_options(
    path: impl AsRef<std::path::Path>,
    to: TargetFormat,
    from: Option<&str>,
    options: &WriteOptions,
) -> Result<Conversion> {
    let parsed = parse_file(path, from)?;
    let mut conv = write_as_with_options(&parsed.network, to, options)?;
    if !is_echo(&parsed.network, to) || !options.is_default() {
        conv.warnings.splice(0..0, parsed.warnings);
    }
    Ok(conv)
}

/// Convert in-memory case `text` of the named `format` (see
/// [`target_format_from_name`]) to `to`.
///
/// Parses `text` once and writes the resulting [`BalancedNetwork`] to `to` without a
/// temporary file. Warnings are ordered read side first, as in
/// [`convert_file`].
///
/// # Errors
/// As [`parse_str`].
pub fn convert_str(text: &str, to: TargetFormat, format: &str) -> Result<Conversion> {
    let parsed = parse_str(text, format)?;
    let mut conv = write_as(&parsed.network, to)?;
    if !is_echo(&parsed.network, to) {
        conv.warnings.splice(0..0, parsed.warnings);
    }
    Ok(conv)
}

/// Convert in-memory case text with write-time cost policies.
pub fn convert_str_with_options(
    text: &str,
    to: TargetFormat,
    format: &str,
    options: &WriteOptions,
) -> Result<Conversion> {
    let parsed = parse_str(text, format)?;
    let mut conv = write_as_with_options(&parsed.network, to, options)?;
    if !is_echo(&parsed.network, to) || !options.is_default() {
        conv.warnings.splice(0..0, parsed.warnings);
    }
    Ok(conv)
}

/// Write `net` into `out_dir` as the named directory format. This function
/// dispatches directory format names for the bindings. PyPSA CSV
/// (`pypsa-csv`/`pypsa`) is the one such
/// format today; a text format name is rejected by name, pointing at
/// [`write_as`]. Returns the write's fidelity warnings.
///
/// # Errors
/// [`Error::UnknownFormat`] for a non-directory format name; the writer's own
/// [`Error`] otherwise.
pub fn write_dir(
    net: &BalancedNetwork,
    to: &str,
    out_dir: impl AsRef<std::path::Path>,
) -> Result<Vec<String>> {
    if is_pypsa_csv_name(to) {
        return write_pypsa_csv_folder(net, out_dir.as_ref()).map(|o| o.warnings);
    }
    Err(Error::UnknownFormat(format!(
        "{to} is not a directory format (directory targets: pypsa-csv/pypsa); \
         text formats serialize through write_as / to_format"
    )))
}

/// Warn when a network with no reference (slack) bus converts to a format
/// whose solvers require one. PowerWorld `.pwb` is the one source that
/// systematically lacks the designation (the binary does not store it), so
/// the silent case would be common; `to_normalized` synthesizes a slack at
/// the largest pmax in service generator bus for consumers that need one.
fn warn_missing_reference(net: &BalancedNetwork, format: TargetFormat, conv: &mut Conversion) {
    let needs_ref = matches!(
        format,
        TargetFormat::Matpower
            | TargetFormat::Psse { .. }
            | TargetFormat::PowerModelsJson
            | TargetFormat::PandapowerJson
            | TargetFormat::Pslf
            | TargetFormat::SurgeJson
    );
    if needs_ref {
        conv.warnings.extend(missing_reference_warning(net));
    }
}

/// The slackless-network warning itself, shared with the PyPSA folder writer
/// (which produces `PypsaCsvOutputs`, not a [`Conversion`], so it cannot go
/// through [`warn_missing_reference`]).
pub(super) fn missing_reference_warning(net: &BalancedNetwork) -> Option<String> {
    (!net.buses.iter().any(|b| b.kind == BusType::Ref)).then(|| {
        "no reference (slack) bus in the source network; power flow tools \
         reject such cases; to_normalized synthesizes a slack at the \
         largest pmax in service generator bus"
            .to_string()
    })
}

/// A normalized network has its tap canonicalized to `1.0` on every line (the
/// `0 → 1` rule), but [`Branch::is_transformer`](crate::network::Branch::is_transformer),
/// the test these writers use to split lines from transformers, keys off
/// `tap != 0`. So a normalized line is written into the transformer section/type.
/// The power flow is identical (a unity-ratio, zero-shift transformer equals a
/// line), but the label is not, so report the fidelity loss rather than relabel
/// it silently. MATPOWER has no separate transformer representation (just a `TAP`
/// column), so it is exempt.
// `tap == 1.0` / `shift == 0.0` are exact by construction: normalization sets a
// line's tap from `effective_tap()` (the literal `1.0`) and its shift from
// `0.0 * DEG_TO_RAD` (exactly `0.0`), so an epsilon compare would be wrong here.
#[allow(clippy::float_cmp)]
fn warn_normalized_tap(net: &BalancedNetwork, format: TargetFormat, conv: &mut Conversion) {
    if matches!(format, TargetFormat::Matpower) {
        return;
    }
    conv.warnings.extend(normalized_tap_warning(net));
}

/// The normalized-label warning itself, shared with the PyPSA folder writer.
// `tap == 1.0` / `shift == 0.0` are exact by construction (see
// `warn_normalized_tap`), so an epsilon compare would be wrong here.
#[allow(clippy::float_cmp)]
pub(super) fn normalized_tap_warning(net: &BalancedNetwork) -> Option<String> {
    if !net.is_normalized() {
        return None;
    }
    // After normalization a line (raw tap 0) and a unity-ratio transformer (raw
    // tap 1) both read as tap 1.0 / shift 0.0, so they cannot be told apart. Count
    // them together as the branches whose line/transformer label is now ambiguous.
    let ambiguous = net
        .branches
        .iter()
        .filter(|b| b.tap == 1.0 && b.shift == 0.0)
        .count();
    (ambiguous > 0).then(|| {
        format!(
            "normalized network: {ambiguous} branch(es) have unit tap and no phase \
             shift, so the line/transformer label is not preserved (the power flow \
             is identical)"
        )
    })
}

/// True when `value` is set and deviates from `reference`: the shared test for
/// "does this rating column carry information the target cannot" used by the
/// rate_b/rate_c drop warnings.
fn nonzero_differs(value: f64, reference: f64) -> bool {
    value.abs() > f64::EPSILON && (value - reference).abs() > f64::EPSILON
}

/// Set a bus's kind through the `bus_pos` index, leaving Isolated buses alone.
/// Shared by the readers that derive bus kinds from generator/slack tables.
pub(crate) fn set_bus_kind(
    buses: &mut [Bus],
    bus_pos: &HashMap<BusId, usize>,
    bus: BusId,
    kind: BusType,
) {
    if let Some(&idx) = bus_pos.get(&bus) {
        if buses[idx].kind != BusType::Isolated {
            buses[idx].kind = kind;
        }
    }
}

/// `base_kv` of a bus through the `bus_pos` index; 0.0 for an unknown bus.
pub(crate) fn bus_kv(buses: &[Bus], bus_pos: &HashMap<BusId, usize>, bus: BusId) -> f64 {
    bus_pos
        .get(&bus)
        .and_then(|&i| buses.get(i))
        .map_or(0.0, |b| b.base_kv)
}

/// Replace characters that would corrupt a quoted or delimited field with
/// `replacement`, so a free-form name can't shift or truncate the record it sits
/// in. `forbidden` lists the destination's quote, delimiter, and comment chars.
/// Returns the value borrowed unchanged when it holds none of them, so the common
/// clean-name path allocates nothing.
///
/// Each text writer calls this at its quoting seam and warns when the result
/// differs from the input (the substitution silently alters operator-facing
/// names): the PSS/E single-quoted bus name and the PowerWorld double-quoted bus
/// name both interpolate a `BalancedNetwork` name straight into a quoted field, where an
/// embedded quote (or, for PSS/E, the `/` inline-comment delimiter) would shift
/// every later column of the record.
/// A line terminator is always replaced, whatever `forbidden` holds: no text
/// record format can carry one inside a field, so an embedded `\n` does not
/// shift a column, it ends the record and makes everything after it parse as
/// a new one. A crafted name could otherwise forge whole records in the
/// written file.
pub(crate) fn sanitize_quoted<'a>(
    value: &'a str,
    forbidden: &[char],
    replacement: char,
) -> std::borrow::Cow<'a, str> {
    let breaks = |c: char| c == '\n' || c == '\r' || forbidden.contains(&c);
    if value.contains(breaks) {
        value
            .chars()
            .map(|c| if breaks(c) { replacement } else { c })
            .collect::<String>()
            .into()
    } else {
        std::borrow::Cow::Borrowed(value)
    }
}

/// Impedance base `v_kv² / base_mva`; 1.0 when either base is missing, so a
/// per-unit ↔ ohm conversion on it is the identity.
pub(crate) fn zbase(v_kv: f64, base_mva: f64) -> f64 {
    if v_kv > 0.0 && base_mva > 0.0 {
        v_kv * v_kv / base_mva
    } else {
        1.0
    }
}

/// Whether writing `net` to `target` echoes the retained source text: the
/// target is the source format and the source is still attached. An echo
/// reproduces the input byte for byte, so read fidelity warnings don't apply.
fn is_echo(net: &BalancedNetwork, target: TargetFormat) -> bool {
    let Some(src) = &net.source else { return false };
    if !same_format(target, net.source_format) {
        return false;
    }
    // A PSS/E source echoes only when the requested revision equals the source's
    // own; any other revision must go through write_psse_rev so the caller gets
    // the layout it asked for instead of the original bytes.
    if let TargetFormat::Psse { rev } = target {
        return psse::header_rev(src) == rev;
    }
    true
}

/// Whether a write target is the same format the network was read from.
fn same_format(target: TargetFormat, source: SourceFormat) -> bool {
    matches!(
        (target, source),
        (TargetFormat::Matpower, SourceFormat::Matpower)
            | (TargetFormat::PowerModelsJson, SourceFormat::PowerModelsJson)
            | (TargetFormat::EgretJson, SourceFormat::EgretJson)
            | (TargetFormat::Psse { .. }, SourceFormat::Psse)
            | (TargetFormat::PowerWorld, SourceFormat::PowerWorld)
            | (TargetFormat::PandapowerJson, SourceFormat::PandapowerJson)
            | (TargetFormat::Pslf, SourceFormat::Pslf)
            | (TargetFormat::Goc3Json, SourceFormat::Goc3Json)
            | (TargetFormat::SurgeJson, SourceFormat::SurgeJson)
            | (
                TargetFormat::DeepMindOpfDataJson,
                SourceFormat::DeepMindOpfDataJson,
            )
    )
}

/// JSON number for a finite `f64`; `Value::Null` for `NaN`/`±Inf`.
pub(crate) fn jnum(x: f64) -> Value {
    serde_json::Number::from_f64(x).map_or(Value::Null, Value::Number)
}

/// Serialize a built JSON tree into a [`Conversion`], appending one warning that
/// names every field where a non-finite `f64` was written as `null` (JSON has no
/// `±Inf`/`NaN`). Shared by the JSON writers.
pub(crate) fn finish(root: Map<String, Value>, mut warnings: Vec<String>) -> Conversion {
    let value = Value::Object(root);
    let mut nulls = BTreeSet::new();
    collect_null_keys(&value, &mut nulls);
    if !nulls.is_empty() {
        warnings.push(format!(
            "non-finite numeric values written as JSON null in field(s): {}",
            nulls.into_iter().collect::<Vec<_>>().join(", ")
        ));
    }
    let text = serde_json::to_string_pretty(&value).expect("a serde_json::Value always serializes");
    Conversion { text, warnings }
}

/// Collect the names of object keys whose value is `null`, anywhere in the tree.
fn collect_null_keys(value: &Value, out: &mut BTreeSet<String>) {
    match value {
        Value::Object(map) => {
            for (key, val) in map {
                if val.is_null() {
                    out.insert(key.clone());
                } else {
                    collect_null_keys(val, out);
                }
            }
        }
        Value::Array(items) => items.iter().for_each(|v| collect_null_keys(v, out)),
        _ => {}
    }
}

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

    #[test]
    fn sanitize_quoted_always_replaces_line_terminators() {
        // A terminator ends the record, so it is replaced whatever the
        // caller's delimiter set holds: a name carrying one could otherwise
        // forge whole records in a written .raw/.aux/.epc.
        for forbidden in [&[][..], &['\''][..], &['"'][..]] {
            let out = sanitize_quoted("A\n42, 'X'\r\nB", forbidden, ' ');
            assert!(
                !out.contains('\n') && !out.contains('\r'),
                "terminator survived with forbidden={forbidden:?}: {out:?}"
            );
        }
        // A clean value is still borrowed, not copied.
        assert!(matches!(
            sanitize_quoted("clean name", &['\''], ' '),
            std::borrow::Cow::Borrowed(_)
        ));
    }

    #[test]
    fn dss_extension_error_names_the_distribution_surface() {
        let err = parse_file("feeder.dss", None).unwrap_err();
        assert!(err.to_string().contains("distribution"), "got: {err}");
    }

    #[test]
    fn distribution_from_token_error_names_the_distribution_surface() {
        for token in ["dss", "pmd", "bmopf"] {
            let err = parse_str("anything", token).unwrap_err();
            assert!(
                err.to_string().contains("distribution surface"),
                "{token}: {err}"
            );
        }
        // A genuinely unknown token still echoes plainly.
        let err = parse_str("anything", "nonesuch").unwrap_err();
        assert!(err.to_string().contains("nonesuch"));
    }

    #[test]
    fn byte_order_mark_is_stripped_and_warned() {
        let case = "\u{feff}function mpc = t\n\
                    mpc.version = '2';\n\
                    mpc.baseMVA = 100;\n\
                    mpc.bus = [1 3 0 0 0 0 1 1.0 0 345 1 1.1 0.9;];\n\
                    mpc.gen = [];\n\
                    mpc.branch = [];\n";
        let parsed = parse_str(case, "matpower").unwrap();
        assert_eq!(parsed.network.buses.len(), 1);
        assert!(
            parsed
                .warnings
                .iter()
                .any(|w| w.contains("byte order mark")),
            "warnings: {:?}",
            parsed.warnings
        );
    }

    #[test]
    fn package_json_error_names_the_package_reader() {
        let err = sniff_json(r#"{"model_kind":"balanced","model":{}}"#).unwrap_err();
        assert!(err.to_string().contains(".pio.json"), "got: {err}");
    }

    #[test]
    fn source_format_strings_round_trip_to_a_target() {
        // The bindings expose `source_format` as its `{:?}` form, and
        // `to_format` routes that string back through `target_format_from_name`.
        // Every writable source format must resolve, including PowerModelsJson /
        // EgretJson, whose camel-case names need the `powermodelsjson` /
        // `egretjson` aliases (issue #75).
        for (sf, want) in [
            (SourceFormat::Matpower, TargetFormat::Matpower),
            (SourceFormat::PowerModelsJson, TargetFormat::PowerModelsJson),
            (SourceFormat::EgretJson, TargetFormat::EgretJson),
            (SourceFormat::Psse, TargetFormat::Psse { rev: 33 }),
            (SourceFormat::PowerWorld, TargetFormat::PowerWorld),
            (SourceFormat::PandapowerJson, TargetFormat::PandapowerJson),
            (SourceFormat::Pslf, TargetFormat::Pslf),
            (SourceFormat::Goc3Json, TargetFormat::Goc3Json),
            (SourceFormat::SurgeJson, TargetFormat::SurgeJson),
            (
                SourceFormat::DeepMindOpfDataJson,
                TargetFormat::DeepMindOpfDataJson,
            ),
        ] {
            let token = format!("{sf:?}");
            assert_eq!(
                target_format_from_name(&token),
                Some(want),
                "source_format {token:?} did not round-trip"
            );
        }
        // The derived/in-memory source formats have no writer target, and
        // neither does the read only .pwb binary.
        for sf in [
            SourceFormat::InMemory,
            SourceFormat::Normalized,
            SourceFormat::Gridfm,
            SourceFormat::PypsaCsv,
            SourceFormat::PowerWorldBinary,
        ] {
            assert_eq!(target_format_from_name(&format!("{sf:?}")), None);
        }
    }
}