Engineering Data Model

This document describes the ENGINEERING data model type in PowerModelsDistribution, which is transformed at runtime, or at the user's direction into a MATHEMATICAL data model for optimization.

In this document,

  • nphases refers to the number of non-neutral, non-ground active phases connected to a component,
  • nconductors refers to all active conductors connected to a component, i.e. length(connections), and
  • nwindings refers to the number of windings of a transformer.

The data structure is in the following format

Dict{String,Any}(
    "data_model" => ENGINEERING,
    "component_type" => Dict{String,Dict{String,Any}}(
        id => Dict{String,Any}(
            "parameter" => value,
            ...
        ),
        ...
    ),
    ...
)

Valid component types are those that are documented in the sections below. Each component object is identified by an id, which must be a string (id <: String), but id does not appear inside of the component dictionary, and only appears as keys to the component dictionaries under each component type. Note that this requirement is so that data structures will be JSON serializable.

Each edge or node component (i.e. all those that are not data objects or buses), is expected to have status fields to specify whether the component is active or disabled, bus or f_bus and t_bus, to specify the buses that are connected to the component, and connections or f_connections and t_connections, to specify the terminals of the buses that are actively connected in an ordered list. NOTE: terminals, connections, f_connections, and t_connections, must be type Vector{Int}.

Parameter values on components are expected to be specified in SI units by default (where applicable) in the engineering data model. Relevant expected units are noted in the sections below. It is possible for the user to select universal scalar factors for power and voltages. For example, if power_scalar_factor and voltage_scalar_factor are their default values given below, where units is listed as watt or var, real units will be kW and kvar. Where units are listed as volt, real units will be kV (multiplied by vm_nom, where that value exists).

The Used column describes the situtations where certain parameters are used. "always" indicates those values are used in all contexts, opf, mld, or any other problem name abbreviation indicate they are used in particular for those problems. "solution" indicates that those parameters are outputs from the solvers. "multinetwork" indicates these values are only used to build multinetwork problems.

Those parameters that have a default may be omitted by the user from the data model, they will be populated by the specified default values.

Components that support "codes", such as lines, switches, and transformers, behave such that any property on said object that conflicts with a value in the code will override the value given in the code object. This is noted on each object where this is relevant.

Root-Level Properties

At the root level of the data structure, the following fields can be found.

NameDefaultTypeUsedDescription
nameStringCase name
data_modelENGINEERINGDataModelalwaysENGINEERING, MATHEMATICAL, or DSS. Type of the data model (this document describes data_model==ENGINEERING)
settingsDict()Dict{String,<:Any}alwaysBase settings for the data model, see Settings section below for details

Settings (settings)

At the root-level of the data model a settings dictionary object is expected, containing the following fields.

NameDefaultTypeUnitsUsedDescription
voltage_scale_factor1e3RealalwaysScalar multiplier for voltage values
power_scale_factor1e3RealalwaysScalar multiplier for power values
vbases_defaultDict{<:Any,Real}alwaysInstruction to set the vbase at a number of buses for non-dimensionalization
sbase_defaultRealalwaysInstruction to set the power base for non-dimensionalization
base_frequency60.0RealHzalwaysFrequency base, i.e. the base frequency of the whole circuit

The parameters voltage_scale_factor and power_scale_factordetermine the base for all voltage and power parameters in this data model. For example,

  • voltage_scale_factor=1E3 and vm_nom=4.0: vm_nom is 4.0 kV/4.0E3 V,
  • power_scale_factor=1E6 and pd_nom=2.0: pd_nom is 2.0 MW/2.0E6 W,
  • power_scale_factor=1E6 and qd_nom=5.0: qd_nom is 5.0 MVAr/5.0E6 VAr,

where the mentioned fields vm_nom, pd_nom and qd_nom are sample voltage and power variables which are defined later.

On the other hand,vbase_default and sbase_default provide default values for a 'per unit' conversion; these do not affect the interpretation of the parameters in this model, like the scale factors do. Note that vbase_default is a Dict{Any,Real}, with pairs of bus ids and voltage magnitude levels, since in per unit conversion, the voltage base can change from bus to bus. The power base is the same everywhere, and therefore sbase_default has a single value.

Buses (bus)

