Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

PowerIO IR reference

This page lists every structural value type in the PowerIO IR, field by field: each field’s type, unit, and sign convention, the invariant the deserializer or the constructors enforce, and what a reader uses when the field is absent. The generated schema at docs/schema/pio-ir/0.12.3/schema.json is the machine form of the same definitions. To keep the two from drifting apart, powerio/tests/ir_reference.rs reads this page and checks in both directions that each table lists the same fields the schema defines for its definition.

Reading the tables

Each field table sits under a line that begins with the words “Schema definition” and gives, in backticks, the $defs entries of the schema the table documents; that line is how the test pairs a table with its definitions. The columns are:

  • field: the JSON member name in value.data (or in the nested record).
  • type: float is a JSON number or one of the strings "Infinity", "-Infinity", and "NaN"; null is refused at a float position. float or null is a float the source may leave unstated. id is a bus identifier: a nonnegative integer, the source’s own bus number. matrix is an array of equal length float arrays. token is one of the listed strings.
  • unit: the physical unit. p.u. is per unit on the network’s base_mva and the bus base_kv unless the row says otherwise.
  • sign: the direction a positive value means; blank when the quantity is unsigned or the sign carries no convention.
  • invariant: what the deserializer refuses or the constructors hold.
  • if absent: required when the serializer always writes the field and the deserializer refuses a document without it; otherwise the value a reader takes when the member is missing.

uid on an element row is the stable component identity that operating points, solutions, and updates refer to. When the source gives none, parse and serialize assign {table}:{row}, so a document PowerIO writes has one wherever a table below says “assigned at serialization”. extras on an element is the map of source fields the typed model has no slot for, keyed by the source’s own field names; the member is required in the document but may be empty.

Structural type names

value.type is one of these names, and value.data has the shape of the schema definition beside it.

structural typeschema definition
powerio.BalancedNetworkBalancedNetwork
powerio.MulticonductorNetworkMulticonductorNetwork
powerio.GeoLayerGeoLayer
powerio.ContingencySetContingencySet
powerio.SubsystemSetSubsystemSet
powerio.MonitoredSetMonitoredSet
powerio.OperatingPoint<powerio.BalancedNetwork>StoredOperatingPoint
powerio.OperatingPoint<powerio.MulticonductorNetwork>StoredOperatingPoint2
powerio.TimeSeries<powerio.BalancedNetwork>StoredTimeSeries
powerio.TimeSeries<powerio.MulticonductorNetwork>StoredTimeSeries2
powerio.TimeSeries<powerio.OperatingPoint<powerio.BalancedNetwork>>StoredOperatingPointTimeSeries
powerio.TimeSeries<powerio.OperatingPoint<powerio.MulticonductorNetwork>>StoredOperatingPointTimeSeries2
powerio.ScenarioSet<powerio.BalancedNetwork>StoredScenarioSet
powerio.ScenarioSet<powerio.MulticonductorNetwork>StoredScenarioSet2
powerio.ScenarioSet<powerio.OperatingPoint<powerio.BalancedNetwork>>StoredOperatingPointScenarioSet
powerio.ScenarioSet<powerio.OperatingPoint<powerio.MulticonductorNetwork>>StoredOperatingPointScenarioSet2
powerio.ScenarioSet<powerio.TimeSeries<powerio.BalancedNetwork>>StoredScenarioSet3
powerio.ScenarioSet<powerio.TimeSeries<powerio.MulticonductorNetwork>>StoredScenarioSet4
powerio.ScenarioSet<powerio.TimeSeries<powerio.OperatingPoint<powerio.BalancedNetwork>>>StoredScenarioSet5
powerio.ScenarioSet<powerio.TimeSeries<powerio.OperatingPoint<powerio.MulticonductorNetwork>>>StoredScenarioSet6
powerio.DcPfInstanceDcPfInstance
powerio.AcPfInstanceAcPfInstance
powerio.DcOpfInstanceDcOpfInstance
powerio.AcOpfInstanceAcOpfInstance
powerio.AcOtsInstanceAcOtsInstance
powerio.McAcPfInstanceMcAcPfInstance
powerio.McAcOpfInstanceMcAcOpfInstance
powerio.LinDist3FlowPfInstanceLinDist3FlowPfInstance
powerio.LinDist3FlowOpfInstanceLinDist3FlowOpfInstance
powerio.AcScucInstanceAcScucInstance
powerio.DcPfSolutionDcPfSolution
powerio.AcPfSolutionAcPfSolution
powerio.DcOpfSolutionDcOpfSolution
powerio.AcOpfSolutionAcOpfSolution
powerio.AcOtsSolutionAcOtsSolution
powerio.SocwrOpfSolutionSocwrOpfSolution
powerio.McAcPfSolutionMcAcPfSolution
powerio.McAcOpfSolutionMcAcOpfSolution
powerio.LinDist3FlowPfSolutionLinDist3FlowPfSolution
powerio.LinDist3FlowOpfSolutionLinDist3FlowOpfSolution
powerio.AcScucSolutionAcScucSolution

powerio.BalancedNetwork

The positive sequence transmission model, in the units MATPOWER uses: powers in MW and MVAr, voltage magnitudes in per unit, angles in degrees, and impedances in per unit on base_mva. Bus identifiers are the source’s own.

Schema definition: BalancedNetwork.

fieldtypeunitsigninvariantif absent
namestringrequired
base_mvafloatMVAfinite and positiverequired
base_frequencyfloatHzpositive60
source_formattokenone of the format tokens (matpower, psse, psse-rawx, powermodels-json, egret-json, powerworld, powerworld-pwb, pslf, pandapower-json, pypsa-csv, gridfm, goc3-json, surge-json, opfdata-json, xiidm, jiidm, cgmes, ucte, ieee-cdf, sincal, in-memory, normalized)required
busesarray of Busid uniquerequired
loadsarray of Loadbus names a busrequired
shuntsarray of Shuntbus names a busrequired
branchesarray of Branchfrom and to name busesrequired
generatorsarray of Generatorbus names a busrequired
storagearray of Storagebus names a busrequired
hvdcarray of Hvdcfrom and to name busesrequired
switchesarray of Switchfrom and to name buses[]
transformers_3warray of Transformer3Wevery winding bus names a bus[]
static_var_compensatorsarray of StaticVarCompensatorbus names a bus[]
areasarray of Areanumber unique[]
solverSolverParams or nullnull
case_metadataCaseMetadataevery member null
geoGeoMeta or nullnull
detailed_connectivityDetailedConnectivity or nullnull
generated_uidsarray of stringsubset of component uid values; identifies identities PowerIO assigned because the source stated none[]

Bus

Schema definition: Bus.

fieldtypeunitsigninvariantif absent
ididunique within busesrequired
kindtoken PQ, PV, REF, ISOLATEDMATPOWER type codes 1, 2, 3, 4required
vmfloatp.u.required
vafloatdegreesrequired
base_kvfloatkVnonnegative; 0 when the source states nonerequired
vmaxfloatp.u.vmin <= vmax; Infinity for no boundrequired
vminfloatp.u.required
evhifloat or nullp.u.emergency band, stated only when it differs from vmaxnull (equals vmax)
evlofloat or nullp.u.stated only when it differs from vminnull (equals vmin)
areaintegerrequired
zoneintegerrequired
namestring or nullnull
uidstring or nullunique within busesassigned at serialization
locationLocation or nullnetwork coordinate spacenull
extrasobjectrequired

Load

Schema definition: Load.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
pfloatMWpositive is consumptionrequired
qfloatMVArpositive is inductive consumptionrequired
in_servicebooleanrequired
voltage_modelLoadVoltageModel or nullnull (constant power)
uidstring or nullunique within loadsassigned at serialization
extrasobjectrequired

LoadVoltageModel is tagged by kind. constant_power has no further member. zip has p_constant_power, p_constant_current, p_constant_impedance (MW, summing to p) and q_constant_power, q_constant_current, q_constant_impedance (MVAr, summing to q), plus an optional v_nom (kV), an optional source load_type code, and an optional scaling factor. exponential has gamma_p, gamma_q, and v_nom, with P = p (V / v_nom)^gamma_p and Q = q (V / v_nom)^gamma_q.

Shunt

Schema definition: Shunt.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
gfloatMW at V = 1 p.u.positive is consumptionrequired
bfloatMVAr at V = 1 p.u.positive is capacitive injectionthe initial value of a switched shuntrequired
in_servicebooleanrequired
section_countinteger or nullnull (unset)
controlSwitchedShuntControl or nullnull (fixed shunt)
uidstring or nullunique within shuntsassigned at serialization
extrasobjectrequired

Schema definition: SwitchedShuntControl.

fieldtypeunitsigninvariantif absent
modetoken locked, continuous, discretePSS/E MODSW 0, 2, and 1 or 3 to 6required
vhighfloatp.u.vlow <= vhighrequired
vlowfloatp.u.required
control_busid or nullnames a busnull (the shunt’s own bus)
regulating_terminalTerminalReference or nullnull
rmpctfloatpercentrequired
blocksarray of ShuntBlockrequired

Schema definition: ShuntBlock.

fieldtypeunitsigninvariantif absent
stepsintegerrequired
gfloatMW at V = 1 p.u. per steppositive is consumptionrequired
bfloatMVAr at V = 1 p.u. per steppositive is capacitive injectionrequired

Branch

Ratings use zero for a zero bound and "Infinity" for no bound in 0.12 JSON, using the same nonfinite spelling as other numeric fields. The reader converts zero ratings in 0.11 documents (integer version 2) to infinity; it does not reinterpret zero in a 0.12 document. This also applies to winding and named ratings. The record shapes stay unchanged.

Schema definition: Branch.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
rfloatp.u.required
xfloatp.u.r and x not both zero when a matrix is builtrequired
bfloatp.u.positive is capacitivetotal line charging; half at each end unless charging is presentrequired
chargingBranchCharging or nullcanonical per terminal admittance when presentnull (derive from b)
rate_afloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_bfloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_cfloatMVA0 is a zero bound; +Inf is unboundedrequired
rating_setsarray of BranchRatingSet[]
current_ratingsBranchCurrentRatings or nullnull
tapfloatratio at the from side0 means 1 (a line); otherwise positiverequired
shiftfloatdegreespositive means the from side voltage leads the to siderequired
in_servicebooleanrequired
angminfloatdegreesangmin <= angmax; -360 and 360 mean unconstrainedrequired
angmaxfloatdegreesrequired
controlTransformerControl or nullnull (a line or a fixed ratio transformer)
solutionBranchSolution or nullnull
namestring or nullnull
uidstring or nullunique within branchesassigned at serialization
routearray of Location or nullnetwork coordinate spacenull
extrasobjectrequired

