Skip to content

Latest commit

 

History

History
488 lines (376 loc) · 59.7 KB

eng-data-model.md

File metadata and controls

488 lines (376 loc) · 59.7 KB
Raw

Engineering Data Model

This document describes the [ENGINEERING](@ref ENGINEERING) data model type in PowerModelsDistribution, which is transformed at runtime, or at the user's direction into a [MATHEMATICAL](@ref 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 situations 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.

Name Default Type Used Description
name String Case name
data_model ENGINEERING DataModel always ENGINEERING, MATHEMATICAL, or DSS. Type of the data model (this document describes data_model==ENGINEERING)
settings Dict() Dict{String,<:Any} always Base 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.

Name Default Type Units Used Description
voltage_scale_factor 1e3 Real always Scalar multiplier for voltage values
power_scale_factor 1e3 Real always Scalar multiplier for power values
vbases_default Dict{String,Real} always Instruction to set the vbase at a number of buses for non-dimensionalization
sbase_default Real always Instruction to set the power base for non-dimensionalization
base_frequency 60.0 Real Hz always Frequency 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).
Name Default Type Units Used Description
terminals [1,2,3,4] Vector{Int} always Terminals for which the bus has active connections
vm_lb Vector{Real} volt opf Minimum conductor-to-ground voltage magnitude, size=nphases
vm_ub Vector{Real} volt opf Maximum conductor-to-ground voltage magnitude, size=nphases
vm_pair_ub Vector{Tuple} opf e.g. [(1,2,210)] means |U1-U2|>210
vm_pair_lb Vector{Tuple} opf e.g. [(1,2,230)] means |U1-U2|<230
grounded [] Vector{Int} always List of terminals which are grounded
rg [] Vector{Real} always Resistance of each defined grounding, size=length(grounded)
xg [] Vector{Real} always Reactance of each defined grounding, size=length(grounded)
vm Vector{Real} volt always Voltage magnitude at bus. If set, voltage magnitude at bus is fixed
va Vector{Real} degree always Voltage angle at bus. If set, voltage angle at bus is fixed
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary 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.

Name Default Type Units Used Description
phases Vector{Int} always Identifies the terminal that represents the neutral conductor
neutral Int always Identifies the terminal that represents the neutral conductor
vm_pn_lb Real opf Minimum phase-to-neutral voltage magnitude for all phases
vm_pn_ub Real opf Maximum phase-to-neutral voltage magnitude for all phases
vm_pp_lb Real opf Minimum phase-to-phase voltage magnitude for all phases
vm_pp_ub Real opf Maximum phase-to-phase voltage magnitude for all phases
vm_ng_ub Real opf Maximum 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.

Name Default Type Units Used Description
f_bus String always id of from-side bus connection
t_bus String always id of to-side bus connection
f_connections Vector{Int} always Indicates for each conductor, to which terminal of the f_bus it connects
t_connections Vector{Int} always Indicates for each conductor, to which terminal of the t_bus it connects
linecode String always id of an associated linecode
rs Matrix{Real} ohm/meter always Series resistance matrix, size=(nconductors,nconductors)
xs Matrix{Real} ohm/meter always Series reactance matrix, size=(nconductors,nconductors)
g_fr zeros(nconductors, nconductors) Matrix{Real} siemens/meter/Hz always From-side conductance, size=(nconductors,nconductors)
b_fr zeros(nconductors, nconductors) Matrix{Real} siemens/meter/Hz always From-side susceptance, size=(nconductors,nconductors)
g_to zeros(nconductors, nconductors) Matrix{Real} siemens/meter/Hz always To-side conductance, size=(nconductors,nconductors)
b_to zeros(nconductors, nconductors) Matrix{Real} siemens/meter/Hz always To-side susceptance, size=(nconductors,nconductors)
length 1.0 Real meter always Length of the line
cm_ub Vector{Real} amp opf Symmetrically applicable current rating, size=nconductors
sm_ub Vector{Real} watt opf Symmetrically applicable power rating, size=nconductors
vad_lb Vector{Real} degree opf Voltage angle difference lower bound
vad_ub Vector{Real} degree opf Voltage angle difference upper bound
status ENABLED Status always ENABLED 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.

