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 ofmp.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 withmp.nme
.- mp.mm_element Properties:
- mp.mm_element Methods:
name()
- get name of element type, e.g.'bus'
,'gen'
np()
- number of ports per element of this typenn()
- number of nodes per element, created by this element typenz()
- number of non-voltage state variables per element of this typedata_model_element()
- get the corresponding data model elementmath_model_element()
- get the corresponding math model elementcount()
- get number of online elements indm
, setnk
add_nodes()
- add nodes to network modeladd_states()
- add non-voltage states to network modeladd_vvars()
- add real-valued voltage variables to network objectadd_zvars()
- add real-valued non-voltage state variables to network objectbuild_params()
- build model parameters from data modelget_nv_()
- get number of (possibly complex) voltage variablesx2vz()
- get port voltages and non-voltage states from combined state vectornode_indices()
- construct node indices from data model element connection infoincidence_matrix()
- construct stacked incidence matrix from set of index vectorsnode_types()
- get node type informationset_node_type_ref()
- make the specified node a reference nodeset_node_type_pv()
- make the specified node a PV nodeset_node_type_pq()
- make the specified node a PQ nodedisplay()
- 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, andkk = 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 andkk = 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 objectname (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 objectname (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
, setnk
.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 objectdm (
mp.data_model
) – data model object
Add nodes to the network model object, based on value nn returned by
nn()
. Calls the network model’sadd_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 objectdm (
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’sadd_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 objectdm (
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 objectdm (
mp.data_model
) – data model objectidx (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 objectdm (
mp.data_model
) – data model object
Construction of incidence matrices
C
andD
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.See also
incidence_matrix()
,node_indices()
.
- 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 thesysx
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 inputx_
.
- 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 objectdm (
mp.data_model
) – data model objectcxn_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; seemp.dm_element.cxn_type()
for more infocxn_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'}
); seemp.dm_element.cxn_idx_prop()
for more infocxn_type_prop (char array or cell array of char arrays) – name(s) of properties containing type of junction elements for each connection, defaults to
''
ifcxn_type
andcxn_type_prop
are provided, but notcxn_type_prop
; seemp.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 formC
.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.
See also
incidence_matrix()
,mp.dm_element.cxn_type()
,mp.dm_element.cxn_idx_prop()
,mp.dm_element.cxn_type_prop()
.
- 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 ofidx
, and columnj
of the corresponding incidence matrix consists of all zeros with a 1 in rowidx(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 objectdm (
mp.data_model
) – data model objectidx (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
See also
mp.NODE_TYPE
.
- set_node_type_ref(dm, idx)
Make the specified node a reference node.
nme.set_node_type_ref(dm, idx)
- Inputs:
dm (
mp.data_model
) – data model objectidx (integer) – index of node to modify, this is the internal network model element index
Set the specified node to type
mp.NODE_TYPE.REF
.Implementation provided by node-creating subclass.
- set_node_type_pv(dm, idx)
Make the specified node a PV node.
nme.set_node_type_pv(dm, idx)
- Inputs:
dm (
mp.data_model
) – data model objectidx (integer) – index of node to modify, this is the internal network model element index
Set the specified node to type
mp.NODE_TYPE.PV
.Implementation provided by node-creating subclass.
- set_node_type_pq(dm, idx)
Make the specified node a PQ node.
nme.set_node_type_pq(dm, idx)
- Inputs:
dm (
mp.data_model
) – data model objectidx (integer) – index of node to modify, this is the internal network model element index
Set the specified node to type
mp.NODE_TYPE.PQ
.Implementation provided by node-creating subclass.
- display()
Display the network model element 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 elements, including total number of elements, nodes per element, ports per element, non-voltage state per element, formulation name, tag, and class, and names and dimensions of the model parameters.