A transformer’s impedance correction table rides in extras. impedance_correction holds {table, variable, points}. variable is ratio or angle (degrees), and each point is {value, factor_re, factor_im}, the complex factor that multiplies the nominal series impedance at that ratio or angle. A three winding transformer keeps three such entries, one per winding or null, and its factor scales that winding’s star impedance. With psse_zcod = 1, entries 0/1/2 instead scale Z12/Z23/Z31, using the sole winding whose control mode is not fixed (regulation may be disabled). Ratio coordinates on a branch are in its effective t1/t2 tap units; three-winding ratio coordinates are bus-base per-unit winding taps. impedance_correction_nominal holds the nominal impedance once apply_impedance_correction has scaled it: [r, x] on a branch and the three pairwise [r, x] on a three winding transformer. impedance_correction_applied holds the corrected impedance that call wrote, in the same layout; a present impedance that differs from it was edited afterward and is the nominal value from then on.

Schema definition: BranchCharging.

fieldtypeunitsigninvariantif absent
g_frfloatp.u.required
b_frfloatp.u.positive is capacitiverequired
g_tofloatp.u.required
b_tofloatp.u.positive is capacitiverequired

Schema definition: BranchRatingSet.

fieldtypeunitsigninvariantif absent
namestringrequired
rate_mvafloatMVA0 is a zero bound; +Inf is unboundedrequired

Schema definition: BranchCurrentRatings.

fieldtypeunitsigninvariantif absent
c_rating_afloatsource units (amperes for PSS/E)required
c_rating_bfloatsource unitsrequired
c_rating_cfloatsource unitsrequired

Schema definition: BranchSolution.

fieldtypeunitsigninvariantif absent
pffloatMWpositive flows into the branch at the from terminalrequired
qffloatMVArpositive flows into the branch at the from terminalrequired
ptfloatMWpositive flows into the branch at the to terminalrequired
qtfloatMVArpositive flows into the branch at the to terminalrequired

Schema definition: TransformerControl.

fieldtypeunitsigninvariantif absent
modetoken fixed, voltage, reactive_flow, active_flow, dc_line_quantity, asymmetric_active_flowPSS/E COD magnitude 0 through 5required
enabledbooleanautomatic adjustment on; the sign of PSS/E CODrequired
controlled_busid or nullnames a busnull
controlled_bus_on_winding_sidebooleanfalse
regulating_terminalTerminalReference or nullnull
band_minfloatp.u. voltage, MVAr, or MW as mode selectsband_min <= band_maxrequired
band_maxfloatas band_minrequired
tap_minfloatratio, or degrees for phase controltap_min <= tap_maxrequired
tap_maxfloatas tap_minrequired
ntpintegernumber of tap positionsrequired
mva_basefloatMVArequired
winding_connection_anglefloat or nulldegreesasymmetric active power flow control onlynull

Generator

Schema definition: Generator.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
pgfloatMWpositive is generationrequired
qgfloatMVArpositive is generationrequired
qmaxfloatMVArqmin <= qmax; Infinity and -Infinity mean unboundedrequired
qminfloatMVArrequired
vgfloatp.u.required
mbasefloatMVApositive when statedrequired
pmaxfloatMWpmin <= pmaxrequired
pminfloatMWrequired
in_servicebooleanrequired
costGenCost or nullnull (no cost curve)
capsmap of string to floatMW, MVAr, MW per minute, or a fraction per keykeys among pc1, pc2, qc1min, qc1max, qc2min, qc2max, ramp_agc, ramp_10, ramp_30, ramp_q, apf, the MATPOWER columns past PMIN{}
energy_sourcetoken hydro, nuclear, wind, thermal, solar, otherother
voltage_regulation_onbooleantrue
regulated_busid or nullnames a busnull (the generator’s own bus)
regulating_terminalTerminalReference or nullnull
active_power_controlActivePowerControl or nullnull
uidstring or nullunique within generatorsassigned at serialization

Schema definition: GenCost.

fieldtypeunitsigninvariantif absent
modelinteger1 is piecewise linear, 2 is polynomialrequired
startupfloatcurrencyrequired
shutdownfloatcurrencyrequired
ncostintegerpolynomial: coeffs.len() == ncost; piecewise: coeffs.len() == 2 * ncostrequired
coeffsarray of floatpolynomial: currency per MW^k per hour, highest order first; piecewise: alternating MW and currency per hour breakpointsrequired

Schema definition: ActivePowerControl.

fieldtypeunitsigninvariantif absent
participatebooleanrequired
droop_percentfloat or nullpercentnull
participation_factorfloat or nullnull
minimum_target_active_power_mwfloat or nullMWnull
maximum_target_active_power_mwfloat or nullMWnull

Storage

The PowerModels storage model.

Schema definition: Storage.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
psfloatMWpositive is withdrawn from the network (charging)required
qsfloatMVArpositive is withdrawn from the networkrequired
energyfloatMWh0 <= energy <= energy_ratingrequired
energy_ratingfloatMWhrequired
charge_ratingfloatMWrequired
discharge_ratingfloatMWrequired
charge_efficiencyfloatfractionin [0, 1]required
discharge_efficiencyfloatfractionin [0, 1]required
thermal_ratingfloatMVArequired
current_ratingfloat or nullamperesnull
qminfloatMVArqmin <= qmaxrequired
qmaxfloatMVArrequired
rfloatp.u.required
xfloatp.u.required
p_lossfloatMWstandby lossrequired
q_lossfloatMVArstandby lossrequired
in_servicebooleanrequired
active_power_controlActivePowerControl or nullnull
uidstring or nullunique within storageassigned at serialization
extrasobjectrequired

Hvdc

A two terminal HVDC line in the MATPOWER dcline convention, whatever the source format. The stored pf, pt, qf, and qt keep these signs throughout 0.11.x: pf is positive from the from bus into the line, and pt, qf, and qt are positive from the line into their bus. The calculations read them through the bus-to-device terminal view (Hvdc::calc_bus_to_device_powers in Rust), positive from each AC bus into the HVDC system: p_from = pf, q_from = -qf, p_to = -pt, q_to = -qt, with p_from + p_to the active power lost. A balanced calculation carries an in service line whose two terminal buses are energized as fixed bus injections, the negatives of its terminal powers: -pf and +qf at the from bus, +pt and +qt at the to bus.

Schema definition: Hvdc.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
in_servicebooleanrequired
pffloatMWpositive flows from the from bus to the to bus, measured at the from endrequired
ptfloatMWpositive flows from the from bus to the to bus, measured at the to endrequired
qffloatMVArpositive is injected into the from busrequired
qtfloatMVArpositive is injected into the to busrequired
vffloatp.u.voltage setpoint at the from busrequired
vtfloatp.u.voltage setpoint at the to busrequired
pminfloatMWbounds on pf; pmin <= pmaxrequired
pmaxfloatMWrequired
qminffloatMVArbounds on qfrequired
qmaxffloatMVArrequired
qmintfloatMVArbounds on qtrequired
qmaxtfloatMVArrequired
loss0floatMWconstant loss termrequired
loss1floatMW per MWlinear loss term in pfrequired
resistance_ohmfloat or nullohmnull
nominal_voltage_kvfloat or nullkVnull
converters_modetoken side1_rectifier_side2_inverter, side1_inverter_side2_rectifier, or nullnull
converter1HvdcConverter or nullnull
converter2HvdcConverter or nullnull
costGenCost or nullusage cost in pfnull
uidstring or nullunique within hvdcassigned at serialization
extrasobjectrequired

Schema definition: HvdcConverter.

fieldtypeunitsigninvariantif absent
componentComponentIdrequired
kindtoken vsc, lccrequired
loss_factor_percentfloatpercent of active powerrequired
power_factorfloat or nullnull
reactive_power_setpoint_mvarfloat or nullMVArnull
regulating_terminalTerminalReference or nullnull
voltage_regulator_onboolean or nullnull
voltage_setpoint_kvfloat or nullkVnull

Switch

A transmission switch. A closed switch stays a switch in the data; the matrix calculations do not lower it to a zero impedance branch.

Schema definition: Switch.

fieldtypeunitsigninvariantif absent
fromidnames a busrequired
toidnames a busrequired
closedbooleanrequired
thermal_ratingfloat or nullMVAnull
current_ratingfloat or nullamperesnull
pffloat or nullMWpositive flows into the switch at the from terminalnull
qffloat or nullMVArpositive flows into the switch at the from terminalnull
ptfloat or nullMWpositive flows into the switch at the to terminalnull
qtfloat or nullMVArpositive flows into the switch at the to terminalnull
uidstring or nullunique within switchesassigned at serialization
extrasobjectrequired

Transformer3W

Three windings joined at a star point; the indexed view star-lowers the record for matrix calculations. Default per-winding service states use this body directly. Nondefault states use the tagged record described below, whose nested body has the same physical fields.

Schema definitions: Transformer3W/anyOf/0, PartialTransformer3WFields.

fieldtypeunitsigninvariantif absent
namestring or nullnull
windingsarray of Windingexactly three, in the order primary, secondary, tertiaryrequired
zarray of Impedanceexactly three: z12, z23, z31required
mag_gfloatp.u. on the system baseconnected where magnetizing_connection saysrequired
mag_bfloatp.u. on the system basepositive is capacitiveconnected where magnetizing_connection saysrequired
magnetizing_connection"star_point" or "winding1_terminal"winding1_terminal connects the admittance from winding 1’s bus to ground, outside its ratio"star_point"
star_vmfloatp.u.solved star point voltagerequired
star_vafloatdegreesrequired
in_servicebooleanrequired
uidstring or nullunique within transformers_3wassigned at serialization
extrasobjectrequired

PSS/E connects MAG1 + jMAG2 from winding 1’s bus to ground, outside that winding’s ratio, and its readers state winding1_terminal; IIDM and CGMES state each leg’s admittance at the star point. The star lowering puts a winding1_terminal admittance on winding 1’s branch as from side charging Ym * tap1², which bus 1 sees as Ym, and a star_point one at the star bus. Every 0.11 document omits the field and states the star point. A writer whose format has only the other placement writes the value there and reports it with its VALUE_SUBSTITUTED code.

Two extras entries carry per winding data, in winding order. Each is present only when it differs from its default. winding_in_service holds three booleans; a winding that is out leaves the other two coupled through the star point, and an absent entry means every winding is in service. winding_rating_sets holds three arrays of {name, rate_mva} objects with the MVA ratings beyond rate_a, rate_b, and rate_c, named as in Branch.rating_sets.

PartialTransformer3W

