mp.set_manager

class mp.set_manager

Bases: handle

mp.set_manager - MP Set Manager base class.

sm = mp.set_manager(label)

Implements functionality to manage the indexing of various named and indexed blocks of elements, such as variables, constraints, etc. This class helps keep track of the ordering and indexing of the various blocks as they are added to the object. Subclasses may implement additional functionality to handle data associated with each block.

mp.set_manager Properties:

label - the label of the set, e.g. 'VARIABLES', 'LINEAR CONSTRAINTS'
idx - indexing information
N - total number of entities in the full set
NS - number of named or named/indexed subsets or blocks
order - struct array of names/indices of blocks in order
data - struct of additional set-type-specific data for each block

mp.set_manager Methods:

set_manager() - constructor
copy() - make a duplicate (shallow copy) of the object
to_struct() - convert object data to a struct
from_struct() - copy object data from a struct
add() - add a named (and optionally indexed) subset of entities
describe_idx() - provide/display name and index label for given indices
display() - display summary of indexing of subsets in object
get_N() - return the number of elements in the set
init_indexed_name() - initialize dimensions for an indexed named set
set_type_idx_map() - map index back to named subset & index within set

By convention, sm is the variable name used for generic mp.set_manager objects.

Simple vs. Indexed Named Subsets

A subset or block of entities can be added as a simple named subset identified by a single name (e.g. foo), or as an indexed named subset identified by a name that is indexed by one or more indices (e.g. bar{4,3}). For an indexed named subset, the dimensions of the indexed subset must be supplied by calling init_indexed_name() before calling add().

Example

Suppose the goal is to create and manage a set of variables related to the charging of a fleet of \(n\) electric vehicles over a week, where we have variables representing daily charging amounts for each vehicle, daily discharge amounts from driving, and the final battery state at the end of the week. These could be organized as 7 blocks of charge variables, 1 for each day of the week, 7 blocks of discharge variables, and 1 battery_state block, where each block consists of an \(n \times 1\) vector of variables.

n = 20;
sm = mp.set_manager('VARIABLES');
sm.init_indexed_name('charge', 7);
sm.init_indexed_name('discharge', 7);
for d = 1:7
    sm.add('charge', {d}, n, ...);
    sm.add('discharge', {d}, n, ...);
end
sm.add('battery_state', n, ...);

The full set of variables will be a \((2 \times 7 + 1) \times n\) vector assembled in the order the variables are added, that is:

x = [
    charge{1};
    discharge{1};
    charge{2};
    discharge{2};
        .
        .
        .
    charge{7};
    discharge{7};
    battery_state ]

Constructor Summary

set_manager(label)

Constructor.

sm = mp.set_manager(label)
sm = mp.set_manager(s)

Input:

label (char array) – label used in display for this set type
s (struct) – a struct to use as an input to from_struct()

Property Summary

label: (char array) label used as header for display

idx = struct('i1',struct(),'iN',struct(),'N',struct())

(struct) indexing information, with the following 3 fields:

i1 - starting index of subset within full set

iN - ending index of subset within full set

N - number of elements in this subset

Each of the 3 fields above is a struct whose field names are the names of the corresponding blocks of elements. They are found in order in the corresponding field of the order property. The value is a scalar (for simple named blocks) or an array (for indexed named blocks).

For example, for a simple block named foo, idx.i1.foo is the starting index of the foo block in the full set. For a bar blocked indexed by i and j, idx.iN.bar(i,j) is the ending index of the bar{i,j} block in the full set. Similarly, idx.N.bar(i,j) is the number of elements in that block, i.e. idx.iN.bar(i,j) - idx.i1.bar(i,j) + 1.

N = 0: (integer) total number of individual elements in set

NS = 0: (integer) total number of subsets in set

order = struct('name',[],'idx',[])

(struct) struct array of names/indices for blocks in the order they appear in the full set, with fields:

name - name of the block, e.g. bar

idx - cell array of indices for the name, e.g. {2,3} ==> bar{2,3}

data = struct(): (struct) additional set-type-specific data for each block

Method Summary

copy(cls)

Duplicate the object.

new_sm = sm.copy()
new_sm = sm.copy(new_class)

Input:: new_class (char array) – (default = same class) name of class to use for new object
Output:: new_sm (mp.set_manager) – duplicate of original object

Make a shallow copy of the object by copying each of the top-level properties.

to_struct()

