1pub const VERSION: &str = env!("CARGO_PKG_VERSION");
90
91pub const IR_SCHEMA_NAME: &str = "pio-ir";
93
94pub const IR_VERSION: &str = "0.12.4";
108
109pub const IR_SCHEMA_ID: &str = "https://powerio.dev/schema/pio-ir/0.12.4/schema.json";
112
113pub use powerio_tx::dynamic::{
115 DynamicCase, DynamicRecord, DynamicStudy, DyrError, UnresolvedBusReference, parse_dyr,
116 parse_dyr_bytes,
117};
118pub 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};
146pub use powerio_tx::{contingency, dynamic, geo, network, version};
151
152pub use powerio_core::diagnostic_codes;
153pub use powerio_core::electrical;
156pub 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
167pub use powerio_core::Error;
170pub type Result<T> = std::result::Result<T, powerio_core::Error>;
171
172pub use powerio_tnd as tnd;
174pub 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};
201pub 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#[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#[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
326fn 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 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
408pub 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
422pub use powerio_prob::OperatingPoint;
425mod value;
426pub use value::{PioScenarioSet, PioTimeSeries, PioValue};
427
428#[derive(Clone, Debug, Default)]
431#[non_exhaustive]
432pub struct ParseOptions {
433 #[cfg(feature = "sincal")]
435 pub sincal_balanced: Option<powerio_tnd::formats::sincal::SincalBalancedReadOptions>,
436 #[cfg(feature = "sincal")]
439 pub sincal_multiconductor: Option<powerio_tnd::formats::sincal::SincalReadOptions>,
440 pub format: Option<powerio_core::FormatId>,
443 pub acquisition_root: Option<std::path::PathBuf>,
446 pub dss_limits: Option<powerio_dist::DssReadLimits>,
449}
450
451impl ParseOptions {
452 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 #[must_use]
463 pub fn format_id(mut self, format: powerio_core::FormatId) -> Self {
464 self.format = Some(format);
465 self
466 }
467
468 #[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 #[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
495pub 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
542pub 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 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 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 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
658fn 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
674fn 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
721fn 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
785fn 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
830fn parse_pypsa(
835 source: powerio_core::Source,
836) -> std::result::Result<powerio_core::PioModule<PioValue>, powerio_core::Error> {
837 if !source.is_directory() {
838 return format::parse(source).map(|module| module.map_value(PioValue::from));
840 }
841 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#[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 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
900fn 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
937enum RoutedFamily {
944 Balanced(Option<format::routing::JsonClass>),
945 Distribution(Option<format::routing::DistributionFormat>),
946 Ravens,
950 Pandapower,
953 Goc3,
954 OpfData,
955 PypsaDirectory,
956 Egret,
957 Geo,
961 Contingency(ContingencyFile),
963 #[cfg(feature = "gridfm")]
964 Gridfm,
965}
966
967fn 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#[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 if directory_has_goc3_data(source) {
1001 return Ok(RoutedFamily::Goc3);
1002 }
1003 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 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 "xml" if powerio_dist::source_looks_like_cim_dist(source) => Ok(
1048 RoutedFamily::Distribution(Some(format::routing::DistributionFormat::CimDist)),
1049 ),
1050 "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 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
1083fn 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
1098pub(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
1106pub(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
1115fn is_geo_token(token: &str) -> bool {
1117 is_geo_layer_token(token) || is_pwd_display_token(token)
1118}
1119
1120#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1124pub(crate) enum ContingencyFile {
1125 Con,
1127 Sub,
1129 Mon,
1131}
1132
1133impl ContingencyFile {
1134 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 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 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 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 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 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
1193pub(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
1205fn 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 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 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 JsonClass::Case(Detection::Known(_) | Detection::Ambiguous | Detection::Unknown) => {
1250 Ok(RoutedFamily::Balanced(Some(class)))
1251 }
1252 }
1253}
1254
1255fn 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 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 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 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 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 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 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 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 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 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 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 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;