BMOPF field mapping

This page says what each BMOPF field becomes in PowerIO, in which unit, and which constraint or objective term it enters. It is the authority for the BMOPF converter, so if you find a field that reads or writes differently from what is written here, one of the two has a defect.

Schema versions come from the dsopt-schema repository. 0.1.0 is the version the IEEE PES Task Force on Benchmarking Multiconductor OPF accepts, and 0.2.0 is the proposal that adds the element classes 0.1.0 has no table for. PowerIO reads both and writes 0.2.0 by default; to write 0.1.0, pass BmopfEmitOptions::with_schema_version(BmopfSchemaVersion::Bmopf010).

Conventions

Every BMOPF quantity is SI and absolute: volts, amperes, watts, vars, volt-amperes, ohms, siemens, metres, radians, hertz, and a cost rate in currency per kilowatt-hour. PowerIO stores the same units with no scaling, so a mapping below gives a unit only where the two names differ.

A matrix element A_k_j is row k, column j, counting from one, and lands in row k - 1, column j - 1 of the corresponding ConductorMatrix. These matrices are symmetric, so the reader fills an unstated transpose cell from its mirror; a stated cell wins over its mirror. A per terminal array has one entry per name in the element’s own terminal map, in that order, and PowerIO keeps that order.

An absent constraint field means no constraint and reads as None; an absent parameter field is zero. A field with no typed slot lands in the element’s extras, and the reader reports it under READ.BMOPF.RETAINED_SOURCE_ONLY. Fields with no typed slot lists every one.

Document level

bus

DistBus, in MulticonductorNetwork::buses().

line and linecode

DistLine and DistLineCode.

A line has exactly one impedance source, and the oneOf in both schema versions enforces it: either a linecode with a length, or inline R_series_1_1 and X_series_1_1 with no linecode.

switch

DistSwitch.

load

DistLoad. Each array has one entry per branch of the load: a phase to neutral branch for WYE, the terminal pair for SINGLE_PHASE, or a line to line branch for DELTA.

generator

DistGenerator. Arrays are per phase conductor; WYE is the only configuration the specification supports.

voltage_source

VoltageSource. Both versions permit exactly one.

shunt and capacitor

DistShunt is raw admittance, grounding impedance included; DistCapacitor is a bank with a nameplate rating.

transformer

DistTransformer with windings: Vec<DistWinding>. The BMOPF subtype is kept in DistTransformer::extras["bmopf_subtype"], because the winding list alone does not pin down every subtype; a centre tap unit, for example, reads as two secondary windings.

Under schema 0.1.0, the nine fields that have no subtype slot (tap, tap_min, tap_max, the four winding neutral fields, and the two no-load fields) are written to extras.transformer.<subtype>.<name> and folded back on read, with each move reported under EMIT.BMOPF.RETAINED_SOURCE_ONLY. Under 0.2.0 the subtypes declare all nine, so nothing moves; only the three tap names change, to tap_ratio, tap_ratio_min, and tap_ratio_max.

OpenDSS Xscarray populates every winding-pair reactance in this order. The reader applies scalar XHL/XHT/XLT updates at edit boundaries; regenerated four-or-more-winding records use the complete Xscarray.

ibr and control_profile

DistIbr and DistControlProfile. Both are typed under either version. Because 0.1.0 has no top-level table for them, that version writes them under extras; on read they come from either place, and the top-level copy wins.

Fields with no typed slot

The classes below read into MulticonductorNetwork::untyped() by class and name, with their properties kept as text, and are written back to the table the target version declares: the top level under 0.2.0, extras under 0.1.0. Reading each one reports READ.BMOPF.RETAINED_SOURCE_ONLY.

dc_bus, dc_branch, dc_grounding, dc_load, dc_source, time_series, wire_data, line_geometry, and a per-element time_series reference map.