Convert object data to a struct.

s = sm.to_struct()

Converts the object data to a struct that can later be converted back to an identical object using mp.struct2object(). Useful for saving the object data to a MAT-file in Octave.

from_struct(s)

Copy object data from a struct.

sm.from_struct(s)

Called by function mp.struct2object(), after creating the object to copy the object data from a struct. Useful for recreating the object after loading struct data from a MAT-file in Octave.

add(name, idx, varargin)

Add a named (and optionally indexed) subset of entities.

sm.add(name, N, ...)
sm.add(name, idx_list, N, ...)

This base class method handles the indexing part. Subclasses are expected to override it to handle any data that goes with each subset added for the given set type.

For example:

% Variable Set
sm_var.add(name, idx_list, N, v0, vl, vu, vt);

% Linear Constraint Set
sm_lin.add(name, idx_list, N, A, l, u, varsets);

% Nonlinear Equality Constraint Set
sm_nle.add(name, idx_list, N, fcn, hess, computed_by, varsets);

% Nonlinear Inequality Constraint Set
sm_nli.add(name, idx_list, N, fcn, hess, computed_by, varsets);

% Quadratic Cost Set
sm_qdc.add(name, idx_list, N, cp, varsets);

% General Nonlinear Cost Set
sm_nlc.add(name, idx_list, N, fcn, varsets);

describe_idx(idxs)

Provide/display name and index label for given indices.

label = sm.describe_idx(idxs)

Returns char arrays describing (name and optionally index) the element of the full set that corresponds to the indices in idxs. The return value is a char array if idxs is a scalar, otherwise it is a cell array of char arrays of the same dimension as idxs.

For example, this method can tell you that element 361 corresponds to element 5 of the foo block ('foo(5)') or to element 17 of the bar{8,5} block ('bar{8,5}(17)')

Input:: idxs (integer) – scalar or array of indices into full set
Output:: label (char array or cell array) – label or cell array of same dimensions as idxs of labels containing the corresponding name (possibly indexed) and index within that name.

Examples:

label = sm.describe_idx(87));
labels = sm.describe_idx([38; 49; 93]));

See also set_type_idx_map().

display(tag)

Display summary of indexing of subsets in 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 indexing for each subset or block, as well as the total number of elements and subsets.

get_N(name, idx)

Return the number of elements in the set.

N = sm.get_N()
N = sm.get_N(name)
N = sm.get_N(name, idx_list)

Returns either the total number of elements in the set or the number corresponding to a specified named block, or indexed named subset.

Examples:

N = sm.get_N()             % total number of elements in set
N = sm.get_N(name)         % # of elements in named set
N = sm.get_N(name, idx)    % # of elements in indexed named set

init_indexed_name(name, dim_list)

Initialize dimensions for an indexed named set.

sm.init_indexed_name(name, dim_list)

A subset or block can be identified by a single name, such as foo, or by a name that is indexed by one or more indices, such as 'bar{3,4}'. For an indexed named set, before adding the indexed subsets themselves, the dimensions of the indexed set of names must be initialized by calling this method.

Inputs:

name (char array) – name of the block or subset
dim_list (cell array) – dimensions of the indexing of the name

Example:

% elements with indexed named set 'R{i,j}'
sm.init_indexed_name('R', {2, 3});
for i = 1:2
    for j = 1:3
        sm.add('R', {i, j}, ...);
    end
end

set_type_idx_map(idxs, group_by_name)

Map index back to named subset & index within set.

s = sm.set_type_idx_map()
s = sm.set_type_idx_map(idxs)
s = sm.set_type_idx_map(idxs, group_by_name)

Returns a struct of same dimensions as idxs specifying, for each index, the corresponding named set and element within the named set.

Inputs:

idxs (integer) – (optional) scalar or array of indices into full set (default, if empty or not provided, is [1:ns]' where ns is the full dimension of the set corresponding to the all elements)
group_by_name (logical) – (default = false) if true, then the results are consolidated, with a single entry in s for each unique name/idx pair, where the i and j fields are vectors. In this case s is 1 dimensional.

Output:

s (struct) – return struct with 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
j : (only if group_by_name == 1 ), corresponding index of full set, equal to a particular element of idxs

Examples:

s = var.set_type_idx_map(87));
s = lin.set_type_idx_map([38; 49; 93]));
s = var.set_type_idx_map());
s = lin.set_type_idx_map([], 1));