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 from mp.net_model and therefore also from mp.element_container, mp_idx_manager, and mp.nm_element. Concrete network model classes are also formulation-specific, inheriting from a corresponding subclass of mp.form.

By convention, network model variables are named nm and network model class class names begin with mp.net_model.

mp.net_model Properties:
mp.net_model Methods:

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:

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:

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:

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 object

  • dm (mp.data_model) – data model object

  • idx (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 object

  • dm (mp.data_model) – data model object

  • idx (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]', where ns 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 object

  • group_by_name (boolean) – if true, results are consolidated, with a single entry in s for each unique name/idx pair, where the i and j fields are vectors

Output:

s (struct) – index map of same dimensions as idxs, unless group_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 specified set_type. The return struct has the following fields:

  • name : name of corresponding set

  • idx : cell array of indices for the name, if named set is indexed

  • i : index of element within the set

  • e : external index (i.e. corresponding row in data model)

  • ID : external ID (i.e. corresponding element ID in data model)

  • j : (only if group_by_name == 1), corresponding index of set type, equal to a particular element of idxs

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 from opt_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 from opt_model of MP-Opt-Model, with the addition of a variable type (vtype).

Returns the initial value v0, lower bound vl and upper bound vu for the full variable vector, or for a specific named or named and indexed variable set. Optionally also returns a corresponding char vector vt 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 object

  • dm (mp.data_model) – data model object

  • idx (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 (if by_elm is 2nd output arg)

    • 'ref'/'pv'/'pq' - index vectors into elements of corresponding node-creating element type (if by_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 object

  • ref (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 object

  • idx (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 object

  • idx (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 object

  • idx (integer) – index of node to modify, this is the internal network model element index

Set the specified node to type mp.NODE_TYPE.PQ.