mp.nm_element

class mp.nm_element

Bases: handle

mp.nm_element - Abstract base class for MATPOWER network model element objects.

A network model element object encapsulates all of the network model parameters for a particular element type. All network model element classes inherit from mp.nm_element and also, like the container, from a formulation-specific subclass of mp.form. Each element type typically implements its own subclasses, which are further subclassed per formulation. A given network model element object contains the aggregate network model parameters for all online instances of that element type, stored in the set of matrices and vectors that correspond to the formulation.

By convention, network model element variables are named nme and network model element class names begin with mp.nme.

mp.mm_element Properties:

nk - number of elements of this type
C - stacked sparse element-node incidence matrices
D - stacked sparse incidence matrices for z-variables
soln - struct for storing solved states, quantities

mp.mm_element Methods:

name() - get name of element type, e.g. 'bus', 'gen'
np() - number of ports per element of this type
nn() - number of nodes per element, created by this element type
nz() - number of non-voltage state variables per element of this type
data_model_element() - get the corresponding data model element
math_model_element() - get the corresponding math model element
count() - get number of online elements in dm, set nk
add_nodes() - add nodes to network model
add_states() - add non-voltage states to network model
add_vvars() - add real-valued voltage variables to network object
add_zvars() - add real-valued non-voltage state variables to network object
build_params() - build model parameters from data model
get_nv_() - get number of (possibly complex) voltage variables
x2vz() - get port voltages and non-voltage states from combined state vector
node_indices() - construct node indices from data model element connection info
incidence_matrix() - construct stacked incidence matrix from set of index vectors
node_types() - get node type information
set_node_type_ref() - make the specified node a reference node
set_node_type_pv() - make the specified node a PV node
set_node_type_pq() - make the specified node a PQ node
display() - display the network model element object

See the Network Model Elements section in the MATPOWER Developer’s Manual for more information.

See also mp.net_model.

Property Summary

nk = 0: (integer) number of elements of this type

C = []: (sparse integer matrix) stacked element-node incidence matrices, where C(i,kk) is 1 if port j of element k is connected to node i, and kk = k + (j-1)*np

D = []: (sparse integer matrix) stacked incidence matrices for z-variables (non-voltage state variables), where D(i,kk) is 1 if z-variable j of element k is the i-th system z-variable and kk = k + (j-1)*nz

soln: (struct) for storing solved states, quantities

Method Summary

name()

Get name of element type, e.g. 'bus', 'gen'.

name = nme.name()

Output:: name (char array) – name of element type, must be a valid struct field name

Implementation provided by an element type specific subclass.

np()

Number of ports per element of this type.

np = nme.np()

Output:: np (integer) – number of ports per element of this type

nn()

Number of nodes per element, created by this element type.

nn = nme.nn()

Output:: nn (integer) – number of ports per element of this type

nz()

Number of non-voltage state variables per element of this type.

nz = nme.nz()

Output:: nz (integer) – number of non-voltage state variables per element of this type

data_model_element(dm, name)

Get the corresponding data model element.

dme = nme.data_model_element(dm)
dme = nme.data_model_element(dm, name)

Inputs:

dm (mp.data_model) – data model object
name (char array) – (optional) name of element type (default is name of this object)

Output:

dme (mp.dm_element) – data model element object

math_model_element(mm, name)

Get the corresponding math model element.

mme = nme.math_model_element(mm)
mme = nme.math_model_element(mm, name)

Inputs:

mm (mp.math_model) – math model object
name (char array) – (optional) name of element type (default is name of this object)

Output:

mme (mp.mm_element) – math model element object

count(dm)

Get number of online elements of this type in dm, set nk.

nk = nme.count(dm)

Input:: dm (mp.data_model) – data model object
Output:: nk (integer) – number of online elements of this type

add_nodes(nm, dm)

Add nodes to network model for this element.

nme.add_nodes(nm, dm)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object

Add nodes to the network model object, based on value nn returned by nn(). Calls the network model’s add_node() nn times.

add_states(nm, dm)

Add non-voltage states to network model for this element.

nme.add_states(nm, dm)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object

Add non-voltage states to the network model object, based on value nz returned by nz(). Calls the network model’s add_state() nz times.

add_vvars(nm, dm, idx)

Add real-valued voltage variables to network object.

nme.add_vvars(nm, dm, idx)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object

Add real-valued voltage variables (v-variables) to the network model object, for each port. Implementation depends on the specific formulation (i.e. subclass of mp.form).

For example, consider an element with np ports and an AC formulation with polar voltage representation. The actual port voltages are complex, but this method would call the network model’s add_var() twice for each port, once for the voltage angle variables and once for the voltage magnitude variables.

Implemented by a formulation-specific subclass.

add_zvars(nm, dm, idx)

Add real-valued non-voltage state variables to network object.