A nondefault winding state uses structural identity "powerio.PartialTransformer3W", including when the whole transformer is off. The nested body requires extras.winding_in_service to contain exactly three booleans, not all true. An explicit all-false state is therefore also tagged. Older IR 2 readers reject this record because its required physical transformer fields are absent at the root. The body preserves all winding rows, identifiers, units, and extension data; no winding is dropped or assigned a fake impedance. Bare nondefault states and malformed tagged records are rejected.

Schema definition: PartialTransformer3WWire/oneOf/0.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.PartialTransformer3W"required
valueobjectcomplete transformer body above with nondefault winding flagsrequired

Schema definition: Winding.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
nominal_kvfloatkV0 defers to the terminal bus base_kvrequired
tapfloatratio1 is nominal (PSS/E WINDV with CW = 1)required
shiftfloatdegreesas Branch.shiftrequired
rate_afloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_bfloatMVA0 is a zero bound; +Inf is unboundedrequired
rate_cfloatMVA0 is a zero bound; +Inf is unboundedrequired
controlTransformerControl or nullnull

Schema definition: Impedance.

fieldtypeunitsigninvariantif absent
rfloatp.u. on the system baserequired
xfloatp.u. on the system baserequired
base_mvafloatMVAthe source’s declared base for the pair; positiverequired

Area

Schema definition: Area.

fieldtypeunitsigninvariantif absent
numberintegerunique within areas; matches Bus.arearequired
namestring or nullnull
net_interchangefloatMWpositive is export out of the arearequired
tolerancefloatMWrequired
slack_busid or nullnames a busnull
area_typestring or nullnull
uidstring or nullnull

StaticVarCompensator

Schema definition: StaticVarCompensator.

fieldtypeunitsigninvariantif absent
busidnames a busrequired
b_min_siemensfloatsiemensb_min_siemens <= b_max_siemensrequired
b_max_siemensfloatsiemensrequired
voltage_setpoint_kvfloatkVrequired
reactive_power_setpoint_mvarfloatMVArpositive is injectionrequired
regulation_modetoken voltage, reactive_powerrequired
regulatingbooleanrequired
regulating_terminalTerminalReference or nullnull
pfloatMWpositive is consumptionrequired
qfloatMVArpositive is consumptionrequired
in_servicebooleanrequired
uidstring or nullnull
extrasobjectrequired

SolverParams

Each member is set only when the source has it.

Schema definition: SolverParams.

fieldtypeunitsigninvariantif absent
newton_tolerancefloat or nullMW and MVAr mismatchnull
max_iterationsinteger or nullnull
zero_impedance_thresholdfloat or nullp.u. reactancenull
adjust_tapsboolean or nullnull
adjust_phase_shiftboolean or nullnull
adjust_dc_tapsboolean or nullnull
adjust_switched_shuntboolean or nullnull
adjust_area_interchangeboolean or nullnull

CaseMetadata

Schema definition: CaseMetadata.

fieldtypeunitsigninvariantif absent
case_datestring or nullnull
forecast_distanceinteger or nullminutes, as the source statesnull
source_model_formatstring or nullnull
minimum_validation_levelstring or nullnull

Coordinates

Schema definition: GeoMeta.

fieldtypeunitsigninvariantif absent
kindtoken source, synthetic, manual, derived, or nulldefault origin of points without their own kindnull

Schema definition: Location.

fieldtypeunitsigninvariantif absent
xfloatnetwork coordinate space; longitude in geographic spacerequired
yfloatnetwork coordinate space; latitude in geographic spacerequired
kindtoken as GeoMeta.kind, or nullnull (the network default)

Component references

Schema definition: ComponentId.

fieldtypeunitsigninvariantif absent
component_typestringthe element table or record kindrequired
local_idstringthe source supplied or assigned identityrequired

Schema definition: TerminalReference.

fieldtypeunitsigninvariantif absent
equipmentComponentIdrequired
terminalinteger1 for single terminal equipment, else the side numberrequired

DetailedConnectivity

The hierarchy and bus breaker or node breaker connectivity a source gives beyond the balanced calculation view (XIIDM, CGMES, PSS/E RAW 35 and RAWX). Every collection is empty when absent. The schema defines the record types under the names below. Their field names end in their units (_kv, _mw, _mvar, _a, _ohm, _h, _f, _km, _degrees, _percent, _seconds), and terminal powers use the load sign convention (positive is consumption) where the record says so.

Schema definition: DetailedConnectivity.

fieldtypeunitsigninvariantif absent
subnetworksarray of Subnetwork[]
substationsarray of Substation[]
voltage_levelsarray of VoltageLevelkVnominal_kv positive[]
bus_breaker_busesarray of BusBreakerBus[]
calculated_busesarray of CalculatedBus[]
connectivity_nodesarray of ConnectivityNode[]
busbar_sectionsarray of BusbarSection[]
junctionsarray of Junction[]
terminalsarray of Terminal[]
switchesarray of TopologySwitch[]
internal_connectionsarray of InternalConnection[]
operational_limit_groupsarray of OperationalLimitGroupamperes, MW, or MVA per limit kind[]
tap_changersarray of TapChangerlow_tap_position <= tap_position when stated[]
equipment_reactive_limitsarray of EquipmentReactiveLimitsMVAr[]
boundary_linesarray of BoundaryLine[]
tie_linesarray of TieLine[]
component_metadataarray of ComponentMetadata[]
omitted_fieldsarray of OmittedFielda field absent from the source, distinct from a stated zero[]
dc_converter_unitsarray of DcConverterUnit[]
dc_topological_nodesarray of DcTopologicalNode[]
dc_nodesarray of DcNode[]
dc_groundsarray of DcGround[]
dc_busbarsarray of DcBusbar[]
dc_linesarray of DcLine[]
dc_series_devicesarray of DcSeriesDevice[]
dc_switchesarray of DcSwitch[]
voltage_source_convertersarray of VoltageSourceConverter[]
line_commutated_convertersarray of LineCommutatedConverter[]

powerio.MulticonductorNetwork

The conductor level distribution model, in SI units (watts, vars, volts, amperes, ohms, siemens, meters) with angles in radians. Bus identifiers and terminal names are the source’s own strings; for OpenDSS the terminal names are its node numbers. An element’s terminal_map lists, in conductor order, the terminals of the named bus it connects to.

Without component geography, this is the original network body. The additive located-network alternative below carries typed points without changing these fields or their meanings.

Schema definitions: MulticonductorNetwork/anyOf/0, MulticonductorNetworkBody.

fieldtypeunitsigninvariantif absent
namestring or nullnull
base_frequencyfloatHzpositiverequired
source_formattoken dss, bmopf-json, pmd-json, cim-dist, sincal, ravens-json, pmd-math-json, pandapower-json, or nullnull
busesarray of DistBusid uniquerequired
linecodesarray of DistLineCodename uniquerequired
linesarray of DistLinebus_from, bus_to name buses; linecode names a line coderequired
switchesarray of DistSwitchbus_from, bus_to name busesrequired
transformersarray of DistTransformerevery winding bus names a busrequired
loadsarray of DistLoadbus names a busrequired
shuntsarray of DistShuntbus names a busrequired
capacitorsarray of DistCapacitorbus names a bus[]
generatorsarray of DistGeneratorbus names a busrequired
ibrsarray of DistIbrbus names a bus; control_profile names a profile[]
control_profilesarray of DistControlProfilename unique[]
sourcesarray of VoltageSourceBMOPF carries exactly onerequired
untypedarray of UntypedObjectrequired
commandsarray of [verb, args] string pairssource orderrequired
optionsarray of [name, value] string pairssource orderrequired
extrasobjectrequired
geoDistGeoMeta or nullnull

LocatedMulticonductorNetwork

The powerio.MulticonductorNetwork value can instead contain a nested "powerio.LocatedMulticonductorNetwork" record. It remains the same runtime network family. An older reader rejects the wrapper because its required electrical fields are absent at the root. This representation works wherever the network is stored, including calculation and collection values.

Schema definition: LocatedNetworkWire.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.LocatedMulticonductorNetwork"required
valueLocatedNetworkFieldsrequired

Schema definition: LocatedNetworkFields.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkBodyoriginal electrical network layout aboverequired
locationsarray of DistComponentLocationat most 1,048,576; one point per exact component identityrequired

Schema definition: DistComponentLocation.

fieldtypeunitsigninvariantif absent
targetbus, line, line_code, switch, transformer, load, generator, ibr, shunt, capacitor, sourcenames the component tablerequired
namestringexact existing component id/name; case sensitiverequired
pointDistGeographicPointindependent of drawing positions, routes and electrical lengthrequired
kindsource, synthetic, manual, derived, or nullpoint originnull

Schema definition: DistGeographicPoint.

fieldtypeunitsigninvariantif absent
latitudefloat or nulldecimal degreesnorth positivefinite, in [-90, 90]; at least one axis presentnull
longitudefloat or nulldecimal degreeseast positivefinite, in [-180, 180]; zero is a stated coordinatenull
datumstring or nullnonempty when stated; null means unknown, never implied WGS84null

DistBus

Schema definition: DistBus.

fieldtypeunitsigninvariantif absent
idstringunique within busesrequired
terminalsarray of stringordered, uniquerequired
groundedarray of stringeach names a terminal of this bus; zero impedance to groundrequired
v_minfloat or nullvoltsv_min <= v_maxnull (unbounded)
v_maxfloat or nullvoltsnull (unbounded)
v_min_phasearray of float or nullvoltsphase order excludes neutral and earth; scalar v_min takes precedencenull
v_max_phasearray of float or nullvoltsphase order excludes neutral and earth; scalar v_max takes precedencenull
vpn_minarray of float or nullvoltsper phase to neutral boundnull
vpn_maxarray of float or nullvoltsnull
vpp_minarray of float or nullvoltsper phase to phase boundnull
vpp_maxarray of float or nullvoltsnull
vpos_minfloat or nullvoltspositive sequence boundnull
vpos_maxfloat or nullvoltsnull
vneg_maxfloat or nullvoltsnegative sequence magnitude capnull
vzero_maxfloat or nullvoltszero sequence magnitude capnull
vn_maxfloat or nullvoltsneutral to ground magnitude capnull
locationDistLocation or nullnetwork coordinate spacenull
extrasobjectrequired

DistLineCode

Schema definition: DistLineCode.

fieldtypeunitsigninvariantif absent
namestringunique within linecodesrequired
n_conductorsintegerpositive; the order of every matrixrequired
r_seriesmatrixohm per metern_conductors square, symmetricrequired
x_seriesmatrixohm per metern_conductors square, symmetricrequired
g_frommatrixsiemens per meterhalf of the shunt admittance, at the from endrequired
b_frommatrixsiemens per meterpositive is capacitiverequired
g_tomatrixsiemens per meterhalf of the shunt admittance, at the to endrequired
b_tomatrixsiemens per meterpositive is capacitiverequired
i_maxarray of float or nullamperes per conductornull
s_maxarray of float or nullVA per conductornull
sourcestring or nullorigin of the matrices (BMOPF source)null
extrasobjectrequired

