Home > matpower4.0 > @opf_model > add_costs.m

add_costs

PURPOSE ^

ADD_COSTS Adds a set of user costs to the model.

SYNOPSIS ^

function om = add_costs(om, name, cp, varsets)

DESCRIPTION ^

ADD_COSTS  Adds a set of user costs to the model.
   OM = ADD_COSTS(OM, NAME, 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(om, 'usr1', cp1, {'Pg', 'Qg', 'z'});
     om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});

   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
       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 OPF_MODEL, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function om = add_costs(om, name, cp, varsets)
0002 %ADD_COSTS  Adds a set of user costs to the model.
0003 %   OM = ADD_COSTS(OM, NAME, CP, VARSETS);
0004 %
0005 %   Adds a named block of user-defined costs to the model. Each set is
0006 %   defined by the CP struct described below. All user-defined sets of
0007 %   costs are combined together into a single set of cost parameters in
0008 %   a single CP struct by BULD_COST_PARAMS. This full aggregate set of
0009 %   cost parameters can be retreived from the model by GET_COST_PARAMS.
0010 %
0011 %   Examples:
0012 %     cp1 = struct('N', N1, 'Cw', Cw1);
0013 %     cp2 = struct('N', N2, 'Cw', Cw2, 'H', H, 'dd', dd, ...
0014 %                   'rh', rh, 'kk', kk, 'mm', mm);
0015 %     om = add_costs(om, 'usr1', cp1, {'Pg', 'Qg', 'z'});
0016 %     om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});
0017 %
0018 %   Let x refer to the vector formed by combining the specified VARSETS,
0019 %   and f_u(x, CP) be the cost at x corresponding to the cost parameters
0020 %   contained in CP, where CP is a struct with the following fields:
0021 %       N      - nw x nx sparse matrix
0022 %       Cw     - nw x 1 vector
0023 %       H      - nw x nw sparse matrix (optional, all zeros by default)
0024 %       dd, mm - nw x 1 vectors (optional, all ones by default)
0025 %       rh, kk - nw x 1 vectors (optional, all zeros by default)
0026 %
0027 %   These parameters are used as follows to compute f_u(x, CP)
0028 %
0029 %       R  = N*x - rh
0030 %
0031 %               /  kk(i),  R(i) < -kk(i)
0032 %       K(i) = <   0,     -kk(i) <= R(i) <= kk(i)
0033 %               \ -kk(i),  R(i) > kk(i)
0034 %
0035 %       RR = R + K
0036 %
0037 %       U(i) =  /  0, -kk(i) <= R(i) <= kk(i)
0038 %               \  1, otherwise
0039 %
0040 %       DDL(i) = /  1, dd(i) = 1
0041 %                \  0, otherwise
0042 %
0043 %       DDQ(i) = /  1, dd(i) = 2
0044 %                \  0, otherwise
0045 %
0046 %       Dl = diag(mm) * diag(U) * diag(DDL)
0047 %       Dq = diag(mm) * diag(U) * diag(DDQ)
0048 %
0049 %       w = (Dl + Dq * diag(RR)) * RR
0050 %
0051 %       f_u(x, CP) = 1/2 * w'*H*w + Cw'*w
0052 %
0053 %   See also OPF_MODEL, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST.
0054 
0055 %   MATPOWER
0056 %   $Id: add_costs.m,v 1.7 2010/04/26 19:45:25 ray Exp $
0057 %   by Ray Zimmerman, PSERC Cornell
0058 %   Copyright (c) 2008-2010 by Power System Engineering Research Center (PSERC)
0059 %
0060 %   This file is part of MATPOWER.
0061 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0062 %
0063 %   MATPOWER is free software: you can redistribute it and/or modify
0064 %   it under the terms of the GNU General Public License as published
0065 %   by the Free Software Foundation, either version 3 of the License,
0066 %   or (at your option) any later version.
0067 %
0068 %   MATPOWER is distributed in the hope that it will be useful,
0069 %   but WITHOUT ANY WARRANTY; without even the implied warranty of
0070 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
0071 %   GNU General Public License for more details.
0072 %
0073 %   You should have received a copy of the GNU General Public License
0074 %   along with MATPOWER. If not, see <http://www.gnu.org/licenses/>.
0075 %
0076 %   Additional permission under GNU GPL version 3 section 7
0077 %
0078 %   If you modify MATPOWER, or any covered work, to interface with
0079 %   other modules (such as MATLAB code and MEX-files) available in a
0080 %   MATLAB(R) or comparable environment containing parts covered
0081 %   under other licensing terms, the licensors of MATPOWER grant
0082 %   you additional permission to convey the resulting work.
0083 
0084 %% prevent duplicate named cost sets
0085 if isfield(om.cost.idx.N, name)
0086     error('@opf_model/add_costs: cost set named ''%s'' already exists', name);
0087 end
0088 
0089 if nargin < 4
0090     varsets = {};
0091 end
0092 if isempty(varsets)
0093     varsets = om.var.order;
0094 end
0095 [nw, nx] = size(cp.N);
0096 
0097 %% check sizes
0098 nv = 0;
0099 for k = 1:length(varsets)
0100     nv = nv + om.var.idx.N.(varsets{k});
0101 end
0102 if nx ~= nv
0103     if nw == 0
0104         cp.N = sparse(nw, nx);
0105     else
0106         error('@opf_model/add_costs: 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('@opf_model/add_costs: 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('@opf_model/add_costs: 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('@opf_model/add_costs: 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('@opf_model/add_costs: 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('@opf_model/add_costs: 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('@opf_model/add_costs: 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 info about this user cost set
0129 om.cost.idx.i1.(name)  = om.cost.N + 1;     %% starting index
0130 om.cost.idx.iN.(name)  = om.cost.N + nw;    %% ending index
0131 om.cost.idx.N.(name)   = nw;                %% number of costs (nw)
0132 om.cost.data.N.(name)  = cp.N;
0133 om.cost.data.Cw.(name) = cp.Cw;
0134 om.cost.data.vs.(name) = varsets;
0135 if isfield(cp, 'H')
0136     om.cost.data.H.(name)  = cp.H;
0137 end
0138 if isfield(cp, 'dd')
0139     om.cost.data.dd.(name) = cp.dd;
0140 end
0141 if isfield(cp, 'rh')
0142     om.cost.data.rh.(name) = cp.rh;
0143 end
0144 if isfield(cp, 'kk')
0145     om.cost.data.kk.(name) = cp.kk;
0146 end
0147 if isfield(cp, 'mm')
0148     om.cost.data.mm.(name) = cp.mm;
0149 end
0150 
0151 %% update number of vars and var sets
0152 om.cost.N  = om.cost.idx.iN.(name);
0153 om.cost.NS = om.cost.NS + 1;
0154 
0155 %% put name in ordered list of var sets
0156 om.cost.order{om.cost.NS} = name;

Generated on Mon 26-Jan-2015 14:56:45 by m2html © 2005