The data model below allows us to include buses of arbitrary many terminals (i.e., more than the usual four). This would be useful for

  • underground lines with multiple neutrals which are not joined at every bus;
  • distribution lines that carry several conventional lines in parallel (see for example the quad circuits in NEVTestCase).
NameDefaultTypeUnitsUsedDescription
terminals[1,2,3,4]Vector{Int}alwaysTerminals for which the bus has active connections; NOTE: type can be either Vector{Int} or Vector{String}, but has to be consistent across all fields referring to terminals
vm_lbVector{Real}voltopfMinimum conductor-to-ground voltage magnitude, size=nphases
vm_ubVector{Real}voltopfMaximum conductor-to-ground voltage magnitude, size=nphases
vm_pair_ubVector{Tuple}opfe.g. [(1,2,210)] means |U1-U2|>210
vm_pair_lbVector{Tuple}opfe.g. [(1,2,230)] means |U1-U2|<230
grounded[]Vector{Int}alwaysList of terminals which are grounded
rg[]Vector{Real}alwaysResistance of each defined grounding, size=length(grounded)
xg[]Vector{Real}alwaysReactance of each defined grounding, size=length(grounded)
vmVector{Real}voltalwaysVoltage magnitude at bus. If set, voltage magnitude at bus is fixed
vaVector{Real}degreealwaysVoltage angle at bus. If set, voltage angle at bus is fixed
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

Each terminal c of the bus has an associated complex voltage phasor v[c]. There are two types of voltage magnitude bounds. The first type bounds the voltage magnitude of each v[c] individually,

  • lb <= |v[c]| <= ub

However, especially in four-wire networks, bounds are more naturally imposed on the difference of two terminal voltages instead, e.g. for terminals c and d,

  • lb <= |v[c]-v[d]| <= ub

This is why we introduce the fields vm_pair_lb and vm_pair_ub, which define bounds for pairs of terminals,

  • \[\forall\]

    (c,d,lb) $\in$ vm_pair_lb: |v[c]-v[d]| >= lb
  • \[\forall\]

    (c,d,ub) $\in$ vm_pair_ub: |v[c]-v[d]| <= ub

Finally, we give an example of how grounding impedances should be entered. If terminal 4 is grounded through an impedance Z=1+j2, we write

  • grounded=[4], rg=[1], xg=[2]

Special Case: three-phase bus

For three-phase buses, instead of specifying bounds explicitly for each pair of windings, often we want to specify 'phase-to-phase', 'phase-to-neutral' and 'neutral-to-ground' bounds. This can be done conveniently with a number of additional fields. First, phases is a list of the phase terminals, and neutral designates a single terminal to be the neutral.

  • The bounds vm_pn_lb and vm_pn_ub specify the same lower and upper bound for the magnitude of the difference of each phase terminal and the neutral.
  • The bounds vm_pp_lb and vm_pp_ub specify the same lower and upper bound for the magnitude of the difference of all phase terminals.
  • vm_ng_ub specifies an upper bound for the neutral terminal, the lower bound is typically zero.

If all of these are specified, these bounds also imply valid bounds for the individual voltage magnitudes,

  • \[\forall\]

    c $\in$ phases: vm_pn_lb - vm_ng_ub <= |v[c]| <= vm_pn_ub + vm_ng_ub
  • 0 <= |v[neutral]|<= vm_ng_ub

Instead of defining the bounds directly, they can be specified through an associated voltage zone.

NameDefaultTypeUnitsUsedDescription
phasesVector{Int}alwaysIdentifies the terminal that represents the neutral conductor
neutralIntalwaysIdentifies the terminal that represents the neutral conductor
vm_pn_lbRealopfMinimum phase-to-neutral voltage magnitude for all phases
vm_pn_ubRealopfMaximum phase-to-neutral voltage magnitude for all phases
vm_pp_lbRealopfMinimum phase-to-phase voltage magnitude for all phases
vm_pp_ubRealopfMaximum phase-to-phase voltage magnitude for all phases
vm_ng_ubRealopfMaximum neutral-to-ground voltage magnitude

Edge Objects

These objects represent edges on the power grid and therefore require f_bus and t_bus (or buses in the case of transformers), and f_connections and t_connections (or connections in the case of transformers).

Lines (line)

This is a pi-model branch. When a linecode is given, and any of rs, xs, b_fr, b_to, g_fr or g_to are specified, any of those overwrite the values on the linecode.