DistLine

Schema definition: DistLine.

fieldtypeunitsigninvariantif absent
namestringunique within linesrequired
bus_fromstringnames a busrequired
bus_tostringnames a busrequired
terminal_map_fromarray of stringn_conductors terminals of bus_fromrequired
terminal_map_toarray of stringn_conductors terminals of bus_torequired
linecodestringnames a line coderequired
lengthfloatmetersnonnegativerequired
i_maxarray of float or nullamperes per conductornull (the line code’s)
s_maxarray of float or nullVA per conductornull (the line code’s)
routearray of DistLocation or nullnetwork coordinate spacenull
extrasobjectrequired

DistSwitch

Schema definition: DistSwitch.

fieldtypeunitsigninvariantif absent
namestringunique within switchesrequired
bus_fromstringnames a busrequired
bus_tostringnames a busrequired
terminal_map_fromarray of stringterminals of bus_from, same length as terminal_map_torequired
terminal_map_toarray of stringterminals of bus_torequired
openbooleanrequired
i_maxarray of float or nullamperes per conductornull
extrasobjectrequired

DistTransformer

Schema definition: DistTransformer.

fieldtypeunitsigninvariantif absent
namestringunique within transformersrequired
phasesinteger1 through 3required
windingsarray of DistWindingtwo or threerequired
xsc_pctarray of floatpercent[xhl] for two windings, [xhl, xht, xlt] for threerequired
extrasobjectrequired

Schema definition: DistWinding.

fieldtypeunitsigninvariantif absent
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
conntoken wye, deltarequired
v_reffloatvolts, line to line for two and three phasespositiverequired
s_ratingfloatVApositiverequired
r_pctfloatpercent of the winding baserequired
tapfloatratio1 is nominalrequired
r_neutralfloat or nullohmnull
x_neutralfloat or nullohmnull

DistLoad

Schema definition: DistLoad.

fieldtypeunitsigninvariantif absent
namestringunique within loadsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
p_nomarray of floatwatts per phasepositive is consumptionone entry per active phaserequired
q_nomarray of floatvars per phasepositive is inductive consumptionsame length as p_nomrequired
voltage_modelDistLoadVoltageModelrequired
extrasobjectrequired

DistLoadVoltageModel is tagged by model. constant_power, constant_current, and constant_impedance each have v_nom (volts per active phase). zip has v_nom and the per phase coefficient arrays alpha_z, alpha_i, alpha_p (active power) and beta_z, beta_i, beta_p (reactive power), each triple summing to one. exponential has v_nom, gamma_p, and gamma_q.

DistCapacitor

Schema definition: DistCapacitor.

fieldtypeunitsigninvariantif absent
namestringunique within capacitorsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
q_ratedfloatvars, whole bank at v_nompositive is capacitive injectionrequired
v_nomfloatvolts, line to line for the three phase configurationspositiverequired
extrasobjectrequired

DistShunt

Schema definition: DistShunt.

fieldtypeunitsigninvariantif absent
namestringunique within shuntsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of bus, the order of the matricesrequired
gmatrixsiemenssquare in terminal_maprequired
bmatrixsiemenspositive is capacitivesquare in terminal_maprequired
extrasobjectrequired

DistGenerator

Schema definition: DistGenerator.

fieldtypeunitsigninvariantif absent
namestringunique within generatorsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
configurationtoken wye, delta, single_phaserequired
p_nomarray of floatwatts per phasepositive is generationrequired
q_nomarray of floatvars per phasepositive is generationsame length as p_nomrequired
p_minarray of float or nullwatts per phasep_min <= p_maxnull
p_maxarray of float or nullwatts per phasenull
q_minarray of float or nullvars per phaseq_min <= q_maxnull
q_maxarray of float or nullvars per phasenull
s_maxarray of float or nullVA per conductornull
i_maxarray of float or nullamperes per conductornull
costarray of float or nullcurrency per kWh per phase, or one scalarnull
extrasobjectrequired

DistIbr

Schema definition: DistIbr.

fieldtypeunitsigninvariantif absent
namestringunique within ibrsrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
prime_movertoken PV, BATTERY, GENERIC, STATCOM, DSTATCOMrequired
topologytoken SINGLE_PHASE, THREE_LEG, FOUR_LEGrequired
s_maxarray of floatVA per phasenameplaterequired
p_availfloat or nullwattsnull
p_minarray of float or nullwatts per phasenull
p_maxarray of float or nullwatts per phasenull
q_minarray of float or nullvars per phasenull
q_maxarray of float or nullvars per phasenull
i_maxarray of float or nullamperes per conductornull
voltage_aggregationtoken PER_PHASE, AVERAGE, or nullnull
control_profilestring or nullnames a control profilenull
extrasobjectrequired

DistControlProfile

Schema definition: DistControlProfile.

fieldtypeunitsigninvariantif absent
namestringunique within control_profilesrequired
volt_varVoltVarControl or nullnull
volt_wattVoltWattControl or nullnull
power_factorPowerFactorControl or nullnull
extrasobjectrequired

Schema definition: VoltVarControl.

fieldtypeunitsigninvariantif absent
breakpointsarray of floatp.u. voltagefour, [U1, U2, U3, U4], ascendingrequired
q_limitsarray of floatq_unitpositive is injectiontwo, [q_absorb, q_inject]: injects q_inject below U1 and absorbs q_absorb above U4required
voltage_referencetoken PN_PER_PHASE, PP_PER_PHASE, PP_AVERAGED, PG_AVERAGED, PN_AVERAGED, PG_PER_PHASE, or nullnull
q_reftoken VAR_MAX, VAR_AVAILABLE, or nullnull
q_unittoken VA_FRACTION, VAR, or nullnull
p_min_for_qfloat or nullwattsnull
p_min_for_q_maxfloat or nullwattsnull

Schema definition: VoltWattControl.

fieldtypeunitsigninvariantif absent
breakpointsarray of floatp.u. voltagetwo, [U5, U6], ascendingrequired
p_limitsarray of floatp_unittwo, [p_low, p_high] ordered by value: p_high at or below U5, p_low at or above U6; a VA_FRACTION limit is a fraction of the p_ref base, S_MAX when absentrequired
voltage_referencetoken as VoltVarControl.voltage_reference, or nullnull
p_reftoken P_AVAILABLE, P_MAX, S_MAX, or nullnull
p_unittoken VA_FRACTION, W, or nullnull

Schema definition: PowerFactorControl.

fieldtypeunitsigninvariantif absent
pffloatpositive when Q has the same sign as P, negative when opposite (the OpenDSS PVSystem and Storage convention)0 < abs(pf) <= 1required

VoltageSource

An earth-referenced source retains the original record below. A source with an explicit reference terminal uses the separately tagged record described after it; it must not add a bare reference field to this legacy record.

Schema definition: VoltageSource/anyOf/0 (the earth-referenced branch).

fieldtypeunitsigninvariantif absent
namestringunique within sourcesrequired
busstringnames a busrequired
terminal_maparray of stringterminals of busrequired
v_magnitudearray of floatvolts per terminal0 on a grounded terminal; same length as terminal_maprequired
v_anglearray of floatradians per terminalsame length as terminal_maprequired
energy_cost_rateoptional array of float$/kWhpositive injection supplies the networkone entry per phase in terminal-map order; excludes neutral terminalsno stated source-price term
extrasobjectrequired

ReferencedVoltageSource

The second source-record alternative has structural identity "powerio.ReferencedVoltageSource". Older IR 2 readers reject this wrapper because the legacy source fields are absent at its root. Existing records remain unchanged. The source can occur anywhere a multiconductor network is stored, including collections and calculation instances.

Schema definition: ReferencedSourceWire/oneOf/0.

fieldtypeunitsigninvariantif absent
typestringexactly "powerio.ReferencedVoltageSource"required
valueobjectreferenced source body belowrequired

Schema definition: ReferencedSourceFields.

fieldtypeunitsigninvariantif absent
namestringunique within sourcesrequired
busstringnames a busrequired
terminal_maparray of stringdistinct declared terminals of bus; excludes the referencerequired
v_magnitudearray of floatvolts per terminal-to-reference differencesame length as terminal_map; a grounded phase can have a nonzero differencerequired
v_anglearray of floatradians per terminal-to-reference differencesame length as terminal_maprequired
reference_terminalstringanother declared terminal on bus; does not imply groundingrequired
energy_cost_rateoptional array of float$/kWhpositive injection supplies the networkper phase in terminal-map orderno stated source-price term
extrasobjectrequired

The voltage constraint is V(terminal) - V(reference) = magnitude * exp(i*angle). Every phase-source current has an equal opposite contribution at the reference. Neither an external neutral connection nor an earth path is inferred.

UntypedObject

An object the reader recognized but does not type, kept so a conversion can report it precisely.

Schema definition: UntypedObject.

fieldtypeunitsigninvariantif absent
classstringrequired
namestringrequired
propsarray of [key, value] string pairssource orderrequired

Distribution coordinates

Schema definition: DistGeoMeta.

fieldtypeunitsigninvariantif absent
kindtoken source, synthetic, manual, derived, or nullnull

Schema definition: DistLocation.

fieldtypeunitsigninvariantif absent
xfloatnetwork coordinate space; longitude in geographic spacerequired
yfloatnetwork coordinate space; latitude in geographic spacerequired
kindtoken as DistGeoMeta.kind, or nullnull (the network default)

powerio.GeoLayer

A standalone geographic document: element points and routes in one coordinate space, keyed by element identity rather than embedded in a case. The canonical .geo.json, GeoJSON, aliased CSV or JSON records, headerless buscoords CSV, and a PowerWorld .pwd display all parse to one, and apply_geo_layer places it onto a network.

Schema definition: GeoLayer.

fieldtypeunitsigninvariantif absent
spaceCoordinateSpacethe space every feature’s coordinates are inrequired
kindtoken source, synthetic, manual, derived, or nulldefault origin of features without their own kindnull
featuresarray of GeoFeatureempty

CoordinateSpace is tagged by space. geographic has an optional crs; x is longitude and y latitude in decimal degrees, and a null crs means EPSG:4326. projected has an optional crs for planar coordinates. diagram has an optional canvas for drawing coordinates with no earth referent. unknown has no further member and means the source declared no space.

Schema definition: Canvas.

