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 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.

Settings (settings)

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

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).

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.

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.

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.

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, configuration may be used. xfmrcode is ignored for this component.

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.

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.

Node Objects

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

Shunts (shunt)

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.

Loads (load)

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,

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,

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]

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]

Generators (generator)

generator Cost Model

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

Photovoltaic Systems (solar)

solar Cost Model

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

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

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.

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.

Transformer Codes (xfmrcode)

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

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.

Fuses (fuse)

Fuses can be defined on any terminal of any physical component