powerio_dist/
lib.rs

1//! `powerio-dist`: a multiconductor distribution network model and lossless
2//! converters between OpenDSS `.dss`, PowerModelsDistribution ENGINEERING
3//! JSON ("PMD JSON"), and the draft JSON schema of the IEEE PES Task Force on
4//! Benchmarking Multiconductor OPF ("BMOPF JSON",
5//! <https://github.com/frederikgeth/bmopf-report>).
6//!
7//! The canonical model is a network in wire coordinates: string bus ids,
8//! ordered string terminal names per bus, explicit grounding, terminal maps
9//! on every element, SI units and radians internally (BMOPF semantics, the
10//! most explicit of the three formats). The transmission model in the
11//! `powerio` crate is positive sequence and stays separate; the two crates
12//! share conventions, not types.
13//!
14//! ```no_run
15//! let net = powerio_dist::parse_file("feeder.dss", None)?;
16//! for w in &net.warnings {
17//!     eprintln!("parse: {w}");
18//! }
19//! let conv = net.to_format(powerio_dist::DistTargetFormat::PmdJson);
20//! # Ok::<(), powerio_dist::Error>(())
21//! ```
22//!
23//! # Fidelity contract
24//!
25//! The contract matches `powerio`. Writing back to the source format
26//! reproduces the file byte for byte via retained source text. Every cross
27//! format conversion regenerates from the typed model and reports each field
28//! the target cannot represent in [`Conversion::warnings`]; nothing drops
29//! silently. The dss reader materializes every OpenDSS class default into an
30//! explicit model value and records which fields were defaulted
31//! ([`DistNetwork::defaulted`]), so BMOPF output is always fully explicit.
32//! The per fixture results live in `docs/conversion-matrix.md`.
33//!
34//! # Float formatting
35//!
36//! Canonical output formats every number as its shortest round trip
37//! representation: Rust's `Display` for `.dss`, serde_json (ryu) for both
38//! JSON formats. The readers parse with serde_json's `float_roundtrip`
39//! feature, so a parse of canonical output recovers the exact bit pattern
40//! and canonical writes are idempotent. JSON cannot carry `Inf`/`NaN`: the
41//! PMD writer emits `null` (PMD restores the value from the field name
42//! suffix), and the BMOPF writer emits `0` with a warning, since the schema
43//! requires numbers. The byte exact echo tier is unaffected; it never
44//! reformats.
45
46pub mod bmopf;
47pub mod convert;
48pub mod dss;
49pub mod error;
50pub mod model;
51pub mod pmd;
52
53pub use bmopf::{parse_bmopf_file, parse_bmopf_str, write_bmopf_json};
54pub use convert::{
55    Conversion, DistTargetFormat, convert_file, convert_str, dist_target_from_name, parse_file,
56    parse_str,
57};
58pub use dss::{parse_dss_file, parse_dss_str, write_dss};
59pub use error::{Error, Result};
60pub use model::{
61    Configuration, DistBus, DistGenerator, DistLine, DistLineCode, DistLoad, DistLoadVoltageModel,
62    DistNetwork, DistShunt, DistSourceFormat, DistSwitch, DistTransformer, Extras, Mat,
63    MulticonductorNetwork, UntypedObject, VoltageSource, Winding, WindingConn,
64};
65pub use pmd::{parse_pmd_file, parse_pmd_str, write_pmd_json};
powerio_dist/lib.rs

powerio_dist/
lib.rs
