opf_model

class opf_model

Bases: opt_model

opf_model - Legacy MATPOWER OPF model class.

OM = OPF_MODEL(MPC)

This class implements the OPF model object used to encapsulate
a given OPF problem formulation. It allows for access to optimization
variables, constraints and costs in named blocks, keeping track of the
ordering and indexing of the blocks as variables, constraints and costs
are added to the problem.

This class is a subclass of OPT_MODEL that adds the 'mpc'
field for storing the MATPOWER case struct used to build the object
along with the get_mpc() method.

It also adds the 'cost' field and the following three methods for
implementing the legacy user-defined OPF costs:
    add_legacy_cost
    params_legacy_cost
    eval_legacy_cost

The following is the structure of the data in the OPF model object.

om
    <opt_model fields> - see OPT_MODEL for details
    .cost       - data for legacy user-defined costs
        .idx
            .i1 - starting row index within full N matrix
            .iN - ending row index within full N matrix
            .N  - number of rows in this cost block in full N matrix
        .N      - total number of rows in full N matrix
        .NS     - number of cost blocks
        .data   - data for each user-defined cost block
            .N  - see help for ADD_LEGACY_COST for details
            .H  -               "
            .Cw -               "
            .dd -               "
            .rr -               "
            .kk -               "
            .mm -               "
            .vs - cell array of variable sets that define xx for this
                  cost block, where the N for this block multiplies xx
        .order  - struct array of names/indices for cost blocks in the
                  order they appear in the rows of the full N matrix
            .name   - name of the block, e.g. R
            .idx    - indices for name, {2,3} => R(2,3)
    .mpc        - MATPOWER case struct used to create this model object
        .baseMVA
        .bus
        .branch
        .gen
        .gencost
        .A  (if present, must have l, u)
        .l
        .u
        .N  (if present, must have fparm, H, Cw)
        .fparm
        .H
        .Cw

See also opt_model.

Constructor Summary

opf_model(mpc)

Constructor.

om = opf_model()
om = opf_model(mpc)

Property Summary

cost = []

data for legacy user-defined costs

mpc = struct()

MATPOWER case struct from which om was built

Method Summary

def_set_types(om)

Define set types var, lin, nle, nli, qdc, nlc, cost.

init_set_types(om)

Initialize data structures for each set type.

set_mpc(om, mpc)

set_mpc() - Sets the MATPOWER case struct.

OM.SET_MPC(MPC)

See also opt_model.

display(om)

display() - Displays the object.

Called when semicolon is omitted at the command-line. Displays the details
of the variables, constraints, costs included in the model.

See also opt_model.

get_mpc(om)

get_mpc() - Returns the MATPOWER case struct.

MPC = OM.GET_MPC()

See also opt_model.

eval_legacy_cost(om, x, name, idx)

eval_legacy_cost() - Evaluates individual or full set of legacy user costs.

F = OM.EVAL_LEGACY_COST(X ...)
[F, DF] = OM.EVAL_LEGACY_COST(X ...)
[F, DF, D2F] = OM.EVAL_LEGACY_COST(X ...)
[F, DF, D2F] = OM.EVAL_LEGACY_COST(X, NAME)
[F, DF, D2F] = OM.EVAL_LEGACY_COST(X, NAME, IDX_LIST)
Evaluates an individual named set or the full set of legacy user
costs and their derivatives for a given value of the optimization vector
X, based on costs added by ADD_LEGACY_COST.

Example:
    [f, df, d2f] = om.eval_legacy_cost(x)
    [f, df, d2f] = om.eval_legacy_cost(x, name)
    [f, df, d2f] = om.eval_legacy_cost(x, name, idx)

See also opt_model, add_legacy_cost(), params_legacy_cost().

params_legacy_cost(om, name, idx)

params_legacy_cost() - Returns cost parameters for legacy user-defined costs.

CP = OM.PARAMS_LEGACY_COST()
CP = OM.PARAMS_LEGACY_COST(NAME)
CP = OM.PARAMS_LEGACY_COST(NAME, IDX_LIST)
[CP, VS] = OM.PARAMS_LEGACY_COST(...)
[CP, VS, I1, IN] = OM.PARAMS_LEGACY_COST(...)

With no input parameters, it assembles and returns the parameters
for the aggregate legacy user-defined cost from all legacy cost sets
added using ADD_LEGACY_COST. The values of these parameters are cached
for subsequent calls. The parameters are contained in the struct CP,
described below.

If a NAME is provided then it simply returns parameter struct CP for the
corresponding named set. Likewise for indexed named sets specified
by NAME and IDX_LIST.

An optional 2nd output argument VS indicates the variable sets used by
this cost set. The size of CP.N will be consistent with VS.

If NAME is provided, optional 3rd and 4th output arguments I1 and IN
indicate the starting and ending row indices of the corresponding
cost set in the full aggregate cost matrix CP.N.

Let X refer to the vector formed by combining the corresponding varsets VS,
and F_U(X, CP) be the cost at X corresponding to the cost parameters
contained in CP, where CP is a struct with the following fields:
    N      - nw x nx sparse matrix (optional, identity matrix by default)
    Cw     - nw x 1 vector
    H      - nw x nw sparse matrix (optional, all zeros by default)
    dd, mm - nw x 1 vectors (optional, all ones by default)
    rh, kk - nw x 1 vectors (optional, all zeros by default)