They pass through and re-emit unchanged. Nothing reads their values into a calculation, so if a case’s behaviour depends on them, the instance PowerIO builds from it does not represent that case. The reader says so per class rather than leaving you to discover it.

The calculation

powerio::to_mc_ac_opf_instance builds a McAcOpfInstance through McAcOpfInstance::from_network. The instance shares the network rather than copying it: it selects which of the network’s stated limits are active constraints and which objective terms are summed, and reads the numbers from the network.

Objective. There is one term, ObjectiveTerm::ActivePowerDispatchCost, which is the specification’s default objective: the sum over every dispatchable element and every phase of that phase’s cost rate against the active power the element injects into the network. A positive cost minimises the element’s injection and a negative cost maximises it, and that holds the same way for a generator, the voltage source, and an IBR. The rate comes from the element’s own per phase cost array: a generator reads it from DistGenerator::cost, and a voltage source or IBR from its extras["cost"]. ObjectiveTerm::NetworkGeneratorCost is the term for a balanced network and is not part of a BMOPF instance.

Constraints. MulticonductorActiveConstraints selects three families, each ConstraintSelection::All by default, which matches the specification’s rule that constraints are active for the elements present.

A family selects by stable element identity, so a study that relaxes one line’s thermal limit refers to that line instead of restating the bound. ConstraintSelection::None relaxes a whole family, and Only lists the elements whose limits stay active.

Equipment behaviour has no selection family, because there is no limit to relax: a closed switch equates its two ends conductor by conductor, an open switch carries no current, the ideal winding pair relates its two coil voltages by the turns ratio and balances ampere-turns, and the voltage source fixes its terminal voltage with a free current. Those hold in every instance built from a network that includes them.

The solution

Solved values stay in McAcOpfSolution and are not written back into the network, so the network still describes the case and the solution describes one result of it.

Checked against what

The reference data is the two published example networks, vendored at tests/data/dist/bmopf/. powerio-dist/tests/bmopf.rs checks that each one parses, that writing the result validates against the schema of the version written, that a second write is identical to the first, and that parsing the written document reproduces the model. The equations above were checked against the specification pages of math-and-data-model-specifications rather than inferred from the data.

BMOPFTools.jl is publicly available and is identified as the generator of example_ieee13.json. The PowerIO 0.11 compatibility change exercises the typed module API, explicit legacy schema version, retained diagnostics, transformer core-shunt locations and nominal n-winding imports. Its numerical suite compares power-flow voltages and transformer admittance with OpenDSS, including independently prepared BMOPF cases and native OpenDSS conversions.

PowerIO’s structural tests additionally check triangular matrix completion, conductor order, regulator fields, proposal provenance and rejected malformed records. These checks distinguish data preservation from the equations a particular solver supports; retaining a regulator or n-winding record does not imply that PowerIO’s own matrix compiler implements it.

Explicit terminal-coil no-load admittance

transformer.<subtype>.<id>.no_load_shunt holds {winding, g, b} in transformer extras and IR version 2. The one-based winding index fixes its physical location, and g + j b is siemens per coil at the terminal voltage. It cannot coexist with the existing from-side g_no_load and b_no_load fields.

OpenDSS and PMD exciting-branch percentages map to winding 2 with a negative magnetizing susceptance. Conversion uses the actual tapped WYE phase-to-neutral or DELTA phase-to-phase coil voltage and divides total transformer VA by the phase count. A winding-2 shunt converts back to those percentages; other locations report that this target parameterization cannot represent them. Legacy BMOPF output preserves the object under extras.transformer and reports the relocation. Nonzero core shunts reject the limited PowerIO passive transformer matrix profile before execution.

The independent check evals/validation/validate_bmopf_core_shunts.py compares six transformer topologies with OpenDSS Yprim through an intermediate PowerIO IR document. BMOPFTools’ 0.11 adapter uses an equivalent bus-shunt matrix and retains the original coil object in provenance. Successful parsing alone does not establish support for a transformer calculation.