NameDefaultTypeUnitsUsedDescription
f_busAnyalwaysid of from-side bus connection
t_busAnyalwaysid of to-side bus connection
f_connectionsVector{Int}alwaysIndicates for each conductor, to which terminal of the f_bus it connects
t_connectionsVector{Int}alwaysIndicates for each conductor, to which terminal of the t_bus it connects
linecodeAnyalwaysid of an associated linecode
rsMatrix{Real}ohm/meteralwaysSeries resistance matrix, size=(nconductors,nconductors)
xsMatrix{Real}ohm/meteralwaysSeries reactance matrix, size=(nconductors,nconductors)
g_frzeros(nconductors, nconductors)Matrix{Real}siemens/meter/HzalwaysFrom-side conductance, size=(nconductors,nconductors)
b_frzeros(nconductors, nconductors)Matrix{Real}siemens/meter/HzalwaysFrom-side susceptance, size=(nconductors,nconductors)
g_tozeros(nconductors, nconductors)Matrix{Real}siemens/meter/HzalwaysTo-side conductance, size=(nconductors,nconductors)
b_tozeros(nconductors, nconductors)Matrix{Real}siemens/meter/HzalwaysTo-side susceptance, size=(nconductors,nconductors)
length1.0RealmeteralwaysLength of the line
cm_ubVector{Real}ampopfSymmetrically applicable current rating, size=nconductors
sm_ubVector{Real}wattopfSymmetrically applicable power rating, size=nconductors
vad_lbVector{Real}degreeopfVoltage angle difference lower bound
vad_ubVector{Real}degreeopfVoltage angle difference upper bound
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively

Transformers (transformer)

These are n-winding (nwinding), n-phase (nphase), lossy transformers. Note that most properties are now Vectors (or Vectors of Vectors), indexed over the windings.

NameDefaultTypeUnitsUsedDescription
busVector{Any}alwaysList of bus for each winding, size=nwindings
connectionsVector{Vector{Int}}alwaysList of connection for each winding, size=((nconductors),nwindings)
configurationsfill(WYE, nwindings)Vector{ConnConfig}alwaysWYE or DELTA. List of configuration for each winding, size=nwindings
xfmrcodeAnyalwaysid of
xsczeros(nwindings*(nwindings-1)/2)Vector{Real}sm_nom[1]alwaysList of short-circuit reactances between each pair of windings, relative to the VA rating of the first winding; enter as a list of the upper-triangle elements
rwzeros(nwindings)Vector{Real}sm_nom[1]alwaysActive power lost due to resistance of each winding, relative to the VA rating of each winding winding
cmag0.0Realsm_nom[1]alwaysTotal no-load reactive power drawn by the transformer, relative to VA rating of the first winding (magnetizing current)
noloadloss0.0Realsm_nom[1]alwaysTotal no-load active power drawn by the transformer, relative to VA rating of the first winding
tm_nomones(nwindings)Vector{Real}alwaysNominal tap ratio for the transformer, size=nwindings (multiplier)
tm_ubVector{Vector{Real}}opfMaximum tap ratio for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_lbVector{Vector{Real}}opfMinimum tap ratio for for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_setfill(fill(1.0,nphases),nwindings)Vector{Vector{Real}}alwaysSet tap ratio for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_fixfill(fill(true,nphases),nwindings)Vector{Vector{Bool}}oltcIndicates for each winding and phase whether the tap ratio is fixed, size=((nphases),nwindings)
polarityfill(1,nwindings)Vector{Int}always
vm_nomVector{Real}voltalways
sm_nomVector{Real}wattalways
sm_ubRealwattopfRating for the total apparent power magnitude at each winding
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively

Asymmetric, Lossless, Two-Winding (AL2W) Transformers (transformer)

Special case of the Generic transformer, which is still a transformer object, but has a simplified method for its definition. These are transformers are asymmetric (A), lossless (L) and two-winding (2W). Asymmetric refers to the fact that the secondary is always has a WYE configuration, whilst the primary can be DELTA. The table below indicates alternate, more simple ways to specify the special case of an AL2W Transformer. xsc and rw cannot be specified for an AL2W transformer, because it is lossless. To use this definition format, all of f_bus, t_bus, f_connections, t_connections, and configuration must be used, and none of buses, connections, configurations may be used. xfmrcode is ignored for this component.