These parameters are used as follows to compute F_U(X, CP)

    R  = N*X - rh

            /  kk(i),  R(i) < -kk(i)
    K(i) = <   0,     -kk(i) <= R(i) <= kk(i)
            \ -kk(i),  R(i) > kk(i)

    RR = R + K

    U(i) =  /  0, -kk(i) <= R(i) <= kk(i)
            \  1, otherwise

    DDL(i) = /  1, dd(i) = 1
             \  0, otherwise

    DDQ(i) = /  1, dd(i) = 2
             \  0, otherwise

    Dl = diag(mm) * diag(U) * diag(DDL)
    Dq = diag(mm) * diag(U) * diag(DDQ)

    w = (Dl + Dq * diag(RR)) * RR

    F_U(X, CP) = 1/2 * w'*H*w + Cw'*w

See also opt_model, add_legacy_cost(), eval_legacy_cost().

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

add_named_set() - Adds a named set of variables/constraints/costs to the model.

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

This method is intended to be a private method, used internally by
the public methods ADD_VAR, ADD_LIN_CONSTRAINT, ADD_NLN_CONSTRAINT
ADD_QUAD_COST, ADD_NLN_COST and ADD_LEGACY_COST.

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

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

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

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

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

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

Legacy Cost Set
    OM.ADD_NAMED_SET('cost', NAME, IDX_LIST, N, CP, VARSETS);

See also opt_model, add_var, add_lin_constraint, add_nln_constraint add_quad_cost, add_nln_cost, add_legacy_cost().

add_legacy_cost(om, name, idx, varargin)

add_legacy_cost() - Adds a set of user costs to the model.

OM.ADD_LEGACY_COST(NAME, CP);
OM.ADD_LEGACY_COST(NAME, CP, VARSETS);
OM.ADD_LEGACY_COST(NAME, IDX_LIST, CP);
OM.ADD_LEGACY_COST(NAME, IDX_LIST, CP, VARSETS);

Adds a named block of user-defined costs to the model. Each set is
defined by the CP struct described below. All user-defined sets of
costs are combined together into a single set of cost parameters in
a single CP struct by BULD_COST_PARAMS. This full aggregate set of
cost parameters can be retreived from the model by GET_COST_PARAMS.

Examples:
    cp1 = struct('N', N1, 'Cw', Cw1);
    cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ...
                  'rh', rh, 'kk', kk, 'mm', mm);
    om.add_legacy_cost('usr1', cp1, {'Pg', 'Qg', 'z'});
    om.add_legacy_cost('usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});

    om.init_indexed_name('c', {2, 3});
    for i = 1:2
      for j = 1:3
        om.add_legacy_cost('c', {i, j}, cp(i,j), ...);
      end
    end

Let x refer to the vector formed by combining the specified VARSETS,
and f_u(x, CP) be the cost at x corresponding to the cost parameters
contained in CP, where CP is a struct with the following fields:
    N      - nw x nx sparse matrix (optional, identity matrix by default)
    Cw     - nw x 1 vector
    H      - nw x nw sparse matrix (optional, all zeros by default)
    dd, mm - nw x 1 vectors (optional, all ones by default)
    rh, kk - nw x 1 vectors (optional, all zeros by default)

These parameters are used as follows to compute f_u(x, CP)

    R  = N*x - rh

            /  kk(i),  R(i) < -kk(i)
    K(i) = <   0,     -kk(i) <= R(i) <= kk(i)
            \ -kk(i),  R(i) > kk(i)

    RR = R + K

    U(i) =  /  0, -kk(i) <= R(i) <= kk(i)
            \  1, otherwise

    DDL(i) = /  1, dd(i) = 1
             \  0, otherwise

    DDQ(i) = /  1, dd(i) = 2
             \  0, otherwise

    Dl = diag(mm) * diag(U) * diag(DDL)
    Dq = diag(mm) * diag(U) * diag(DDQ)

    w = (Dl + Dq * diag(RR)) * RR

    f_u(x, CP) = 1/2 * w'*H*w + Cw'*w

See also opt_model, params_legacy_cost(), eval_legacy_cost().

init_indexed_name(om, set_type, name, dim_list)

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

OM.INIT_INDEXED_NAME(SET_TYPE, NAME, DIM_LIST)

Initializes the dimensions for an indexed named variable, constraint
or cost set.

Variables, constraints and costs are referenced in OPT_MODEL in terms
of named sets. The specific 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
    SET_TYPE = 'nle'   => nonlinear equality constraint set
    SET_TYPE = 'nli'   => nonlinear inequality constraint set
    SET_TYPE = 'qdc'   => quadratic cost set
    SET_TYPE = 'nlc'   => nonlinear cost set
    SET_TYPE = 'cost'  => legacy cost set

Indexed Named Sets

A variable, constraint or cost 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, constraint or cost 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)'
    om.init_indexed_name('lin', 'R', {2, 3});
    for i = 1:2
      for j = 1:3
        om.add_lin_constraint('R', {i, j}, A{i,j}, ...);
      end
    end

See also opt_model, add_var, add_lin_constraint, add_nln_constraint, add_quad_cost, add_nln_cost, add_legacy_cost().