Skip to main content

powerio/
lib.rs

1//! PowerIO: compiler infrastructure for power system data.
2//!
3//! The short `powerio` name is the entry facade over the component crates:
4//! `powerio-core` (sources, diagnostics, errors, modules), `powerio-tx`
5//! (the balanced transmission model and its format parsing and emission),
6//! `powerio-dist` (the multiconductor distribution model), and `powerio-prob`
7//! (operating points, problem instances, and solutions). The facade owns the
8//! dynamic value boundary: [`PioValue`], [`parse`], [`emit`], [`serialize`],
9//! and [`deserialize`].
10//!
11//! [`parse`] compiles one input into `PioModule<PioValue>`, routing to
12//! whichever built in family claims it. Inspect the value with ordinary enum
13//! matching and emit the module without discarding its input or diagnostics:
14//!
15//! ```no_run
16//! let module = powerio::parse("case9.m")?;
17//! match module.value() {
18//!     powerio::PioValue::BalancedNetwork(network) => {
19//!         println!("{} buses", network.buses().len());
20//!     }
21//!     other => println!("parsed {}", other.type_name()),
22//! }
23//! powerio::emit(&module, "matpower", "copy.m")?;
24//! # Ok::<(), Box<dyn std::error::Error>>(())
25//! ```
26//!
27//! A file name, a directory name, and content already in memory all reach the
28//! same operation, so it does not multiply into name-, text-, and
29//! byte-specific verbs:
30//!
31//! ```no_run
32//! let from_file = powerio::parse("case9.m")?;
33//! let from_directory = powerio::parse("pypsa_case/")?;
34//! let from_memory = powerio::parse(std::fs::read("case9.egret.json")?)?;
35//! # Ok::<(), Box<dyn std::error::Error>>(())
36//! ```
37//!
38//! Content in memory carries the name `<memory>`, which identifies no format,
39//! so a format detected from a file extension rather than from the document
40//! itself is either declared or named:
41//!
42//! ```no_run
43//! let declared = powerio::parse_with_options(
44//!     std::fs::read("case9.m")?,
45//!     &powerio::ParseOptions::default().format("matpower")?,
46//! )?;
47//! let named = powerio::parse(powerio::Source::from_memory(
48//!     "case9.m",
49//!     std::fs::read("case9.m")?,
50//! )?)?;
51//! # Ok::<(), Box<dyn std::error::Error>>(())
52//! ```
53//!
54//! A geographic layer is a value like any other: the canonical `.geo.json`,
55//! GeoJSON, aliased CSV or JSON records, headerless buscoords CSV, and a
56//! PowerWorld `.pwd` display all parse to [`PioValue::GeoLayer`], `emit`
57//! writes one as `geo-json`, and [`apply_geo_layer`] places one onto a case.
58//!
59//! The three files a PSS/E contingency analysis reads are values of the same
60//! kind. A `.con` parses to [`PioValue::ContingencySet`], a `.sub` to
61//! [`PioValue::SubsystemSet`], and a `.mon` to [`PioValue::MonitoredSet`];
62//! `emit` writes each back under its own token, and `ContingencySet::resolve`,
63//! `Subsystem::select_buses`, and `MonitoredSet::resolve` bind one to a
64//! network.
65//!
66//! [`parse_with_options`] selects the parser explicitly and widens the
67//! directory a format may refer to further files beneath. [`Source`] and
68//! [`Destination`] remain the advanced input and output: a source carrying
69//! named buffers for a multi-file case in memory, and a memory destination
70//! with its artifact root name.
71//!
72//! ```no_run
73//! let module = powerio::parse_with_options(
74//!     "case.data",
75//!     &powerio::ParseOptions::default().format("psse")?,
76//! )?;
77//! # Ok::<(), Box<dyn std::error::Error>>(())
78//! ```
79//!
80//! Native SINCAL projects are behind the `sincal` feature, on by default,
81//! which brings in SQLite through `powerio-tnd`. A build with
82//! `default-features = false` needs no C compiler: [`grid_formats`] then
83//! lists no SINCAL format, [`ParseOptions`] and [`EmitOptions`] carry no
84//! SINCAL field, and a SINCAL source or target fails with
85//! `REQUEST.SINCAL.FEATURE_DISABLED`. [`resolve_format`] still describes the
86//! SINCAL tokens, because format metadata is not a build probe.
87
88/// The facade version recorded on producers and stored modules.
89pub const VERSION: &str = env!("CARGO_PKG_VERSION");
90
91/// The `schema` discriminator of every PowerIO IR document.
92pub const IR_SCHEMA_NAME: &str = "pio-ir";
93
94/// The release whose PowerIO IR schema this build writes, stated as the
95/// `version` of every document it serializes.
96///
97/// Compatibility follows the release series as Cargo defines it: one minor
98/// release before 1.0 (0.12.x) and one major release from 1.0 on. A reader accepts a document from any release in its own series,
99/// including a later one, and refuses a structural type it does not
100/// implement, one type at a time. A change that existing readers cannot read
101/// starts a new series. This build also reads the integer version `2` that
102/// every 0.11 release wrote.
103///
104/// The constant names a release at or after the workspace version, and
105/// equals it in a published release. `producer.version` names the software
106/// that wrote a document, which need not be PowerIO.
107pub const IR_VERSION: &str = "0.12.4";
108
109/// The `$id` of the schema describing this build's document:
110/// `pio-ir/<IR_VERSION>/schema.json` beneath `https://powerio.dev/schema/`.
111pub const IR_SCHEMA_ID: &str = "https://powerio.dev/schema/pio-ir/0.12.4/schema.json";
112
113/// Loss-preserving PSS/E transient-stability parsing and explicit study pairing.
114pub use powerio_tx::dynamic::{
115    DynamicCase, DynamicRecord, DynamicStudy, DyrError, UnresolvedBusReference, parse_dyr,
116    parse_dyr_bytes,
117};
118/// Typed PSS/E DYR model views and model-aware generator linking.
119pub use powerio_tx::dynamic_models::{
120    DynamicModel, Esac1a, Exst1, Gast, Gencls, Hygov, Ieeest, LinkIssue, LinkedModel,
121    MachineDynamics, MachineLinking, ModelError, ModelRole, RoundRotor, SUPPORTED_MODELS,
122    SalientPole, Sexs, Tgov1, generator_source_impedance, link_machines, psse_machine_ids,
123    typed_model,
124};
125
126use powerio_tx::format;
127pub use powerio_tx::{
128    Area, AutomaticOrder, AutomaticSpec, AutomaticTarget, BalancedNetwork, Branch, BranchCharging,
129    BranchCurrentRatings, BranchRatingSet, BranchRef, BranchSolution, BranchSusceptanceFormula,
130    Bus, BusId, BusSubset, BusType, Canvas, Change, ChangeOp, ChangeUnit, ContingencyAction,
131    ContingencyCase, ContingencyParsed, ContingencyResolution, ContingencySet, CoordinateSpace,
132    CoordsKind, DEFAULT_BASE_FREQUENCY, Detection, ElementKey, Expanded, Extras, GenCaps, GenCost,
133    Generator, GeoApplyReport, GeoFeature, GeoGeometry, GeoLayer, GeoMeta, GeoParsed, GeoTarget,
134    Hvdc, Impedance, IndexCore, IndexedNetwork, InterfaceMember, JSON_CLASSES, JoinName, JsonClass,
135    Load, LoadVoltageModel, Location, MagnetizingConnection, MonitorScope, MonitorStatement,
136    MonitoredParsed, MonitoredResolution, MonitoredSet, PsseEquipmentIndex, PwdDisplay,
137    PwdSubstation, ResolvedCase, ResolvedComponent, ResolvedInterface, ResolvedVoltageScope,
138    RetainedStatement, Selector, SelectorGroup, SharedPsseEquipmentIndex, Shunt, ShuntBlock,
139    SkipRule, SolverParams, SourceFormat, Storage, Subsystem, SubsystemParsed, SubsystemSelector,
140    SubsystemSet, Switch, SwitchedShuntControl, SwitchedShuntMode, Transformer3W,
141    TransformerControl, TransformerControlMode, UnresolvedAction, UnresolvedMonitor,
142    UnresolvedMonitorReason, UnresolvedReason, Winding, apply_substation_points,
143    calc_series_admittance_of, classify_json_bytes, classify_json_text, repair_values,
144    to_geo_layer_from_pwd, to_lonlat_from_pwd_mercator,
145};
146/// Balanced network records and the public network and geographic submodules.
147/// Derived indexes, normalization data, solver tables, and component error
148/// types remain available from `powerio-tx` rather than being duplicated at
149/// the facade root.
150pub use powerio_tx::{contingency, dynamic, geo, network, version};
151
152pub use powerio_core::diagnostic_codes;
153/// The scalar electrical formulas both network families share: the per unit
154/// impedance base, the power factor relations and the voltage power law.
155pub use powerio_core::electrical;
156/// The common module records and containers. These explicit facade exports
157/// keep ordinary callers out of the component crate paths.
158pub use powerio_core::{
159    ArtifactPath, ComponentId, Destination, Diagnostic, DiagnosticCode, DiagnosticId,
160    DiagnosticInfo, DiagnosticSeverity, DiagnosticStage, Digest, DigestAlgorithm, EmitResult,
161    EmittedOutput, Fidelity, FormatId, HistoryEntry, HistoryId, HistoryKind, MemoryArtifact,
162    OutputLayout, PioModule, Producer, Scenario, ScenarioId, ScenarioSet, Source, SourceBuffer,
163    SourceDescriptor, SourceId, SourceMapEntry, SourceRelation, SourceSpan, SourceTree,
164    SourceTreeLimits, StagedEdit, TimePoint, TimeSeries,
165};
166
167/// The facade error covers source acquisition, routing, stored modules, and
168/// component failures converted at their boundary.
169pub use powerio_core::Error;
170pub type Result<T> = std::result::Result<T, powerio_core::Error>;
171
172/// Integrated transmission/distribution models, transformations, and adapters.
173pub use powerio_tnd as tnd;
174/// Distribution types and facade format dispatch.
175/// Types whose names overlap with balanced network types stay grouped here.
176pub mod dist {
177    pub use powerio_dist::*;
178    #[cfg(feature = "sincal")]
179    pub use powerio_tnd::formats::sincal::{SincalReadOptions, parse_sincal};
180    pub fn parse(
181        source: powerio_core::Source,
182    ) -> std::result::Result<powerio_core::PioModule<MulticonductorNetwork>, powerio_core::Error>
183    {
184        #[cfg(feature = "sincal")]
185        if source.format().is_some_and(|f| {
186            crate::format::routing::parse_distribution_format(f.as_str())
187                == Some(crate::format::routing::DistributionFormat::SincalMulticonductor)
188        }) {
189            return parse_sincal(source, &SincalReadOptions::default());
190        }
191        powerio_dist::parse(source)
192    }
193}
194pub use powerio_dist::{
195    BmopfEmitOptions, ConductorMatrix, DistComponentLocation, DistGeoMeta, DistGeographicPoint,
196    DistGraphEdgeKind, DistLocationTarget, MulticonductorNetwork, NeutralKronOptions,
197    NeutralKronReport,
198};
199
200pub use powerio_prob::solution::{SocwrOpfDuals, SocwrOpfSolution, SocwrOpfValues};
201/// The calculation types used by solver consumers. The full problem
202/// vocabulary lives in [`powerio_prob`]; these types sit at the facade root so
203/// a consumer does not need a second PowerIO dependency to name its boundary.
204pub use powerio_prob::{
205    AcBusSpecification, AcOpfInstance, AcOpfSolution, AcOtsInstance, AcOtsOptions, AcOtsSolution,
206    AcPfInstance, AcPfSolution, AcScucInstance, AcScucSolution, ActivePower, ActivePowerUnit,
207    ApparentPower, ApparentPowerUnit, BalancedCalculationInstance, BranchCurrentLimit,
208    BranchSelection, BranchSwitchingCost, CalculationUpdate, CurrentLimitPolicy,
209    DcBusSpecification, DcOpfInstance, DcOpfSolution, DcPfInstance, DcPfSolution, IslandingPolicy,
210    LinDist3FlowApplicability, LinDist3FlowApplicabilityStatus, LinDist3FlowBuildOptions,
211    LinDist3FlowLimitCheck, LinDist3FlowLimitKind, LinDist3FlowNode, LinDist3FlowOpfInstance,
212    LinDist3FlowOpfSolution, LinDist3FlowOpfValues, LinDist3FlowPfInstance, LinDist3FlowPfSolution,
213    LinDist3FlowPreparationAction, LinDist3FlowPreparationActionKind,
214    LinDist3FlowPreparationReport, LinDist3FlowReferencePolicy, LinDist3FlowReferenceProvenance,
215    LinDist3FlowReferenceState, LinDist3FlowTopology, LinDist3FlowUnsupported, LoadAllocation,
216    McAcOpfInstance, McAcOpfSolution, McAcPfInstance, McAcPfSolution, NetworkUpdate,
217    OperatingPointUpdate, ReactivePower, ReactivePowerUnit, Termination,
218    ThreeWindingTransformerTerminalActivePower, ThreeWindingTransformerTerminalPower, UpdateChange,
219    UpdateReport, UpdatedField, apply_bus_load_active_power, apply_updates,
220    evaluate_lindist3flow_pf_limits,
221};
222
223/// Matrix and graph data, re-exported from `powerio-matrix` under the
224/// `matrix` feature. Matrix construction is never a parse result, so the
225/// facade's automatic parsing and [`PioValue`] do not change with this
226/// feature.
227#[cfg(feature = "matrix")]
228pub use powerio_matrix as matrix;
229
230#[cfg(feature = "gridfm")]
231#[doc(hidden)]
232#[path = "gridfm.rs"]
233pub mod __gridfm;
234pub mod codes;
235pub mod collection;
236pub use collection::{Collection, CollectionLimits, CollectionSelection};
237mod formats;
238pub use formats::{FormatInfo, GridFormatInfo, NetworkFamily, grid_formats, resolve_format};
239#[cfg(feature = "gridfm")]
240mod collect;
241pub mod dist_geo;
242#[cfg(feature = "gridfm")]
243pub use __gridfm::codes as gridfm_codes;
244mod stored;
245mod write;
246pub use write::{EmitOptions, emit, emit_with_options};
247#[cfg(feature = "sincal")]
248mod sincal_write;
249#[cfg(feature = "sincal")]
250pub use sincal_write::{ArchiveOptions, SincalContainer, SincalExperimentalOptions};
251mod ir;
252#[cfg(feature = "schema")]
253pub use ir::generate_ir_schema;
254pub use ir::{deserialize, serialize, serialize_diagnostics};
255pub mod transform;
256pub use transform::{
257    ac_ots_instance_from_base, ac_ots_solution, apply_geo_layer, fix_ac_ots_topology,
258    materialize_ac_ots_solution, network_with_operating_point, neutral_kron,
259    neutral_kron_with_options, to_ac_opf_instance, to_ac_ots_instance,
260    to_ac_ots_instance_with_options, to_ac_pf_instance, to_balanced, to_balanced_report,
261    to_dc_opf_instance, to_dc_pf_instance, to_lindist3flow_opf_instance,
262    to_lindist3flow_opf_instance_with_options, to_lindist3flow_pf_instance,
263    to_lindist3flow_pf_instance_with_options, to_mc_ac_opf_instance, to_mc_ac_pf_instance,
264};
265
266#[derive(Clone, Copy, Debug, Eq, PartialEq)]
267enum Goc3DataFileKind {
268    Problem,
269    Solution,
270}
271
272#[derive(Default)]
273struct Goc3DataFiles {
274    problem: Option<SourceBuffer>,
275    solution: Option<SourceBuffer>,
276}
277
278impl Goc3DataFiles {
279    fn insert(&mut self, kind: Goc3DataFileKind, buffer: SourceBuffer) -> Result<()> {
280        let slot = match kind {
281            Goc3DataFileKind::Problem => &mut self.problem,
282            Goc3DataFileKind::Solution => &mut self.solution,
283        };
284        if let Some(existing) = slot {
285            return Err(Error::new(
286                &powerio_tx::diagnostics::codes::READ_GOC3_AMBIGUOUS_DOCUMENTS,
287                format!(
288                    "GO Challenge 3 source contains both `{}` and `{}` as {} data files",
289                    existing.name(),
290                    buffer.name(),
291                    match kind {
292                        Goc3DataFileKind::Problem => "problem",
293                        Goc3DataFileKind::Solution => "solution",
294                    }
295                ),
296            ));
297        }
298        *slot = Some(buffer);
299        Ok(())
300    }
301}
302
303/// The GO Challenge 3 root keys, read without building a document tree.
304#[derive(Default, serde::Deserialize)]
305struct Goc3Roots {
306    #[serde(default)]
307    network: Option<serde::de::IgnoredAny>,
308    #[serde(default)]
309    time_series_input: Option<serde::de::IgnoredAny>,
310    #[serde(default)]
311    reliability: Option<serde::de::IgnoredAny>,
312    #[serde(default)]
313    time_series_output: Option<serde::de::IgnoredAny>,
314}
315
316impl Goc3Roots {
317    fn is_problem(&self) -> bool {
318        self.network.is_some() && self.time_series_input.is_some() && self.reliability.is_some()
319    }
320
321    fn is_solution(&self) -> bool {
322        self.time_series_output.is_some()
323    }
324}
325
326/// The GO Challenge 3 root keys of a JSON document, or `None` for a well
327/// formed document whose root is not an object.
328fn goc3_roots(buffer: &SourceBuffer) -> Result<Option<Goc3Roots>> {
329    match serde_json::from_slice::<Goc3Roots>(buffer.content_bytes()) {
330        Ok(roots) => Ok(Some(roots)),
331        Err(error) if error.classify() == serde_json::error::Category::Data => Ok(None),
332        Err(error) => Err(Error::new(
333            &powerio_tx::diagnostics::codes::PARSE_GOC3_MALFORMED,
334            format!("{}: {error}", buffer.name()),
335        )),
336    }
337}
338
339fn goc3_file_kind(buffer: &SourceBuffer) -> Result<Option<Goc3DataFileKind>> {
340    let Some(roots) = goc3_roots(buffer)? else {
341        return Ok(None);
342    };
343    match (roots.is_problem(), roots.is_solution()) {
344        (true, false) => Ok(Some(Goc3DataFileKind::Problem)),
345        (false, true) => Ok(Some(Goc3DataFileKind::Solution)),
346        (false, false) => Ok(None),
347        (true, true) => Err(Error::new(
348            &powerio_tx::diagnostics::codes::READ_GOC3_AMBIGUOUS_DOCUMENTS,
349            format!(
350                "{} contains both the GO Challenge 3 problem and solution roots",
351                buffer.name()
352            ),
353        )),
354    }
355}
356
357fn goc3_data_files(source: &Source) -> Result<Goc3DataFiles> {
358    let mut buffers = if source.is_directory() {
359        let mut buffers = Vec::new();
360        for name in source.entry_names()? {
361            if std::path::Path::new(name.as_str())
362                .extension()
363                .and_then(|extension| extension.to_str())
364                .is_some_and(|extension| extension.eq_ignore_ascii_case("json"))
365            {
366                buffers.push(source.buffer(&name)?);
367            }
368        }
369        buffers
370    } else {
371        let mut buffers = vec![source.primary_buffer()?];
372        // `entry_names` succeeds here only for an in-memory source with named
373        // buffers. A file source never searches sibling files.
374        if let Ok(names) = source.entry_names() {
375            for name in names {
376                buffers.push(source.root_buffer(name.as_str())?);
377            }
378        }
379        buffers
380    };
381    buffers.sort_by(|left, right| left.name().cmp(right.name()));
382
383    let mut files = Goc3DataFiles::default();
384    for buffer in buffers {
385        if let Some(kind) = goc3_file_kind(&buffer)? {
386            files.insert(kind, buffer)?;
387        }
388    }
389    Ok(files)
390}
391
392fn directory_has_goc3_data(source: &Source) -> bool {
393    source.entry_names().is_ok_and(|names| {
394        names.into_iter().any(|name| {
395            std::path::Path::new(name.as_str())
396                .extension()
397                .and_then(|extension| extension.to_str())
398                .is_some_and(|extension| extension.eq_ignore_ascii_case("json"))
399                && source.buffer(&name).is_ok_and(|buffer| {
400                    goc3_roots(&buffer).is_ok_and(|roots| {
401                        roots.is_some_and(|roots| roots.is_solution() || roots.is_problem())
402                    })
403                })
404        })
405    })
406}
407
408/// Transform the `Substation` table in PowerWorld AUX text into a geographic
409/// layer without exposing the component parser's borrowed `AuxFile` type.
410///
411/// Rows without a finite number, latitude, and longitude are skipped. A valid
412/// AUX document with no usable substation coordinates returns an empty layer.
413///
414/// # Errors
415/// The AUX section syntax is malformed.
416pub fn to_geo_layer_from_aux_text(text: &str) -> Result<GeoLayer> {
417    let aux = powerio_tx::format::powerworld::aux_sections(text)
418        .map_err(|error| Error::new(error.code(), error.to_string()).with_cause(error))?;
419    Ok(powerio_tx::to_geo_layer_from_aux_substations(&aux))
420}
421
422/// A possibly partial assignment of instantaneous operating quantities over
423/// one network's fixed equipment identities.
424pub use powerio_prob::OperatingPoint;
425mod value;
426pub use value::{PioScenarioSet, PioTimeSeries, PioValue};
427
428/// Optional configuration for [`parse_with_options`]. Every field defaults to
429/// inference, so [`ParseOptions::default`] is what [`parse`] uses.
430#[derive(Clone, Debug, Default)]
431#[non_exhaustive]
432pub struct ParseOptions {
433    /// Explicit native selections for the sincal-balanced format only.
434    #[cfg(feature = "sincal")]
435    pub sincal_balanced: Option<powerio_tnd::formats::sincal::SincalBalancedReadOptions>,
436    /// Explicit native-variant, daily-snapshot and Access-acquisition options.
437    /// Valid only with the sincal-multiconductor format selection.
438    #[cfg(feature = "sincal")]
439    pub sincal_multiconductor: Option<powerio_tnd::formats::sincal::SincalReadOptions>,
440    /// The parser selected by its stable format token rather than inferred
441    /// from the input's name and content.
442    pub format: Option<powerio_core::FormatId>,
443    /// The directory beneath which a format may refer to further files,
444    /// widening the default of the input file's own directory.
445    pub acquisition_root: Option<std::path::PathBuf>,
446    /// The limits an OpenDSS read works under, for a case too large for the
447    /// defaults. `None` keeps the defaults. No effect on any other format.
448    pub dss_limits: Option<powerio_dist::DssReadLimits>,
449}
450
451impl ParseOptions {
452    /// Select the parser by its stable format token.
453    ///
454    /// # Errors
455    /// `REQUEST.FORMAT.INVALID_ID` when the token is not a format identifier.
456    pub fn format(mut self, format: &str) -> std::result::Result<Self, powerio_core::Error> {
457        self.format = Some(powerio_core::FormatId::new(format)?);
458        Ok(self)
459    }
460
461    /// Select the parser by an already validated format identity.
462    #[must_use]
463    pub fn format_id(mut self, format: powerio_core::FormatId) -> Self {
464        self.format = Some(format);
465        self
466    }
467
468    /// Permit acquisition of files a format refers to beneath `root`.
469    #[must_use]
470    pub fn acquisition_root(mut self, root: impl Into<std::path::PathBuf>) -> Self {
471        self.acquisition_root = Some(root.into());
472        self
473    }
474
475    /// Set the limits an OpenDSS read works under. A case with several
476    /// hundred thousand lines and loads needs more than the defaults allow.
477    ///
478    /// ```no_run
479    /// use powerio::dist::DssReadLimits;
480    ///
481    /// let limits = DssReadLimits::default()
482    ///     .max_include_bytes(1 << 30)
483    ///     .max_properties(1 << 26);
484    /// let options = powerio::ParseOptions::default().dss_limits(limits);
485    /// let module = powerio::parse_with_options("region/Master.dss", &options)?;
486    /// # Ok::<(), powerio::Error>(())
487    /// ```
488    #[must_use]
489    pub fn dss_limits(mut self, limits: powerio_dist::DssReadLimits) -> Self {
490        self.dss_limits = Some(limits);
491        self
492    }
493}
494
495/// Parse one source into a compiled module of whichever built in family
496/// claims it. Balanced network formats produce
497/// [`PioValue::BalancedNetwork`]; network only distribution formats (OpenDSS
498/// `.dss`, PMD ENGINEERING JSON, BMOPF JSON, and distribution CIM) produce
499/// [`PioValue::MulticonductorNetwork`]. A source that defines a particular
500/// calculation produces that calculation's value. One DOE GO Challenge 3
501/// problem data file produces [`PioValue::AcScucInstance`]. One source that
502/// contains a problem data file and its matching solution data file produces
503/// [`PioValue::AcScucSolution`]; a solution data file alone is rejected because
504/// its row identities and time axis come from the problem. DeepMind OPFData
505/// JSON, which explicitly represents a solved AC OPF, produces
506/// [`PioValue::AcOpfSolution`]. The parser's findings are the module's
507/// diagnostics, and the module keeps the original input, so writing the same
508/// format again returns the original file content.
509///
510/// The input is a file or directory name, content already in memory, or a
511/// [`powerio_core::Source`] carrying named buffers or a widened acquisition
512/// root. [`parse_with_options`] selects the parser explicitly. Content in
513/// memory carries the name [`powerio_core::MEMORY_SOURCE_NAME`], which
514/// identifies no format, so a format detected from a file extension rather
515/// than from the document itself is either declared through the options or
516/// named through [`powerio_core::Source::from_memory`].
517///
518/// The family comes from the input's declared format when one was selected,
519/// and otherwise from the name and content: `.dss` and `.glm` extensions route
520/// to the distribution parser (`.glm` defaults to the PNNL GridLAB-D profile;
521/// declare `gridlabd-arras` for Arras). A `.json` document routes by its top level markers
522/// ([`format::routing::classify_json_text`]), a name with no recognized
523/// extension whose content opens a JSON document (an in-memory source has no
524/// extension) routes the same way, a `.xml` document, a name with no
525/// recognized extension, or a directory member that reads as distribution CIM
526/// ([`powerio_dist::source_looks_like_cim_dist`]) routes to the distribution parser,
527/// and every other name routes to the balanced network hub, whose own
528/// detection and refusals apply.
529///
530/// PowerIO IR is not a grid exchange format: [`parse`] refuses it and
531/// [`deserialize`] reads the current PowerIO IR document.
532///
533/// # Errors
534/// The routed family's failure, carrying its findings and the retained
535/// source.
536pub fn parse(
537    input: impl powerio_core::IntoSource,
538) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
539    parse_with_options(input, &ParseOptions::default())
540}
541
542/// Parse one input under `options`, which selects the parser explicitly or
543/// widens the directory a format may refer to further files beneath.
544/// [`parse`] is this operation with the default options.
545///
546/// # Errors
547/// The input cannot be acquired, the format cannot be selected, or the routed
548/// family fails, each carrying its own diagnostic code.
549pub fn parse_with_options(
550    input: impl powerio_core::IntoSource,
551    options: &ParseOptions,
552) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
553    let mut source = input.into_source()?;
554    if let Some(root) = &options.acquisition_root {
555        source = source.with_acquisition_root(root.clone())?;
556    }
557    if let Some(format) = &options.format {
558        source = source.with_format(format.clone());
559    }
560    #[cfg(not(feature = "sincal"))]
561    if names_sincal_source(&source) {
562        return Err(sincal_feature_disabled().with_source(source));
563    }
564    #[cfg(feature = "sincal")]
565    if options.sincal_balanced.is_some() && options.sincal_multiconductor.is_some() {
566        return Err(powerio_core::Error::new(
567            &codes::REQUEST_SINCAL_OPTIONS_PROFILE,
568            "SINCAL selections must name exactly one electrical family",
569        )
570        .with_source(source));
571    }
572    #[cfg(feature = "sincal")]
573    if let Some(sincal) = &options.sincal_balanced {
574        return powerio_tnd::formats::sincal::parse_sincal_balanced_with_options(source, sincal)
575            .map(|m| m.map_value(PioValue::from));
576    }
577    #[cfg(feature = "sincal")]
578    if let Some(sincal) = &options.sincal_multiconductor {
579        if source
580            .format()
581            .and_then(|f| format::routing::parse_distribution_format(f.as_str()))
582            != Some(format::routing::DistributionFormat::SincalMulticonductor)
583        {
584            return Err(powerio_core::Error::new(
585                &codes::REQUEST_SINCAL_OPTIONS_PROFILE,
586                "sincal_multiconductor options require explicit format sincal-multiconductor",
587            )
588            .with_source(source));
589        }
590        return powerio_tnd::formats::sincal::parse_sincal(source, sincal)
591            .map(|m| m.map_value(PioValue::from));
592    }
593    #[cfg(feature = "sincal")]
594    if names_sincal_source(&source) {
595        if source.format().is_some_and(|f| {
596            format::routing::parse_distribution_format(f.as_str())
597                == Some(format::routing::DistributionFormat::SincalMulticonductor)
598        }) {
599            return dist::parse(source).map(|m| m.map_value(PioValue::from));
600        }
601        return powerio_tnd::formats::sincal::parse_balanced(source)
602            .map(|m| m.map_value(PioValue::from));
603    }
604    match routed_family(&source)? {
605        RoutedFamily::Goc3 => parse_goc3(source),
606        RoutedFamily::OpfData => powerio_prob::__internal::__decode_opfdata_solution(source)
607            .map(|module| module.map_value(PioValue::from)),
608        RoutedFamily::Distribution(detected) => {
609            let source = match (source.format(), detected) {
610                (None, Some(format)) => {
611                    source.with_format(powerio_core::FormatId::new(format.name())?)
612                }
613                _ => source,
614            };
615            // A PMD multinetwork document holds one network per time step.
616            let pmd = source.format().is_some_and(|f| {
617                format::routing::parse_distribution_format(f.as_str())
618                    == Some(format::routing::DistributionFormat::PmdJson)
619            });
620            if pmd && powerio_dist::pmd::is_multinetwork(&source) {
621                return powerio_dist::pmd::parse_multinetwork(source)
622                    .map(|module| module.map_value(PioValue::from));
623            }
624            parse_distribution(source, options).map(|module| module.map_value(PioValue::from))
625        }
626        RoutedFamily::PypsaDirectory => parse_pypsa(source),
627        #[cfg(feature = "gridfm")]
628        RoutedFamily::Gridfm => parse_gridfm(source),
629        RoutedFamily::Egret => parse_egret(source),
630        RoutedFamily::Geo => parse_geo_layer(source),
631        RoutedFamily::Contingency(kind) => parse_contingency_file(source, kind),
632        RoutedFamily::Balanced(json_class) => format::parse_with_json_class(source, json_class)
633            .map(|module| module.map_value(PioValue::from)),
634        // The two MG-RAVENS profiles share one token and one top level
635        // shape; the adapter that spans both models reads the profile from
636        // the document and hands the source to the crate that owns it.
637        RoutedFamily::Ravens => match powerio_tnd::formats::ravens::parse(source)? {
638            powerio_tnd::formats::ravens::RavensModule::Balanced(module) => {
639                Ok(module.map_value(PioValue::from))
640            }
641            powerio_tnd::formats::ravens::RavensModule::Multiconductor(module) => {
642                Ok(module.map_value(PioValue::from))
643            }
644        },
645        // A three-phase pandapower network reads as multiconductor and any
646        // other as balanced, by the tables the document fills.
647        RoutedFamily::Pandapower => match powerio_tnd::formats::pandapower::parse(source)? {
648            powerio_tnd::formats::pandapower::PandapowerModule::Balanced(module) => {
649                Ok(module.map_value(PioValue::from))
650            }
651            powerio_tnd::formats::pandapower::PandapowerModule::Multiconductor(module) => {
652                Ok(module.map_value(PioValue::from))
653            }
654        },
655    }
656}
657
658/// The distribution parse under the caller's OpenDSS limits, which apply to
659/// an OpenDSS source alone.
660fn parse_distribution(
661    source: powerio_core::Source,
662    options: &ParseOptions,
663) -> std::result::Result<powerio_core::PioModule<MulticonductorNetwork>, powerio_core::Error> {
664    let dss = source.format().is_some_and(|f| {
665        format::routing::parse_distribution_format(f.as_str())
666            == Some(format::routing::DistributionFormat::Dss)
667    });
668    match options.dss_limits {
669        Some(limits) if dss => powerio_dist::parse_with_dss_limits(source, limits),
670        _ => dist::parse(source),
671    }
672}
673
674/// Parse the official GO Challenge 3 problem file, or a problem and its
675/// matching solution file supplied by one directory or one memory source.
676/// File roles come from the required top level JSON fields, not filenames.
677/// A solution file alone is incomplete because it contains neither the
678/// component definitions nor the time axis.
679fn parse_goc3(
680    source: powerio_core::Source,
681) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
682    let source = source.with_format(powerio_core::FormatId::new("goc3-json")?);
683    let files = match goc3_data_files(&source) {
684        Ok(files) => files,
685        Err(error) => return Err(error.with_source(source)),
686    };
687    let Some(problem) = files.problem else {
688        let message = if files.solution.is_some() {
689            "a GO Challenge 3 solution file requires the matching problem file in the same source"
690        } else {
691            "the source contains neither a GO Challenge 3 problem file nor a solution file"
692        };
693        return Err(Error::new(
694            &powerio_tx::diagnostics::codes::READ_GOC3_PROBLEM_REQUIRED,
695            message,
696        )
697        .with_source(source));
698    };
699
700    let (instance, diagnostics) =
701        match powerio_prob::__internal::__parse_goc3_problem_buffer(&problem) {
702            Ok(parsed) => parsed,
703            Err(error) => return Err(error.with_source(source)),
704        };
705    let value = match files.solution {
706        Some(solution) => {
707            let solution = match powerio_prob::__internal::__parse_goc3_output_buffer(
708                std::sync::Arc::new(instance),
709                &solution,
710            ) {
711                Ok(solution) => solution,
712                Err(error) => return Err(error.with_source(source)),
713            };
714            PioValue::from(solution)
715        }
716        None => PioValue::from(instance),
717    };
718    powerio_core::PioModule::parsed(value, source, diagnostics)
719}
720
721/// Read one standalone geographic document into [`PioValue::GeoLayer`]. A
722/// PowerWorld `.pwd` display lifts into a diagram space layer with substation
723/// targets; every other supported document is already a layer. The reader's
724/// notes on records it could not use become the module's diagnostics.
725fn parse_geo_layer(
726    source: powerio_core::Source,
727) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
728    let name = source.name().to_owned();
729    let declared = source.format().map(|format| format.as_str().to_owned());
730    let is_display = declared.as_deref().is_some_and(is_pwd_display_token)
731        || std::path::Path::new(&name)
732            .extension()
733            .and_then(|extension| extension.to_str())
734            .is_some_and(|extension| extension.eq_ignore_ascii_case("pwd"));
735
736    let buffer = match source.primary_buffer() {
737        Ok(buffer) => buffer,
738        Err(error) => return Err(error.with_source(source)),
739    };
740    let (layer, diagnostics) = if is_display {
741        match powerio_tx::format::powerworld::__parse_pwd_layer(buffer.content_bytes()) {
742            Ok(parsed) => (parsed.layer, parsed.diagnostics),
743            Err(error) => {
744                return Err(Error::new(error.code(), error.to_string())
745                    .with_cause(error)
746                    .with_source(source));
747            }
748        }
749    } else {
750        let text = match std::str::from_utf8(buffer.content_bytes()) {
751            Ok(text) => text,
752            Err(cause) => {
753                return Err(Error::new(
754                    &powerio_tx::diagnostics::codes::READ_GEO_NOT_TEXT,
755                    format!("a geographic layer document is not valid UTF-8: {cause}"),
756                )
757                .with_source(source));
758            }
759        };
760        match powerio_tx::geo::GeoLayer::parse(
761            text,
762            std::path::Path::new(&name)
763                .file_name()
764                .and_then(|name| name.to_str()),
765        ) {
766            Ok(parsed) => (parsed.layer, parsed.diagnostics),
767            Err(error) => {
768                return Err(Error::new(error.code(), error.to_string())
769                    .with_cause(error)
770                    .with_source(source));
771            }
772        }
773    };
774    let source = match declared {
775        Some(_) => source,
776        None => source.with_format(powerio_core::FormatId::new(if is_display {
777            "powerworld-pwd"
778        } else {
779            "geo-json"
780        })?),
781    };
782    powerio_core::PioModule::parsed(PioValue::from(layer), source, diagnostics)
783}
784
785/// Read one PSS/E contingency analysis file into its own value. The reader
786/// keeps a statement outside its grammar as the original line and reports it;
787/// those notes become the module's diagnostics, so nothing the file states is
788/// lost between the text and the value.
789fn parse_contingency_file(
790    source: powerio_core::Source,
791    kind: ContingencyFile,
792) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
793    let buffer = match source.primary_buffer() {
794        Ok(buffer) => buffer,
795        Err(error) => return Err(error.with_source(source)),
796    };
797    let text = match std::str::from_utf8(buffer.content_bytes()) {
798        Ok(text) => text,
799        Err(cause) => {
800            return Err(Error::new(
801                kind.not_text_code(),
802                format!("{} is not valid UTF-8: {cause}", kind.description()),
803            )
804            .with_source(source));
805        }
806    };
807    let parsed = match kind {
808        ContingencyFile::Con => powerio_tx::ContingencySet::parse(text)
809            .map(|parsed| (PioValue::from(parsed.set), parsed.diagnostics)),
810        ContingencyFile::Sub => powerio_tx::SubsystemSet::parse(text)
811            .map(|parsed| (PioValue::from(parsed.set), parsed.diagnostics)),
812        ContingencyFile::Mon => powerio_tx::MonitoredSet::parse(text)
813            .map(|parsed| (PioValue::from(parsed.set), parsed.diagnostics)),
814    };
815    let (value, diagnostics) = match parsed {
816        Ok(parsed) => parsed,
817        Err(error) => {
818            return Err(Error::new(error.code(), error.to_string())
819                .with_cause(error)
820                .with_source(source));
821        }
822    };
823    let source = match source.format() {
824        Some(_) => source,
825        None => source.with_format(powerio_core::FormatId::new(kind.token())?),
826    };
827    powerio_core::PioModule::parsed(value, source, diagnostics)
828}
829
830/// PyPSA CSV dispatch: one snapshot with no series siblings is the scalar
831/// profile through the balanced hub; a declared axis routes to the sequence
832/// parser, producing a network series or, when only operating quantities
833/// vary, an operating point series over one shared network.
834fn parse_pypsa(
835    source: powerio_core::Source,
836) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
837    if !source.is_directory() {
838        // A file claiming the PyPSA token gets the hub's own refusal wording.
839        return format::parse(source).map(|module| module.map_value(PioValue::from));
840    }
841    // Directory routing identified the source before the typed reader runs.
842    // Record that decision on an undeclared source so same format emission
843    // can distinguish a PyPSA directory from the GridFM directory family.
844    let source = match source.format() {
845        Some(_) => source,
846        None => source.with_format(powerio_core::FormatId::new("pypsa-csv")?),
847    };
848    let axis = match format::__pypsa_axis(&source) {
849        Ok(axis) => axis,
850        Err(error) => {
851            let core = powerio_core::Error::new(error.code(), error.to_string());
852            return Err(core.with_source(source));
853        }
854    };
855    match axis {
856        format::PypsaAxis::SingleSnapshot => {
857            format::parse(source).map(|module| module.map_value(PioValue::from))
858        }
859        format::PypsaAxis::Series => {
860            match powerio_prob::__internal::__decode_pypsa_sequence(&source) {
861                Ok((sequence, diagnostics)) => {
862                    let value = match sequence {
863                        powerio_prob::__internal::PypsaSequence::Networks(series) => {
864                            PioValue::from(series)
865                        }
866                        powerio_prob::__internal::PypsaSequence::OperatingPoints(points) => {
867                            PioValue::from(points)
868                        }
869                    };
870                    powerio_core::PioModule::parsed(value, source, diagnostics)
871                }
872                Err(error) => Err(error.with_source(source)),
873            }
874        }
875    }
876}
877
878/// gridfm dispatch: every scenario of the Parquet dataset as one scenario
879/// set over shared element identities.
880#[cfg(feature = "gridfm")]
881fn parse_gridfm(
882    source: powerio_core::Source,
883) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
884    if !source.is_directory() {
885        // A file claiming the gridfm token gets the hub's own refusal wording.
886        return format::parse(source).map(|module| module.map_value(PioValue::from));
887    }
888    let source = match source.format() {
889        Some(_) => source,
890        None => source.with_format(powerio_core::FormatId::new("gridfm")?),
891    };
892    match __gridfm::parse_gridfm_source(&source) {
893        Ok((set, diagnostics)) => {
894            powerio_core::PioModule::parsed(PioValue::from(set), source, diagnostics)
895        }
896        Err(error) => Err(error.with_source(source)),
897    }
898}
899
900/// Egret dispatch: a document declaring `system.time_keys` routes to the
901/// sequence parser and produces a balanced network time series; a scalar
902/// document routes through the balanced hub.
903fn parse_egret(
904    source: powerio_core::Source,
905) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
906    let declares_series = {
907        let buffer = source.primary_buffer()?;
908        std::str::from_utf8(buffer.content_bytes()).is_ok_and(format::__egret_declares_time_series)
909    };
910    if !declares_series {
911        return format::parse(source).map(|module| module.map_value(PioValue::from));
912    }
913    let parsed = {
914        let buffer = source.primary_buffer()?;
915        let stem = std::path::Path::new(source.name())
916            .file_stem()
917            .and_then(|stem| stem.to_str())
918            .map(str::to_owned);
919        match std::str::from_utf8(buffer.content_bytes()) {
920            Ok(text) => format::__parse_egret_time_series(text, stem.as_deref())
921                .map_err(|error| powerio_core::Error::new(error.code(), error.to_string())),
922            Err(error) => {
923                let cause = powerio_tx::Error::FormatRead {
924                    format: "case text",
925                    message: format!("not valid UTF-8: {error}"),
926                };
927                Err(powerio_core::Error::new(cause.code(), cause.to_string()))
928            }
929        }
930    };
931    match parsed {
932        Ok(series) => powerio_core::PioModule::parsed(PioValue::from(series), source, Vec::new()),
933        Err(error) => Err(error.with_source(source)),
934    }
935}
936
937/// The family a source routes to. The balanced hub is the default: it owns
938/// the guidance for unknown names and refused shapes. `Balanced` carries the
939/// JSON classification when routing here was itself the result of one (so
940/// the balanced hub does not classify the same text a second time); `None`
941/// when the source routed here by extension, by a declared token, or by a
942/// directory shape, none of which run a JSON classification at all.
943enum RoutedFamily {
944    Balanced(Option<format::routing::JsonClass>),
945    Distribution(Option<format::routing::DistributionFormat>),
946    /// An MG-RAVENS document, by token or by content. The profile, and so
947    /// the family, follows the document; `powerio_tnd::formats::ravens`
948    /// decides.
949    Ravens,
950    /// A pandapower document, by token or by content. Its tables select the
951    /// family. `powerio_tnd::formats::pandapower` decides.
952    Pandapower,
953    Goc3,
954    OpfData,
955    PypsaDirectory,
956    Egret,
957    /// A standalone geographic document: the canonical `.geo.json`, GeoJSON,
958    /// aliased CSV or JSON records, headerless buscoords CSV, or a PowerWorld
959    /// `.pwd` display lifted into a diagram space layer.
960    Geo,
961    /// One of the three text files a PSS/E contingency analysis reads.
962    Contingency(ContingencyFile),
963    #[cfg(feature = "gridfm")]
964    Gridfm,
965}
966
967/// Whether `source` names a SINCAL project: a declared format that resolves
968/// to one of the SINCAL tokens, or an undeclared `.sinx` archive. Content
969/// never selects the family, so SQLite bytes under another name route as
970/// before.
971fn names_sincal_source(source: &powerio_core::Source) -> bool {
972    match source.format() {
973        Some(format) => write::is_sincal_format(format.as_str()),
974        None => std::path::Path::new(source.name())
975            .extension()
976            .is_some_and(|extension| extension.eq_ignore_ascii_case("sinx")),
977    }
978}
979
980/// The refusal a SINCAL source or target meets in a build without the
981/// `sincal` feature. One code for parse and emit, shared with `powerio-tx`.
982#[cfg(not(feature = "sincal"))]
983pub(crate) fn sincal_feature_disabled() -> powerio_core::Error {
984    powerio_core::Error::new(
985        &powerio_tx::diagnostics::codes::REQUEST_SINCAL_FEATURE_DISABLED,
986        "this build of powerio compiled without the `sincal` feature, so it cannot read or write SINCAL projects; enable the `sincal` feature (on by default) to include the SQLite backed readers",
987    )
988}
989
990fn routed_family(
991    source: &powerio_core::Source,
992) -> std::result::Result<RoutedFamily, powerio_core::Error> {
993    if let Some(declared) = source.format() {
994        return Ok(family_of_token(declared.as_str()));
995    }
996    if source.is_directory() {
997        // GOC3 pairs are identified by their official JSON roots rather than
998        // filenames. The format parser performs the exact cardinality and
999        // schema checks after routing.
1000        if directory_has_goc3_data(source) {
1001            return Ok(RoutedFamily::Goc3);
1002        }
1003        // PyPSA is a CSV folder containing network.csv. GridFM is a Parquet
1004        // dataset with bus_data.parquet at one of its documented locations.
1005        // Anything else falls to the balanced hub's refusal.
1006        let marker = powerio_core::ArtifactPath::new("network.csv")
1007            .expect("static name is a valid artifact path");
1008        if source.buffer(&marker).is_ok() {
1009            return Ok(RoutedFamily::PypsaDirectory);
1010        }
1011        #[cfg(feature = "gridfm")]
1012        if let Ok(entries) = source.entry_names()
1013            && entries.iter().any(|entry| {
1014                entry.as_str().ends_with("bus_data.parquet")
1015                    && matches!(entry.as_str().matches('/').count(), 0..=2)
1016            })
1017        {
1018            return Ok(RoutedFamily::Gridfm);
1019        }
1020        // Distribution CIM documents carry per phase or customer classes and
1021        // no CGMES model header; a CGMES profile directory has neither.
1022        if powerio_dist::source_looks_like_cim_dist(source) {
1023            return Ok(RoutedFamily::Distribution(Some(
1024                format::routing::DistributionFormat::CimDist,
1025            )));
1026        }
1027        return Ok(RoutedFamily::Balanced(None));
1028    }
1029    let extension = std::path::Path::new(source.name())
1030        .extension()
1031        .and_then(|extension| extension.to_str())
1032        .unwrap_or_default()
1033        .to_ascii_lowercase();
1034    if has_geo_layer_extension(source.name()) {
1035        return Ok(RoutedFamily::Geo);
1036    }
1037    match extension.as_str() {
1038        "glm" => Ok(RoutedFamily::Distribution(Some(
1039            format::routing::DistributionFormat::Gridlabd,
1040        ))),
1041        "dss" => Ok(RoutedFamily::Distribution(Some(
1042            format::routing::DistributionFormat::Dss,
1043        ))),
1044        "json" => json_family(source),
1045        // CIM RDF/XML is CGMES unless the document reads as distribution
1046        // CIM; XIIDM never declares the RDF and CIM namespaces.
1047        "xml" if powerio_dist::source_looks_like_cim_dist(source) => Ok(
1048            RoutedFamily::Distribution(Some(format::routing::DistributionFormat::CimDist)),
1049        ),
1050        // Extensions with dedicated non-JSON readers keep them; anything
1051        // else (a nameless in-memory source above all) can still carry a
1052        // JSON document, so content that opens one routes by classification,
1053        // mirroring the balanced hub's own sniff.
1054        "pwd" | "geojson" => Ok(RoutedFamily::Geo),
1055        "con" => Ok(RoutedFamily::Contingency(ContingencyFile::Con)),
1056        "sub" => Ok(RoutedFamily::Contingency(ContingencyFile::Sub)),
1057        "mon" => Ok(RoutedFamily::Contingency(ContingencyFile::Mon)),
1058        "m" | "raw" | "aux" | "epc" | "pwb" | "uct" => Ok(RoutedFamily::Balanced(None)),
1059        _ => {
1060            let jsonish = source.primary_buffer().is_ok_and(|buffer| {
1061                std::str::from_utf8(buffer.content_bytes()).is_ok_and(|text| {
1062                    // Strip a UTF-8 BOM the way the JSON classifier does, so
1063                    // a BOM-prefixed nameless document routes the same as
1064                    // the identical content saved with a .json name.
1065                    text.trim_start_matches('\u{feff}')
1066                        .trim_start()
1067                        .starts_with(['{', '['])
1068                })
1069            });
1070            if jsonish {
1071                json_family(source)
1072            } else if powerio_dist::source_looks_like_cim_dist(source) {
1073                Ok(RoutedFamily::Distribution(Some(
1074                    format::routing::DistributionFormat::CimDist,
1075                )))
1076            } else {
1077                Ok(RoutedFamily::Balanced(None))
1078            }
1079        }
1080    }
1081}
1082
1083/// Whether `name` carries the compound `geo.json` extension: the whole name,
1084/// or the name after a separator, so `layer.geo.json`, `layer_geo.json`, and
1085/// `layer-geo.json` all state a layer. A stem that merely ends in the same
1086/// letters (`apogeo.json`) does not, and keeps its JSON classification, which
1087/// matters because JSON content classification has no layer verdict and would
1088/// refuse the file as an unrecognized case.
1089fn has_geo_layer_extension(name: &str) -> bool {
1090    let name = name.to_ascii_lowercase();
1091    let extension = powerio_tx::geo::GEO_LAYER_EXTENSION;
1092    name == extension
1093        || name
1094            .strip_suffix(extension)
1095            .is_some_and(|stem| stem.ends_with(['.', '_', '-', '/', '\\']))
1096}
1097
1098/// Whether `token` names the standalone geographic layer document.
1099pub(crate) fn is_geo_layer_token(token: &str) -> bool {
1100    matches!(
1101        token.to_ascii_lowercase().replace(['-', '_'], "").as_str(),
1102        "geojson" | "geo" | "geolayer"
1103    )
1104}
1105
1106/// Whether `token` names a PowerWorld display file, which reads as a diagram
1107/// space layer.
1108pub(crate) fn is_pwd_display_token(token: &str) -> bool {
1109    matches!(
1110        token.to_ascii_lowercase().replace(['-', '_'], "").as_str(),
1111        "pwd" | "powerworldpwd" | "powerworlddisplay"
1112    )
1113}
1114
1115/// Whether `token` names a document that reads into [`PioValue::GeoLayer`].
1116fn is_geo_token(token: &str) -> bool {
1117    is_geo_layer_token(token) || is_pwd_display_token(token)
1118}
1119
1120/// Which of the three PSS/E contingency analysis files a source holds. Each
1121/// is its own format token, its own value type, and its own writer; the three
1122/// never cross.
1123#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1124pub(crate) enum ContingencyFile {
1125    /// The contingency description file, `.con`.
1126    Con,
1127    /// The subsystem description file, `.sub`.
1128    Sub,
1129    /// The monitored element file, `.mon`.
1130    Mon,
1131}
1132
1133impl ContingencyFile {
1134    /// The canonical format token.
1135    pub(crate) const fn token(self) -> &'static str {
1136        match self {
1137            Self::Con => "psse-con",
1138            Self::Sub => "psse-sub",
1139            Self::Mon => "psse-mon",
1140        }
1141    }
1142
1143    /// The conventional filename suffix, without a leading dot.
1144    pub(crate) const fn extension(self) -> &'static str {
1145        match self {
1146            Self::Con => "con",
1147            Self::Sub => "sub",
1148            Self::Mon => "mon",
1149        }
1150    }
1151
1152    /// The name of the one artifact an emission writes. A path destination
1153    /// uses the caller's own path; a memory destination uses its root name.
1154    /// `con` alone is a reserved device name on Windows, so every name here
1155    /// carries a stem.
1156    pub(crate) const fn artifact_name(self) -> &'static str {
1157        match self {
1158            Self::Con => "contingency.con",
1159            Self::Sub => "subsystem.sub",
1160            Self::Mon => "monitored.mon",
1161        }
1162    }
1163
1164    /// The structural type name the file reads into.
1165    pub(crate) const fn type_name(self) -> &'static str {
1166        match self {
1167            Self::Con => "powerio.ContingencySet",
1168            Self::Sub => "powerio.SubsystemSet",
1169            Self::Mon => "powerio.MonitoredSet",
1170        }
1171    }
1172
1173    /// The code for input that is not UTF-8 text.
1174    const fn not_text_code(self) -> &'static powerio_core::DiagnosticInfo {
1175        use powerio_tx::diagnostics::codes;
1176        match self {
1177            Self::Con => &codes::READ_CON_NOT_TEXT,
1178            Self::Sub => &codes::READ_SUB_NOT_TEXT,
1179            Self::Mon => &codes::READ_MON_NOT_TEXT,
1180        }
1181    }
1182
1183    /// How the refusal names the file, in prose.
1184    const fn description(self) -> &'static str {
1185        match self {
1186            Self::Con => "a PSS/E contingency description file",
1187            Self::Sub => "a PSS/E subsystem description file",
1188            Self::Mon => "a PSS/E monitored element file",
1189        }
1190    }
1191}
1192
1193/// The PSS/E contingency analysis file a format token names, or `None` for
1194/// every other token. Case, hyphens, and underscores do not distinguish
1195/// spellings, so `psse-con`, `psse_con`, `PSSECon`, and `con` are one name.
1196pub(crate) fn contingency_file_of_token(token: &str) -> Option<ContingencyFile> {
1197    match token.to_ascii_lowercase().replace(['-', '_'], "").as_str() {
1198        "con" | "pssecon" | "contingency" => Some(ContingencyFile::Con),
1199        "sub" | "pssesub" | "subsystem" => Some(ContingencyFile::Sub),
1200        "mon" | "pssemon" | "monitored" => Some(ContingencyFile::Mon),
1201        _ => None,
1202    }
1203}
1204
1205/// The family a JSON document's content markers select.
1206fn json_family(
1207    source: &powerio_core::Source,
1208) -> std::result::Result<RoutedFamily, powerio_core::Error> {
1209    use format::routing::{Detection, JsonClass, SourceFormat, TransmissionFormat};
1210
1211    let buffer = source.primary_buffer()?;
1212    // Family routing needs decoded text; a non-UTF-8 `.json` fails in
1213    // the balanced hub with its own wording. Classification never ran, so
1214    // the balanced hub gets no hint and classifies it itself.
1215    let Ok(text) = std::str::from_utf8(buffer.content_bytes()) else {
1216        return Ok(RoutedFamily::Balanced(None));
1217    };
1218    let class = format::routing::classify_json_text(text);
1219    match class {
1220        JsonClass::Case(Detection::Known(SourceFormat::Transmission(
1221            TransmissionFormat::Goc3Json,
1222        ))) => Ok(RoutedFamily::Goc3),
1223        JsonClass::Case(Detection::Known(SourceFormat::Transmission(
1224            TransmissionFormat::DeepMindOpfDataJson,
1225        ))) => Ok(RoutedFamily::OpfData),
1226        JsonClass::Case(Detection::Known(SourceFormat::Transmission(
1227            TransmissionFormat::EgretJson,
1228        ))) => Ok(RoutedFamily::Egret),
1229        JsonClass::Case(Detection::Known(SourceFormat::Transmission(
1230            TransmissionFormat::PandapowerJson,
1231        ))) => Ok(RoutedFamily::Pandapower),
1232        // Either MG-RAVENS classification: the header classifier sees only
1233        // the top level tables, and the adapter spanning both models reads
1234        // the profile from the whole document.
1235        JsonClass::Case(Detection::Known(
1236            SourceFormat::Transmission(TransmissionFormat::RavensJson)
1237            | SourceFormat::Distribution(format::routing::DistributionFormat::RavensJson),
1238        )) => Ok(RoutedFamily::Ravens),
1239        JsonClass::Case(Detection::Known(SourceFormat::Distribution(format))) => {
1240            Ok(RoutedFamily::Distribution(Some(format)))
1241        }
1242        JsonClass::Module => Err(powerio_core::Error::new(
1243            &codes::REQUEST_PARSE_POWERIO_IR,
1244            "PowerIO IR is not a grid exchange format; call deserialize(source)",
1245        )),
1246        // The balanced hub owns the refusal wording for unrecognized or
1247        // ambiguous documents. Pass the classification through so it does not
1248        // inspect the same bytes twice.
1249        JsonClass::Case(Detection::Known(_) | Detection::Ambiguous | Detection::Unknown) => {
1250            Ok(RoutedFamily::Balanced(Some(class)))
1251        }
1252    }
1253}
1254
1255/// The family a declared format token selects. Unknown tokens fall to the
1256/// balanced hub, which owns the refusal wording and the accepted name list.
1257fn family_of_token(token: &str) -> RoutedFamily {
1258    use format::TargetFormat;
1259
1260    if is_geo_token(token) {
1261        return RoutedFamily::Geo;
1262    }
1263    if let Some(kind) = contingency_file_of_token(token) {
1264        return RoutedFamily::Contingency(kind);
1265    }
1266
1267    if format::routing::parse_distribution_format(token)
1268        == Some(format::routing::DistributionFormat::RavensJson)
1269    {
1270        return RoutedFamily::Ravens;
1271    }
1272    if let Some(format) = format::routing::parse_distribution_format(token) {
1273        return RoutedFamily::Distribution(Some(format));
1274    }
1275    if format::is_pypsa_csv_name(token) {
1276        return RoutedFamily::PypsaDirectory;
1277    }
1278    #[cfg(feature = "gridfm")]
1279    if token.eq_ignore_ascii_case("gridfm") {
1280        return RoutedFamily::Gridfm;
1281    }
1282    match format::parse_target_format(token) {
1283        Some(TargetFormat::Goc3Json) => RoutedFamily::Goc3,
1284        Some(TargetFormat::DeepMindOpfDataJson) => RoutedFamily::OpfData,
1285        Some(TargetFormat::EgretJson) => RoutedFamily::Egret,
1286        Some(TargetFormat::PandapowerJson) => RoutedFamily::Pandapower,
1287        _ => RoutedFamily::Balanced(None),
1288    }
1289}
1290
1291#[cfg(test)]
1292mod tests {
1293    use super::*;
1294
1295    fn memory(name: &str, text: &str) -> powerio_core::Source {
1296        powerio_core::Source::from_memory(name, text.as_bytes().to_vec()).expect("memory source")
1297    }
1298
1299    fn parse(
1300        source: powerio_core::Source,
1301    ) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
1302        super::parse(source)
1303    }
1304
1305    fn options(format: Option<&str>) -> ParseOptions {
1306        match format {
1307            Some(format) => ParseOptions::default().format(format).unwrap(),
1308            None => ParseOptions::default(),
1309        }
1310    }
1311
1312    fn assert_value_type(module: &powerio_core::PioModule<PioValue>, expected: &str) {
1313        assert_eq!(module.value().type_name(), expected);
1314    }
1315
1316    #[test]
1317    fn dss_limits_in_the_options_reach_the_opendss_read() {
1318        // One byte of include budget admits the first include and refuses
1319        // the second; the defaults follow both.
1320        let source = || {
1321            memory(
1322                "Master.dss",
1323                "new circuit.c\nredirect a.dss\nredirect b.dss\n",
1324            )
1325            .with_named_buffer("a.dss", b"new load.a bus1=sourcebus.1 kv=1 kw=1\n".to_vec())
1326            .unwrap()
1327            .with_named_buffer("b.dss", b"new load.b bus1=sourcebus.1 kv=1 kw=1\n".to_vec())
1328            .unwrap()
1329        };
1330        let module = parse_with_options(source(), &ParseOptions::default()).expect("dss parses");
1331        assert_value_type(&module, "powerio.MulticonductorNetwork");
1332
1333        let limits = powerio_dist::DssReadLimits::default().max_include_bytes(1);
1334        let options = ParseOptions::default().dss_limits(limits);
1335        let error = parse_with_options(source(), &options).expect_err("the second include");
1336        assert!(
1337            error
1338                .diagnostics()
1339                .iter()
1340                .any(|d| d.code() == "READ.DSS.INCLUDE_BUDGET"),
1341            "{error}"
1342        );
1343
1344        // The limits belong to the OpenDSS read alone.
1345        let case = "function mpc = case\n\
1346                    mpc.version = '2';\n\
1347                    mpc.baseMVA = 100;\n\
1348                    mpc.bus = [1 3 0 0 0 0 1 1 0 230 1 1.1 0.9;];\n\
1349                    mpc.gen = [1 0 0 10 -10 1 100 1 10 0;];\n\
1350                    mpc.branch = [];\n";
1351        let module = parse_with_options(memory("case.m", case), &options).expect("matpower");
1352        assert_value_type(&module, "powerio.BalancedNetwork");
1353    }
1354
1355    #[test]
1356    fn a_matpower_source_parses_to_a_balanced_network() {
1357        let case = "function mpc = case\n\
1358                    mpc.version = '2';\n\
1359                    mpc.baseMVA = 100;\n\
1360                    mpc.bus = [1 3 0 0 0 0 1 1 0 230 1 1.1 0.9;];\n\
1361                    mpc.gen = [1 0 0 10 -10 1 100 1 10 0;];\n\
1362                    mpc.branch = [];\n";
1363        let module = parse(
1364            memory("case.m", case).with_format(powerio_core::FormatId::new("matpower").unwrap()),
1365        )
1366        .expect("matpower parses");
1367        assert_value_type(&module, "powerio.BalancedNetwork");
1368    }
1369
1370    #[test]
1371    fn memory_parse_retains_its_name_and_optional_format() {
1372        let case = "function mpc = inline\n\
1373                    mpc.version = '2';\n\
1374                    mpc.baseMVA = 100;\n\
1375                    mpc.bus = [1 3 0 0 0 0 1 1 0 230 1 1.1 0.9;];\n\
1376                    mpc.gen = [1 0 0 10 -10 1 100 1 10 0;];\n\
1377                    mpc.branch = [];\n";
1378
1379        let detected = super::parse(memory("inline-case.m", case)).expect("name detects MATPOWER");
1380        assert_eq!(detected.source().unwrap().name(), "inline-case.m");
1381        assert_eq!(
1382            detected.source().unwrap().format().map(FormatId::as_str),
1383            Some("matpower")
1384        );
1385
1386        let declared = super::parse_with_options(
1387            memory("consumer-input", case),
1388            &ParseOptions::default().format("matpower").unwrap(),
1389        )
1390        .expect("declared MATPOWER");
1391        let source = declared.source().expect("source retained");
1392        assert_eq!(source.name(), "consumer-input");
1393        assert_eq!(source.format().map(FormatId::as_str), Some("matpower"));
1394    }
1395
1396    #[test]
1397    fn universal_parse_reads_declared_iso_8859_1_xiidm_and_retains_exact_bytes() {
1398        let text = r#"<?xml version="1.0" encoding="ISO-8859-1"?>
1399<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_17" id="case" caseDate="2026-01-01T00:00:00Z" forecastDistance="0" sourceFormat="Réseau PowSybl" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
1400  <iidm:voltageLevel id="VL" nominalV="225" topologyKind="BUS_BREAKER">
1401    <iidm:busBreakerTopology><iidm:bus id="B" v="225" angle="0"/></iidm:busBreakerTopology>
1402    <iidm:generator id="G" energySource="OTHER" minP="0" maxP="100" voltageRegulatorOn="true" targetP="50" targetV="225" bus="B" connectableBus="B"><iidm:minMaxReactiveLimits minQ="-20" maxQ="20"/></iidm:generator>
1403  </iidm:voltageLevel>
1404</iidm:network>"#;
1405        let bytes: Vec<u8> = text
1406            .chars()
1407            .map(|value| u8::try_from(u32::from(value)).expect("fixture is ISO-8859-1"))
1408            .collect();
1409        assert!(std::str::from_utf8(&bytes).is_err());
1410
1411        for (name, format) in [
1412            ("case.xiidm", None),
1413            ("case.xml", None),
1414            ("memory", Some("xiidm")),
1415        ] {
1416            let source = Source::from_memory(name, bytes.clone()).unwrap();
1417            let module = super::parse_with_options(source, &options(format)).unwrap();
1418            let PioValue::BalancedNetwork(network) = &module.value() else {
1419                panic!(
1420                    "expected BalancedNetwork, got {}",
1421                    module.value().type_name()
1422                );
1423            };
1424            assert_eq!(
1425                network.case_metadata().source_model_format.as_deref(),
1426                Some("Réseau PowSybl")
1427            );
1428            let retained = module.source().unwrap();
1429            assert_eq!(retained.format().map(FormatId::as_str), Some("xiidm"));
1430            assert_eq!(retained.primary_buffer().unwrap().bytes(), bytes);
1431
1432            let emitted =
1433                emit(&module, "xiidm", Destination::memory("copy.xiidm").unwrap()).unwrap();
1434            assert_eq!(emitted.fidelity(), Fidelity::ExactSameFormat);
1435            let EmittedOutput::Memory { artifacts } = emitted.into_output() else {
1436                panic!("memory destination returned a path output");
1437            };
1438            assert_eq!(artifacts.len(), 1);
1439            assert_eq!(artifacts[0].bytes(), bytes);
1440        }
1441    }
1442
1443    #[test]
1444    fn a_dss_source_parses_to_a_multiconductor_network() {
1445        let module = parse(memory(
1446            "feeder.dss",
1447            "New Circuit.c basekv=12.47 bus1=src\n",
1448        ))
1449        .expect("dss parses");
1450        let PioValue::MulticonductorNetwork(network) = &module.value() else {
1451            panic!(
1452                "expected multiconductor network, got {}",
1453                module.value().type_name()
1454            );
1455        };
1456        assert_eq!(network.name().as_deref(), Some("c"));
1457    }
1458
1459    #[test]
1460    fn distribution_cim_routes_by_content_and_echoes_its_bytes() {
1461        let fixture = concat!(
1462            env!("CARGO_MANIFEST_DIR"),
1463            "/../tests/data/dist/cim/micro_feeder.xml"
1464        );
1465        let bytes = std::fs::read(fixture).unwrap();
1466        // By the `.xml` extension, with no name at all, and from a
1467        // directory holding the document.
1468        let dir = tempfile::tempdir().unwrap();
1469        std::fs::write(dir.path().join("feeder.xml"), &bytes).unwrap();
1470        for source in [
1471            Source::from_memory("feeder.xml", bytes.clone()).unwrap(),
1472            Source::from_memory("<memory>", bytes.clone()).unwrap(),
1473            Source::open(dir.path()).unwrap(),
1474        ] {
1475            let module = parse(source).expect("distribution CIM parses");
1476            assert_value_type(&module, "powerio.MulticonductorNetwork");
1477            assert_eq!(
1478                module
1479                    .source()
1480                    .and_then(Source::format)
1481                    .map(FormatId::as_str),
1482                Some("cim-dist")
1483            );
1484        }
1485        let module = parse(Source::from_memory("feeder.xml", bytes.clone()).unwrap()).unwrap();
1486        let emitted = emit(
1487            &module,
1488            "cim-dist",
1489            Destination::memory("copy.xml").unwrap(),
1490        )
1491        .unwrap();
1492        assert_eq!(emitted.fidelity(), Fidelity::ExactSameFormat);
1493        let EmittedOutput::Memory { artifacts } = emitted.into_output() else {
1494            panic!("memory destination returned a path output");
1495        };
1496        assert_eq!(artifacts[0].bytes(), bytes);
1497
1498        // The network records where it came from, and the IR carries it.
1499        let PioValue::MulticonductorNetwork(network) = module.value() else {
1500            panic!("distribution CIM parses to a multiconductor network");
1501        };
1502        assert_eq!(
1503            *network.source_format(),
1504            Some(powerio_dist::DistSourceFormat::CimDist)
1505        );
1506        let stored = serialize(&module, Destination::memory("feeder.pio.json").unwrap()).unwrap();
1507        let EmittedOutput::Memory { artifacts } = stored.into_output() else {
1508            panic!("memory destination returned a path output");
1509        };
1510        let back = deserialize(
1511            Source::from_memory("feeder.pio.json", artifacts[0].bytes().to_vec()).unwrap(),
1512        )
1513        .unwrap();
1514        let PioValue::MulticonductorNetwork(network) = back.value() else {
1515            panic!("the IR keeps the multiconductor network");
1516        };
1517        assert_eq!(
1518            *network.source_format(),
1519            Some(powerio_dist::DistSourceFormat::CimDist)
1520        );
1521    }
1522
1523    #[test]
1524    fn a_declared_distribution_format_routes_without_an_extension() {
1525        let module = parse(
1526            memory("<memory>", "New Circuit.c basekv=12.47 bus1=src\n")
1527                .with_format(powerio_core::FormatId::new("dss").unwrap()),
1528        )
1529        .expect("declared dss parses");
1530        assert_value_type(&module, "powerio.MulticonductorNetwork");
1531    }
1532
1533    #[test]
1534    fn json_routes_by_top_level_markers() {
1535        // A PMD document carries `data_model`, which no balanced format does.
1536        let module = parse(memory(
1537            "feeder.json",
1538            r#"{"data_model": "ENGINEERING", "bus": {}}"#,
1539        ))
1540        .expect("pmd parses");
1541        assert_value_type(&module, "powerio.MulticonductorNetwork");
1542    }
1543
1544    #[test]
1545    fn a_bare_network_object_is_not_powerio_ir_or_a_case_format() {
1546        let error = parse(memory(
1547            "net.json",
1548            r#"{"name":"network","base_mva":100.0,"buses":[],"branches":[]}"#,
1549        ))
1550        .expect_err("an unmarked network object must not parse");
1551        assert!(error.to_string().contains("cannot infer JSON format"));
1552    }
1553
1554    #[test]
1555    fn the_error_path_retains_the_source() {
1556        let error = parse(memory("case.m", "not matpower at all")).expect_err("malformed");
1557        assert!(error.retained_source().is_some());
1558    }
1559
1560    fn fixture(path: &str) -> String {
1561        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
1562        std::fs::read_to_string(root.join(path)).unwrap()
1563    }
1564
1565    #[test]
1566    fn goc3_parses_to_an_scuc_instance() {
1567        // A calculation defining source produces its calculation's value,
1568        // never the bare network its data could also build.
1569        let text = fixture("../powerio-prob/tests/data/goc3_small.json");
1570        let module = parse(memory("goc3_small.json", &text)).expect("goc3 parses");
1571        assert_value_type(&module, "powerio.AcScucInstance");
1572        assert!(module.source().is_some());
1573        let PioValue::AcScucInstance(instance) = &module.value() else {
1574            unreachable!();
1575        };
1576        assert_eq!(instance.network().buses().len(), 2);
1577    }
1578
1579    #[test]
1580    fn goc3_problem_and_solution_parse_with_the_one_public_operation() {
1581        let problem = fixture("../tests/data/goc3/goc3_small.json");
1582        let solution = fixture("../tests/data/goc3/goc3_small_solution.json");
1583        let source = powerio_core::Source::from_memory("problem.json", problem.into_bytes())
1584            .unwrap()
1585            .with_named_buffer("solution.json", solution.into_bytes())
1586            .unwrap();
1587        let module = parse(source).expect("problem and solution parse together");
1588        let PioValue::AcScucSolution(solution) = &module.value() else {
1589            panic!(
1590                "expected AC SCUC solution, got {}",
1591                module.value().type_name()
1592            );
1593        };
1594        assert_eq!(solution.instance().network().buses().len(), 2);
1595        assert_eq!(
1596            solution.network_outputs().shunt_step,
1597            vec![vec![1], vec![2]]
1598        );
1599        assert_eq!(module.sources().len(), 2);
1600
1601        let emitted = emit(
1602            &module,
1603            "goc3-json",
1604            Destination::memory("solution.json").unwrap(),
1605        )
1606        .expect("solution emits as official GOC3 output");
1607        let EmittedOutput::Memory { artifacts } = emitted.output() else {
1608            unreachable!();
1609        };
1610        assert_eq!(artifacts.len(), 1);
1611        let document: serde_json::Value = serde_json::from_slice(artifacts[0].bytes()).unwrap();
1612        assert!(document.get("time_series_output").is_some());
1613        assert!(document.get("network").is_none());
1614    }
1615
1616    #[test]
1617    fn goc3_solution_alone_names_the_missing_problem() {
1618        let solution = fixture("../tests/data/goc3/goc3_small_solution.json");
1619        let error = parse(memory("solution.json", &solution))
1620            .expect_err("a solution without its problem is incomplete");
1621        assert!(error.to_string().contains("matching problem file"));
1622        assert!(error.retained_source().is_some());
1623    }
1624
1625    #[test]
1626    fn opfdata_parses_to_an_ac_opf_solution() {
1627        let text = fixture("../tests/data/opfdataset/example_0.json");
1628        let module = parse(memory("example_0.json", &text)).expect("opfdata parses");
1629        let PioValue::AcOpfSolution(solution) = &module.value() else {
1630            panic!(
1631                "expected AC OPF solution, got {}",
1632                module.value().type_name()
1633            );
1634        };
1635        assert_eq!(
1636            module
1637                .sources()
1638                .first()
1639                .and_then(|source| source.format())
1640                .map(powerio_core::FormatId::as_str),
1641            Some("opfdata-json")
1642        );
1643        assert_eq!(
1644            *solution.termination(),
1645            powerio_prob::Termination::NotReported
1646        );
1647        assert!((solution.objective() - 2_265.953_939_003_096).abs() < 1e-9);
1648
1649        let instance = solution.instance();
1650        assert_eq!(instance.network().buses().len(), 14);
1651        assert_eq!(instance.network().generators().len(), 5);
1652        let initial = instance.initial_point().expect("OPFData includes initials");
1653        let generator_id = instance.network().generators()[0]
1654            .uid
1655            .as_deref()
1656            .expect("parsed generators have stable identities");
1657        assert!((initial.generator_active_power(generator_id).unwrap() - 170.0).abs() < 1e-9);
1658        assert!((initial.generator_voltage_setpoint(generator_id).unwrap() - 1.0).abs() < 1e-12);
1659        assert!(solution.residuals().max_active_power_mismatch.unwrap() < 1.0);
1660        assert!(solution.residuals().max_reactive_power_mismatch.unwrap() < 1.0);
1661    }
1662
1663    #[test]
1664    fn malformed_opfdata_uses_the_universal_parse_error_path() {
1665        let error = parse(
1666            memory("broken.json", "{\"grid\": {}}")
1667                .with_format(powerio_core::FormatId::new("opfdata-json").unwrap()),
1668        )
1669        .expect_err("malformed OPFData");
1670        assert!(error.retained_source().is_some());
1671    }
1672
1673    const BMOPF_TINY: &str = r#"{
1674      "bus": {"a": {"terminal_names": ["1", "2", "3", "n"],
1675        "perfectly_grounded_terminals": ["n"]}},
1676      "voltage_source": {"s": {"bus": "a", "terminal_map": ["1", "2", "3"],
1677        "v_magnitude": [240.0, 240.0, 240.0], "v_angle": [0.0, -2.0944, 2.0944]}}
1678    }"#;
1679
1680    #[test]
1681    fn bmopf_parses_to_a_multiconductor_network() {
1682        // BMOPF shares the multiconductor network model. Callers construct a
1683        // power flow or optimal power flow instance explicitly afterward.
1684        let module = parse(memory("feeder.json", BMOPF_TINY)).expect("sniffed bmopf parses");
1685        assert_value_type(&module, "powerio.MulticonductorNetwork");
1686
1687        let module = parse(
1688            memory("<memory>", BMOPF_TINY)
1689                .with_format(powerio_core::FormatId::new("bmopf-json").unwrap()),
1690        )
1691        .expect("declared bmopf parses");
1692        assert_value_type(&module, "powerio.MulticonductorNetwork");
1693    }
1694
1695    #[test]
1696    fn nameless_json_text_routes_by_content() {
1697        // An in-memory source has no extension, so the family comes
1698        // from the document's own markers. Calculation and distribution
1699        // formats dispatch the same way they would from a `.json` file.
1700        let goc3 = fixture("../powerio-prob/tests/data/goc3_small.json");
1701        let module = parse(memory("<memory>", &goc3)).expect("nameless goc3 parses");
1702        assert_value_type(&module, "powerio.AcScucInstance");
1703
1704        let module = parse(memory("<memory>", BMOPF_TINY)).expect("nameless bmopf parses");
1705        assert_value_type(&module, "powerio.MulticonductorNetwork");
1706    }
1707
1708    #[test]
1709    fn a_declared_problem_format_that_fails_retains_the_source() {
1710        let error = parse(
1711            memory("broken.json", "{\"network\": {}}")
1712                .with_format(powerio_core::FormatId::new("goc3-json").unwrap()),
1713        )
1714        .expect_err("malformed goc3");
1715        assert!(error.retained_source().is_some());
1716    }
1717
1718    const PYPSA_STATIC: [(&str, &str); 4] = [
1719        ("network.csv", "name\nseq\n"),
1720        ("buses.csv", "name,v_nom\nB1,138.0\nB2,138.0\n"),
1721        ("loads.csv", "name,bus,p_set,q_set\nL1,B2,5.0,1.0\n"),
1722        (
1723            "generators.csv",
1724            "name,bus,control,p_nom,p_set\nG1,B1,Slack,100.0,12.0\n",
1725        ),
1726    ];
1727
1728    fn pypsa_folder(extra: &[(&str, &str)]) -> tempfile::TempDir {
1729        let temp = tempfile::tempdir().unwrap();
1730        for (name, content) in PYPSA_STATIC.iter().chain(extra) {
1731            std::fs::write(temp.path().join(name), content).unwrap();
1732        }
1733        temp
1734    }
1735
1736    #[test]
1737    fn a_pypsa_snapshot_parses_to_a_balanced_network() {
1738        let dir = pypsa_folder(&[("snapshots.csv", ",snapshot\n0,now\n")]);
1739        let module =
1740            parse(powerio_core::Source::open(dir.path()).unwrap()).expect("snapshot parses");
1741        assert_value_type(&module, "powerio.BalancedNetwork");
1742    }
1743
1744    #[test]
1745    fn a_pypsa_input_series_parses_to_a_network_time_series() {
1746        let dir = pypsa_folder(&[
1747            ("snapshots.csv", ",snapshot\n0,now\n1,later\n"),
1748            ("loads-p_set.csv", "snapshot,L1\nnow,10.0\nlater,20.0\n"),
1749        ]);
1750        let module = parse(powerio_core::Source::open(dir.path()).unwrap()).expect("series parses");
1751        assert_value_type(&module, "powerio.TimeSeries<powerio.BalancedNetwork>");
1752        assert!(module.source().is_some());
1753        let PioValue::TimeSeries(series) = &module.value() else {
1754            unreachable!();
1755        };
1756        assert_eq!(series.len(), 2);
1757        let PioValue::BalancedNetwork(later) = series.get(1).unwrap() else {
1758            unreachable!();
1759        };
1760        assert!((later.loads()[0].p - 20.0).abs() < 1e-12);
1761    }
1762
1763    #[test]
1764    fn a_pypsa_voltage_series_parses_to_operating_points() {
1765        let dir = pypsa_folder(&[
1766            ("snapshots.csv", ",snapshot\n0,now\n1,later\n"),
1767            (
1768                "buses-v_mag_pu.csv",
1769                "snapshot,B1,B2\nnow,1.0,0.99\nlater,1.0,0.97\n",
1770            ),
1771            (
1772                "buses-v_ang.csv",
1773                "snapshot,B1,B2\nnow,0.0,-0.017453292519943295\nlater,0.0,-0.03490658503988659\n",
1774            ),
1775        ]);
1776        let module = parse(powerio_core::Source::open(dir.path()).unwrap()).expect("series parses");
1777        assert_value_type(
1778            &module,
1779            "powerio.TimeSeries<powerio.OperatingPoint<powerio.BalancedNetwork>>",
1780        );
1781        let PioValue::TimeSeries(series) = &module.value() else {
1782            unreachable!();
1783        };
1784        let PioValue::BalancedOperatingPoint(later) = series.get(1).unwrap() else {
1785            unreachable!();
1786        };
1787        assert!((later.bus_voltage_magnitude(powerio_tx::BusId(2)).unwrap() - 0.97).abs() < 1e-12);
1788    }
1789
1790    #[test]
1791    fn a_pypsa_axis_with_no_series_stays_a_network_time_series() {
1792        // Several declared snapshots and nothing varying preserve the axis
1793        // as networks sharing every table; nothing here is an operating
1794        // point series.
1795        let dir = pypsa_folder(&[("snapshots.csv", ",snapshot\n0,now\n1,later\n")]);
1796        let module = parse(powerio_core::Source::open(dir.path()).unwrap()).expect("axis parses");
1797        assert_value_type(&module, "powerio.TimeSeries<powerio.BalancedNetwork>");
1798    }
1799
1800    const EGRET_SERIES: &str = r#"{
1801        "model_name": "uc2",
1802        "elements": {
1803            "bus": {"1": {"matpower_bustype": "ref", "base_kv": 138.0},
1804                    "2": {"matpower_bustype": "PQ", "base_kv": 138.0}},
1805            "load": {"load_1": {"bus": "2",
1806                "p_load": {"data_type": "time_series", "values": [10.0, 20.0]},
1807                "q_load": 3.0}},
1808            "generator": {"1": {"bus": "1", "pg": 12.0, "qg": 0.0,
1809                "p_min": 0.0, "p_max": 50.0, "q_min": -10.0, "q_max": 10.0}},
1810            "branch": {"1": {"from_bus": "1", "to_bus": "2",
1811                "resistance": 0.01, "reactance": 0.1, "charging_susceptance": 0.0,
1812                "rating_long_term": 100.0, "rating_short_term": 100.0,
1813                "rating_emergency": 100.0, "transformer_phase_shift": 0.0}}
1814        },
1815        "system": {"baseMVA": 100.0, "time_keys": ["t1", "t2"]}
1816    }"#;
1817
1818    #[test]
1819    fn egret_time_keys_parse_to_a_network_time_series() {
1820        let module = parse(
1821            memory("uc2.json", EGRET_SERIES)
1822                .with_format(powerio_core::FormatId::new("egret-json").unwrap()),
1823        )
1824        .expect("egret series parses");
1825        assert_value_type(&module, "powerio.TimeSeries<powerio.BalancedNetwork>");
1826        assert!(module.source().is_some());
1827
1828        // The sniffed route agrees with the declared one.
1829        let module = parse(memory("uc2.json", EGRET_SERIES)).expect("sniffed egret parses");
1830        assert_value_type(&module, "powerio.TimeSeries<powerio.BalancedNetwork>");
1831    }
1832
1833    #[cfg(feature = "gridfm")]
1834    #[test]
1835    fn powerio_ir_uses_deserialize_not_parse() {
1836        use powerio_tx::{Bus, BusId, BusType};
1837        let network = powerio_tx::BalancedNetwork::in_memory(
1838            "stored",
1839            100.0,
1840            vec![Bus::new(BusId(1), BusType::Ref, 230.0)],
1841            vec![],
1842        );
1843        let original = powerio_core::PioModule::new(PioValue::BalancedNetwork(network));
1844        let emitted = serialize(&original, Destination::memory("case.pio.json").unwrap())
1845            .expect("module serializes");
1846        let EmittedOutput::Memory { artifacts } = emitted.into_output() else {
1847            unreachable!();
1848        };
1849        let module = deserialize(
1850            Source::from_memory("case.pio.json", artifacts[0].bytes().to_vec()).unwrap(),
1851        )
1852        .expect("module deserializes");
1853        assert_value_type(&module, "powerio.BalancedNetwork");
1854        assert!(module.source().is_some());
1855    }
1856
1857    #[cfg(feature = "gridfm")]
1858    #[test]
1859    fn a_gridfm_dataset_parses_to_a_scenario_set() {
1860        // Write a two scenario dataset with the matrix writer, then parse the
1861        // directory through the universal parse.
1862        let case = concat!(env!("CARGO_MANIFEST_DIR"), "/../tests/data/case9.m");
1863        let base = powerio_tx::parse(powerio_core::Source::open(case).unwrap())
1864            .expect("case9 parses")
1865            .into_value();
1866        let mut varied = base.clone();
1867        varied.loads_mut()[0].p += 5.0;
1868        let out = tempfile::tempdir().unwrap();
1869        let snapshots = [
1870            powerio_matrix::GridfmSnapshot::new(&base, 0),
1871            powerio_matrix::GridfmSnapshot::new(&varied, 1),
1872        ];
1873        powerio_matrix::emit_gridfm_batch(
1874            &snapshots,
1875            out.path(),
1876            &powerio_matrix::GridfmOptions::default(),
1877        )
1878        .expect("dataset writes");
1879
1880        let module =
1881            parse(powerio_core::Source::open(out.path()).unwrap()).expect("dataset parses");
1882        assert_value_type(&module, "powerio.ScenarioSet<powerio.BalancedNetwork>");
1883        assert!(module.source().is_some());
1884        let PioValue::ScenarioSet(set) = &module.value() else {
1885            unreachable!();
1886        };
1887        assert_eq!(set.len(), 2);
1888        assert!(set.get("0").is_some());
1889        assert!(set.get("1").is_some());
1890    }
1891
1892    #[test]
1893    fn an_unrecognized_directory_is_refused_with_the_hub_wording() {
1894        let dir = tempfile::tempdir().unwrap();
1895        std::fs::write(dir.path().join("notes.txt"), "not a case").unwrap();
1896        let error =
1897            parse(powerio_core::Source::open(dir.path()).unwrap()).expect_err("refused directory");
1898        assert!(error.to_string().contains("directory"), "{error}");
1899    }
1900
1901    #[test]
1902    fn a_scalar_egret_document_stays_a_balanced_network() {
1903        let scalar = EGRET_SERIES
1904            .replace(r#", "time_keys": ["t1", "t2"]"#, "")
1905            .replace(
1906                r#"{"data_type": "time_series", "values": [10.0, 20.0]}"#,
1907                "10.0",
1908            );
1909        let module = parse(
1910            memory("uc2.json", &scalar)
1911                .with_format(powerio_core::FormatId::new("egret-json").unwrap()),
1912        )
1913        .expect("scalar egret parses");
1914        assert_value_type(&module, "powerio.BalancedNetwork");
1915    }
1916}
1917
1918#[cfg(feature = "schema")]
1919mod schema_units;