mp_idx_manager

class mp_idx_manager

Bases: handle

mp_idx_manager - MATPOWER Index Manager abstract class

A MATPOWER Index Manager object can be used to manage the indexing of
various named and indexed blocks of various set types, 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.

The types of named sets to be managed by the class are defined by the
DEF_SET_TYPES method, which assigns a struct to the 'set_types' field.

Properties
    set_types   - a struct defined by DEF_SET_TYPES method
    userdata    - a struct containing arbitrary data added by the user

Private Methods
    add_named_set - Adds named subset of a particular type to the
        object.

    def_set_types - (must be implemented in the subclass) Returns a
        struct defining the various set types, where the key is the
        set type name, which must also be declared as a property in
        the object's class, and the value is a string name used for
        display purposes.

        E.g.
            function obj = def_set_types(obj)
                obj.set_types = struct(...
                        'var', 'variable', ...
                        'lin', 'linear constraint' ...
                    );
            end

    init_set_types - Initializes the structures needed to track the
        ordering and indexing of each set type and can be overridden
        to initialize any additional data to be stored with each block
        of each set type. Ideally, this would be called at the end
        of the MP_IDX_MANAGER constructor, but this is not possible
        in Octave 5.2 and earlier due to a bug related to altering
        fields of an object not yet fully constructed.
        Fixed in Octave v6.x: https://savannah.gnu.org/bugs/?52614
        The workaround is to be sure that this method is called by
        some subclass method(s) after object construction, but before
        any other use (e.g. in display() and add_*() methods).

    valid_named_set_type - Returns a label for the given named set
        type if valid, empty otherwise.

Public Methods
    add_<SET-TYPE> - (must be implemented in the subclass) Used to
        add a block of the given set type to the object, using the
        private ADD_NAMED_SET method internally followed by the
        handling of any data specific to that set type.

    copy - Makes a shallow copy of the object.

    describe_idx - Identifies indices of a given set type.
        E.g. variable 361 corresponds to Pg(68)

    display - (must be implemented in the subclass) Displays the
        object (called automatically when you omit the semicolon at
        the command-line).

    display_set - Prints to screen the indexing details for the
        specified set type. Intended to be called by DISPLAY method.

    get_idx - Returns index structure(s) for specified set type(s),
        with starting/ending indices and number of elements for
        each named (and optionally indexed) block.

    get_userdata - Retreives values of user data stored in the object.

    get - Return the value of any individual field.

    getN - Returns the number of elements of any given set type,
        optionally for a single named block.

    init_indexed_name - Initializes the dimensions for an indexed
        named set.

    params_<SET-TYPE> - (must be implemented in the subclass)
        Returns set-type-specific data for a given type.

The following is the structure of the data in the object, using a set
type named 'var' for illustration. Each field of .idx or .data is a
struct whose field names are the names of the corresponding blocks of
elements of that type (e.g. variables, constraints, etc.). They are
found in order in the corresponding .order field. The description next
to these fields gives the meaning of the value for each named sub-field.
E.g. obj.var.data.v0.Pg contains a vector of initial values for the 'Pg'
block of variables.

obj
    .var        - data for 'var' set type, e.g. variable sets that
                  make up the full optimization variable x
        .idx
            .i1 - starting index within x
            .iN - ending index within x
            .N  - number of elements in this variable set
        .N      - total number of elements in x
        .NS     - number of variable sets or named blocks
        .data   - additional set-type-specific data for each block
        .order  - struct array of names/indices for variable
                  blocks in the order they appear in x
            .name   - name of the block, e.g. Pg
            .idx    - indices for name, {2,3} => Pg(2,3)
    .userdata   - any user defined data
        .(user defined fields)

Constructor Summary

mp_idx_manager(s)

Constructor.

obj = mp_idx_manager()
obj = mp_idx_manager(a_struct)
obj = mp_idx_manager(an_obj)

Method Summary

init_set_types()

Initialize indexing structures for each set type.

copy()

Duplicate the object.

display_set(stype, sname)

Display indexing information for a given set type.

set_type_idx_map(set_type, idxs, group_by_name)

set_type_idx_map() - Maps index for set type back to named set & index within set

