Skip to main content

powerio_dist/
lib.rs

1//! Multiconductor distribution network models and converters for OpenDSS
2//! `.dss`, PowerModelsDistribution ENGINEERING
3//! JSON ("PMD JSON"), the draft JSON schema of the IEEE PES Task Force on
4//! Benchmarking Multiconductor OPF ("BMOPF JSON",
5//! <https://github.com/distribution-system-opt/dsopt-schema>), and
6//! distribution CIM (CIM100 RDF/XML, see [`cim`]).
7//!
8//! The model uses wire coordinates: string bus IDs, ordered terminal names,
9//! explicit grounding, terminal maps on every element, SI units, and radians.
10//! The transmission model in `powerio` is positive sequence and remains a
11//! separate type.
12//!
13//! ```no_run
14//! let source = powerio_core::Source::open("feeder.dss")?;
15//! let module = powerio_dist::parse(source)?;
16//! for line in powerio_dist::diagnostics::render_diagnostics(module.diagnostics()) {
17//!     eprintln!("parse: {line}");
18//! }
19//! let emitted = powerio_dist::emit(
20//!     &module,
21//!     powerio_dist::DistTargetFormat::PmdJson,
22//!     powerio_core::Destination::memory("feeder.pmd.json")?,
23//! )?;
24//! for line in powerio_dist::diagnostics::render_diagnostics(emitted.diagnostics()) {
25//!     eprintln!("emit: {line}");
26//! }
27//! # Ok::<(), powerio_core::Error>(())
28//! ```
29//!
30//! SINCAL adapters are provided by `powerio_tnd::formats::sincal` and the
31//! `powerio` facade. This model crate is independent of SQLite and integration.
32//!
33//! # Fidelity rules
34//!
35//! Emitting to the retained source format returns the original bytes. Cross
36//! format emission uses the typed model and reports fields the target cannot
37//! represent through [`powerio_core::EmitResult::diagnostics`]. The DSS reader expands OpenDSS
38//! class defaults into explicit model values and records them in
39//! [`MulticonductorNetwork::defaulted`]. BMOPF output includes those values.
40//! The per fixture results live in `docs/conversion-matrix.md`.
41//!
42//! # Float formatting
43//!
44//! Canonical output formats every number as its shortest round trip
45//! representation: Rust's `Display` for `.dss`, serde_json (ryu) for both
46//! JSON formats. The readers parse with serde_json's `float_roundtrip`
47//! feature, so a parse of canonical output recovers the exact bit pattern
48//! and canonical emissions are idempotent. JSON cannot carry `Inf`/`NaN`: the
49//! PMD emitter uses `null` (PMD restores the value from the field name
50//! suffix), and the BMOPF emitter uses `0` with a warning, since the schema
51//! requires numbers. The byte exact echo tier is unaffected; it never
52//! reformats.
53
54pub mod bmopf;
55pub mod cim;
56mod collect;
57mod connection;
58pub mod convert;
59mod current_form;
60pub mod dense;
61pub mod diagnostics;
62pub mod dss;
63pub mod error;
64pub mod geo;
65pub mod glm;
66pub mod graph;
67pub mod kron;
68pub mod lindist3flow;
69pub mod model;
70pub mod overhead;
71pub mod pmd;
72mod portable_path;
73pub mod ravens;
74pub mod readiness;
75pub mod sequence;
76mod shielded_cable;
77/// The scalar electrical formulas both network families share, which live
78/// in powerio-core ([`electrical::calc_impedance_base`], the power factor
79/// relations and the voltage power law term).
80pub use powerio_core::electrical;
81pub mod terminal_index;
82#[cfg(test)]
83pub(crate) mod testkit;
84mod transform_audit;
85pub mod transformer;
86pub mod voltage_zones;
87
88pub use bmopf::{BMOPF_SCHEMA_ID, BmopfEmitOptions};
89pub use cim::{
90    CIM_DIST_HEAD_BYTES, looks_like_cim_dist, looks_like_cim_dist_header,
91    source_looks_like_cim_dist,
92};
93pub use connection::{
94    ConnectionChannel, calc_capacitor_susceptance, calc_coil_susceptance_matrix,
95    calc_connection_channels, calc_element_connection, calc_mapped_neutral_position,
96    calc_wye_neutral_position, lindist3flow_carries_connection, orient_delta_ring,
97};
98pub use convert::{
99    DistTargetFormat, EmitOptions, classify_distribution_json, emit, emit_with_options, parse,
100    parse_dist_target_format, parse_with_dss_limits,
101};
102pub use diagnostics::{Diagnostic, DiagnosticCode, DiagnosticSeverity, DiagnosticStage};
103pub use dss::{DssEmitOptions, DssLoadVoltageBounds, DssReadLimits};
104pub use error::{Error, Result};
105pub use geo::{
106    CoordinateSpace, DistCanvas, DistComponentLocation, DistCoordsKind, DistGeoMeta,
107    DistGeographicPoint, DistLocation, DistLocationTarget,
108};
109pub use graph::{
110    DistGraph, DistGraphAttachment, DistGraphAttachmentKind, DistGraphBus, DistGraphEdge,
111    DistGraphEdgeKind,
112};
113pub use kron::{
114    NeutralKronAction, NeutralKronBus, NeutralKronGrounding, NeutralKronOptions,
115    NeutralKronRecovery, NeutralKronReduction, NeutralKronReport, neutral_kron_reduce,
116};
117pub use lindist3flow::{
118    LinDist3FlowPreparationAction, LinDist3FlowPreparationActionKind,
119    LinDist3FlowPreparationPolicy, LinDist3FlowPreparationReport, LinDist3FlowPreparedNetwork,
120    prepare_lindist3flow_network,
121};
122pub use model::{
123    ActivePowerReference, ActivePowerUnit, ConductorMatrix, Configuration, ControlVoltageReference,
124    DistBus, DistCapacitor, DistControlProfile, DistGenerator, DistIbr, DistLine, DistLineCode,
125    DistLoad, DistLoadVoltageModel, DistShunt, DistSourceFormat, DistSwitch, DistTransformer,
126    DistWinding, DistWindingConn, Extras, IbrPrimeMover, IbrTopology, IbrVoltageAggregation,
127    MulticonductorNetwork, PowerFactorControl, ReactivePowerReference, ReactivePowerUnit,
128    TerminalRole, UntypedObject, VoltVarControl, VoltWattControl, VoltageSource,
129    calc_terminal_role, find_unresolved_references,
130};
131pub use readiness::{
132    ElectricalReadiness, ReadinessFinding, ReadinessSeverity, audit_electrical_readiness,
133    require_electrical_readiness,
134};
135pub use terminal_index::{MulticonductorTerminalIndex, TerminalIndexError};
136
137mod load_voltage;
138pub use load_voltage::{
139    ZipLaw, ZipVoltage, calc_load_nominal_admittance, calc_zip_coefficient, calc_zip_nominal_power,
140};