NameDefaultTypeUnitsUsedDescription
f_busAnyalwaysAlternative way to specify buses, requires both f_bus and t_bus
t_busAnyalwaysAlternative way to specify buses, requires both f_bus and t_bus
f_connectionsVector{Int}alwaysAlternative way to specify connections, requires both f_connections and t_connections, size=nphases
t_connectionsVector{Int}alwaysAlternative way to specify connections, requires both f_connections and t_connections, size=nphases
configurationWYEConnConfigalwaysWYE or DELTA. Alternative way to specify the from-side configuration, to-side is always WYE
tm_nom1.0RealalwaysNominal tap ratio for the transformer (multiplier)
tm_ubVector{Real}opfMaximum tap ratio for each phase (base=tm_nom), size=nphases
tm_lbVector{Real}opfMinimum tap ratio for each phase (base=tm_nom), size=nphases
tm_setfill(1.0,nphases)Vector{Real}alwaysSet tap ratio for each phase (base=tm_nom), size=nphases
tm_fixfill(true,nphases)Vector{Bool}oltcIndicates for each phase whether the tap ratio is fixed, size=nphases
sm_ubRealopfRating for the total apparent power magnitude at each winding

Transformers with voltage regulator control (controls)

Special case of the Generic transformer, which is part of the transformer object, and emulates a standard utility voltage regulator. The taps of these transformers can be controlled by modelling a line drop compensator.

NameDefaultTypeUnitsUsedDescription
vregVector{Vector{Real}}voltoltcVoltage regulator reference, default value is 120.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
bandVector{Vector{Real}}voltoltcVoltage bandwidth, default value is 3.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
ptratioVector{Vector{Real}}oltcVoltage ratio of the potential transformer, default value is 60.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
ctprimVector{Vector{Real}}ampoltcCurrent transformer rating on primary side, default value is 300.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
rVector{Vector{Real}}voltoltcResistance setting on line drop compensator, default value is 0.0 for both controlled winding and winding without regulator control, size=((nphases),nwindings)
xVector{Vector{Real}}voltoltcReactance setting on line drop compensator, default value is 0.0 for both controlled winding and winding without regulator control, size=((nphases),nwindings)

Switches (switch)

Switches without rs, xs or a linecode (conductance/susceptance not considered), defined the switch will be treated as lossless. If lossy parameters are defined, switch objects will be decomposed into virtual branch & bus, and an ideal switch.

NameDefaultTypeUnitsUsedDescription
f_busAnyalwaysid of from-side bus connection
t_busAnyalwaysid of to-side bus connection
f_connectionsVector{Int}alwaysIndicates for each conductor, to which terminal of the f_bus it connects
t_connectionsVector{Int}alwaysIndicates for each conductor, to which terminal of the t_bus it connects
cm_ubVector{Real}ampopfSymmetrically applicable current rating
sm_ubVector{Real}wattopfSymmetrically applicable power rating
linecodeAnyalwaysid of an associated linecode, does not take into account conductance/susceptance
rszeros(nphases,nphases)Matrix{Real}ohmalwaysSeries resistance matrix, size=(nphases,nphases)
xszeros(nphases,nphases)Matrix{Real}ohmalwaysSeries reactance matrix, size=(nphases,nphases)
dispatchableNODispatchableNO or YES, indicates whether switch state can be changed in a switching optimization problem
stateCLOSEDSwitchStatealwaysCLOSED: closed or OPEN: open, to indicate state of switch
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively

Node Objects

These are objects that have single bus connections. Every object will have at least bus, connections, and status.

Shunts (shunt)

NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
gsMatrix{Real}siemensalwaysConductance, size=(nconductors,nconductors)
bsMatrix{Real}siemensalwaysSusceptance, size=(nconductors,nconductors)
modelGENERICShuntModelGENERIC, CAPACITOR, or REACTOR. Indicates the type of shunt which may be necessary for transient stability analysis
dispatchableNODispatchablemldNO or YES, indicates whether a shunt can be shed
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

Shunts with capacitor control (controls)

Special case of the shunt capacitors, which is part of the shunt object, and emulates a typical utility capacitor control (CapControl) by sending switching messages.