nme.add_zvars(nm, dm, idx)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object
idx (cell array) – indices for named and indexed variables

Add real-valued non-voltage state variables (z-variables) to the network model object. Implementation depends on the specific formulation (i.e. subclass of mp.form).

For example, consider an element with nz z-variables and a formulation in which these are complex. This method would call the network model’s add_var() twice for each complex z-variable, once for the variables representing the real part and once for the imaginary part.

Implemented by a formulation-specific subclass.

build_params(nm, dm)

Build model parameters from data model.

nme.build_params(nm, dm)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object

Construction of incidence matrices C and D are handled in this base class. Building of the formulation-specific model parameters must be implemented by a formulation-specific subclass. The subclass should call its parent in order to construct the incidence matrices.

get_nv_(sysx)

Get number of (possibly complex) voltage variables.

nv_ = nme.get_nv_(sysx)

Input:: sysx (boolean) – if true the state x_ refers to the full (possibly complex) system state (all node voltages and system non-voltage states), otherwise it is the state vector for this specific element type (port voltages and element non-voltage states)
Output:: nv_ (integer) – number of (possibly complex) voltage variables in the state variable x_, whose meaning depends on the sysx input

x2vz(x_, sysx, idx)

Get port voltages and non-voltage states from combined state vector.

[v_, z_, vi_] = nme.x2vz(x_, sysx, idx)

Inputs:

x_ (double) – possibly complex state vector
sysx (boolean) – if true the state x_ refers to the full (possibly complex) system state (all node voltages and system non-voltage states), otherwise it is the state vector for this specific element type (port voltages and element non-voltage states)
idx (integer) – vector of port indices of interest

Outputs:

v_ (double) – vector of (possibly complex) port voltages
z_ (double) – vector of (possibly complex) non-voltage state variables
vi_ (double) – vector of (possibly complex) port voltages for selected ports only, as indexed by idx

This method extracts voltage and non-voltage states from a combined state vector, optionally with voltages for specific ports only.

Note, that this method can operate on multiple state vectors simultaneously, by specifying x_ as a matrix. In this case, each output will have the same number of columns, one for each column of the input x_.

node_indices(nm, dm, cxn_type, cxn_idx_prop, cxn_type_prop)

Construct node indices from data model element connection info.

nidxs = nme.node_indices(nm, dm)
nidxs = nme.node_indices(nm, dm, cxn_type, cxn_idx_prop)
nidxs = nme.node_indices(nm, dm, cxn_type, cxn_idx_prop, cxn_type_prop)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object
cxn_type (char array or cell array of char arrays) – name(s) of type(s) of junction elements, i.e. node-creating elements (e.g. 'bus'), to which this element connects; see mp.dm_element.cxn_type() for more info
cxn_idx_prop (char array or cell array of char arrays) – name(s) of property(ies) containing indices of junction elements that define connections (e.g. {'fbus', 'tbus'}); see mp.dm_element.cxn_idx_prop() for more info
cxn_type_prop (char array or cell array of char arrays) – name(s) of properties containing type of junction elements for each connection, defaults to '' if cxn_type and cxn_type_prop are provided, but not cxn_type_prop; see mp.dm_element.cxn_type_prop() for more info

Output:

nidxs (cell array) – 1 x np cell array of node index vectors for each port

This method constructs the node index vectors for each port. That is, element p of nidxs is the vector of indices of the nodes to which port p of these elements are connected. These node indices can be used to construct the element-node incidence matrices that form C.

By default, the connection information is obtained from the corresponding data model element, as described in the Connections section in the MATPOWER Developer’s Manual.

incidence_matrix(m, varargin)

Construct stacked incidence matrix from set of index vectors.

CD = nme.incidence_matrix(m, idx1, idx2, ...)

Inputs:

m (integer) – total number of nodes or states
idx1 (integer) – index vector for nodes corresponding to this element’s first port, or state variables corresponding to this element’s first non-voltage state
idx2 (integer) – same as idx1 for second port or non-voltage state, and so on

Output:

CD (sparse matrix) – stacked incidence matrix (C for ports, D for states)

Forms an m x n incidence matrix for each input index vector idx, where n is the dimension of idx, and column j of the corresponding incidence matrix consists of all zeros with a 1 in row idx(j).

These incidence matrices are then stacked horizontally to form a single matrix return value.

node_types(nm, dm, idx)

Get node type information.

ntv           = nme.node_types(nm, dm)
[ref, pv, pq] = nme.node_types(nm, dm)
          ... = nme.node_types(nm, dm, idx)

Inputs:

nm (mp.net_model) – network model object
dm (mp.data_model) – data model object
idx (integer) – index (not used in base method)

Outputs:

ntv (integer) – node type vector, valid element values are:
ref (integer) – vector of indices of reference nodes
pv (integer) – vector of indices of PV nodes
pq (integer) – vector of indices of PQ nodes