Name Default Type Units Used Description
bus Vector{String} always List of bus for each winding, size=nwindings
connections Vector{Vector{Int}} always List of connection for each winding, size=((nconductors),nwindings)
configurations fill(WYE, nwindings) Vector{ConnConfig} always WYE or DELTA. List of configuration for each winding, size=nwindings
xfmrcode String always id of
xsc zeros(nwindings*(nwindings-1)/2) Vector{Real} sm_nom[1] always List 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
rw zeros(nwindings) Vector{Real} sm_nom[1] always Active power lost due to resistance of each winding, relative to the VA rating of each winding winding
cmag 0.0 Real sm_nom[1] always Total no-load reactive power drawn by the transformer, relative to VA rating of the first winding (magnetizing current)
noloadloss 0.0 Real sm_nom[1] always Total no-load active power drawn by the transformer, relative to VA rating of the first winding
tm_nom ones(nwindings) Vector{Real} always Nominal tap ratio for the transformer, size=nwindings (multiplier)
tm_ub Vector{Vector{Real}} opf Maximum tap ratio for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_lb Vector{Vector{Real}} opf Minimum tap ratio for for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_set fill(fill(1.0,nphases),nwindings) Vector{Vector{Real}} always Set tap ratio for each winding and phase, size=((nphases),nwindings) (base=tm_nom)
tm_fix fill(fill(true,nphases),nwindings) Vector{Vector{Bool}} oltc Indicates for each winding and phase whether the tap ratio is fixed, size=((nphases),nwindings)
polarity fill(1,nwindings) Vector{Int} always
vm_nom Vector{Real} volt always
sm_nom Vector{Real} watt always
sm_ub Real watt opf Rating for the total apparent power magnitude at each winding
status ENABLED Status always ENABLED 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.

Name Default Type Units Used Description
f_bus String always Alternative way to specify buses, requires both f_bus and t_bus
t_bus String always Alternative way to specify buses, requires both f_bus and t_bus
f_connections Vector{Int} always Alternative way to specify connections, requires both f_connections and t_connections, size=nphases
t_connections Vector{Int} always Alternative way to specify connections, requires both f_connections and t_connections, size=nphases
configuration WYE ConnConfig always WYE or DELTA. Alternative way to specify the from-side configuration, to-side is always WYE
tm_nom 1.0 Real always Nominal tap ratio for the transformer (multiplier)
tm_ub Vector{Real} opf Maximum tap ratio for each phase (base=tm_nom), size=nphases
tm_lb Vector{Real} opf Minimum tap ratio for each phase (base=tm_nom), size=nphases
tm_set fill(1.0,nphases) Vector{Real} always Set tap ratio for each phase (base=tm_nom), size=nphases
tm_fix fill(true,nphases) Vector{Bool} oltc Indicates for each phase whether the tap ratio is fixed, size=nphases
sm_ub Real opf Rating 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.

Name Default Type Units Used Description
vreg Vector{Vector{Real}} volt oltc Voltage regulator reference, default value is 120.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
band Vector{Vector{Real}} volt oltc Voltage bandwidth, default value is 3.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
ptratio Vector{Vector{Real}} oltc Voltage ratio of the potential transformer, default value is 60.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
ctprim Vector{Vector{Real}} amp oltc Current transformer rating on primary side, default value is 300.0 for the controlled winding, 0.0 for winding without regulator control, size=((nphases),nwindings)
r Vector{Vector{Real}} volt oltc Resistance setting on line drop compensator, default value is 0.0 for both controlled winding and winding without regulator control, size=((nphases),nwindings)
x Vector{Vector{Real}} volt oltc Reactance 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.

Name Default Type Units Used Description
f_bus String always id of from-side bus connection
t_bus String always id of to-side bus connection
f_connections Vector{Int} always Indicates for each conductor, to which terminal of the f_bus it connects
t_connections Vector{Int} always Indicates for each conductor, to which terminal of the t_bus it connects
cm_ub Vector{Real} amp opf Symmetrically applicable current rating
sm_ub Vector{Real} watt opf Symmetrically applicable power rating
linecode String always id of an associated linecode, does not take into account conductance/susceptance
rs zeros(nphases,nphases) Matrix{Real} ohm always Series resistance matrix, size=(nphases,nphases)
xs zeros(nphases,nphases) Matrix{Real} ohm always Series reactance matrix, size=(nphases,nphases)
dispatchable NO Dispatchable NO or YES, indicates whether switch state can be changed in a switching optimization problem
state CLOSED SwitchState always CLOSED: closed or OPEN: open, to indicate state of switch
status ENABLED Status always ENABLED 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)

Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
gs Matrix{Real} siemens always Conductance, size=(nconductors,nconductors)
bs Matrix{Real} siemens always Susceptance, size=(nconductors,nconductors)
model GENERIC ShuntModel GENERIC, CAPACITOR, or REACTOR. Indicates the type of shunt which may be necessary for transient stability analysis
dispatchable NO Dispatchable mld NO or YES, indicates whether a shunt can be shed
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,Any} multinetwork Dictionary 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.