NameDefaultTypeUnitsUsedDescription
typeVector{String}capcControl type, default is current for controlled phase, `for uncontrolled phase,size=1forkvartype, otherwisesize=(nphases)`
element``Stringcapcsource_id of element (typically line or transformer) to which CapControl is connected
terminalVector{Int}capcNumber of the terminal of circuit element to which CapControl is connected, default is 1 for controlled phase, 0 for uncontrolled phase, size=1 for kvar type, otherwise size=(nphases)
onsettingVector{Real}capcValue at which the CapControl switches the capacitor on, default is 300.0 for controlled phase, 0.0 for uncontrolled phase, size=1 for kvar type, otherwise size=(nphases)
offsettingVector{Real}capcValue at which the CapControl switches the capacitor off, default is 200.0 for controlled phase, 0.0 for uncontrolled phase, size=1 for kvar type, otherwise size=(nphases)
voltoverrideVector{Bool}capcIndicate whether voltage over ride is enabled, default is false for both controlled and uncontrolled phases, size=1 for kvar type, otherwise size=(nphases)
ptratioVector{Real}capcRatio of potential transformer, default is 60.0 for controlled phase, 0.0 for uncontrolled phase, size=(nphases)
ctratioVector{Real}capcRatio of current transformer, default is 60.0 for controlled phase, 0.0 for uncontrolled phase, size=(nphases)
vminVector{Real}voltcapcMinimum voltage below which CapControl switches the capacitor on, default is 115.0 for controlled phase, 0.0 for uncontrolled phase, size=1 for kvar type, otherwise size=(nphases)
vmaxVector{Real}voltcapcMaximum voltage above which CapControl switches the capacitor off, default is 126.0 for controlled phase, 0.0 for uncontrolled phase, size=1 for kvar type, otherwise size=(nphases)

Loads (load)

NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
configurationWYEConnConfigalwaysWYE or DELTA. If WYE, connections[end]=neutral
modelPOWERLoadModelalwaysPOWER, IMPEDANCE, CURRENT, EXPONENTIAL, or ZIP. Indicates the type of voltage-dependency
pd_nomVector{Real}wattalwaysNominal active load, with respect to vm_nom, size=nphases
qd_nomVector{Real}varalwaysNominal reactive load, with respect to vm_nom, size=nphases
vm_nomRealvoltmodel!=POWERNominal voltage (multiplier)
dispatchableNODispatchablemldNO or YES, indicates whether a load can be shed
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

Multi-phase loads define a number of individual loads connected between two terminals each. How they are connected, is defined both by configuration and connections. The table below indicates the value of configuration and lengths of the other properties for a consistent definition,

configuration`connections``pd_nom=qd_nom=pd_exp=...`
DELTA21
DELTA33
WYE21
WYE32
WYENN-1

Note that for delta loads, only 2 and 3 connections are allowed. Each individual load i is connected between two terminals, exposed to a voltage magnitude v[i], which leads to a consumption pd[i]+j*qd[i]. The model then defines the relationship between these quantities,

modelpd[i]/pd_nom[i]=qd[i]/qd_nom[i]=
POWER11
CURRENT(v[i]/vm_nom)(v[i]/vm_nom)
IMPEDANCE(v[i]/vm_nom)^2(v[i]/vm_nom)^2

Two more model types are supported, which need additional fields and are defined below.

model == EXPONENTIAL

  • (pd[i]/pd_nom[i]) = (v[i]/vm_nom)^pd_exp[i]
  • (qd[i]/qd_nom[i]) = (v[i]/vm_nom)^qd_exp[i]
NameDefaultTypeUnitsUsedDescription
pd_expRealmodel==EXPONENTIAL
qd_expRealmodel==EXPONENTIAL

model == ZIP

  • (pd[i]/pd_nom) = pd_cz[i]*(v[i]/vm_nom)^2 + pd_ci[i]*(v[i]/vm_nom) + pd_cp[i]
  • (qd[i]/qd_nom) = qd_cz[i]*(v[i]/vm_nom)^2 + qd_ci[i]*(v[i]/vm_nom) + qd_cp[i]
NameDefaultTypeUnitsUsedDescription
vm_nomRealvoltmodel==ZIPNominal voltage (multiplier)
pd_czRealmodel==ZIP
pd_ciRealmodel==ZIP
pd_cpRealmodel==ZIP
qd_czRealmodel==ZIP
qd_ciRealmodel==ZIP
qd_cpRealmodel==ZIP

