mp.data_model

class mp.data_model

Bases: mp.element_container

mp.data_model - Base class for MATPOWER data model objects.

The data model object encapsulates the input data provided by the user for the problem of interest and the output data presented back to the user upon completion. It corresponds roughly to the mpc (MATPOWER case) and results structs used throughout the legacy MATPOWER implementation, but encapsulated in an object with additional functionality. It includes tables of data for each type of element in the system.

A data model object is primarily a container for data model element (mp.dm_element) objects. Concrete data model classes may be specific to the task.

By convention, data model variables are named dm and data model class names begin with mp.data_model.

mp.data_model Properties:

base_mva - system per unit MVA base
base_kva - system per unit kVA base
source - source of data, e.g. mpc (MATPOWER case struct)
userdata - arbitrary user data

mp.data_model Methods:

data_model() - constructor, assign default data model element classes
copy() - make duplicate of object
build() - create, add, and build element objects
count() - count instances of each element and remove if count is zero
initialize() - initialize (online/offline) status of each element
update_status() - update (online/offline) status based on connectivity, etc
build_params() - extract/convert/calculate parameters for online elements
online() - get number of online elements of named type
display() - display the data model object
pretty_print() - pretty print data model to console or file
pp_flags() - from options, build flags to control pretty printed output
pp_section_label() - construct section header lines for output
pp_section_list() - return list of section tags
pp_have_section() - return true if section exists for object
pp_section() - pretty print the given section
pp_get_headers() - construct pretty printed lines for section headers
pp_get_headers_cnt() - construct pretty printed lines for cnt section headers
pp_get_headers_ext() - construct pretty printed lines for ext section headers
pp_data() - pretty print the data for the given section
set_bus_v_lims_via_vg() - set gen bus voltage limits based on gen voltage setpoints

See the Data Model Object section in the MATPOWER Developer’s Manual for more information.

Constructor Summary

data_model()

Constructor, assign default data model element classes.

dm = mp.data_model()

Property Summary

base_mva: (double) system per unit MVA base, for balanced single-phase systems/sections, must be provided if system includes any 'bus' elements

base_kva: (double) system per unit kVA base, for unbalanced 3-phase systems/sections, must be provided if system includes any 'bus3p' elements

source: source of data, e.g. mpc (MATPOWER case struct)

userdata = struct(): (struct) arbitrary user data

Method Summary

copy()

Create a duplicate of the data model object, calling the copy() method on each element.

new_dm = dm.copy()

build(d, dmc)

Create and add data model element objects.

dm.build(d, dmc)

Inputs:

d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)
dmc (mp.dm_converter) – data model converter

Create the data model element objects by instantiating each class in the element_classes property and adding the resulting object to the elements property. Then proceed through the following additional build() stages for each element.

Import

Count

Initialize

Update status

Build parameters

See the Building a Data Model section in the MATPOWER Developer’s Manual for more information.

count()

Count instances of each element and remove if count() is zero.

dm.count()

Call each element’s count() method to determine the number of instances of that element in the data, and remove the element type from elements if the count is 0.

Called by build() to perform its count stage. See the Building a Data Model section in the MATPOWER Developer’s Manual for more information.

initialize()

Initialize (online/offline) status of each element.

dm.initialize()

Call each element’s initialize() method to initialize() statuses and create ID to row index mappings.

Called by build() to perform its initialize stage. See the Building a Data Model section in the MATPOWER Developer’s Manual for more information.

update_status()

Update (online/offline) status based on connectivity, etc.

dm.update_status()

Call each element’s update_status() method to update statuses based on connectivity or other criteria and define element properties containing number and row indices of online elements, indices of offline elements, and mapping of row indices to indices in online and offline element lists.

Called by build() to perform its update status stage. See the Building a Data Model section in the MATPOWER Developer’s Manual for more information.

build_params()

Extract/convert/calculate parameters for online elements.

dm.build_params()

Call each element’s build_params() method to build parameters as necessary for online elements from the original data tables (e.g. p.u. conversion, initial state, etc.) and store them in element-specific properties.

Called by build() to perform its build parameters stage. See the Building a Data Model section in the MATPOWER Developer’s Manual more information.

online(name)

Get number of online elements of named type.

n = dm.online(name)

Input:: name (char array) – name of element type (e.g. 'bus', 'gen') as returned by the element’s name() method
Output:: n (integer) – number of online elements

display()

Display the data model object.

This method is called automatically when omitting a semicolon on a line that retuns an object of this class.

Displays the details of the data model elements.

pretty_print(mpopt, fd)

Pretty print data model to console or file.

dm.pretty_print(mpopt)
dm.pretty_print(mpopt, fd)
[dm, out] = dm.pretty_print(mpopt, fd)

Inputs:

mpopt (struct) – MATPOWER options struct
fd (integer) – (optional, default = 1) file identifier to use for printing, (1 for standard output, 2 for standard error)