fieldtypeunitsigninvariantif absent
widthfloat or nullcanvas unitspositivethe drawing width the source statesnull
heightfloat or nullcanvas unitspositivethe drawing height the source statesnull
unitsstring or nullthe source’s own name for its canvas unitsnull

GeoFeature

Schema definition: GeoFeature.

fieldtypeunitsigninvariantif absent
targettoken bus, branch, or substationthe element family the feature placesrequired
keyElementKeyat least one member names an element, unless a branch states both endpointsrequired
geometryGeoGeometryevery coordinate is finiterequired
fromstring or nulla branch’s endpoint bus, the unordered fallback identitynull
tostring or nullthe other endpoint busnull
kindtoken as GeoLayer.kind, or nullnull (the layer default)

GeoGeometry is one tagged object: point is a single [x, y] position for a placed element, and line_string is an array of [x, y] positions for a route. Positions are in the layer’s coordinate space, a route has at least one, and every coordinate is finite.

ElementKey

Matching tries uid, then id, then case insensitive name; a branch additionally falls back to the unordered (from, to) bus pair.

Schema definition: ElementKey.

fieldtypeunitsigninvariantif absent
uidstring or nullthe durable identity (buses:3, branches:7)null
idstring or nullthe source’s own element identifiernull
namestring or nullmatched case insensitivelynull
indexinteger or nullpositive1-based row alias, accepted on read and never writtennull

powerio.ContingencySet

One PSS/E contingency description file (.con): the outages a contingency analysis runs. Reading holds what the file states and touches no network; ContingencySet::resolve binds a set to the elements of a network, and ContingencySet::expand turns the automatic specifications into explicit cases over a subsystem set. A statement the grammar does not cover keeps its original line, so a document written back with to_con states everything the source did.

Schema definition: ContingencySet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
casesarray of ContingencyCasein file orderempty
automaticarray of AutomaticSpecin file orderempty
skipsarray of SkipRulethe branches automatic expansion leaves aloneempty
retainedarray of RetainedStatementfile level statements outside the grammarempty

ContingencyCase

Every action of one case applies together.

Schema definition: ContingencyCase.

fieldtypeunitsigninvariantif absent
namestringnonemptyrequired
actionsarray of ContingencyActionin file orderempty

ContingencyAction is one tagged object, keyed by kind. open_branch names from, to, and circuit; open_three_winding names buses, three bus identifiers, and circuit. remove_machine and add_machine name bus and id. remove_shunt and remove_load name bus and an optional id, and a statement with no id names every such element at the bus. remove_switched_shunt and disconnect_bus name bus alone. change_load and change_generation name bus and a Change. unrecognized carries the original text, and a nested dispatch block keeps all of its lines joined with newlines.

Schema definition: Change.

fieldtypeunitsigninvariantif absent
optoken increase, decrease, or setwhether the amount adds to, subtracts from, or replaces the present valuerequired
amountfloatMW or percent, as unit sayspositive is the stated magnitudefiniterequired
unittoken mw or percentrequired

AutomaticSpec

One specification expands into one case per element of a subsystem.

Schema definition: AutomaticSpec.

fieldtypeunitsigninvariantif absent
ordertoken single or doublehow many elements one case outagesrequired
targettoken branch, unit, or tiethe element family the expansion draws from; tie is the branches crossing the subsystem borderrequired
subsystemstringnames a subsystem of the .sub file the expansion runs againstrequired
low_voltage_3wboolean3WLOWVOLTAGE: a branch expansion also takes the low voltage winding of a three winding transformerrequired

Schema definition: SkipRule.

fieldtypeunitsigninvariantif absent
fromidone terminal of the excluded branchrequired
toidthe other terminalrequired
circuitstringthe branch circuit idrequired

RetainedStatement

A statement outside the grammar of its file, kept as the source wrote it. The three contingency analysis files share this record.

Schema definition: RetainedStatement.

fieldtypeunitsigninvariantif absent
lineintegerthe 1-based source line the statement was read from; at least 1required
textstringthe line, with its surrounding whitespace droppedrequired
after_endbooleanthe statement follows the file level END, and the .con writer states it after the END it writes; the .sub and .mon writers state every kept statement before theirs, so it is false therefalse

powerio.SubsystemSet

One PSS/E subsystem description file (.sub): the named bus groups a contingency description file and a monitored element file draw on. Subsystem::select_buses names the buses of one subsystem in a network, and SubsystemSet::to_sub writes the set back.

Schema definition: SubsystemSet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
subsystemsarray of Subsystemin file orderempty
retainedarray of RetainedStatementfile level statements outside the grammarempty

Subsystem

A subsystem is the union of its selector groups.

Schema definition: Subsystem.

fieldtypeunitsigninvariantif absent
namestringnonempty; a .con or .mon statement names it without caserequired
groupsarray of SelectorGroupthe implicit group comes first when it has any selectorempty
retainedarray of RetainedStatementstatements inside this subsystem, and outside any JOIN group, that are outside the grammarempty

Schema definition: SelectorGroup.

fieldtypeunitsigninvariantif absent
joinJoinName or nullhow the file stated the group; null is the implicit group, which holds the selectors stated outside any JOINnull
selectorsarray of SubsystemSelectorbus sets that intersect across selector types within one groupempty
retainedarray of RetainedStatementlines read while this JOIN was open that are outside the grammar; the implicit group holds noneempty

JoinName is one tagged object, keyed by kind: anonymous has no further member and states a JOIN with no name, and named carries the group name. Two groups stated anonymous are two groups, whose bus sets union.

SubsystemSelector is one tagged object, keyed by kind. area, zone, and owner name an inclusive from and to number range; bus names an inclusive range of bus identifiers; kv_range names an inclusive base kV band whose lo is at most its hi. A source statement naming one value reads as a range whose two ends are equal.

powerio.MonitoredSet

One PSS/E monitored element file (.mon): the branch flows, interface flows, and bus voltages a contingency analysis reports on. MonitoredSet::resolve binds the statements to the rows of a network against a subsystem set, and MonitoredSet::to_mon writes the set back.

Schema definition: MonitoredSet.

fieldtypeunitsigninvariantif absent
headerarray of stringthe comment lines ahead of the first statement, as writtenempty
statementsarray of MonitorStatementin file orderempty
retainedarray of RetainedStatementstatements outside the grammarempty

MonitorStatement is one tagged object, keyed by kind. branches_in_subsystem names a subsystem and low_voltage_3w, and takes every branch with both terminals in it. ties_from_subsystem names a subsystem and takes every branch with exactly one terminal in it. branches carries the branches a MONITOR BRANCHES block lists. interface names the interface name, an optional rating_mw, and the branches whose flows sum over it. Both carry the block’s lines that state no branch as retained. voltage_range names a scope and a vmin at most its vmax, both in per unit. voltage_deviation names a scope, a down limit, and an optional up limit; a source statement naming one value states the downward limit alone.

MonitorScope is one tagged object, keyed by kind: all_buses has no further member, subsystem carries a subsystem name, bus a bus identifier, area, zone, and owner a number under their own name, and kv a base kV value.

Schema definition: BranchRef.

fieldtypeunitsigninvariantif absent
fromidone terminal of the monitored branchrequired
toidthe other terminalrequired
circuitstringthe branch circuit id; an absent id in the source reads as 1required

powerio.OperatingPoint<N>

An alternate electrical assignment, possibly partial, over the fixed component identities of one base network N: demand, setpoints, dispatch, voltages, injections, service status, switch positions, transformer taps, and phase shifts. Any quantity the point leaves out resolves to the network’s own value.

Schema definitions: StoredOperatingPoint, StoredOperatingPoint2.

fieldtypeunitsigninvariantif absent
networkBalancedNetwork or MulticonductorNetwork, as the type name saysthe complete base networkrequired
quantitiesmap of quantity name to StoredQuantityper quantity, belowkeys among the quantity names of the network familyrequired

Schema definition: StoredQuantity.

fieldtypeunitsigninvariantif absent
identitiesarray of stringeach names a component of the network; unique; same length as valuesrequired
valuesarray of floatthe quantity’s unit; a flag is 0 or 1required

identities and values carry at most 4,194,304 entries each; see Resource limits.

An operating point stored inside a collection or an instance omits the network, because the enclosing record gives it once.

Schema definition: StoredOperatingPointAssignment.

fieldtypeunitsigninvariantif absent
quantitiesmap of quantity name to StoredQuantityas StoredOperatingPoint.quantitiesrequired

Balanced quantities. A bus quantity is keyed by the bus id’s decimal spelling; an element quantity by the element’s uid.

quantitykeyed byunitsign
bus_voltage_magnitudebus idp.u.
bus_voltage_anglebus iddegrees
bus_active_injectionbus idMWpositive into the network
bus_reactive_injectionbus idMVArpositive into the network
generator_active_powergenerator uidMWpositive is generation
generator_reactive_powergenerator uidMVArpositive is generation
generator_voltage_setpointgenerator uidp.u.
generator_in_servicegenerator uidflag
load_active_powerload uidMWpositive is consumption
load_reactive_powerload uidMVArpositive is consumption
branch_in_servicebranch uidflag
branch_tap_ratiobranch uidratio
branch_phase_shiftbranch uiddegreesas Branch.shift
switch_closedswitch uidflag

Multiconductor quantities. A terminal quantity is keyed bus_id/terminal, a per phase element quantity element_name/terminal, and a whole element quantity by the element name.

quantitykeyed byunitsign
terminal_voltage_magnitudebus/terminalvolts
terminal_voltage_anglebus/terminalradians
load_active_powerload/terminalwattspositive is consumption
load_reactive_powerload/terminalvarspositive is consumption
generator_active_powergenerator/terminalwattspositive is generation
generator_reactive_powergenerator/terminalvarspositive is generation
transformer_taptransformer nameratio
capacitor_stepscapacitor namecount
switch_closedswitch nameflag

powerio.TimeSeries<T>

Ordered time points and one value of T per point. Labels are the source’s own; PowerIO imposes no calendar meaning.

Schema definitions: StoredTimeSeries, StoredTimeSeries2.

fieldtypeunitsigninvariantif absent
time_pointsarray of TimePointrequired
valuesarray of the element type, each a complete networksame length as time_pointsrequired

A series of operating points gives the shared base network once.

Schema definitions: StoredOperatingPointTimeSeries, StoredOperatingPointTimeSeries2.

fieldtypeunitsigninvariantif absent
networkthe base network, or nullnull only for an empty seriesrequired when values is nonempty
time_pointsarray of TimePointrequired
valuesarray of StoredOperatingPointAssignmentsame length as time_points; identities name components of networkrequired

Schema definition: TimePoint.

