Skip to main content

Crate powerio_dist

Crate powerio_dist 

Source
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 token cim-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 .dss support: 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§

ConnectionChannel
One channel of a connection: the terminal its power enters and the terminal it returns through, as positions in the element’s terminal map. to is None for a channel that returns through ground.
Diagnostic
One coded user facing finding.
DiagnosticCode
Stable dotted identity of one diagnostic.

Enums§

DiagnosticSeverity
Severity of one user facing finding.
DiagnosticStage
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_count terminals of coils coils with susceptances susceptance (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_count terminals carrying channel_count stated powers, one channel per power in power order:
calc_element_connection
The channels of an element’s connection at bus over its terminal map (calc_connection_channels), with a WYE neutral found by calc_wye_neutral_position. channel_count is the element’s number of stated powers or phases; None reads 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 power at v_nom: conj(S) / V², siemens, the constant impedance law’s admittance and the current Y U every law reduces to at or below its low voltage threshold.
calc_mapped_neutral_position
The position in terminal_map of the one mapped terminal that is not a phase of a bus with terminals bus_terminals: a terminal the bus does not carry, or one whose crate::calc_terminal_role under conventions is neutral or earth. None when every mapped terminal is a phase. The one WYE neutral rule: calc_wye_neutral_position reads 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_role over the network’s terminal conventions) is not a phase, ground terminal 0 included (calc_mapped_neutral_position). None when every mapped terminal is a phase.
calc_zip_coefficient
The ZIP coefficient that draws power at a nominal voltage of magnitude magnitude and unit phasor direction (1.0 for a zero angle reference): the power itself, the current conj(S) e^{jθ} / |V| (that is conj(S / V)), or the impedance |V|² / conj(S) (zero for zero power), the reciprocal of calc_load_nominal_admittance’s conj(S) / |V|² formed without a reciprocal. The inverse of calc_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, and S = |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_channels exist 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: +1 keeps each channel from terminal k to the next terminal of the ring, -1 returns each to the preceding one. A ring of fewer than three channels has one orientation.