S = OBJ.SET_TYPE_IDX_MAP(SET_TYPE, IDXS)
S = OBJ.SET_TYPE_IDX_MAP(SET_TYPE)
S = OBJ.SET_TYPE_IDX_MAP(SET_TYPE, 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 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
    j : (only if GROUP_BY_NAME == 1), corresponding index of set type,
        equal to a particular element of IDXS
If IDXS is empty or not provided it defaults to [1:NS]', where NS is the
full dimension of the set corresponding to the all elements for the
specified set type.

If GROUP_BY_NAME is 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.

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

See also describe_idx(), opt_model.

get(varargin)

get() - Returns the value of a field.

VAL = OBJ.GET(FIELD1, FIELD2, ...)

Example:
    var_order = obj.get('var', 'order');

See also opt_model.

get_userdata(name)

get_userdata() - Used to retrieve values of user data.

VAL = OBJ.GET_USERDATA(NAME) returns the value specified by the given name
or an empty matrix if userdata with NAME does not exist.

This function allows the user to retrieve any arbitrary data that was
saved in the object for later use. Data for a given NAME is saved by
assigning it to OBJ.userdata.(NAME).

This can be useful, for example, when using a user function to add
variables or constraints, etc. Suppose some special indexing is
constructed when adding some variables or constraints. This indexing data
can be stored and used later to "unpack" the results of the solved case.

See also opt_model.

valid_named_set_type(set_type)

valid_named_set_type() - Returns a label for the given named set type or empty.

-----  PRIVATE METHOD  -----

STR = OBJ.VALID_NAMED_SET_TYPE(SET_TYPE)

Returns a string corresponding to the type of the named set for
valid values of SET_TYPE, otherwise an empty string. Can be used to
check whether SET_TYPE is a valid type.

Valid set types, and the corresponding values are defined as a struct
returned by the DEF_SET_TYPES method.

E.g. The following method ...
    function obj = def_set_types(obj)
        obj.set_types = struct(...
                'var', 'variable', ...
                'lin', 'linear constraint' ...
            );
    end

... indicates the following valid SET_TYPES and corresponding
return values:

    SET_TYPE    STR
    'var'       'variable'
    'lin'       'linear constraint'

add_named_set(set_type, name, idx, N, varargin)

add_named_set() - Adds a named set of a particular type to the object.

-----  PRIVATE METHOD  -----

This method is intended to be a private method, used internally by
the public methods for each set type, e.g. ADD_VAR, ADD_LIN_CONSTRAINT,
etc. This method handles the indexing part. The set-type-specific methods
that call it need to handle any data that goes with each set added.

E.g.

Variable Set
    OBJ.ADD_NAMED_SET('var', NAME, IDX_LIST, N, V0, VL, VU, VT);

Linear Constraint Set
    OBJ.ADD_NAMED_SET('lin', NAME, IDX_LIST, N, A, L, U, VARSETS);

Nonlinear Inequality Constraint Set
    OBJ.ADD_NAMED_SET('nle', NAME, IDX_LIST, N, FCN, HESS, COMPUTED_BY, VARSETS);

Nonlinear Inequality Constraint Set
    OBJ.ADD_NAMED_SET('nli', NAME, IDX_LIST, N, FCN, HESS, COMPUTED_BY, VARSETS);

Quadratic Cost Set
    OBJ.ADD_NAMED_SET('qdc', NAME, IDX_LIST, N, CP, VARSETS);

General Nonlinear Cost Set
    OBJ.ADD_NAMED_SET('nlc', NAME, IDX_LIST, N, FCN, VARSETS);

See OPT_MODEL and its methods ADD_VAR, ADD_LIN_CONSTRAINT,
    ADD_NLN_CONSTRAINT, ADD_QUAD_COST and ADD_NLN_COST.

See also opt_model.

describe_idx(set_type, idxs)

describe_idx() - Identifies element indices for a give set type.

LABEL = OBJ.DESCRIBE_IDX(SET_TYPE, IDXS)

Returns strings describing (name and index) the element of the
specified set type (e.g. variable or constraint) that corresponds to
the indices in IDXS. The return value is a string if IDXS is a scalar,
otherwise it is a cell array of strings of the same dimension as IDXS.

Examples:
    label = obj.describe_idx('var', 87));
    labels = obj.describe_idx('lin', [38; 49; 93]));

See also set_type_idx_map(), opt_model.

getN(set_type, name, idx)

getN() - Returns the number of elements of a given set type.