fieldtypeunitsigninvariantif absent
labelstringnonempty, boundedrequired
durationDuration or nullthe interval the point coversnull

Schema definition: Duration.

fieldtypeunitsigninvariantif absent
secsintegersecondsrequired
nanosintegernanosecondsbelow one billionrequired

powerio.ScenarioSet<T>

Named alternatives of T with no implied order. Either every scenario has a probability or none does; when present, the probabilities are nonnegative and sum to one within SCENARIO_PROBABILITY_TOLERANCE.

Schema definitions: StoredScenarioSet, StoredScenarioSet2, StoredScenarioSet3, StoredScenarioSet4, StoredScenarioSet5, StoredScenarioSet6.

fieldtypeunitsigninvariantif absent
scenariosarray of the scenario recordid uniquerequired

Schema definitions: StoredScenario, StoredScenario2, StoredScenario3, StoredScenario4, StoredScenario5, StoredScenario6.

fieldtypeunitsigninvariantif absent
idstringnonempty, bounded, unique in the setrequired
probabilityfloat or nullin [0, 1]null
valuethe element type: a network, a network time series, or an operating point time seriesrequired

A scenario set of operating points gives the shared base network once.

Schema definitions: StoredOperatingPointScenarioSet, StoredOperatingPointScenarioSet2.

fieldtypeunitsigninvariantif absent
networkthe base network, or nullnull only for an empty setrequired when scenarios is nonempty
scenariosarray of StoredOperatingPointScenarioid uniquerequired

Schema definition: StoredOperatingPointScenario.

fieldtypeunitsigninvariantif absent
idstringnonempty, bounded, unique in the setrequired
probabilityfloat or nullin [0, 1]null
quantitiesmap of quantity name to StoredQuantityidentities name components of networkrequired

Instances

An instance is the complete input to one named calculation, including the network it runs over. An instance may also include an initial_point, a starting operating assignment a solver may use, whose identities refer to components of the instance’s network.

powerio.DcPfInstance

Schema definition: DcPfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF busrequired
approximationtoken series_susceptance, tap_adjusted_reactance, reactance_only, tap_adjusted_series_susceptance, series_susceptance_no_phase_shiftthe DC branch susceptance formularequired
initial_pointStoredOperatingPointAssignment or nullnull
hvdc_treatmenttoken fixed_injection, ignorehow the specifications treat HVDC lines; written only when not ignoreignore

The bus specifications are derived from the network: a REF bus contributes its stated angle, an ISOLATED bus no equation, and every other bus its net active injection over in service generators and loads. Under fixed_injection each in service HVDC line whose terminal buses are energized adds a fixed injection of -pf at its from bus and +pt at its to bus; under ignore HVDC lines add nothing. A document without hvdc_treatment reads as ignore: a document written before the field existed, when the instance left HVDC lines out, denotes the calculation it did when written, and an ignore instance is written without the field.

powerio.AcPfInstance

Schema definition: AcPfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF busrequired
specificationsarray of AcBusSpecificationone per bus, in bus table orderrequired
initial_pointStoredOperatingPointAssignment or nullnull
hvdc_treatmenttoken fixed_injection, ignorehow specifications derived for a replacement network treat HVDC lines; written only when not ignoreignore

AcBusSpecification is tagged by kind. pq gives p (MW) and q (MVAr), the prescribed net injection; pv gives p and vm (p.u.); reference gives vm and va (degrees); isolated gives nothing. Powers are net injections into the network, positive for generation.

powerio.DcOpfInstance

Schema definition: DcOpfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF bus and one in service generator on a non isolated busrequired
objectiveObjectiverequired
constraintsActiveConstraintsrequired
approximationtoken as DcPfInstance.approximationrequired
initial_pointStoredOperatingPointAssignment or nullnull

powerio.AcOpfInstance

Schema definition: AcOpfInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkat least one REF bus and one in service generator on a non isolated busrequired
objectiveObjectiverequired
constraintsActiveConstraintsrequired
initial_pointStoredOperatingPointAssignment or nullnull

Schema definition: Objective.

fieldtypeunitsigninvariantif absent
termsarray of ObjectiveTermempty is a feasibility problem[]

ObjectiveTerm is tagged by term: network_generator_cost sums the network’s generator cost curves; active_power_dispatch_cost prices active dispatch; branch_switching_cost adds the opening and closing costs of an AC optimal transmission switching instance’s status changes.

Schema definition: ActiveConstraints.

fieldtypeunitsigninvariantif absent
generator_capabilityConstraintSelectionactive and reactive generator limitsrequired
voltage_boundsConstraintSelectionbus voltage magnitude boundsrequired
thermal_limitsConstraintSelectionbranch thermal limitsrequired
angle_boundsConstraintSelectionbranch angle difference boundsrequired

ConstraintSelection is tagged by select: all (every element with a stated limit), none (the family is relaxed), or only with identities, the list of element identities (uid values, or bus ids) the family applies to.

powerio.AcOtsInstance

An AC optimal power flow problem whose branch statuses are decisions. The base network keeps every physical branch, and its in_service bits are the initial topology.

Schema definition: AcOtsInstance.

fieldtypeunitsigninvariantif absent
baseAcOpfInstancethe network, objective, constraint selections, and initial pointrequired
optionsAcOtsOptionsrequired

Schema definition: AcOtsOptions.

fieldtypeunitsigninvariantif absent
switchableBranchSelectionan only identity names one branch, oncerequired
switching_costsarray of BranchSwitchingCostone record per branch at most[]: switching costs nothing
islandingtokenforbidden (no AC island of the initial topology may split; islands that are separate initially stay valid, and closing a branch may join islands) or allowed (islands may split, and each final island gets one reference bus). Under either policy a final topology that leaves buses a generator supplied initially in an island with no in-service generator is refused; no load is shedrequired
max_openinteger or nullbranchesat most the branch count, at least the open branches that cannot switch; counts every open branchnull: no budget
max_switchedinteger or nullbranchesat most the switchable count; counts changes against the initial statusnull: no budget
current_limitstokenskip, stated (the records below), or derive_from_rate_a (PowerModels’ calc_current_limits!)required
stated_current_limitsarray of BranchCurrentLimitone record per branch at most[]

BranchSelection is tagged by select: all (every physical branch, including initially open ones), none, or only with identities, the branch identities (uid values) that may switch.

Schema definition: BranchSwitchingCost.

fieldtypeunitsigninvariantif absent
idstringa branch identityrequired
open_costfloatobjective unitsfinite and nonnegative; charged when an initially closed branch opensrequired
close_costfloatobjective unitsfinite and nonnegative; charged when an initially open branch closesrequired

Schema definition: BranchCurrentLimit.

fieldtypeunitsigninvariantif absent
idstringa branch identityrequired
from_pufloat or nullp.u. on base_mva and the from bus base_kvfinite and positivenull: unbounded
to_pufloat or nullp.u. on base_mva and the to bus base_kvfinite and positivenull: unbounded

powerio.McAcPfInstance

Schema definition: McAcPfInstance.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkat least one voltage sourcerequired
initial_pointStoredOperatingPointAssignment or nullnull

The prescribed terminal powers, source voltages, and active regulator and capacitor controls are derived from the network.

powerio.McAcOpfInstance

Schema definition: McAcOpfInstance.

fieldtypeunitsigninvariantif absent
networkMulticonductorNetworkat least one voltage sourcerequired
objectiveObjectiverequired
constraintsMulticonductorActiveConstraintsrequired
initial_pointStoredOperatingPointAssignment or nullnull

powerio.LinDist3FlowPfInstance

The fixed-dispatch instance carries the same coefficient formulation as the OPF type, but its objective is empty and conductor limits are monitored after a converged solve rather than enforced as conic constraints.

Schema definition: LinDist3FlowPfInstance.

fieldtypeunitsigninvariantif absent
formulationLinDist3FlowOpfInstancezero objective, fixed generator dispatch, and conductor_limits selected as nonerequired

powerio.LinDist3FlowOpfInstance

Schema definition: LinDist3FlowOpfInstance.

fieldtypeunitsigninvariantif absent
baseMcAcOpfInstancecomplete multiconductor AC OPF instancerequired
optionsLinDist3FlowBuildOptionsfixed reference, unsupported-data, and neutral-provenance policies used to construct the formulationrequired

Schema definition: LinDist3FlowBuildOptions.

fieldtypeunitsigninvariantif absent
reference_policyauto, explicit, or source_propagatedselects the fixed coefficient phasorsrequired
unsupportedreject, lower, approximate, or permissiveselects the audited preparation-policy levelrequired
require_neutral_provenanceboolrequires a recorded neutral-Kron projection when truerequired

Schema definition: MulticonductorActiveConstraints.

fieldtypeunitsigninvariantif absent
terminal_voltage_boundsConstraintSelectionrequired
conductor_limitsConstraintSelectioncurrent or apparent power limitsrequired
generator_capabilityConstraintSelectionper phase boundsrequired

powerio.AcScucInstance

The DOE GO Challenge 3 formulation: one balanced network plus scheduling, reserve, and contingency inputs. Powers in the inputs are per unit on the network’s base_mva, times are hours from the start of the horizon, and costs are dollars or dollars per per unit hour, as the data format gives them.

Schema definition: AcScucInstance.

fieldtypeunitsigninvariantif absent
networkBalancedNetworkrequired
inputsScucInputsidentities name components of network; time varying records match the horizonrequired

Schema definition: ScucInputs.

fieldtypeunitsigninvariantif absent
interval_durationsarray of floathourspositive; chronologicalrequired
devicesarray of ScucDeviceid uniquerequired
active_reserve_zonesarray of ScucActiveReserveZonerequired
reactive_reserve_zonesarray of ScucReactiveReserveZonerequired
contingenciesarray of ScucContingencyrequired
shuntsarray of ScucShuntrequired
transformer_controlsarray of ScucTransformerControlrequired
branch_switching_costsarray of ScucBranchSwitchingCostrequired
violation_costsScucViolationCostsrequired

Schema definition: ScucDevice.

fieldtypeunitsigninvariantif absent
idComponentIdthe generator or load in the networkrequired
kindtoken producer, consumerrequired
on_costfloatdollarsrequired
startup_costfloatdollarsrequired
shutdown_costfloatdollarsrequired
initial_on_statusbooleanrequired
initial_commitmentScucInitialCommitmentrequired
minimum_up_timefloathoursrequired
minimum_down_timefloathoursrequired
ramp_limitsScucRampLimitsrequired
reserve_limitsScucReserveLimitsrequired
reactive_capabilityScucReactiveCapabilityrequired
energy_lower_boundsarray of ScucEnergyRequirementrequired
energy_upper_boundsarray of ScucEnergyRequirementrequired
startup_cost_adjustmentsarray of ScucStartupCostAdjustmentrequired
startup_limitsarray of ScucStartupLimitrequired
periodsarray of ScucDevicePeriodone per interval, chronologicalrequired

