Home > matpower7.1 > lib > @opf_model > add_legacy_cost.m

add_legacy_cost

PURPOSE ^

ADD_LEGACY_COST Adds a set of user costs to the model.

SYNOPSIS ^

function om = add_legacy_cost(om, name, idx, varargin)

DESCRIPTION ^

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.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function om = add_legacy_cost(om, name, idx, varargin)
0002 %ADD_LEGACY_COST  Adds a set of user costs to the model.
0003 %
0004 %   OM.ADD_LEGACY_COST(NAME, CP);
0005 %   OM.ADD_LEGACY_COST(NAME, CP, VARSETS);
0006 %   OM.ADD_LEGACY_COST(NAME, IDX_LIST, CP);
0007 %   OM.ADD_LEGACY_COST(NAME, IDX_LIST, CP, VARSETS);
0008 %
0009 %   Adds a named block of user-defined costs to the model. Each set is
0010 %   defined by the CP struct described below. All user-defined sets of
0011 %   costs are combined together into a single set of cost parameters in
0012 %   a single CP struct by BULD_COST_PARAMS. This full aggregate set of
0013 %   cost parameters can be retreived from the model by GET_COST_PARAMS.
0014 %
0015 %   Examples:
0016 %       cp1 = struct('N', N1, 'Cw', Cw1);
0017 %       cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ...
0018 %                     'rh', rh, 'kk', kk, 'mm', mm);
0019 %       om.add_legacy_cost('usr1', cp1, {'Pg', 'Qg', 'z'});
0020 %       om.add_legacy_cost('usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});
0021 %
0022 %       om.init_indexed_name('c', {2, 3});
0023 %       for i = 1:2
0024 %         for j = 1:3
0025 %           om.add_legacy_cost('c', {i, j}, cp(i,j), ...);
0026 %         end
0027 %       end
0028 %
0029 %   Let x refer to the vector formed by combining the specified VARSETS,
0030 %   and f_u(x, CP) be the cost at x corresponding to the cost parameters
0031 %   contained in CP, where CP is a struct with the following fields:
0032 %       N      - nw x nx sparse matrix (optional, identity matrix by default)
0033 %       Cw     - nw x 1 vector
0034 %       H      - nw x nw sparse matrix (optional, all zeros by default)
0035 %       dd, mm - nw x 1 vectors (optional, all ones by default)
0036 %       rh, kk - nw x 1 vectors (optional, all zeros by default)
0037 %
0038 %   These parameters are used as follows to compute f_u(x, CP)
0039 %
0040 %       R  = N*x - rh
0041 %
0042 %               /  kk(i),  R(i) < -kk(i)
0043 %       K(i) = <   0,     -kk(i) <= R(i) <= kk(i)
0044 %               \ -kk(i),  R(i) > kk(i)
0045 %
0046 %       RR = R + K
0047 %
0048 %       U(i) =  /  0, -kk(i) <= R(i) <= kk(i)
0049 %               \  1, otherwise
0050 %
0051 %       DDL(i) = /  1, dd(i) = 1
0052 %                \  0, otherwise
0053 %
0054 %       DDQ(i) = /  1, dd(i) = 2
0055 %                \  0, otherwise
0056 %
0057 %       Dl = diag(mm) * diag(U) * diag(DDL)
0058 %       Dq = diag(mm) * diag(U) * diag(DDQ)
0059 %
0060 %       w = (Dl + Dq * diag(RR)) * RR
0061 %
0062 %       f_u(x, CP) = 1/2 * w'*H*w + Cw'*w
0063 %
0064 %   See also OPT_MODEL, PARAMS_LEGACY_COST, EVAL_LEGACY_COST.
0065 
0066 %   MATPOWER
0067 %   Copyright (c) 2008-2020, Power Systems Engineering Research Center (PSERC)
0068 %   by Ray Zimmerman, PSERC Cornell
0069 %
0070 %   This file is part of MATPOWER.
0071 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0072 %   See https://matpower.org for more info.
0073 
0074 if iscell(idx)
0075     cp = varargin{1};
0076     args = varargin(2:end);
0077 else                            %% simple named set
0078     cp = idx;
0079     args = varargin;
0080     idx = {};
0081 end
0082 
0083 if isempty(args)
0084     varsets = {};
0085 else
0086     varsets = args{1};
0087 end
0088 
0089 %% convert varsets from cell to struct array if necessary
0090 varsets = om.varsets_cell2struct(varsets);
0091 nv = om.varsets_len(varsets);   %% number of variables
0092 
0093 if isfield(cp, 'N')
0094     [nw, nx] = size(cp.N);
0095 else
0096     nw = length(cp.Cw);
0097     nx = nw;
0098     cp.N = speye(nw, nx);
0099 end
0100 
0101 %% check sizes
0102 if nx ~= nv
0103     if nw == 0
0104         cp.N = sparse(nw, nx);
0105     else
0106         error('@opt_model/add_legacy_cost: number of columns in N (%d x %d) does not match\nnumber of variables (%d)\n', nw, nx, nv);
0107     end
0108 end
0109 if size(cp.Cw, 1) ~= nw
0110     error('@opt_model/add_legacy_cost: number of rows of Cw (%d x %d) and N (%d x %d) must match\n', size(cp.Cw), nw, nx);
0111 end
0112 if isfield(cp, 'H') && (size(cp.H, 1) ~= nw || size(cp.H, 2) ~= nw)
0113     error('@opt_model/add_legacy_cost: both dimensions of H (%d x %d) must match the number of rows in N (%d x %d)\n', size(cp.H), nw, nx);
0114 end
0115 if isfield(cp, 'dd') && size(cp.dd, 1) ~= nw
0116     error('@opt_model/add_legacy_cost: number of rows of dd (%d x %d) and N (%d x %d) must match\n', size(cp.dd), nw, nx);
0117 end
0118 if isfield(cp, 'rh') && size(cp.rh, 1) ~= nw
0119     error('@opt_model/add_legacy_cost: number of rows of rh (%d x %d) and N (%d x %d) must match\n', size(cp.rh), nw, nx);
0120 end
0121 if isfield(cp, 'kk') && size(cp.kk, 1) ~= nw
0122     error('@opt_model/add_legacy_cost: number of rows of kk (%d x %d) and N (%d x %d) must match\n', size(cp.kk), nw, nx);
0123 end
0124 if isfield(cp, 'mm') && size(cp.mm, 1) ~= nw
0125     error('@opt_model/add_legacy_cost: number of rows of mm (%d x %d) and N (%d x %d) must match\n', size(cp.mm), nw, nx);
0126 end
0127 
0128 %% add the legacy cost set
0129 om.add_named_set('cost', name, idx, nw, cp, varsets);

Generated on Fri 09-Oct-2020 11:21:31 by m2html © 2005