N = OBJ.GETN(SET_TYPE)
N = OBJ.GETN(SET_TYPE, NAME)
N = OBJ.GETN(SET_TYPE, NAME, IDX_LIST)

Returns either the total number of elements of a given set type
(e.g. variable, constraint, etc.) or the number corresponding to a
specified named block, or indexed named set.

Examples:
    N = obj.getN('var')      : total number of variables
    N = obj.getN('lin')      : total number of linear constraints
    N = obj.getN('var', name)    : # of variables in named set
    N = obj.getN('lin', name)    : # of linear constraints in named set
    N = obj.getN('var', name, idx) : # of variables in indexed named set

See also opt_model.

init_indexed_name(set_type, name, dim_list)

init_indexed_name() - Initializes the dimensions for an indexed named set.

OBJ.INIT_INDEXED_NAME(SET_TYPE, NAME, DIM_LIST)

Initializes the dimensions for an indexed named set.

For example, variables and linear constraints could be referenced in
terms of named sets, where the type of named set being referenced is
given by SET_TYPE, with the following valid options:
    SET_TYPE = 'var'   => variable set
    SET_TYPE = 'lin'   => linear constraint set

Indexed Named Sets

In this case a variable or constraint set can be identified by a single
NAME, such as 'Pmismatch', or by a name that is indexed by one or more
indices, such as 'Pmismatch(3,4)'. For an indexed named set, before adding
the indexed variable or constraint sets themselves, the dimensions of
the indexed set must be set by calling INIT_INDEXED_NAME, where DIM_LIST
is a cell array of the dimensions.

Examples:
    %% linear constraints with indexed named set 'R(i,j)'
    obj.init_indexed_name('lin', 'R', {2, 3});
    for i = 1:2
      for j = 1:3
        obj.add_lin_constraint('R', {i, j}, A{i,j}, ...);
      end
    end

See OPT_MODEL, and its methods INIT_INDEXED_NAME, ADD_VAR,
        ADD_LIN_CONSTRAINT, ADD_NLN_CONSTRAINT, ADD_QUAD_COST and
        ADD_NLN_COST.

get_idx(varargin)

get_idx() - Returns the idx struct for the various set types.

IDX = OBJ.GET_IDX(SET_TYPE)
[IDX1, IDX2, ...] = OBJ.GET_IDX(SET_TYPE1, SET_TYPE2, ...)

Returns a structure for each set type with the beginning and ending
index value and the number of elements for each named block. The 'i1'
field (that's a one) is a struct with all of the starting indices, 'iN'
contains all the ending indices and 'N' contains all the sizes. Each is
a struct whose fields are the named blocks.

For example, if 'var' is the set type used for a vector x of optimization
variables, and 'lin' is for a set of linear constraints, then the
following examples illustrate how GET_IDX might be used.

Examples:
    [vv, ll] = obj.get_idx('var', 'lin');

    For a variable block named 'z' we have ...
        vv.i1.z - starting index for 'z' in optimization vector x
        vv.iN.z - ending index for 'z' in optimization vector x
        vv.N.z  - number of elements in 'z'

    To extract a 'z' variable from x:
        z = x(vv.i1.z:vv.iN.z);

    To extract the multipliers on a linear constraint set
    named 'foo', where mu_l and mu_u are the full set of
    linear constraint multipliers:
        mu_l_foo = mu_l(ll.i1.foo:ll.iN.foo);
        mu_u_foo = mu_u(ll.i1.foo:ll.iN.foo);

    The number of linear constraints in a set named 'bar':
        nbar = ll.N.bar;
      (note: the following is preferable ...
        nbar = obj.getN('lin', 'bar');
      ... if you haven't already called get_idx to get ll.)

    If 'z', 'foo' and 'bar' are indexed sets, then you can
    replace them with something like 'z(i,j)', 'foo(i,j,k)'
    or 'bar(i)' in the examples above.

The GET_IDX method can be overridden to also return the idx structs of
set types in a pre-specified order when called without input arguments.

E.g.
    vv = obj.get_idx()          % for variables
    [vv, ll] = obj.get_idx()    % for linear constraints

See OPT_MODEL, and its methods GET_IDX, ADD_VAR,
        ADD_LIN_CONSTRAINT, ADD_NLN_CONSTRAINT, ADD_QUAD_COST and
        ADD_NLN_COST.