add_costs

ADD_COSTS  Adds a set of user costs to the model.

   -----  DEPRECATED - Please use one of the following instead:  -----
   -----  ADD_QUAD_COST, ADD_NLN_COST, ADD_LEGACY_COST           -----
   -----  or INIT_INDEXED_NAME                                   -----

   OM.ADD_COSTS(NAME, CP);
   OM.ADD_COSTS(NAME, CP, VARSETS);
   OM.ADD_COSTS(NAME, DIM_LIST); (deprecated, use INIT_INDEXED_NAME instead)
   OM.ADD_COSTS(NAME, IDX_LIST, CP);
   OM.ADD_COSTS(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_costs('usr1', cp1, {'Pg', 'Qg', 'z'});
       om.add_costs('usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});

       om.init_indexed_name('c', {2, 3});
       for i = 1:2
         for j = 1:3
           om.add_costs('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, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST.

0001 function om = add_costs(om, name, idx, varargin)
0002 %ADD_COSTS  Adds a set of user costs to the model.
0003 %
0004 %   -----  DEPRECATED - Please use one of the following instead:  -----
0005 %   -----  ADD_QUAD_COST, ADD_NLN_COST, ADD_LEGACY_COST           -----
0006 %   -----  or INIT_INDEXED_NAME                                   -----
0007 %
0008 %   OM.ADD_COSTS(NAME, CP);
0009 %   OM.ADD_COSTS(NAME, CP, VARSETS);
0010 %   OM.ADD_COSTS(NAME, DIM_LIST); (deprecated, use INIT_INDEXED_NAME instead)
0011 %   OM.ADD_COSTS(NAME, IDX_LIST, CP);
0012 %   OM.ADD_COSTS(NAME, IDX_LIST, CP, VARSETS);
0013 %
0014 %   Adds a named block of user-defined costs to the model. Each set is
0015 %   defined by the CP struct described below. All user-defined sets of
0016 %   costs are combined together into a single set of cost parameters in
0017 %   a single CP struct by BULD_COST_PARAMS. This full aggregate set of
0018 %   cost parameters can be retreived from the model by GET_COST_PARAMS.
0019 %
0020 %   Examples:
0021 %       cp1 = struct('N', N1, 'Cw', Cw1);
0022 %       cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ...
0023 %                     'rh', rh, 'kk', kk, 'mm', mm);
0024 %       om.add_costs('usr1', cp1, {'Pg', 'Qg', 'z'});
0025 %       om.add_costs('usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});
0026 %
0027 %       om.init_indexed_name('c', {2, 3});
0028 %       for i = 1:2
0029 %         for j = 1:3
0030 %           om.add_costs('c', {i, j}, cp(i,j), ...);
0031 %         end
0032 %       end
0033 %
0034 %   Let x refer to the vector formed by combining the specified VARSETS,
0035 %   and f_u(x, CP) be the cost at x corresponding to the cost parameters
0036 %   contained in CP, where CP is a struct with the following fields:
0037 %       N      - nw x nx sparse matrix (optional, identity matrix by default)
0038 %       Cw     - nw x 1 vector
0039 %       H      - nw x nw sparse matrix (optional, all zeros by default)
0040 %       dd, mm - nw x 1 vectors (optional, all ones by default)
0041 %       rh, kk - nw x 1 vectors (optional, all zeros by default)
0042 %
0043 %   These parameters are used as follows to compute f_u(x, CP)
0044 %
0045 %       R  = N*x - rh
0046 %
0047 %               /  kk(i),  R(i) < -kk(i)
0048 %       K(i) = <   0,     -kk(i) <= R(i) <= kk(i)
0049 %               \ -kk(i),  R(i) > kk(i)
0050 %
0051 %       RR = R + K
0052 %
0053 %       U(i) =  /  0, -kk(i) <= R(i) <= kk(i)
0054 %               \  1, otherwise
0055 %
0056 %       DDL(i) = /  1, dd(i) = 1
0057 %                \  0, otherwise
0058 %
0059 %       DDQ(i) = /  1, dd(i) = 2
0060 %                \  0, otherwise
0061 %
0062 %       Dl = diag(mm) * diag(U) * diag(DDL)
0063 %       Dq = diag(mm) * diag(U) * diag(DDQ)
0064 %
0065 %       w = (Dl + Dq * diag(RR)) * RR
0066 %
0067 %       f_u(x, CP) = 1/2 * w'*H*w + Cw'*w
0068 %
0069 %   See also OPT_MODEL, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST.
0070 
0071 %   MATPOWER
0072 %   Copyright (c) 2008-2017, Power Systems Engineering Research Center (PSERC)
0073 %   by Ray Zimmerman, PSERC Cornell
0074 %
0075 %   This file is part of MATPOWER.
0076 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0077 %   See https://matpower.org for more info.
0078 
0079 if iscell(idx) && isempty(varargin) %% just setting dimensions for indexed set
0080     om.init_indexed_name('cost', name, idx);
0081 else
0082     om.add_legacy_cost(name, idx, varargin{:});
0083 end