ScucReactiveCapability is tagged by kind: none; linear with reactive_power_at_zero_active_power and a slope; bounded with the _max and _min forms of both.

Schema definition: ScucDevicePeriod.

fieldtypeunitsigninvariantif absent
on_status_minbooleanrequired
on_status_maxbooleanrequired
active_power_minfloatp.u.active_power_min <= active_power_maxrequired
active_power_maxfloatp.u.required
reactive_power_minfloatp.u.reactive_power_min <= reactive_power_maxrequired
reactive_power_maxfloatp.u.required
energy_cost_blocksarray of ScucEnergyCostBlockrequired
reserve_costsScucReserveCostsrequired

Schema definition: ScucEnergyCostBlock.

fieldtypeunitsigninvariantif absent
block_sizefloatp.u.nonnegativerequired
marginal_costfloatdollars per p.u. hourrequired

Schema definition: ScucReserveCosts.

fieldtypeunitsigninvariantif absent
regulation_upfloatdollars per p.u. hourrequired
regulation_downfloatdollars per p.u. hourrequired
synchronizedfloatdollars per p.u. hourrequired
nonsynchronizedfloatdollars per p.u. hourrequired
ramping_up_onlinefloatdollars per p.u. hourrequired
ramping_up_offlinefloatdollars per p.u. hourrequired
ramping_down_onlinefloatdollars per p.u. hourrequired
ramping_down_offlinefloatdollars per p.u. hourrequired
reactive_upfloatdollars per p.u. hourrequired
reactive_downfloatdollars per p.u. hourrequired

Schema definition: ScucReserveLimits.

fieldtypeunitsigninvariantif absent
regulation_upfloatp.u.nonnegativerequired
regulation_downfloatp.u.nonnegativerequired
synchronizedfloatp.u.nonnegativerequired
nonsynchronizedfloatp.u.nonnegativerequired
ramping_up_onlinefloatp.u.nonnegativerequired
ramping_up_offlinefloatp.u.nonnegativerequired
ramping_down_onlinefloatp.u.nonnegativerequired
ramping_down_offlinefloatp.u.nonnegativerequired

Schema definition: ScucRampLimits.

fieldtypeunitsigninvariantif absent
upfloatp.u. per hournonnegativerequired
downfloatp.u. per hournonnegativerequired
startupfloatp.u. per hournonnegativerequired
shutdownfloatp.u. per hournonnegativerequired

Schema definition: ScucInitialCommitment.

fieldtypeunitsigninvariantif absent
accumulated_up_timefloathoursnonnegativerequired
accumulated_down_timefloathoursnonnegativerequired

Schema definition: ScucEnergyRequirement.

fieldtypeunitsigninvariantif absent
start_timefloathoursstart_time <= end_timerequired
end_timefloathoursrequired
energyfloatp.u. hourrequired

Schema definition: ScucStartupCostAdjustment.

fieldtypeunitsigninvariantif absent
maximum_down_timefloathoursrequired
costfloatdollarsrequired

Schema definition: ScucStartupLimit.

fieldtypeunitsigninvariantif absent
start_timefloathoursstart_time <= end_timerequired
end_timefloathoursrequired
maximum_startupsintegerrequired

Schema definition: ScucActiveReserveZone.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
busesarray of ComponentIdeach names a bus of the networkrequired
regulation_up_requirement_fractionfloatfraction of zone loadrequired
regulation_down_requirement_fractionfloatfraction of zone loadrequired
synchronized_requirement_fractionfloatfraction of zone loadrequired
nonsynchronized_requirement_fractionfloatfraction of zone loadrequired
ramping_up_requirementarray of floatp.u.one per intervalrequired
ramping_down_requirementarray of floatp.u.one per intervalrequired
regulation_up_violation_costfloatdollars per p.u. hourrequired
regulation_down_violation_costfloatdollars per p.u. hourrequired
synchronized_violation_costfloatdollars per p.u. hourrequired
nonsynchronized_violation_costfloatdollars per p.u. hourrequired
ramping_up_violation_costfloatdollars per p.u. hourrequired
ramping_down_violation_costfloatdollars per p.u. hourrequired

Schema definition: ScucReactiveReserveZone.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
busesarray of ComponentIdeach names a bus of the networkrequired
reactive_up_requirementarray of floatp.u.one per intervalrequired
reactive_down_requirementarray of floatp.u.one per intervalrequired
reactive_up_violation_costfloatdollars per p.u. hourrequired
reactive_down_violation_costfloatdollars per p.u. hourrequired

Schema definition: ScucContingency.

fieldtypeunitsigninvariantif absent
idComponentIduniquerequired
componentsarray of ComponentIdChallenge 3 requires exactly one AC line, transformer, or DC linerequired

Schema definition: ScucShunt.

fieldtypeunitsigninvariantif absent
idComponentIdthe shunt in the networkrequired
initial_stepintegerstep_min <= initial_step <= step_maxrequired
step_minintegerrequired
step_maxintegerrequired
conductance_per_stepfloatp.u.required
susceptance_per_stepfloatp.u.positive is capacitiverequired

Schema definition: ScucTransformerControl.

fieldtypeunitsigninvariantif absent
idComponentIdthe two winding transformer in the networkrequired
tap_ratio_minfloatp.u.tap_ratio_min <= tap_ratio_maxrequired
tap_ratio_maxfloatp.u.required
phase_shift_minfloatradiansphase_shift_min <= phase_shift_maxrequired
phase_shift_maxfloatradiansrequired

Schema definition: ScucBranchSwitchingCost.

fieldtypeunitsigninvariantif absent
idComponentIdthe branch or transformer in the networkrequired
connection_costfloatdollarsrequired
disconnection_costfloatdollarsrequired

Schema definition: ScucViolationCosts.

fieldtypeunitsigninvariantif absent
active_power_balancefloatdollars per p.u. hourrequired
reactive_power_balancefloatdollars per p.u. hourrequired
branch_thermal_limitfloatdollars per p.u. hourrequired
energy_requirementfloatdollars per p.u. hourrequired

Solutions

A solution contains the instance it solves, and its arrays follow the instance network’s table order: one entry per bus, per branch, or per generator. Injections are net injections into the network at a bus, positive for generation; branch flows are measured into the branch at the named terminal. Each solution says how the calculation ended and what residuals the producer reported. producer is the producer’s free text solver identity, or null. In the DC, AC, SOCWR, multiconductor, and LinDist3Flow solutions, a per bus, branch, generator, terminal, source, or conductor array carries at most 4,194,304 entries; see Resource limits.

Termination is tagged by kind: converged, iteration_limit, infeasible, unbounded, failed, or not_reported, for a source that stores a solved calculation without termination information, as DeepMind OPFData does.

Schema definition: Residuals.

fieldtypeunitsigninvariantif absent
max_active_power_mismatchfloat or nullMWlargest absolute active balance mismatchnull (not reported)
max_reactive_power_mismatchfloat or nullMVArlargest absolute reactive balance mismatchnull (not reported)

Schema definition: GeneratorDispatch.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive is generationone per generatorrequired
q_mvararray of floatMVArpositive is generationone per generator, or emptyrequired

Schema definition: ThreeWindingTransformerTerminalActivePower.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive flows into the transformer at the windingthree entries, winding orderrequired

Schema definition: ThreeWindingTransformerTerminalPower.

fieldtypeunitsigninvariantif absent
p_mwarray of floatMWpositive flows into the transformer at the windingthree entries, winding orderrequired
q_mvararray of floatMVArpositive flows into the transformer at the windingthree entries, winding orderrequired

powerio.DcPfSolution

Schema definition: DcPfSolution.

fieldtypeunitsigninvariantif absent
instanceDcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_active_powersarray of ThreeWindingTransformerTerminalActivePowerone per three winding transformerrequired
generator_dispatchGeneratorDispatch or nullnull

powerio.AcPfSolution

Schema definition: AcPfSolution.

fieldtypeunitsigninvariantif absent
instanceAcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_magnitudearray of floatp.u.one per busrequired
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
bus_reactive_injectionarray of floatMVArpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired
generator_dispatchGeneratorDispatch or nullnull

powerio.DcOpfSolution

Multipliers and marginals are the optimizing producer’s optional economic outputs, in the objective’s units per MW; no currency is assumed.

Schema definition: DcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceDcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
three_winding_transformer_terminal_active_powersarray of ThreeWindingTransformerTerminalActivePowerone per three winding transformerrequired
objectivefloatobjective unitsrequired
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
branch_from_limit_multiplierarray of float or nullobjective units per MWone per branch; finite and nonnegativenull
branch_to_limit_multiplierarray of float or nullobjective units per MWone per branch; finite and nonnegativenull

powerio.AcOpfSolution

Schema definition: AcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
bus_voltage_magnitudearray of floatp.u.one per busrequired
bus_voltage_anglearray of floatdegreesone per busrequired
bus_active_injectionarray of floatMWpositive into the networkone per busrequired
bus_reactive_injectionarray of floatMVArpositive into the networkone per busrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
generator_reactive_powerarray of floatMVArpositive is generationone per generatorrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired
objectivefloatobjective unitsrequired
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
bus_reactive_power_marginalarray of float or nullobjective units per MVArone per busnull
branch_from_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull
branch_to_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull

powerio.AcOtsSolution

The final branch statuses of an AC optimal transmission switching instance and the AC optimal power flow solution of the fixed-topology problem they derive. Reading the document checks the topology against the instance and requires ac_solution.instance to state exactly that fixed problem and every open branch to carry zero flow. A NaN flow on an open branch records no flow. Other values follow the AC optimal power flow solution’s own rules, which accept NaN for an out-of-service generator or a non-converged objective. The objective is the AC objective plus the switching cost when the instance’s objective states branch_switching_cost.

Schema definition: AcOtsSolution.

fieldtypeunitsigninvariantif absent
instanceAcOtsInstancerequired
branch_closedarray of booleanone per branch; fixed branches unchanged; within the budgets and islanding policyrequired
ac_solutionAcOpfSolutionsolves the fixed-topology problem; open branches carry zero flowrequired

powerio.SocwrOpfSolution

The PowerModels SOCWR relaxation of an AcOpfInstance. Its objective is a lower bound, and its voltage products make no claim of an AC feasible phasor.

Schema definition: SocwrOpfSolution.

fieldtypeunitsigninvariantif absent
instanceAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
valuesSocwrOpfValuesrequired
dualsSocwrOpfDualsevery member null
objective_lower_boundfloatobjective unitsrequired