Outputs:

dm (mp.data_model) – the data model object
out (struct) – struct of output control flags

Displays the model parameters to a pretty-printed text format. The result can be output either to the console or to a file.

The output is organized into sections and each element type controls its own output for each section. The default sections are:

cnt - counts, number of online, offline, and total elements of this type

sum - summary, e.g. total amount of capacity, load, line loss, etc.

ext - extremes, e.g. min and max voltages, nodal prices, etc.

det - details, table of detailed data, e.g. voltages, prices for buses, dispatch, limits for generators, etc.

pp_flags(mpopt)

From options, build flags to control pretty printed output.

[out, add] = dm.pp_flags(mpopt)

Input:

mpopt (struct) – MATPOWER options struct

Outputs:

out (struct) – struct of output control flags

out
  .all    (-1, 0 or 1)
  .any    (0 or 1)
  .sec
    .cnt
      .all    (-1, 0 or 1)
      .any    (0 or 1)
    .sum    (same as cnt)
    .ext    (same as cnt)
    .det
      .all    (-1, 0 or 1)
      .any    (0 or 1)
      .elm
        .<name>    (0 or 1)

where <name> is the name of the corresponding element type.

add (struct) – additional data for subclasses to use

add
  .s0
    .<name> = 0
  .s1
    .<name> = 1
  .suppress    (-1, 0 or 1)
  .names    (cell array of element names)
  .ne       (number of element names)

See also pretty_print().

pp_section_label(label, blank_line)

Construct pretty printed lines for section label.

h = dm.pp_section_label(label, blank_line)

Inputs:

label (char array) – label for the section header
blank_line (boolean) – include a blank line before the section label if true

Output:

h (cell array of char arrays) – individual lines of section label

See also pretty_print().

pp_section_list(out)

Return list of section tags.

sections = dm.pp_section_list(out)

Input:: out (struct) – struct of output control flags (see pp_flags() for details)
Output:: sections (cell array of char arrays) – e.g. {'cnt', 'sum', 'ext', 'det'}

See also pretty_print().

pp_have_section(section, mpopt)

Return true if section exists for object with given options.

TorF = dm.pp_have_section(section, mpopt)

Inputs:

section (char array) – e.g. 'cnt', 'sum', 'ext', or 'det'
mpopt (struct) – MATPOWER options struct

Output:

TorF (boolean) – true if section exists

See also pretty_print().

pp_section(section, out_s, mpopt, fd)

Pretty print the given section.

dm.pp_section(section, out_s, mpopt, fd)

Inputs:

section (char array) – e.g. 'cnt', 'sum', 'ext', or 'det'
out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct
fd (integer) – (optional, default = 1) file identifier to use for printing, (1 for standard output, 2 for standard error)

See also pretty_print().

pp_get_headers(section, out_s, mpopt)

Construct pretty printed lines for section headers.

h = dm.pp_get_headers(section, out_s, mpopt)

Inputs:

section (char array) – e.g. 'cnt', 'sum', 'ext', or 'det'
out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct

Output:

h (cell array of char arrays) – individual lines of section headers

See also pretty_print().

pp_get_headers_cnt(out_s, mpopt)

Construct pretty printed lines for cnt section headers.

h = dm.pp_get_headers_cnt(out_s, mpopt)

Inputs:

out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct

Output:

h (cell array of char arrays) – individual lines of cnt section headers

pp_get_headers_ext(out_s, mpopt)

Construct pretty printed lines for ext section headers.

h = dm.pp_get_headers_cnt(out_s, mpopt)

Inputs:

out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct

Output:

h (cell array of char arrays) – individual lines of ext section headers

pp_get_headers_other(section, out_s, mpopt)

Construct pretty printed lines for other section headers.

Returns nothing in base class, but subclasses can implement other section types (e.g. 'lim' for OPF).

h = dm.pp_get_headers_other(section, out_s, mpopt)

Inputs:

section (char array) – e.g. 'cnt', 'sum', 'ext', or 'det'
out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct

Output:

h (cell array of char arrays) – individual lines of ext section headers

pp_data(section, out_s, mpopt, fd)

Pretty print the data for the given section.

dm.pp_data(section, out_s, mpopt, fd)

Inputs:

section (char array) – e.g. 'cnt', 'sum', 'ext', or 'det'
out_s (struct) – output control flags for the section, out_s = out.sec.(section)
mpopt (struct) – MATPOWER options struct
fd (integer) – (optional, default = 1) file identifier to use for printing, (1 for standard output, 2 for standard error)

set_bus_v_lims_via_vg(use_vg)

Set gen bus voltage limits based on gen voltage setpoints.

dm.set_bus_v_lims_via_vg(use_vg)

Input:: use_vg (double) – 1 if voltage setpoint should be used, 0 for original bus voltage bounds, or fractional value between 0 and 1 for bounds interpolated between the two.