Expand description
Multiconductor distribution network models and converters for OpenDSS
.dss, PowerModelsDistribution ENGINEERING
JSON (“PMD JSON”), the draft JSON schema of the IEEE PES Task Force on
Benchmarking Multiconductor OPF (“BMOPF JSON”,
https://github.com/distribution-system-opt/dsopt-schema), and
distribution CIM (CIM100 RDF/XML, see cim).
The model uses wire coordinates: string bus IDs, ordered terminal names,
explicit grounding, terminal maps on every element, SI units, and radians.
The transmission model in powerio is positive sequence and remains a
separate type.
let source = powerio_core::Source::open("feeder.dss")?;
let module = powerio_dist::parse(source)?;
for line in powerio_dist::diagnostics::render_diagnostics(module.diagnostics()) {
eprintln!("parse: {line}");
}
let emitted = powerio_dist::emit(
&module,
powerio_dist::DistTargetFormat::PmdJson,
powerio_core::Destination::memory("feeder.pmd.json")?,
)?;
for line in powerio_dist::diagnostics::render_diagnostics(emitted.diagnostics()) {
eprintln!("emit: {line}");
}SINCAL adapters are provided by powerio_tnd::formats::sincal and the
powerio facade. This model crate is independent of SQLite and integration.
§Fidelity rules
Emitting to the retained source format returns the original bytes. Cross
format emission uses the typed model and reports fields the target cannot
represent through [powerio_core::EmitResult::diagnostics]. The DSS reader expands OpenDSS
class defaults into explicit model values and records them in
MulticonductorNetwork::defaulted. BMOPF output includes those values.
The per fixture results live in docs/conversion-matrix.md.
§Float formatting
Canonical output formats every number as its shortest round trip
representation: Rust’s Display for .dss, serde_json (ryu) for both
JSON formats. The readers parse with serde_json’s float_roundtrip
feature, so a parse of canonical output recovers the exact bit pattern
and canonical emissions are idempotent. JSON cannot carry Inf/NaN: the
PMD emitter uses null (PMD restores the value from the field name
suffix), and the BMOPF emitter uses 0 with a warning, since the schema
requires numbers. The byte exact echo tier is unaffected; it never
reformats.
Re-exports§
pub use bmopf::BMOPF_SCHEMA_ID;pub use bmopf::BmopfEmitOptions;pub use cim::CIM_DIST_HEAD_BYTES;pub use cim::looks_like_cim_dist;pub use cim::looks_like_cim_dist_header;pub use cim::source_looks_like_cim_dist;pub use convert::DistTargetFormat;pub use convert::EmitOptions;pub use convert::classify_distribution_json;pub use convert::emit;pub use convert::emit_with_options;pub use convert::parse;pub use convert::parse_dist_target_format;pub use convert::parse_with_dss_limits;pub use dss::DssEmitOptions;pub use dss::DssLoadVoltageBounds;pub use dss::DssReadLimits;pub use error::Error;pub use error::Result;pub use geo::CoordinateSpace;pub use geo::DistCanvas;pub use geo::DistComponentLocation;pub use geo::DistCoordsKind;pub use geo::DistGeoMeta;pub use geo::DistGeographicPoint;pub use geo::DistLocation;pub use geo::DistLocationTarget;pub use graph::DistGraph;pub use graph::DistGraphAttachment;pub use graph::DistGraphAttachmentKind;pub use graph::DistGraphBus;pub use graph::DistGraphEdge;pub use graph::DistGraphEdgeKind;pub use kron::NeutralKronAction;pub use kron::NeutralKronBus;pub use kron::NeutralKronGrounding;pub use kron::NeutralKronOptions;pub use kron::NeutralKronRecovery;pub use kron::NeutralKronReduction;pub use kron::NeutralKronReport;pub use kron::neutral_kron_reduce;pub use lindist3flow::LinDist3FlowPreparationAction;pub use lindist3flow::LinDist3FlowPreparationActionKind;pub use lindist3flow::LinDist3FlowPreparationPolicy;pub use lindist3flow::LinDist3FlowPreparationReport;pub use lindist3flow::LinDist3FlowPreparedNetwork;pub use lindist3flow::prepare_lindist3flow_network;pub use model::ActivePowerReference;pub use model::ActivePowerUnit;pub use model::ConductorMatrix;pub use model::Configuration;pub use model::ControlVoltageReference;pub use model::DistBus;pub use model::DistCapacitor;pub use model::DistControlProfile;pub use model::DistGenerator;pub use model::DistIbr;pub use model::DistLine;pub use model::DistLineCode;pub use model::DistLoad;pub use model::DistLoadVoltageModel;pub use model::DistShunt;pub use model::DistSourceFormat;pub use model::DistSwitch;pub use model::DistTransformer;pub use model::DistWinding;pub use model::DistWindingConn;pub use model::Extras;pub use model::IbrPrimeMover;pub use model::IbrTopology;pub use model::IbrVoltageAggregation;pub use model::MulticonductorNetwork;pub use model::PowerFactorControl;pub use model::ReactivePowerReference;pub use model::ReactivePowerUnit;pub use model::TerminalRole;pub use model::UntypedObject;pub use model::VoltVarControl;pub use model::VoltWattControl;pub use model::VoltageSource;pub use model::calc_terminal_role;pub use model::find_unresolved_references;pub use readiness::ElectricalReadiness;pub use readiness::ReadinessFinding;pub use readiness::ReadinessSeverity;pub use readiness::audit_electrical_readiness;pub use readiness::require_electrical_readiness;pub use terminal_index::MulticonductorTerminalIndex;pub use terminal_index::TerminalIndexError;
Modules§
- bmopf
- The BMOPF task force JSON schema (https://github.com/distribution-system-opt/dsopt-schema).
- cim
- Distribution CIM: IEC 61968 and 61970 CIM100 RDF/XML for unbalanced
feeders, read into and written from the
MulticonductorNetwork(format tokencim-dist). - convert
- Distribution format dispatch.
- dense
- Small dense matrix algebra shared by every conductor sized calculation:
the series impedance inverses of lines and transformers, the potential
coefficient inverses of overhead geometry, and Kron reduction. The kernel
is [
powerio_core::dense], the one dense elimination; this module re-exports it. - diagnostics
- The codes this crate emits.
- dss
- OpenDSS
.dsssupport: tokenizer, RPN, class tables, raw object layer. - electrical
- The scalar electrical formulas both network families share, which live
in powerio-core (
electrical::calc_impedance_base, the power factor relations and the voltage power law term). The scalar electrical formulas both network families share: the per unit impedance base, the power factor relations and the voltage power law term. Each is the one implementation the transmission, distribution, composition and matrix crates call. - error
- geo
- Typed coordinate metadata for the distribution model.
- glm
- GridLAB-D source syntax, bounded offline preprocessing and static import.
- graph
- Render ready bus and terminal graph projection.
- kron
- Explicit-neutral Kron projection for
MulticonductorNetwork. - lindist3flow
- Audited, format-neutral network preparation for LinDist3Flow.
- model
- The canonical multiconductor network model.
- overhead
- Overhead line conductor equations shared by the OpenDSS and GridLAB-D geometry readers: the simplified Carson earth return impedance and Maxwell’s potential coefficients.
- pmd
- The PowerModelsDistribution ENGINEERING model as JSON (“PMD JSON”).
- ravens
- MG-RAVENS JSON import and export for the multiconductor
MulticonductorNetwork. - readiness
- Pre-solver structural readiness checks for distribution networks.
- sequence
- Symmetrical components: the one transform pair between sequence and phase quantities.
- terminal_
index - The flat terminal index of a multiconductor network: every declared bus terminal at one position, in bus table order and each bus’s stated terminal order. The one terminal indexing every multiconductor calculation reads, with one bus identity rule: bus names compare ASCII case insensitively, terminal names exactly.
- transformer
- Transformer winding physics: the pairwise leakage and its reduction, each winding’s coil voltage, connection and delta orientation, the neutral grounding and magnetizing branch a unit states, and the finite leakage primitive admittance over its physical terminals.
- voltage_
zones - Voltage base zones: the buses that share one voltage base, and the flood of zone bases across transformers.
Structs§
- Connection
Channel - One channel of a connection: the terminal its power enters and the
terminal it returns through, as positions in the element’s terminal map.
toisNonefor a channel that returns through ground. - Diagnostic
- One coded user facing finding.
- Diagnostic
Code - Stable dotted identity of one diagnostic.
Enums§
- Diagnostic
Severity - Severity of one user facing finding.
- Diagnostic
Stage - Pipeline stage encoded by the first segment of a diagnostic code.
- ZipLaw
- A GridLAB-D ZIP load term: the law its coefficient states.
Traits§
- ZipVoltage
- The nominal voltage a ZIP conversion reads: a real magnitude (
f64, a zero angle reference) or a phasor (Complex64).
Functions§
- calc_
capacitor_ susceptance - A capacitor bank’s susceptance matrix, siemens, over its terminal map.
- calc_
coil_ susceptance_ matrix - The susceptance matrix over
terminal_countterminals of coilscoilswith susceptancessusceptance(one per coil, in coil order): each coil adds its susceptance to its terminal’s diagonal and, when it returns through another terminal rather than ground, to that terminal’s diagonal and subtracts it between the two. The one capacitor coil stamp:calc_capacitor_susceptance, the BMOPF per coil capacitor lowering and the OpenDSS common return capacitor bank read it. - calc_
connection_ channels - The channels of a connection of
terminal_countterminals carryingchannel_countstated powers, one channel per power in power order: - calc_
element_ connection - The channels of an element’s connection at
busover its terminal map (calc_connection_channels), with a WYE neutral found bycalc_wye_neutral_position.channel_countis the element’s number of stated powers or phases;Nonereads it from the map: a WYE has one channel per phase terminal, a two terminal DELTA or single phase element one channel, and any other DELTA one channel per terminal (a ring). - calc_
load_ nominal_ admittance - The nominal admittance of a load branch drawing
poweratv_nom:conj(S) / V², siemens, the constant impedance law’s admittance and the currentY Uevery law reduces to at or below its low voltage threshold. - calc_
mapped_ neutral_ position - The position in
terminal_mapof the one mapped terminal that is not a phase of a bus with terminalsbus_terminals: a terminal the bus does not carry, or one whosecrate::calc_terminal_roleunderconventionsis neutral or earth.Nonewhen every mapped terminal is a phase. The one WYE neutral rule:calc_wye_neutral_positionreads it over a network, the BMOPF capacitor lowering over a document’s bus. - calc_
wye_ neutral_ position - The position of a WYE connection’s explicit neutral in an element’s
terminal map: the one mapped terminal whose role on the bus
(
crate::calc_terminal_roleover the network’s terminal conventions) is not a phase, ground terminal0included (calc_mapped_neutral_position).Nonewhen every mapped terminal is a phase. - calc_
zip_ coefficient - The ZIP coefficient that draws
powerat a nominal voltage of magnitudemagnitudeand unit phasordirection(1.0for a zero angle reference): the power itself, the currentconj(S) e^{jθ} / |V|(that isconj(S / V)), or the impedance|V|² / conj(S)(zero for zero power), the reciprocal ofcalc_load_nominal_admittance’sconj(S) / |V|²formed without a reciprocal. The inverse ofcalc_zip_nominal_power: the GridLAB-D load, explicit connection and triplex writers read it. - calc_
zip_ nominal_ power - The complex power a ZIP coefficient draws at its nominal voltage
voltage: the constant power itself,S = V conj(I)for a constant current, andS = |V|² / conj(Z)for a constant impedance (zero for a zero impedance, which GridLAB-D reads as no term). The one ZIP coefficient to power conversion: the GridLAB-D load, explicit connection and triplex readers read it. - lindist3flow_
carries_ connection - Whether the LinDist3Flow model carries a connection: its
calc_connection_channelsexist and need no explicit neutral and no split delta, so every WYE channel returns through ground and a DELTA connection is one terminal pair or the three phase ring. The one LinDist3Flow connection rule: the instance shape check and the incidence builder read it. - orient_
delta_ ring - Orient a DELTA ring of channels:
+1keeps each channel from terminalkto the next terminal of the ring,-1returns each to the preceding one. A ring of fewer than three channels has one orientation.