mp.net_model
- class mp.net_model
Bases:
mp.nm_element
,mp.element_container
,mp_idx_manager
mp.net_model
- Abstract base class for MATPOWER network model objects.The network model defines the states of and connections between network elements, as well as the parameters and functions defining the relationships between states and port injections. A given network model implements a specific network model formulation, and defines sets of nodes, ports, and states.
A network model object is primarily a container for network model element (
mp.nm_element
) objects and is itself a network model element. All network model classes inherit frommp.net_model
and therefore also frommp.element_container
,mp_idx_manager
, andmp.nm_element
. Concrete network model classes are also formulation-specific, inheriting from a corresponding subclass ofmp.form
.By convention, network model variables are named
nm
and network model class class names begin withmp.net_model
.- mp.net_model Properties:
the_np
- total number of portsthe_nz
- total number of non-voltage statesnv
- total number of (real) voltage variablesnode
-mp_idx_manager
data for nodesport
-mp_idx_manager
data for portsstate
-mp_idx_manager
data for non-voltage states
- mp.net_model Methods:
name()
- return name of this network element type ('network'
)np()
- return number of ports for this network elementnz()
- return number of (possibly complex) non-voltage states for this network elementbuild()
- create, add, and build network model element objectsadd_nodes()
- elements add nodes, then add corresponding voltage variablesadd_states()
- elements add states, then add corresponding state variablesbuild_params()
- build incidence matrices, parameters, add ports for each elementstack_matrix_params()
- form network matrix parameter by stacking corresponding element parametersstack_vector_params()
- form network vector parameter by stacking corresponding element parametersadd_vvars()
- add voltage variable(s) for each network nodeadd_zvars()
- add non-voltage state variable(s) for each network statedef_set_types()
- define node, state, and port set types formp_idx_manager
init_set_types()
- initialize structures for tracking/indexing nodes, states, portsdisplay()
- display the network model objectadd_node()
- add named set of nodesadd_port()
- add named set of portsadd_state()
- add named set of statesset_type_idx_map()
- map node/port/state index back to named set & index within setset_type_label()
- create a user-readable label to identify a node, port, or stateadd_var()
- add a set of variables to the modelparams_var()
- return initial value, bounds, and variable type for variablesget_node_idx()
- get index information for named node setget_port_idx()
- get index information for named port setget_state_idx()
- get index information for named state setnode_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 node
See the Network Model Object section in the MATPOWER Developer’s Manual for more information.
See also
mp.form
,mp.nm_element
,mp.task
,mp.data_model
,mp.math_model
.- Property Summary
- the_np = 0
(integer) total number of ports
- the_nz = 0
(integer) total number of non-voltage states
- nv = 0
(integer) total number of (real) voltage variables
- node = []
(struct)
mp_idx_manager
data for nodes
- port = []
(struct)
mp_idx_manager
data for ports
- state = []
(struct)
mp_idx_manager
data for non-voltage states
- Method Summary
- name()
Return the name of this network element type (
'network'
).name = nm.name()
- np()
Return the number of ports for this network element.
np = nm.np()
- nz()
Return the number of (possibly complex) non-voltage states for this network element.
nz = nm.nz()
- build(dm)
Create, add, and
build()
network model element objects.nm.build(dm)
- Input:
dm (
mp.data_model
) – data model object
Create and add network model element objects, add nodes and states, and build the parameters for all elements.
See also
add_nodes()
,add_states()
,build_params()
.
- add_nodes(nm, dm)
Elements add nodes, then add corresponding voltage variables.
nm.add_nodes(nm, dm)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model object
Each element can add its nodes, then the network model itself can add additional nodes, and finally corresponding voltage variables are added for each node.
See also
add_vvars()
,add_states()
.
- add_states(nm, dm)
Elements add states, then add corresponding state variables.
nm.add_states(nm, dm)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model object
Each element can add its states, then corresponding non-voltage state variables are added for each state.
See also
add_zvars()
,add_nodes()
.
- build_params(nm, dm)
Build incidence matrices and parameters, and add ports for each element.
nm.build_params(nm, dm)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model object
For each element, build connection and state variable incidence matrices and element parameters, and add ports. Then construct the full network connection and state variable incidence matrices.
- stack_matrix_params(name, vnotz)
Form network matrix parameter by stacking corresponding element parameters.
M = nm.stack_matrix_params(name, vnotz)
- Inputs:
name (char array) – name of the parameter of interest
vnotz (boolean) – true if columns of parameter correspond to voltage variables, false otherwise
- Output:
M (double) – matrix parameter of interest for the full network
A given matrix parameter (e.g.
Y
) for the full network is formed by stacking the corresponding matrix parameters for each element along the matrix block diagonal.
- stack_vector_params(name)
Form network vector parameter by stacking corresponding element parameters.
v = nm.stack_vector_params(name)
- Input:
name (char array) – name of the parameter of interest
- Output:
v (double) – vector parameter of interest for the full network
A given vector parameter (e.g.
s
) for the full network is formed by vertically stacking the corresponding vector parameters for each element.
- add_vvars(nm, dm, idx)
Add voltage variable(s) for each network node.
nm.add_vvars(nm, dm) nm.add_vvars(nm, dm, idx)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectidx (integer) – index for name and indexed variables (currently unused here)
Also updates the
nv
property.See also
add_zvars()
,add_nodes()
.
- add_zvars(nm, dm, idx)
Add non-voltage state variable(s) for each network state.
nm.add_zvars(nm, dm) nm.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 (currently unused here)
See also
add_vvars()
,add_states()
.
- def_set_types()
Define node, state, and port set types for
mp_idx_manager
.nm.def_set_types()
Define the following set types:
'node'
- NODES'state'
- STATES'port'
- PORTS
See also
mp_idx_manager
.
- init_set_types()
Initialize structures for tracking/indexing nodes, states, ports.
nm.init_set_types()
See also
mp_idx_manager
.
- display()
Display the network 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 nodes, ports, states, voltage variables, non-voltage state variables, and network model elements.
See also
mp_idx_manager
.
- add_node(name, idx, N)
Add named set of nodes.
nm.add_node(name, N) nm.add_node(name, idx, N)
- Inputs:
name (char array) – name for set of nodes
idx (cell array) – indices for named, indexed set of nodes
N (integer) – number of nodes in set
See also
mp_idx_manager.add_named_set()
.
- add_port(name, idx, N)
Add named set of ports.
nm.add_port(name, N) nm.add_port(name, idx, N)
- Inputs:
name (char array) – name for set of ports
idx (cell array) – indices for named, indexed set of ports
N (integer) – number of ports in set
See also
mp_idx_manager.add_named_set()
.
- add_state(name, idx, N)
Add named set of states.
nm.add_state(name, N) nm.add_state(name, idx, N)
- Inputs:
name (char array) – name for set of states
idx (cell array) – indices for named, indexed set of states
N (integer) – number of states in set
See also
mp_idx_manager.add_named_set()
.
- set_type_idx_map(set_type, idxs, dm, group_by_name)
Map node/port/state index back to named set & index within set.
s = obj.set_type_idx_map(set_type) s = obj.set_type_idx_map(set_type, idxs) s = obj.set_type_idx_map(set_type, idxs, dm) s = obj.set_type_idx_map(set_type, idxs, dm, group_by_name)
- Inputs:
set_type (char array) –
'node'
,'port'
, or'state'
idxs (integer) – vector of indices, defaults to
[1:ns]'
, wherens
is the full dimension of the set corresponding to the all elements for the specified set type (i.e. node, port, or state)dm (
mp.data_model
) – data model objectgroup_by_name (boolean) – if true, results are consolidated, with a single entry in
s
for each unique name/idx pair, where thei
andj
fields are vectors
- Output:
s (struct) – index map of same dimensions as
idxs
, unlessgroup_by_name
is true, in which case it is 1 dimensional
Returns a struct of same dimensions as
idxs
specifying, for each index, the corresponding named set and element within the named set for the specifiedset_type
. The return struct has the following fields:name
: name of corresponding setidx
: cell array of indices for the name, if named set is indexedi
: index of element within the sete
: external index (i.e. corresponding row in data model)ID
: external ID (i.e. corresponding element ID in data model)j
: (only ifgroup_by_name
== 1), corresponding index of set type, equal to a particular element ofidxs
Examples:
s = nm.set_type_idx_map('node', 87, dm)); s = nm.set_type_idx_map('port', [38; 49; 93], dm)); s = nm.set_type_idx_map('state')); s = nm.set_type_idx_map('node', [], dm, 1));
- set_type_label(set_type, idxs, dm)
Create a user-readable label to identify a node, port, or state.
label = nm.set_type_label(set_type, idxs) label = nm.set_type_label(set_type, idxs, dm)
- Inputs:
set_type (char array) –
'node'
,'port'
, or'state'
idxs (integer) – vector of indices
dm (
mp.data_model
) – data model object
- Output:
label (cell array) – same dimensions as
idxs
, where each entry is a char array
Example:
labels = nm.set_type_label('port', [1;6;15;20], dm) labels = 4×1 cell array {'gen 1' } {'load 3' } {'branch(1) 9'} {'branch(2) 5'}
- add_var(vtype, name, idx, varargin)
Add a set of variables to the model.
nm.add_var(vtype, name, N, v0, vl, vu, vt) nm.add_var(vtype, name, N, v0, vl, vu) nm.add_var(vtype, name, N, v0, vl) nm.add_var(vtype, name, N, v0) nm.add_var(vtype, name, N) nm.add_var(vtype, name, idx_list, N, v0, vl, vu, vt) nm.add_var(vtype, name, idx_list, N, v0, vl, vu) nm.add_var(vtype, name, idx_list, N, v0, vl) nm.add_var(vtype, name, idx_list, N, v0) nm.add_var(vtype, name, idx_list, N)
- Inputs:
vtype (char array) – variable type, must be a valid struct field name
name (char array) – name of variable set
idx_list (cell array) – optional index list
N (integer) – number of variables in the set
v0 (double) – N x 1 col vector, initial value of variables, default is
0
vl (double) – N x 1 col vector, lower bounds, default is
-Inf
vu (double) – N x 1 col vector, upper bounds, default is
Inf
vt (char) – scalar or 1 x N row vector, variable type, default is
'C'
, valid element values are:'C'
- continuous'I'
- integer'B'
- binary
Essentially identical to the
add_var()
method fromopt_model
of MP-Opt-Model, with the addition of a variable type (vtype
).See also
opt_model.add_var()
.
- params_var(vtype, name, idx)
Return initial value, bounds, and variable type for variables.
[v0, vl, vu] = nm.params_var(vtype) [v0, vl, vu] = nm.params_var(vtype, name) [v0, vl, vu] = nm.params_var(vtype, name, idx_list) [v0, vl, vu, vt] = nm.params_var(...)
- Inputs:
vtype (char array) – variable type, must be a valid struct field name
name (char array) – name of variable set
idx_list (cell array) – optional index list
- Outputs:
v0 (double) – N x 1 col vector, initial value of variables
vl (double) – N x 1 col vector, lower bounds
vu (double) – N x 1 col vector, upper bounds
vt (char) – scalar or 1 x N row vector, variable type, valid element values are:
'C'
- continuous'I'
- integer'B'
- binary
Essentially identical to the
params_var()
method fromopt_model
of MP-Opt-Model, with the addition of a variable type (vtype
).Returns the initial value
v0
, lower boundvl
and upper boundvu
for the full variable vector, or for a specific named or named and indexed variable set. Optionally also returns a corresponding char vectorvt
of variable types, where'C'
,'I'
and'B'
represent continuous, integer, and binary variables, respectively.Examples:
[vr0, vrmin, vrmax] = obj.params_var('vr'); [pg0, pg_lb, pg_ub] = obj.params_var('zr', 'pg'); [zij0, zij_lb, zij_ub, ztype] = obj.params_var('zi', 'z', {i, j});
See also
opt_model.params_var()
.
- get_node_idx(name)
Get index information for named node set.
[i1 iN] = nm.get_node_idx(name) nidx = nm.get_node_idx(name)
- Input:
name (char array) – name of node set
- Outputs:
i1 (integer) – index of first node for
name
iN (integer) – index of last node for
name
nidx (integer or cell array) – indices of nodes for
name
, equal to either[i1:iN]'
or{[i1(1):iN(1)]', ..., [i1(n):iN(n)]'}
- get_port_idx(name)
Get index information for named port set.
[i1 iN] = nm.get_port_idx(name) pidx = nm.get_port_idx(name)
- Input:
name (char array) – name of port set
- Outputs:
i1 (integer) – index of first port for
name
iN (integer) – index of last port for
name
pidx (integer or cell array) – indices of ports for
name
, equal to either[i1:iN]'
or{[i1(1):iN(1)]', ..., [i1(n):iN(n)]'}
- get_state_idx(name)
Get index information for named state set.
[i1 iN] = nm.get_state_idx(name) sidx = nm.get_state_idx(name)
- Input:
name (char array) – name of state set
- Outputs:
i1 (integer) – index of first state for
name
iN (integer) – index of last state for
name
sidx (integer or cell array) – indices of states for
name
, equal to either[i1:iN]'
or{[i1(1):iN(1)]', ..., [i1(n):iN(n)]'}
- node_types(nm, dm, idx, skip_ensure_ref)
Get node type information.
ntv = nm.node_types(nm, dm) [ntv, by_elm] = nm.node_types(nm, dm) [ref, pv, pq] = nm.node_types(nm, dm) [ref, pv, pq, by_elm] = nm.node_types(nm, dm) ... = nm.node_types(nm, dm, idx) ... = nm.node_types(nm, dm, idx, skip_ensure_ref)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectidx (integer) – index (not used in base method)
skip_ensure_ref (boolean) – unless true, if there is no reference node, the first PV node will be converted to a new reference
- 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
by_elm (struct) –
by_elm(k)
is struct for k-th node-creating element type, with fields:'name'
- name of corresponding node-creating element type'ntv'
- node type vector (ifby_elm
is 2nd output arg)'ref'
/'pv'
/'pq'
- index vectors into elements of corresponding node-creating element type (ifby_elm
is 4th output arg)
See also
mp.NODE_TYPE
,ensure_ref_node()
.
- ensure_ref_node(dm, ref, pv, pq)
Ensure there is at least one reference node.
[ref, pv, pq] = nm.ensure_ref_node(dm, ref, pv, pq) ntv = nm.ensure_ref_node(dm, ntv)
- Inputs:
dm (
mp.data_model
) – data model objectref (integer) – vector of indices of reference nodes
pv (integer) – vector of indices of PV nodes
pq (integer) – vector of indices of PQ nodes
ntv (integer) – node type vector, valid element values are:
- Outputs:
ref (integer) – updated vector of indices of reference nodes
pv (integer) – updated vector of indices of PV nodes
pq (integer) – updated vector of indices of PQ nodes
ntv (integer) – updated node type vector
- set_node_type_ref(dm, idx)
Make the specified node a reference node.
nm.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
.
- set_node_type_pv(dm, idx)
Make the specified node a PV node.
nm.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
.
- set_node_type_pq(dm, idx)
Make the specified node a PQ node.
nm.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
.