Distribution networks

OpenDSS, PMD JSON, and BMOPF sources parse into a MulticonductorNetwork: buses with named terminals, lines with per length impedance matrices, transformers with windings, loads and generators with per terminal powers.

VoltageSource.reference_terminal identifies the other voltage endpoint on the source bus. nothing means earth; a terminal name does not imply grounding.

feeder = parse("IEEE13Nodeckt.dss")     # PioModule{MulticonductorNetwork}
net = feeder.value

net.name
net.base_frequency                       # 60.0
net.source_format                        # "dss"

net.buses                                # Elements{MulticonductorBus}
net.line_codes                            # Elements{MulticonductorLineCode}
net.lines
net.switches
net.transformers
net.loads
net.generators
net.ibrs                                 # inverter based resources
net.control_profiles
net.shunts
net.capacitors
net.voltage_sources
net.untyped_objects                              # source objects kept without a typed slot
net.commands                             # retained source commands (solve, ...)
net.options                              # name => value pairs
lc = net.line_codes[1]
lc.resistance                            # conductor_count square, ohm per metre
lc.reactance
lc.susceptance_from + lc.susceptance_to  # siemens per metre

line = net.lines[1]
line.bus_from, line.terminals_from       # "650", ["1", "2", "3"]
line.line_code, line.length_m

load = net.loads[1]
load.terminals                           # phases and neutral
load.active_power_nominal_w              # one entry per phase
load.voltage_model                       # "constant_power", ...

Units are SI (volts, watts, vars, metres, ohms, siemens), and terminal maps are vectors of terminal names in the order the source lists them.

Writing

emit writes the same three formats. If you read a module from OpenDSS and change nothing, writing it as "dss" gives you the original .dss files back; PMD JSON and BMOPF are canonical output, with diagnostics for whatever the target format cannot represent.

emit(feeder, "dss", "copy.dss")
emit(feeder, "pmd").text
emit(feeder, "bmopf").text

OpenDSS, PMD JSON, and BMOPF are grid exchange formats: other tools read and write them, and they enter PowerIO through parse and leave through emit. PowerIO IR, written by serialize and read by deserialize, is PowerIO's own serialization of a module, diagnostics and history included, for handing a module to another PowerIO consumer. It is not an exchange format, and no other tool reads it.

There is one BMOPF. PowerIO reads and writes the schema proposed in dsopt-schema#2, subject to Task Force ratification. Its metadata identifies the immutable schema and producer provenance. "bmopf" and "bmopf-json" are the BMOPF format strings; a "bmopf-json@<version>" string is refused. A document from an older BMOPF draft, including the draft PowerIO 0.11 wrote, is read as BMOPF with one READ.BMOPF.SCHEMA_LEGACY warning, and writing it produces the current schema.

Bus phase_to_ground_voltage_min_v and phase_to_ground_voltage_max_v contain unequal phase limits in volts. Their entries follow bus terminal order, excluding neutral and earth terminals. Uniform limits use voltage_min_v and voltage_max_v. These values survive PowerIO IR serialization and typed access after the module that supplied the network leaves scope.

Calculations

to_mc_ac_pf_instance and to_mc_ac_opf_instance construct multiconductor power flow and optimal power flow instances from a network module. The multiconductor admittance matrix is not bound in this release.

PowerIO.MulticonductorNetwork — Type
MulticonductorNetwork

A conductor level distribution network. Read the tables through properties: net.buses, net.line_codes, net.lines, net.switches, net.transformers, net.loads, net.generators, net.ibrs, net.control_profiles, net.shunts, net.capacitors, net.voltage_sources, net.untyped_objects, net.commands, net.options. Scalars: net.name, net.base_frequency, net.source_format, net.geo.

source
PowerIO.MulticonductorBus — Type
MulticonductorBus

One multiconductor bus: its id, terminals, grounded_terminals, and the voltage limits the source states (volts). Phase vectors follow terminal order with neutral and earth terminals excluded. Scalar bounds apply uniformly.

source
PowerIO.MulticonductorLineCode — Type
MulticonductorLineCode

Per length impedance of a line: the resistance, reactance, and terminal conductance_from, susceptance_from, conductance_to, susceptance_to matrices (ohm per metre and siemens per metre, conductor_count square), the per conductor limits, and the source the code came from.

source
PowerIO.MulticonductorLine — Type
MulticonductorLine

One line from bus_from to bus_to with its terminal maps, line_code, length_m, optional route, and per conductor limits.

source
PowerIO.MulticonductorLoad — Type
MulticonductorLoad

One load: configuration, nominal powers per active load branch, the voltage_model name, and ZIP/exponential coefficients in the same branch order. terminals also includes the return conductor, so its length can exceed the number of power channels.

source
PowerIO.MulticonductorGenerator — Type
MulticonductorGenerator

One generator with per terminal nominal powers, optional limits, dispatch cost, and apparent power and current limits.

source
PowerIO.InverterBasedResource — Type
InverterBasedResource

One inverter based resource: topology, prime_mover, limits, available active power, and the control_profile it follows.

source
PowerIO.ControlProfile — Type
ControlProfile

One inverter control profile: a fixed power_factor, a volt_var curve, a volt_watt curve, or a combination.

source
PowerIO.VoltageSource — Type
VoltageSource

One ideal voltage source with per terminal magnitude (volts), angle (radians), and optional per-phase energy cost rates (dollars/kWh). reference_terminal names the other voltage endpoint on bus; nothing means earth. A named reference does not imply grounding.

source
PowerIO.UntypedObject — Type
UntypedObject

One source object retained without a typed PowerIO representation: its class_name, name, and properties as name => value pairs (a positional property has nothing as its name).

source

Source energy prices from BMOPF are available as net.voltage_sources[i].energy_cost_rate_per_kwh. The optional vector follows phase order in the source terminal map, excluding neutral terminals. Its unit is $/kWh. The prices survive PowerIO IR serialization; using them in an objective remains the responsibility of the selected calculation.

Bounded load laws retain their ZIP fractions or independent P/Q exponents, nominal voltages, voltage-band transitions, dropout and current limits. network.loads[i] exposes these as typed values; absent optional bounds remain nothing. The original 16-argument MulticonductorLoad constructor remains available for ordinary laws.

instance.loads on an McAcPfInstance is a lazy table of prescribed power arrays, complete voltage laws and terminal maps. A row copies only its own borrowed arrays. Reference conductors can make the terminal map longer than the power-channel arrays. Reading a load never serializes or clones the network.

Ordinary load records remain readable with libraries from before the load details accessors through their legacy accessor. Complete bounded-law reads and McAcPfInstance.loads require the additive load-details accessors; a legacy refusal is propagated rather than returning an incomplete bounded law.