ADD_COSTS Adds a set of user costs to the model.
OM = ADD_COSTS(OM, NAME, CP);
OM = ADD_COSTS(OM, NAME, CP, VARSETS);
OM = ADD_COSTS(OM, NAME, DIM_LIST);
OM = ADD_COSTS(OM, NAME, IDX_LIST, CP);
OM = ADD_COSTS(OM, 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(om, 'usr1', cp1, {'Pg', 'Qg', 'z'});
om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'});
om = add_costs(om, 'c', {2, 3});
for i = 1:2
for j = 1:3
om = add_costs(om, '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 % OM = ADD_COSTS(OM, NAME, CP); 0004 % OM = ADD_COSTS(OM, NAME, CP, VARSETS); 0005 % OM = ADD_COSTS(OM, NAME, DIM_LIST); 0006 % OM = ADD_COSTS(OM, NAME, IDX_LIST, CP); 0007 % OM = ADD_COSTS(OM, 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_costs(om, 'usr1', cp1, {'Pg', 'Qg', 'z'}); 0020 % om = add_costs(om, 'usr2', cp2, {'Vm', 'Pg', 'Qg', 'z'}); 0021 % 0022 % om = add_costs(om, 'c', {2, 3}); 0023 % for i = 1:2 0024 % for j = 1:3 0025 % om = add_costs(om, '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, BUILD_COST_PARAMS, GET_COST_PARAMS, COMPUTE_COST. 0065 0066 % MATPOWER 0067 % Copyright (c) 2008-2015 by Power System Engineering Research Center (PSERC) 0068 % by Ray Zimmerman, PSERC Cornell 0069 % 0070 % $Id: add_costs.m 2644 2015-03-11 19:34:22Z ray $ 0071 % 0072 % This file is part of MATPOWER. 0073 % Covered by the 3-clause BSD License (see LICENSE file for details). 0074 % See http://www.pserc.cornell.edu/matpower/ for more info. 0075 0076 if iscell(idx) 0077 if ~isempty(varargin) %% indexed named set 0078 % (calls to substruct() are relatively expensive ... 0079 % s1 = substruct('.', name, '()', idx); 0080 % s2 = substruct('.', name, '{}', idx); 0081 % ... so replace them with these more efficient lines) 0082 s1 = struct('type', {'.', '()'}, 'subs', {name, idx}); 0083 s2 = s1; 0084 s2(2).type = '{}'; 0085 0086 %% prevent duplicate named cost sets 0087 if subsref(om.cost.idx.i1, s1) ~= 0 0088 str = '%d'; for m = 2:length(idx), str = [str ',%d']; end 0089 nname = sprintf(['%s(' str, ')'], name, idx{:}); 0090 error('@opt_model/add_costs: cost set named ''%s'' already exists', nname); 0091 end 0092 0093 cp = varargin{1}; 0094 args = varargin(2:end); 0095 else %% just setting dimensions for indexed set 0096 %% prevent duplicate named cost sets 0097 if isfield(om.cost.idx.N, name) 0098 error('@opt_model/add_costs: cost set named ''%s'' already exists', name); 0099 end 0100 0101 cp = []; 0102 args = {}; 0103 end 0104 else %% simple named set 0105 %% prevent duplicate named cost sets 0106 if isfield(om.cost.idx.N, name) 0107 error('@opt_model/add_costs: cost set named ''%s'' already exists', name); 0108 end 0109 0110 cp = idx; 0111 args = varargin; 0112 idx = {}; 0113 end 0114 0115 if isempty(cp) %% just setting dimensions for indexed set 0116 %% add info about this cost set 0117 om.cost.idx.i1.(name) = zeros(idx{:}); %% starting index 0118 om.cost.idx.iN.(name) = zeros(idx{:}); %% ending index 0119 om.cost.idx.N.(name) = zeros(idx{:}); %% number of costs (nw) 0120 om.cost.data.N.(name) = cell(idx{:}); 0121 om.cost.data.Cw.(name) = cell(idx{:}); 0122 om.cost.data.vs.(name) = cell(idx{:}); 0123 else 0124 if isempty(args) 0125 varsets = {}; 0126 else 0127 varsets = args{1}; 0128 end 0129 if ~isempty(varsets) && iscell(varsets) 0130 empty_cells = cell(1, length(varsets)); 0131 [empty_cells{:}] = deal({}); %% empty cell arrays 0132 varsets = struct('name', varsets, 'idx', empty_cells); 0133 end 0134 if isfield(cp, 'N') 0135 [nw, nx] = size(cp.N); 0136 else 0137 nw = length(cp.Cw); 0138 nx = nw; 0139 cp.N = speye(nw, nx); 0140 end 0141 0142 %% check sizes 0143 if isempty(varsets) 0144 nv = om.var.N; 0145 else 0146 nv = 0; 0147 s = struct('type', {'.', '()'}, 'subs', {'', 1}); 0148 for k = 1:length(varsets) 0149 % (calls to substruct() are relatively expensive ... 0150 % s = substruct('.', varsets(k).name, '()', varsets(k).idx); 0151 % ... so replace it with these more efficient lines) 0152 s(1).subs = varsets(k).name; 0153 s(2).subs = varsets(k).idx; 0154 nv = nv + subsref(om.var.idx.N, s); 0155 end 0156 end 0157 if nx ~= nv 0158 if nw == 0 0159 cp.N = sparse(nw, nx); 0160 else 0161 error('@opt_model/add_costs: number of columns in N (%d x %d) does not match\nnumber of variables (%d)\n', nw, nx, nv); 0162 end 0163 end 0164 if size(cp.Cw, 1) ~= nw 0165 error('@opt_model/add_costs: number of rows of Cw (%d x %d) and N (%d x %d) must match\n', size(cp.Cw), nw, nx); 0166 end 0167 if isfield(cp, 'H') && (size(cp.H, 1) ~= nw || size(cp.H, 2) ~= nw) 0168 error('@opt_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); 0169 end 0170 if isfield(cp, 'dd') && size(cp.dd, 1) ~= nw 0171 error('@opt_model/add_costs: number of rows of dd (%d x %d) and N (%d x %d) must match\n', size(cp.dd), nw, nx); 0172 end 0173 if isfield(cp, 'rh') && size(cp.rh, 1) ~= nw 0174 error('@opt_model/add_costs: number of rows of rh (%d x %d) and N (%d x %d) must match\n', size(cp.rh), nw, nx); 0175 end 0176 if isfield(cp, 'kk') && size(cp.kk, 1) ~= nw 0177 error('@opt_model/add_costs: number of rows of kk (%d x %d) and N (%d x %d) must match\n', size(cp.kk), nw, nx); 0178 end 0179 if isfield(cp, 'mm') && size(cp.mm, 1) ~= nw 0180 error('@opt_model/add_costs: number of rows of mm (%d x %d) and N (%d x %d) must match\n', size(cp.mm), nw, nx); 0181 end 0182 0183 if isempty(idx) %% simple named set 0184 %% add info about this user cost set 0185 om.cost.idx.i1.(name) = om.cost.N + 1; %% starting index 0186 om.cost.idx.iN.(name) = om.cost.N + nw; %% ending index 0187 om.cost.idx.N.(name) = nw; %% number of costs (nw) 0188 om.cost.data.N.(name) = cp.N; 0189 om.cost.data.Cw.(name) = cp.Cw; 0190 om.cost.data.vs.(name) = varsets; 0191 if isfield(cp, 'H') 0192 om.cost.data.H.(name) = cp.H; 0193 end 0194 if isfield(cp, 'dd') 0195 om.cost.data.dd.(name) = cp.dd; 0196 end 0197 if isfield(cp, 'rh') 0198 om.cost.data.rh.(name) = cp.rh; 0199 end 0200 if isfield(cp, 'kk') 0201 om.cost.data.kk.(name) = cp.kk; 0202 end 0203 if isfield(cp, 'mm') 0204 om.cost.data.mm.(name) = cp.mm; 0205 end 0206 0207 %% update number of vars and var sets 0208 om.cost.N = om.cost.idx.iN.(name); 0209 om.cost.NS = om.cost.NS + 1; 0210 0211 %% add to ordered list of var sets 0212 om.cost.order(om.cost.NS).name = name; 0213 om.cost.order(om.cost.NS).idx = {}; 0214 else %% indexed named set 0215 %% add info about this user cost set 0216 om.cost.idx.i1 = subsasgn(om.cost.idx.i1, s1, om.cost.N + 1); %% starting index 0217 om.cost.idx.iN = subsasgn(om.cost.idx.iN, s1, om.cost.N + nw); %% ending index 0218 om.cost.idx.N = subsasgn(om.cost.idx.N, s1, nw); %% number of costs (nw) 0219 0220 om.cost.data.N = subsasgn(om.cost.data.N, s2, cp.N); 0221 om.cost.data.Cw = subsasgn(om.cost.data.Cw, s2, cp.Cw); 0222 om.cost.data.vs = subsasgn(om.cost.data.vs, s2, varsets); 0223 if isfield(cp, 'H') 0224 om.cost.data.H = subsasgn(om.cost.data.H, s2, cp.H); 0225 end 0226 if isfield(cp, 'dd') 0227 om.cost.data.dd = subsasgn(om.cost.data.dd, s2, cp.dd); 0228 end 0229 if isfield(cp, 'rh') 0230 om.cost.data.rh = subsasgn(om.cost.data.rh, s2, cp.rh); 0231 end 0232 if isfield(cp, 'kk') 0233 om.cost.data.kk = subsasgn(om.cost.data.kk, s2, cp.kk); 0234 end 0235 if isfield(cp, 'mm') 0236 om.cost.data.mm = subsasgn(om.cost.data.mm, s2, cp.mm); 0237 end 0238 0239 %% update number of costs and cost sets 0240 om.cost.N = subsref(om.cost.idx.iN, s1); 0241 om.cost.NS = om.cost.NS + 1; 0242 0243 %% add to ordered list of cost sets 0244 om.cost.order(om.cost.NS).name = name; 0245 om.cost.order(om.cost.NS).idx = idx; 0246 end 0247 end