Generators (generator)

NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
configurationWYEConnConfigalwaysWYE or DELTA. If WYE, connections[end]=neutral
vgVector{Real}voltcontrol_mode==ISOCHRONOUSVoltage magnitude setpoint
pg_lbzeros(nphases)Vector{Real}wattopfLower bound on active power generation per phase, size=nphases
pg_ubfill(Inf, nphases)Vector{Real}wattopfUpper bound on active power generation per phase, size=nphases
qg_lb-pg_ubVector{Real}varopfLower bound on reactive power generation per phase, size=nphases
qg_ubpg_ubVector{Real}varopfUpper bound on reactive power generation per phase, size=nphases
pgVector{Real}wattsolutionPresent active power generation per phase, size=nphases
qgVector{Real}varsolutionPresent reactive power generation per phase, size=nphases
control_modeFREQUENCYDROOPControlModeFREQUENCYDROOP or ISOCHRONOUS
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

generator Cost Model

The generator cost model is currently specified by the following fields.

NameDefaultTypeUnitsUsedDescription
cost_pg_model2IntopfCost model type, 1 = piecewise-linear, 2 = polynomial
cost_pg_parameters[0.0, 1.0, 0.0]Vector{Real}/MVAopfCost model polynomial

Photovoltaic Systems (solar)

NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
configurationWYEConnConfigalwaysWYE or DELTA. If WYE, connections[end]=neutral
pg_lbVector{Real}wattopfLower bound on active power generation per phase, size=nphases
pg_ubVector{Real}wattopfUpper bound on active power generation per phase, size=nphases
qg_lbVector{Real}varopfLower bound on reactive power generation per phase, size=nphases
qg_ubVector{Real}varopfUpper bound on reactive power generation per phase, size=nphases
pgVector{Real}wattsolutionPresent active power generation per phase, size=nphases
qgVector{Real}varsolutionPresent reactive power generation per phase, size=nphases
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

solar Cost Model

The cost model for a photovoltaic system currently matches that of generators.

NameDefaultTypeUnitsUsedDescription
cost_pg_model2IntopfCost model type, 1 = piecewise-linear, 2 = polynomial
cost_pg_parameters[0.0, 1.0, 0.0]Vector{Real}/MVAopfCost model polynomial

Wind Turbine Systems (wind)

Wind turbine systems are most closely approximated by induction machines, also known as asynchronous machines. These are not currently supported, but there is plans to support them in the future.

Storage (storage)

A storage object is a flexible component that can represent a variety of energy storage objects, like Li-ion batteries, hydrogen fuel cells, flywheels, etc.

  • How to include the inverter model for this? Similar issue as for a PV generator
NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
configurationWYEConnConfigalwaysWYE or DELTA. If WYE, connections[end]=neutral
energyRealwatt-hralwaysStored energy
energy_ubRealopfmaximum energy rating
charge_ubRealopfmaximum charge rating
discharge_ubRealopfmaximum discharge rating
sm_ubRealwattopfPower rating,
cm_ubRealampopfCurrent rating,
charge_efficiencyRealpercentalwayscharging efficiency (losses)
discharge_efficiencyRealpercentalwaysdisharging efficiency (losses)
qs_ubRealopfMaximum reactive power injection,
qs_lbRealopfMinimum reactive power injection,
rsRealohmalwaysconverter resistance
xsRealohmalwaysconverter reactance
pexRealalwaysTotal active power standby exogenous flow (loss)
qexRealalwaysTotal reactive power standby exogenous flow (loss)
psVector{Real}wattsolutionPresent active power injection
qsVector{Real}varsolutionPresent reactive power injection
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

Voltage Sources (voltage_source)

A voltage source is a source of power at a set voltage magnitude and angle connected to a slack bus. If rs or xs are not specified, the voltage source is assumed to be lossless, otherwise virtual branch and bus will be created in the mathematical model to represent the internal losses of the voltage source.