Schema definition: SocwrOpfValues.

fieldtypeunitsigninvariantif absent
bus_voltage_magnitude_squaredarray of floatp.u. squaredw[i] = |V_i|^2; one per busrequired
branch_voltage_product_realarray of floatp.u. squaredRe(V_from conj(V_to)); one per branchrequired
branch_voltage_product_imaginaryarray of floatp.u. squaredIm(V_from conj(V_to)); one per branchrequired
generator_active_powerarray of floatMWpositive is generationone per generatorrequired
generator_reactive_powerarray of floatMVArpositive is generationone per generatorrequired
branch_from_active_flowarray of floatMWpositive into the branch at the from terminalone per branchrequired
branch_from_reactive_flowarray of floatMVArpositive into the branch at the from terminalone per branchrequired
branch_to_active_flowarray of floatMWpositive into the branch at the to terminalone per branchrequired
branch_to_reactive_flowarray of floatMVArpositive into the branch at the to terminalone per branchrequired
three_winding_transformer_terminal_powersarray of ThreeWindingTransformerTerminalPowerone per three winding transformerrequired

The four branch flow keys were branch_from_active_power, branch_from_reactive_power, branch_to_active_power, and branch_to_reactive_power in 0.11; the reader accepts those spellings in a 0.11 document.

Schema definition: SocwrOpfDuals.

fieldtypeunitsigninvariantif absent
bus_active_power_marginalarray of float or nullobjective units per MWone per busnull
bus_reactive_power_marginalarray of float or nullobjective units per MVArone per busnull
branch_from_thermal_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull
branch_to_thermal_limit_multiplierarray of float or nullobjective units per MVAone per branch; finite and nonnegativenull

powerio.McAcPfSolution

Terminal columns run in bus table order and, within a bus, in the bus’s stated terminal order. Source columns run in source table order and, within a source, in its terminal_map order.

Schema definition: McAcPfSolution.

fieldtypeunitsigninvariantif absent
instanceMcAcPfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
terminal_voltage_magnitudearray of floatvoltsone per terminalrequired
terminal_voltage_anglearray of floatradiansone per terminalrequired
terminal_current_magnitudearray of float or nullamperesone per terminalnull
terminal_active_powerarray of float or nullwattspositive into the networkone per terminalnull
source_active_injectionarray of floatwattspositive into the networkone per source terminalrequired

powerio.McAcOpfSolution

generator_active_power is per terminal of each generator’s terminal_map. A generator’s cost and bounds are per coil, and generator_coil_active_power is the dispatch in that layout: a WYE generator has one coil per phase terminal in terminal_map order and none for the neutral; a DELTA generator on three terminals has the coils from terminal 1 to 2, 2 to 3, and 3 to 1 of its terminal_map; a DELTA or SINGLE_PHASE generator on two terminals has one coil. The two columns differ for a DELTA generator and for a WYE generator whose neutral voltage is not zero. generator_coil_active_power is written only when the producer reported it, from 0.12.3 on; a release before 0.12.3 refuses a document that states it.

Schema definition: McAcOpfSolution.

fieldtypeunitsigninvariantif absent
instanceMcAcOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
terminal_voltage_magnitudearray of floatvoltsone per terminalrequired
terminal_voltage_anglearray of floatradiansone per terminalrequired
terminal_current_magnitudearray of float or nullamperesone per terminalnull
terminal_active_powerarray of float or nullwattspositive into the networkone per terminalnull
source_active_injectionarray of floatwattspositive into the networkone per source terminalrequired
generator_active_powerarray of floatwattspositive is generationone per generator terminal: generator table order, each generator’s terminal_map order, neutral includedrequired
generator_coil_active_powerarray of float or nullwattspositive is generationone per generator coil: generator table order, each generator’s coil ordernull
objectivefloatobjective unitsrequired

powerio.LinDist3FlowOpfSolution

The value arrays follow the topology and device channel orders fixed by the embedded instance, independently of a solver’s column ordering.

Schema definition: LinDist3FlowOpfSolution.

fieldtypeunitsigninvariantif absent
instanceLinDist3FlowOpfInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
valuesLinDist3FlowOpfValuesphysical primal valuesrequired
objectivefloatobjective unitsrequired

powerio.LinDist3FlowPfSolution

The value arrays use the same physical axes and SI conventions as the OPF solution. Limit checks exist only for a converged point and report retained line/contact ratings that the fixed-dispatch problem deliberately did not enforce.

Schema definition: LinDist3FlowPfSolution.

fieldtypeunitsigninvariantif absent
instanceLinDist3FlowPfInstancerequired
terminationTerminationnon-converged results have no limit_checksrequired
residualsResidualsrequired
producerstring or nullnull
valuesLinDist3FlowOpfValuesphysical primal valuesrequired
limit_checksarray of LinDist3FlowLimitCheckidentities name retained line conductorsrequired

Schema definition: LinDist3FlowLimitCheck.

fieldtypeunitsigninvariantif absent
linestringretained line identityrequired
conductornonnegative integerposition in that line’s conductor orderrequired
kindline_apparent_power, line_current_from, or line_current_todetermines whether value and limit are VA or Arequired
valuefloatVA or Anonnegativefiniterequired
limitfloatVA or Apositivefiniterequired
loading_ratiofloatper unit of limitnonnegativeequals value / limitrequired
overloadedbooltrue exactly when loading_ratio > 1required
constraint_enforcedboolalways false for fixed dispatchrequired

Schema definition: LinDist3FlowOpfValues.

fieldtypeunitsigninvariantif absent
terminal_voltage_magnitude_squaredarray of floatvolts squarednonnegativetopology node orderrequired
line_active_powerarray of floatwattspositive from parent to childtopology conductor orderrequired
line_reactive_powerarray of floatvarspositive from parent to childtopology conductor orderrequired
generator_active_powerarray of floatwattspositive is generationgenerator table and channel orderrequired
generator_reactive_powerarray of floatvarspositive is generationgenerator table and channel orderrequired
source_active_powerarray of floatwattspositive into the networksource table and terminal-map orderrequired
source_reactive_powerarray of floatvarspositive into the networksource table and terminal-map orderrequired

powerio.AcScucSolution

The GO Challenge 3 output fields. Every series is values[t][row] over the instance’s time points and the corresponding table order; a series a producer did not supply is empty.

Schema definition: AcScucSolution.

fieldtypeunitsigninvariantif absent
instanceAcScucInstancerequired
terminationTerminationrequired
residualsResidualsrequired
producerstring or nullnull
network_outputsScucNetworkOutputsrequired
device_outputsScucDeviceOutputsrequired
objectivefloat or nulldollarsnull

Schema definition: ScucNetworkOutputs.

fieldtypeunitsigninvariantif absent
bus_vmarray of array of floatp.u.one row per time point, one per busrequired
bus_vaarray of array of floatradiansone per busrequired
shunt_steparray of array of integerone per shuntrequired
ac_line_on_statusarray of array of booleanone per AC linerequired
transformer_tmarray of array of floatratioone per two winding transformerrequired
transformer_taarray of array of floatradiansone per two winding transformerrequired
transformer_on_statusarray of array of booleanone per two winding transformerrequired
dc_line_pdc_frarray of array of floatp.u.positive from the from bus to the to busone per DC line[]
dc_line_qdc_frarray of array of floatp.u.positive is injected into the from busone per DC line[]
dc_line_qdc_toarray of array of floatp.u.positive is injected into the to busone per DC line[]

Schema definition: ScucDeviceOutputs.

fieldtypeunitsigninvariantif absent
on_statusarray of array of booleanone row per time point, one per devicerequired
startup_statusarray of array of booleanrequired
shutdown_statusarray of array of booleanrequired
p_onarray of array of floatp.u.positive is production for a producer, consumption for a consumerrequired
qarray of array of floatp.u.as p_onrequired
p_reg_res_uparray of array of floatp.u.nonnegativerequired
p_reg_res_downarray of array of floatp.u.nonnegativerequired
p_syn_resarray of array of floatp.u.nonnegativerequired
p_nsyn_resarray of array of floatp.u.nonnegativerequired
p_ramp_res_up_onlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_up_offlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_down_onlinearray of array of floatp.u.nonnegativerequired
p_ramp_res_down_offlinearray of array of floatp.u.nonnegativerequired
q_res_uparray of array of floatp.u.nonnegativerequired
q_res_downarray of array of floatp.u.nonnegativerequired

Module records

The records beside value in a .pio.json document. .pio.json schema explains what each one is for; the tables here list their fields.

Schema definition: Producer.

fieldtypeunitsigninvariantif absent
namestringnonempty, boundedrequired
versionstringnonempty, boundedrequired

Schema definition: SourceDescriptor.

fieldtypeunitsigninvariantif absent
idstringunique among sources; spans and source map entries name itrequired
namestringa file name, never a local file pathrequired
byte_lengthintegerbytesevery span into this source ends at or before itrequired
formatstring or nulla format tokennull
digestDigest or nullnull

Schema definition: Digest.

fieldtypeunitsigninvariantif absent
algorithmtoken sha256required
valuestring64 lowercase hexadecimal charactersrequired

Schema definition: SourceSpan.

fieldtypeunitsigninvariantif absent
sourcestringnames a source idrequired
byte_startintegerbytes into the retained sourcebyte_start <= byte_end <= byte_lengthrequired
byte_endintegerbytes into the retained sourcehalf openrequired

Schema definition: SourceMapEntry.

fieldtypeunitsigninvariantif absent
targetstringan RFC 6901 pointer into value.datarequired
relationtoken exact, defaulted, inferred, converted_units, aggregated, split, synthetic, transformed, retained_extrarequired
spansarray of SourceSpanempty only for defaulted, synthetic, and transformed[]

Schema definition: Diagnostic.

fieldtypeunitsigninvariantif absent
idstringunique among diagnostics; assigned d0, d1, … at serialization when a record has nonerequired
codestringNAMESPACE.SCOPE.SPECIFICrequired
severitytoken error, warning, remark, noterequired
messagestringone linerequired
targetstring or nullan RFC 6901 pointer into value.datanull
spansarray of SourceSpanthe records the finding is about[]
relatedarray of stringeach names a diagnostic id in the document[]
detailsobject{}
suggested_actionstring or nullnull

Schema definition: HistoryEntry.

fieldtypeunitsigninvariantif absent
idstringunique among historyrequired
kindtoken parse, transform, edit, repair, solverequired
namestringthe operationrequired
input_typestring or nulla structural type namenull
output_typestring or nulla structural type namenull
parametersobject{}
assumptionsarray of string[]
lossesarray of string[]