Name Default Type Units Used Description
type Vector{String} capc Control type, default is current for controlled phase, `` for uncontrolled phase,size=1for`kvar`type, otherwise`size=(nphases)`
element String capc source_id of element (typically line or transformer) to which CapControl is connected
terminal Vector{Int} capc Number 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)
onsetting Vector{Real} capc Value 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)
offsetting Vector{Real} capc Value 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)
voltoverride Vector{Bool} capc Indicate whether voltage over ride is enabled, default is false for both controlled and uncontrolled phases, size=1 for kvar type, otherwise size=(nphases)
ptratio Vector{Real} capc Ratio of potential transformer, default is 60.0 for controlled phase, 0.0 for uncontrolled phase, size=(nphases)
ctratio Vector{Real} capc Ratio of current transformer, default is 60.0 for controlled phase, 0.0 for uncontrolled phase, size=(nphases)
vmin Vector{Real} volt capc Minimum 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)
vmax Vector{Real} volt capc Maximum 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)

Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
configuration WYE ConnConfig always WYE or DELTA. If WYE, connections[end]=neutral
model POWER LoadModel always POWER, IMPEDANCE, CURRENT, EXPONENTIAL, or ZIP. Indicates the type of voltage-dependency
pd_nom Vector{Real} watt always Nominal active load, with respect to vm_nom, size=nphases
qd_nom Vector{Real} var always Nominal reactive load, with respect to vm_nom, size=nphases
vm_nom Real volt model!=POWER Nominal voltage (multiplier)
dispatchable NO Dispatchable mld NO or YES, indicates whether a load can be shed
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary 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
DELTA 2 1
DELTA 3 3
WYE 2 1
WYE 3 2
WYE N N-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,

model pd[i]/pd_nom[i]= qd[i]/qd_nom[i]=
POWER 1 1
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]
Name Default Type Units Used Description
pd_exp Real model==EXPONENTIAL
qd_exp Real model==EXPONENTIAL

model == ZIP

ZIP load models are split into IMPEDANCE, CURRENT, POWER models.

  • (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]
Name Default Type Units Used Description
zipv Vector{Real} model==ZIP First 3 are ZIP weighting factors for active power (pd_cz,pd_ci,pd_cp), next 3 are ZIP weighting factors for reactive power (qd_cz,qd_ci,qd_cp), last 1 is cut-off voltage in p.u. of base kV; load is 0 below this cut-off

Generators (generator)

Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
configuration WYE ConnConfig always WYE or DELTA. If WYE, connections[end]=neutral
vg Vector{Real} volt control_mode==ISOCHRONOUS Voltage magnitude setpoint
pg_lb zeros(nphases) Vector{Real} watt opf Lower bound on active power generation per phase, size=nphases
pg_ub fill(Inf, nphases) Vector{Real} watt opf Upper bound on active power generation per phase, size=nphases
qg_lb -pg_ub Vector{Real} var opf Lower bound on reactive power generation per phase, size=nphases
qg_ub pg_ub Vector{Real} var opf Upper bound on reactive power generation per phase, size=nphases
pg Vector{Real} watt solution Present active power generation per phase, size=nphases
qg Vector{Real} var solution Present reactive power generation per phase, size=nphases
control_mode FREQUENCYDROOP ControlMode FREQUENCYDROOP or ISOCHRONOUS
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary containing time series parameters.

generator Cost Model

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

Name Default Type Units Used Description
cost_pg_model 2 Int opf Cost model type, 1 = piecewise-linear, 2 = polynomial
cost_pg_parameters [0.0, 1.0, 0.0] Vector{Real} $/MVA opf Cost model polynomial

Photovoltaic Systems (solar)

Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
configuration WYE ConnConfig always WYE or DELTA. If WYE, connections[end]=neutral
pg_lb Vector{Real} watt opf Lower bound on active power generation per phase, size=nphases
pg_ub Vector{Real} watt opf Upper bound on active power generation per phase, size=nphases
qg_lb Vector{Real} var opf Lower bound on reactive power generation per phase, size=nphases
qg_ub Vector{Real} var opf Upper bound on reactive power generation per phase, size=nphases
pg Vector{Real} watt solution Present active power generation per phase, size=nphases
qg Vector{Real} var solution Present reactive power generation per phase, size=nphases
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary containing time series parameters.

solar Cost Model

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