NameDefaultTypeUnitsUsedDescription
busAnyalwaysid of bus connection
connectionsVector{Int}alwaysOrdered list of connected conductors, size=nconductors
configurationWYEConnConfigalwaysWYE or DELTA. If WYE, connections[end]=neutral
vmones(nphases)Vector{Real}voltalwaysVoltage magnitude set at slack bus, size=nphases
vazeros(nphases)RealdegreealwaysVoltage angle offsets at slack bus, applies symmetrically to each phase angle
rszeros(nconductors,nconductors)Matrix{Real}ohmalwaysInternal series resistance of voltage source, size=(nconductors,nconductors)
xszeros(nconductors,nconductors)Matrix{Real}ohmalwaysInternal series reactance of voltage soure, size=(nconductors,nconductors)
statusENABLEDStatusalwaysENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_seriesDict{String,Any}multinetworkDictionary containing time series parameters.

Data Objects (codes, time series, etc.)

These objects are referenced by node and edge objects, but are not part of the network themselves, only containing data.

Linecodes (linecode)

Linecodes are easy ways to specify properties common to multiple lines.

NameDefaultTypeUnitsUsedDescription
rsMatrix{Real}ohm/meteralwaysSeries resistance, size=(nconductors,nconductors)
xsMatrix{Real}ohm/meteralwaysSeries reactance, size=(nconductors,nconductors)
g_frzeros(nconductors,nconductors)Matrix{Real}siemens/meter/HzalwaysFrom-side conductance, size=(nconductors,nconductors)
b_frzeros(nconductors,nconductors)Matrix{Real}siemens/meter/HzalwaysFrom-side susceptance, size=(nconductors,nconductors)
g_tozeros(nconductors,nconductors)Matrix{Real}siemens/meter/HzalwaysTo-side conductance, size=(nconductors,nconductors)
b_tozeros(nconductors,nconductors)Matrix{Real}siemens/meter/HzalwaysTo-side susceptance, size=(nconductors,nconductors)
cm_ubfill(Inf,nconductors)Vector{Real}ampereopfmaximum current per conductor, symmetrically applicable
sm_ubfill(Inf,nconductors)Vector{Real}wattopfmaximum power per conductor, symmetrically applicable

Transformer Codes (xfmrcode)

Transformer codes are easy ways to specify properties common to multiple transformers

NameDefaultTypeUnitsUsedDescription
configurationsfill(WYE, nwindings)Vector{ConnConfig}alwaysWYE or DELTA. List of configuration for each winding, size=nwindings
xsc[0.0]Vector{Real}ohmalwaysList of short-circuit reactances between each pair of windings; enter as a list of the upper-triangle elements, size=(nwindings == 2 ? 1 : 3)
rwzeros(nwindings)Vector{Real}ohmalwaysList of the winding resistance for each winding, size=nwindings
tm_nomones(nwindings)Vector{Real}alwaysNominal tap ratio for the transformer, size=nwindings (multiplier)
tm_ubVector{Vector{Real}}opfMaximum tap ratio for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_lbVector{Vector{Real}}opfMinimum tap ratio for for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_setfill(fill(1.0, nphases), nwindings)Vector{Vector{Real}}alwaysSet tap ratio for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_fixfill(fill(true, nphases), nwindings)Vector{Vector{Bool}}alwaysIndicates for each winding and phase whether the tap ratio is fixed, size=((nphases), nwindings)

Time Series (time_series)

Time series objects are used to specify time series for e.g. load or generation forecasts.

Some parameters for components specified in this document can support a time series by inserting a referece to a time_series object into the time_series dictionary inside a component under the relevant parameter name. For example, for a load, if pd_nom is supposed to be a time series, the user would specify "time_series" => Dict("pd_nom" => time_series_id) where time_series_id is the id of an object in time_series, and has type Any.

NameDefaultTypeUnitsUsedDescription
timeVector{Union{Real,String}}houralwaysTime points at which values are specified. If time is specified in String, units not required to be in hours.
valuesVector{Real}alwaysMultipers at each time step given in time
offset0RealhouralwaysStart time offset
replacetrueBoolalwaysIndicates to replace with data, instead of multiply. Will only work on non-Array data

Fuses (fuse)

Fuses can be defined on any terminal of any physical component

NameDefaultTypeUnitsUsedDescription
component_typeString
component_idAny
terminalsVector{Int}
fuse_curveArray{Vector{Real},2}specifies the fuse blowing condition
minimum_melting_curveArray{Vector{Real},2}specifies the minimum melting conditions of the fuse