Name Default Type Units Used Description
cost_pg_model 2 Int opf Cost model type, 1 = piecewise-linear, 2 = polynomial
cost_pg_parameters [0.0, 1.0, 0.0] Vector{Real} $/MVA opf Cost 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
Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
configuration WYE ConnConfig always WYE or DELTA. If WYE, connections[end]=neutral
energy Real watt-hr always Stored energy
energy_ub Real opf maximum energy rating
charge_ub Real opf maximum charge rating
discharge_ub Real opf maximum discharge rating
sm_ub Real watt opf Power rating,
cm_ub Real amp opf Current rating,
charge_efficiency Real percent always charging efficiency (losses)
discharge_efficiency Real percent always discharging efficiency (losses)
qs_ub Real opf Maximum reactive power injection,
qs_lb Real opf Minimum reactive power injection,
rs Real ohm always converter resistance
xs Real ohm always converter reactance
pex Real always Total active power standby exogenous flow (loss)
qex Real always Total reactive power standby exogenous flow (loss)
ps Vector{Real} watt solution Present active power injection
qs Vector{Real} var solution Present reactive power injection
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary 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.

Name Default Type Units Used Description
bus String always id of bus connection
connections Vector{Int} always Ordered list of connected conductors, size=nconductors
configuration WYE ConnConfig always WYE or DELTA. If WYE, connections[end]=neutral
vm ones(nphases) Vector{Real} volt always Voltage magnitude set at slack bus, size=nphases
va zeros(nphases) Real degree always Voltage angle offsets at slack bus, applies symmetrically to each phase angle
rs zeros(nconductors,nconductors) Matrix{Real} ohm always Internal series resistance of voltage source, size=(nconductors,nconductors)
xs zeros(nconductors,nconductors) Matrix{Real} ohm always Internal series reactance of voltage soure, size=(nconductors,nconductors)
status ENABLED Status always ENABLED or DISABLED. Indicates if component is enabled or disabled, respectively
time_series Dict{String,String} multinetwork Dictionary 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.

Name Default Type Units Used Description
rs Matrix{Real} ohm/meter always Series resistance, size=(nconductors,nconductors)
xs Matrix{Real} ohm/meter always Series reactance, size=(nconductors,nconductors)
g_fr zeros(nconductors,nconductors) Matrix{Real} siemens/meter/Hz always From-side conductance, size=(nconductors,nconductors)
b_fr zeros(nconductors,nconductors) Matrix{Real} siemens/meter/Hz always From-side susceptance, size=(nconductors,nconductors)
g_to zeros(nconductors,nconductors) Matrix{Real} siemens/meter/Hz always To-side conductance, size=(nconductors,nconductors)
b_to zeros(nconductors,nconductors) Matrix{Real} siemens/meter/Hz always To-side susceptance, size=(nconductors,nconductors)
cm_ub fill(Inf,nconductors) Vector{Real} ampere opf maximum current per conductor, symmetrically applicable
sm_ub fill(Inf,nconductors) Vector{Real} watt opf maximum power per conductor, symmetrically applicable

Transformer Codes (xfmrcode)

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

Name Default Type Units Used Description
configurations fill(WYE, nwindings) Vector{ConnConfig} always WYE or DELTA. List of configuration for each winding, size=nwindings
xsc [0.0] Vector{Real} ohm always List of short-circuit reactances between each pair of windings; enter as a list of the upper-triangle elements, size=(nwindings == 2 ? 1 : 3)
rw zeros(nwindings) Vector{Real} ohm always List of the winding resistance for each winding, size=nwindings
tm_nom ones(nwindings) Vector{Real} always Nominal tap ratio for the transformer, size=nwindings (multiplier)
tm_ub Vector{Vector{Real}} opf Maximum tap ratio for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_lb Vector{Vector{Real}} opf Minimum tap ratio for for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_set fill(fill(1.0, nphases), nwindings) Vector{Vector{Real}} always Set tap ratio for each winding and phase, size=((nphases), nwindings) (base=tm_nom)
tm_fix fill(fill(true, nphases), nwindings) Vector{Vector{Bool}} always Indicates 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 reference 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.

Name Default Type Units Used Description
time Union{Vector{Real},Vector{String}} hour always Time points at which values are specified. If time is specified in String, units not required to be in hours.
values Vector{Real} always Multipers at each time step given in time
offset 0 Real hour always Start time offset
replace true Bool always Indicates 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

Name Default Type Units Used Description
component_type String
component_id String
terminals Vector{Int}
fuse_curve Array{Vector{Real},2} specifies the fuse blowing condition
minimum_melting_curve Array{Vector{Real},2} specifies the minimum melting conditions of the fuse